# Minitswap (Full)

## Overview

Minitswap is Initia's solution to address the user experience challenges posed by the lengthy withdrawal challenge periods of optimistic bridges. Furthermore, while setting the period to a longer timeframe increases the duration in which a challenge can be made, it simultaneously increases the wait time required for withdrawals.

The Minitswap DEX is then to designed to allow users to freely, quickly, and efficiently bridge tokens between Initita L1 and Minitias.

## Motivation

While optimistic token bridges between a Layer 1 (L1) and a Layer 2 (L2) chain provides a secure way of transferring assets between chains, it comes with various downsides

- **Long Withdrawal Times**: Transferring tokens from L1 to L2 is usually instantaneous, but the reverse direction involves long wait times, often days, before receiving assets on L1.
- **Single Sequencer Risks**: Creating a DEX pair between the original token on L1 and the bridged tokens can mitigate long withdrawal times. However, most L2s currently operate with a single sequencer, raising security, reliability, and centralization concerns for liquidity providers.
- **Lack of Liquidity**: These issues can result in insufficient liquidity in the token pool, leading to unfavorable swap prices, high volatility, and significant slippage for users bridging tokens back to L1.

## Goal

- **Manipulation Resistance**: The architecture of the Minitia and related systems themselves already has safeguards in place to prevent various forms of manipulation from malicious actors. The Minitswap DEX is further designed to ensure that, in any unforeseen events, any subsequent damages are minimized.
- **Capital Efficiency**: As the number of Minitias continue to increase, naively, the same number of DEX pairs must also exists. This results in liquidity fragmentation, high slippage and volatility, and subpar user experience.

## Design

Minitswap itself is designed as a virtual pool DEX between $INIT$ and the various $IbcOpINIT_m$ tokens for each of the Minitias. The exchange rates on each swap are determined by the StableSwap formula.

To achieve the above goal, two main improvements are made to the base design:
- **Rate Limiting**: To protect against manipulation, the net amount of $IbcOpINIT$ tokens that can be swapped back into INIT tokens is limited.
- **Single INIT Token Pool**: To minimize liquidity fragmentation, a single INIT token pool that can be paired with multiple $IbcOpINIT$ tokens pools, instead of having separate INIT token pools for each Minitia.

## Mechanisms

### Target Ratio Calculation

The ratio $R_{target}$ the follows the formula:

$$
R_{target}=0.5+(R_{max}-0.5)\times\frac{(fI)^3}{(1+|fI|^3)}
$$

In the example below, we have the lower bound 0.5 in green, and a $R_\text{max}=0.7$. We get the purple and red curves when we let $f=2$ and $0.5$ respectively.

### Peg Keeper Swaps
The Peg Keeper Swap is designed to keep the exchange rate between $INIT$ and $IbcOpINIT$ close to 1 to facilitate efficient swaps for users.

When run, the Peg Keeper swap follows the following procedure:

1. Calculate the current $R_{target}$ and the `max_recover_amount`, which defines the maximum size of the pegkeeper swap that can be performed in this swap. This is to prevent a huge pegkeeper swap from happening.
2. Check if another Peg Keeper has been run in the same block. Continue if no swaps have been run.
3. Calculate the $INIT$ amount the Peg Keeper needs to reach $R_{target}$. Let's call this `swap_amount_to_reach_fr`.
4. Check if `swap_amount_to_reach_fr > max_recover_amount`
- If true, swap only `max_recover_amount`.
- If false, swap `swap_amount_to_reach_fr`.

### Internal Rebalancing

The system has an internal rebalancing procedure that aims to continuously recover some of the Peg Keeper's $INIT$ balance by converting its $IbcOpINIT$ into $INIT$ using IBC and OP Bridge. Specifically, it follows the steps:

1. Bridge the Peg Keeper's $IbcOpINIT_m$ back to the Minitia $m$ using IBC, receiving $OpINIT_m$.
2. This is then further bridged back into $INIT$ by using the OP Bridge.

## User Flow

### L1 to L2

In this case, the user wants to efficiently bridge their $INIT$ tokens on the Initia L1 to a Minitia $m$ and ends up with the $OpINIT_m$ token for that Minitia.

1. **Initiate Swap on Minitswap DEX**: The user sends a transaction to the Minitswap DEX to swap their $INIT$ tokens into $IbcOpINIT_m$ tokens.
2. **Simulate Swap**: The DEX simulates swapping the user’s $INIT$ tokens into $IbcOpINIT_m$ tokens.
3. **Compare Swap and Direct Bridging**: The DEX compares the simulated amount of $IbcOpINIT_m$ tokens with the amount the user would receive if they bridged directly through the OP bridge.
4. **Perform Optimal Action**
- If the amount of $IbcOpINIT_m$ tokens from the swap is greater, the DEX performs the swap. The output $IbcOpINIT_m$ tokens are then bridged to the destination L2 through IBC.
- If the direct bridging through the OP bridge provides a better amount, the DEX initiates a direct transfer to the destination Minitia $m$ for the user using the OP bridge.
5. **Final Outcome**: In both cases, once the OP Bridge or IBC transfer is complete, the user receives the most amount of $OpINIT_m$ tokens in their wallet on the destination Minitia possible.

In details, the swap process itself is as follows:

1. **Calculate $IbcOpINIT_m$ Received**: Minitswap calculates how much $IbcOpINIT_m$ the user will receive based on the current Virtual Pool state, updating the state in the process.
2. **Fee Deduction**: Minitswap deducts a fee based on a predefined value and an additional fee from any extra $IbcOpINIT_m$ that the user receives.
3. **Peg Keeper Swap Check**: Once the user’s swap action and fee calculation are complete, Minitswap checks if a Peg Keeper Swap should be performed based on the latest Virtual Pool state.
4. **Internal Rebalancing Check**: After completing the Peg Keeper Swap, Minitswap checks if internal rebalancing is possible based on the Peg Keeper’s $IbcOpINIT$ balance. If balancing is possible, it is initiated.

### L2 to L1

In this case, the user is currently holding $OpINIT_m$ tokens on a Minitia L2 $m$ and would like to bridge it back to $INIT$ tokens on the L1.

1. **Transfer to Initia L1 via IBC**: The user begins by transferring their $OpINIT_m$ tokens on the Minitia L2 back to Initia L1 using IBC. As a result, they receive $IbcOpINIT_m$ tokens on the Initia L1.
2. **Swap on Minitswap DEX**: Once the IBC transfer is complete and the user has $IbcOpINIT_m$ tokens on Initia L1, they initiate a swap transaction on the Minitswap DEX to convert their $IbcOpINIT_m$ tokens into $INIT$ tokens.
3. **Minitswap Swap Process**
- **Peg Keeper Swap Check**: Minitswap first checks if a Peg Keeper Swap can be performed. If this is possible, the swap is executed directly through the Peg Keeper.
- **Calculate $INIT$ Received**: If the Peg Keeper Swap is not applicable, Minitswap calculates the amount of $INIT$ the user will receive based on the updated state of the Virtual Pool.
- **Fee Deduction**: Minitswap deducts a predefined fee amount from the transaction.
- **Internal Rebalancing Check**: After completing the user’s swap transaction, Minitswap checks if internal rebalancing is possible based on the Peg Keeper’s $IbcOpINIT$ balance. If balancing is possible, it is executed to maintain market stability.
4. **Final Outcome**: If the swap is successful, the user receives $INIT$ tokens in their wallet on Initia L1.

By using Minitswap, the user is able to instantaneously bridge tokens from any Minitia back to Initia L1 without loss of fungibility that comes with utilizing IBC directly and without having to wait for the OP Bridge challenge period.

### Direct Swap

The Direct Swap is an alternative swap process available to users, allowing them to directly exchange their $INIT$ tokens for the Peg Keeper’s $IbcOpINIT$ tokens. This exchange happens at the average price at which the Peg Keeper has purchased $INIT$ tokens.

The Direct Swap mechanism aims to incentivize users to help the Peg Keeper replenish its $INIT$ token balance, which gets depleted over time.

Initially, the Direct Swap might not seem attractive due to the Target Ratio being close to 0.5. However, as the Peg Keeper’s balance of OP bridged tokens increases, the Direct Swap option becomes more appealing to users.

## Terminology

**INIT Token Variants**

| Term | Definition |
|-----------------|----------------------------------------------------------------------------------------------------------|
| $INIT$ | The vanilla Initia INIT tokens on the Initia L1 |
| $m$ | The destination Minitia that the user wants to bridge to |
| $OpINIT_m$ | The variation of the INIT tokens bridged directly from the Initia L1 to the destination Minitia $m$ |
| $IbcOpINIT_m$ | The variation of the INIT token that was bridged from Initia L1 to the Minitia $m$ through OP Bridge, then subsequently back to the L1 through IBC |

**Bridges**

| Term | Description |
|-----------------|-----------------------------------------------------------------------------------------------------|
| IBC Bridge | The Inter-Blockchain Communication Protocol used as a bridging solution between Minitias. Bridging in both directions is instantaneous. |
| OPINIT Bridge | Initia's implementation of an optimistic bridge to be used as the primary bridge between the Initia L1 and all Minitias. Deposits into Minitias are instantaneous, but withdrawals have a waiting period.|

**Actors**

| **Term** | **Description** |
|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Virtual Pool** | The liquidity pool used to facilitate the swaps. Initially, the pool starts at a size $V$, with a virtual $IbcOpINIT$ balance of $V$ and a virtual $INIT$ balance of $V$. The exchange rate for swaps through the pool is determined by the StableSwap formula. The Virtual Pool does not allow the amount of $IbcOpINIT$ tokens to be less than $V$ because, in such cases, it is more economical for the user to use the OP Bridge directly. |
| **Liquidity Provider** | A user that provides $INIT$ token liquidity to the Minitswap DEX. Unlike conventional DEXes, Minitswap only allows for single-sided $INIT$ token deposits. |
| **Peg Keeper** | A virtual market participant implemented into the DEX that automatically swaps $INIT$ tokens for $IbcOpINIT$ tokens directly before or after all user swaps. The aim of the peg keeper is to maintain a swap price close to 1 before fees. |
| **User** | The end user using the Minitswap DEX who seeks to swap $IbcOpINIT$ tokens into $INIT$. |

**Parameters**

| Symbol | Term | Description |
|------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| $V$ | Virtual Pool size | An on-chain governance-set parameter that defines the size of the virtual liquidity pool. A larger value increases the total available swap liquidity for Minitswap and helps facilitate a larger swap volume, all else being equal. |
| $B$ | Peg Keeper's $IbcOpINIT$ token balance | This balance increases when a user swaps $IbcOpINIT$ tokens for $INIT$ and sometimes decreases when a transfer and swap in the opposite direction occurs. |
| $I$ | Virtual Pool imbalance | This is defined to be the ratio of the Virtual Pool size $V$ and the Peg Keeper balance $B$. The ratio measures how far the virtual pool currently deviates from the initial state. When there is a large volume of swaps in only one direction, the ratio increases. |
| $R_{target}$ | Target Ratio | Defines the ideal proportion of $IbcOpInit$ vs. $INIT$ in the virtual pool. For example, an $R_{target}$ of 0.6 implies that the ratio is 6:4. This value increases as $B$ increases. |
| $R_{max}$ | Max Ratio | A governance-controlled value that defines the largest $R_{target}$ value allowed. |
| $f$ | Flexibility | A governance-controlled variable that modifies the Peg Keeper's tolerance towards imbalance. A higher flexibility means that a low target ratio can be maintained even with a high imbalance. When the flexibility is low, the Peg Keeper will interfere less frequently compared to high flexibility, ceteris paribus. |