Metapools

A metapool is a pool where a stablecoin is paired against the LP token from another pool, a so-called base pool.

Contract Source & Deployment

Source code available on Github.

The deployment of metapools is permissionless and can be done via the deploy_metapool function within the StableSwap-NG Factory.

Examples

The examples following each code block of the corresponding functions provide a basic illustration of input/output values. When using the function in production, ensure not to set _min_dy, _min_amount, etc., to zero or other arbitrary numbers. Otherwise, MEV bots may frontrun or sandwich your transaction, leading to a potential loss of funds.

The examples are based on the USDV<>3CRV metapool: 0xc273fd237F23cb13296D0Cc2897F0B7A61e83387.

Oracle Methods Documentation

Comprehensive documentation for Oracle Methods is available on a dedicated page, accessible here.

The AMM metapool contract implementation utilizes two internal functions to transfer tokens/coins in and out of the pool and then accordingly update stored_balances.

These function slightly differ to the ones from plain pools, as there needs to be some additional logic because of the basepools:

_transfer_in()

_transfer_in(coin_metapool_idx: int128, coin_basepool_idx: int128, dx: uint256, sender: address, expect_optimistic_transfer: bool, is_base_pool_swap: bool = False) -> uint256:

Input	Type	Description
`coin_metapool_idx`	`int128`	Metapool index of the input coin.
`coin_basepool_idx`	`int128`	Basepool index of the input coin.
`dx`	`uint256`	Amount to transfer in.
`sender`	`address`	Address to transfer coins from.
`expect_optimistic_transfer`	`bool`	`True` if the contract expects an optimistic coin transfer (see `exchange_received()`).
`is_base_pool_swap`	`bool`	If the exchange is a basepool swap (if `i and i > 0`); defaulted to `False`.


@internal
def _transfer_in(
    coin_metapool_idx: int128,
    coin_basepool_idx: int128,
    dx: uint256,
    sender: address,
    expect_optimistic_transfer: bool,
    is_base_pool_swap: bool = False,
) -> uint256:
    """
    @notice Contains all logic to handle ERC20 token transfers.
    @param coin_metapool_idx metapool index of input coin
    @param coin_basepool_idx basepool index of input coin
    @param dx amount of `_coin` to transfer into the pool.
    @param sender address to transfer `_coin` from.
    @param expect_optimistic_transfer True if contract expects an optimistic coin transfer
    @param is_base_pool_swap Default is set to False.
    @return amount of coins received
    """
    _input_coin: ERC20 = ERC20(coins[coin_metapool_idx])
    _stored_balance: uint256 = self.stored_balances[coin_metapool_idx]
    _input_coin_is_in_base_pool: bool = False

    # Check if _transfer_in is being called by _exchange_underlying:
    if coin_basepool_idx >= 0 and coin_metapool_idx == 1:

        _input_coin = ERC20(BASE_COINS[coin_basepool_idx])
        _input_coin_is_in_base_pool = True

    _dx: uint256 = _input_coin.balanceOf(self)

    # ------------------------- Handle Transfers -----------------------------

    if expect_optimistic_transfer:

        if not _input_coin_is_in_base_pool:
            _dx = _dx - _stored_balance
            assert _dx >= dx  # dev: pool did not receive tokens for swap

    else:

        assert dx > 0  # dev : do not transferFrom 0 tokens into the pool
        assert _input_coin.transferFrom(
            sender,
            self,
            dx,
            default_return_value=True
        )
        _dx = _input_coin.balanceOf(self) - _dx

    # ------------ Check if liquidity needs to be added somewhere ------------

    if _input_coin_is_in_base_pool:
        if is_base_pool_swap:
            return _dx  # <----- _exchange_underlying: all input goes to swap.
            # So, we will not increment self.stored_balances for metapool_idx.

        # Swap involves base <> meta pool interaction. Add incoming base pool
        # token to the base pool, mint _dx base pool LP token (idx 1) and add
        # that to self.stored_balances and return that instead.
        _dx = self._meta_add_liquidity(_dx, coin_basepool_idx)

    # ----------------------- Update Stored Balances -------------------------

    self.stored_balances[coin_metapool_idx] += _dx

    return _dx

@internal
def _meta_add_liquidity(dx: uint256, base_i: int128) -> uint256:

    coin_i: address = coins[MAX_METAPOOL_COIN_INDEX]
    x: uint256 = ERC20(coin_i).balanceOf(self)

    if BASE_N_COINS == 2:

        base_inputs: uint256[2] = empty(uint256[2])
        base_inputs[base_i] = dx
        StableSwap2(BASE_POOL).add_liquidity(base_inputs, 0)

    if BASE_N_COINS == 3:

        base_inputs: uint256[3] = empty(uint256[3])
        base_inputs[base_i] = dx
        StableSwap3(BASE_POOL).add_liquidity(base_inputs, 0)

    return ERC20(coin_i).balanceOf(self) - x

_transfer_out()

_transfer_out(_coin_idx: int128, _amount: uint256, receiver: address):

Input	Type	Description
`coin_idx`	`int128`	Index value of the token to transfer out.
`_amount`	`uint256`	Amount to transfer out.
`receiver`	`address`	Address to send the tokens to.


stored_balances: DynArray[uint256, MAX_COINS]

@internal
def _transfer_out(
    _coin_idx: int128, _amount: uint256, receiver: address
):
    """
    @notice Transfer a single token from the pool to receiver.
    @param _coin_idx Index of the token to transfer out
    @param _amount Amount of token to transfer out
    @param receiver Address to send the tokens to
    """

    coin_balance: uint256 = ERC20(coins[_coin_idx]).balanceOf(self)

    # ------------------------- Handle Transfers -----------------------------

    assert ERC20(coins[_coin_idx]).transfer(
        receiver, _amount, default_return_value=True
    )

    # ----------------------- Update Stored Balances -------------------------

    self.stored_balances[_coin_idx] = coin_balance - _amount

Methods with underlying coins

In metapools, coin[0] is always the metapool token, and coin[1] is always the basepool token. When working with the basepool underlying tokens such as exchange_underlying and others, the coin indices of the basepool are appended after coin[0], which is the metapool token.

E.g., in the USDV<>3CRV pool: coin[0] = USDV, coin[1] = DAI, coin[2] = USDC, and coin[3] = USDT.

Exchange Methods¶

Three functions for token exchanges:

The regular exchange function.
A novel exchange_received function that executes a token exchange based on the internal balances of the pool.
Additionally, the metapool implementation includes an exchange_underlying function, which allows tokens to be exchanged with the underlying tokens the asset is paired against. For example, swapping USDV for USDT in the USDV<>3CRV pool.

`exchange`¶

StableSwap.exchange(i: int128, j: int128, _dx: uint256, _min_dy: uint256, _receiver: address = msg.sender) -> uint256:

Warning

This exchange swaps between the metapool token and the basepool LP token. coin[0] is always the metapool token and coin[1] is the basepool LP token. To exchange the metapool token against underlying coins, one needs to use the exchange_underlying function.

Function to exchange _dx amount of coin i for coin j and receive a minimum amount of _min_dy.

Returns: amount of output coin received (uint256).

Emits: TokenExchange

Input	Type	Description
`i`	`int128`	Index value of the input coin.
`j`	`int128`	Index value of the output coin.
`_dx`	`uint256`	Amount of coin `i` being exchanged.
`_min_dy`	`uint256`	Minimum amount of coin `j` to receive.
`_receiver`	`address`	Receiver of the output tokens; defaults to msg.sender.

Source code


event TokenExchange:
    buyer: indexed(address)
    sold_id: int128
    tokens_sold: uint256
    bought_id: int128
    tokens_bought: uint256

@external
@nonreentrant('lock')
def exchange(
    i: int128,
    j: int128,
    _dx: uint256,
    _min_dy: uint256,
    _receiver: address = msg.sender,
) -> uint256:
    """
    @notice Perform an exchange between two coins
    @dev Index values can be found via the `coins` public getter method
    @param i Index value for the coin to send
    @param j Index value of the coin to recieve
    @param _dx Amount of `i` being exchanged
    @param _min_dy Minimum amount of `j` to receive
    @return Actual amount of `j` received
    """
    return self._exchange(
        msg.sender,
        i,
        j,
        _dx,
        _min_dy,
        _receiver,
        False
    )

@internal
def _exchange(
    sender: address,
    i: int128,
    j: int128,
    _dx: uint256,
    _min_dy: uint256,
    receiver: address,
    expect_optimistic_transfer: bool
) -> uint256:

    assert i != j  # dev: coin index out of range
    assert _dx > 0  # dev: do not exchange 0 coins

    rates: DynArray[uint256, MAX_COINS] = self._stored_rates()
    old_balances: DynArray[uint256, MAX_COINS] = self._balances()
    xp: DynArray[uint256, MAX_COINS] = self._xp_mem(rates, old_balances)

    # --------------------------- Do Transfer in -----------------------------

    # `dx` is whatever the pool received after ERC20 transfer:
    dx: uint256 = self._transfer_in(
        i,
        -1,  # <----- we're not handling underlying coins here.
        _dx,
        sender,
        expect_optimistic_transfer
    )

    # ------------------------------- Exchange -------------------------------

    # xp[i] + dx * rates[i] / PRECISION
    x: uint256 = xp[i] + unsafe_div(dx * rates[i], PRECISION)
    dy: uint256 = self.__exchange(x, xp, rates, i, j)
    assert dy >= _min_dy, "Exchange resulted in fewer coins than expected"

    # --------------------------- Do Transfer out ----------------------------

    self._transfer_out(j, dy, receiver)

    # ------------------------------------------------------------------------

    log TokenExchange(msg.sender, i, _dx, j, dy)

    return dy

@internal
def __exchange(
    x: uint256,
    _xp: DynArray[uint256, MAX_COINS],
    rates: DynArray[uint256, MAX_COINS],
    i: int128,
    j: int128,
) -> uint256:

    amp: uint256 = self._A()
    D: uint256 = math.get_D(_xp, amp, N_COINS)
    y: uint256 = math.get_y(i, j, x, _xp, amp, D, N_COINS)

    dy: uint256 = _xp[j] - y - 1  # -1 just in case there were some rounding errors
    dy_fee: uint256 = dy * self._dynamic_fee((_xp[i] + x) / 2, (_xp[j] + y) / 2, self.fee) / FEE_DENOMINATOR

    # Convert all to real units
    dy = (dy - dy_fee) * PRECISION / rates[j]

    self.admin_balances[j] += (
        unsafe_div(dy_fee * admin_fee, FEE_DENOMINATOR)  # dy_fee * admin_fee / FEE_DENOMINATOR
    ) * PRECISION / rates[j]

    # Calculate and store state prices:
    xp: DynArray[uint256, MAX_COINS] = _xp
    xp[i] = x
    xp[j] = y
    # D is not changed because we did not apply a fee
    self.upkeep_oracles(xp, amp, D)

    return dy

Input	Type	Description
`i`	`int128`	Index value of input coin.
`j`	`int128`	Index value of output coin.
`_dx`	`uint256`	Amount of coin `i` being exchanged.
`_min_dy`	`uint256`	Minimum amount of coin `j` to receive.
`_receiver`	`address`	Receiver of the output tokens; defaults to `msg.sender`.

Input	Type	Description
`i`	`int128`	Index value of underlying input coin.
`j`	`int128`	Index value of underlying output coin.
`_dx`	`uint256`	Amount of coin `i` being exchanged.
`_min_dy`	`uint256`	Minimum amount of coin `j` to receive.
`receiver`	`address`	Receiver of the output tokens; defaults to msg.sender.

Input	Type	Description
`_amounts`	`DynArray[uint256, MAX_COINS]`	List of coin amounts to deposit.
`_min_amount`	`uint256`	Minimum amount of LP tokens to mint.
`_receiver`	`address`	Receiver of the LP tokens; defaults to `msg.sender`.

Input	Type	Description
`_burn_amount`	`uint256`	Amount of LP tokens to be burned.
`_min_amounts`	`DynArray[uint256, MAX_COINS]`	Minimum amounts of coins to receive.
`_receiver`	`address`	Receiver of the coins; defaults to `msg.sender`.
`_claim_admin_fees`	`bool`	If admin fees should be claimed; defaults to `true`.

Input	Type	Description
`_burn_amount`	`uint256`	Amount of LP tokens to burn/withdraw.
`i`	`int128`	Index value of the coin to withdraw.
`_min_received`	`uint256`	Minimum amount of coin to receive.
`_receiver`	`address`	Receiver of the coins; defaults to `msg.sender`.

Input	Type	Description
`_amounts`	`DynArray[uint256, MAX_COINS]`	List of amounts of coins to withdraw.
`_max_burn_amount`	`uint256`	Maximum amount of LP tokens to burn.
`_receiver`	`address`	Receiver of the coins; defaults to `msg.sender`.

Input	Type	Description
`_amounts`	`DynArray[uint256, MAX_COINS]`	Amount of coins being deposited/withdrawn.
`_is_deposit`	`bool`	`true` = deposit, `false` = withdraw.

Input	Type	Description
`_burn_amount`	`uint256`	Amount of LP tokens to burn.
`i`	`int128`	Index value of the coin to withdraw.

Metapools

Exchange Methods¶

exchange¶

exchange_received¶

exchange_underlying¶

get_dy¶

get_dy_underlying¶

get_dx¶

get_dx_underlying¶

Adding and Removing Liquidity¶

add_liquidity¶

remove_liquidity¶

remove_liquidity_one_coin¶

remove_liquidity_imbalance¶

calc_token_amount¶

calc_withdraw_one_coin¶

Fee Methods¶

fee¶

dynamic_fee¶

admin_fee¶

offpeg_fee_multiplier¶

stored_rates¶

admin_balances¶

withdraw_admin_fees¶

Amplification Coefficient¶

A¶

A_precise¶

initial_A¶

future_A¶

initial_A_time¶

future_A_time¶

Contract Info Methods¶

BASE_POOL¶

BASE_N_COINS¶

BASE_COINS¶

coins¶

balances¶

get_balances¶

N_COINS¶

totalSupply¶

`exchange`¶

`exchange_received`¶

`exchange_underlying`¶

`get_dy`¶

`get_dy_underlying`¶

`get_dx`¶

`get_dx_underlying`¶

`add_liquidity`¶

`remove_liquidity`¶

`remove_liquidity_one_coin`¶

`remove_liquidity_imbalance`¶

`calc_token_amount`¶

`calc_withdraw_one_coin`¶

`fee`¶

`dynamic_fee`¶

`admin_fee`¶

`offpeg_fee_multiplier`¶

`stored_rates`¶

`admin_balances`¶

`withdraw_admin_fees`¶

`A`¶

`A_precise`¶

`initial_A`¶

`future_A`¶

`initial_A_time`¶

`future_A_time`¶

`BASE_POOL`¶

`BASE_N_COINS`¶

`BASE_COINS`¶

`coins`¶

`balances`¶

`get_balances`¶

`N_COINS`¶

`totalSupply`¶