Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Liquidity Pools in Depth

Swap price and fee tier

Turbine Pools always swap at current market mid-price plus the pool's fee.

For example, if the current price of a USDC/USDT pair is 1.00, and the pool's fee tier is 1%, you can swap 100 USDC into 99 USDT, or 100 USDT into 99 USDC.

Two modes of providing liquidity

Providing liquidity in pool ratio

At any point in time, each Turbine Pool has some ratio of its reserves. For example, if a pool holds 10,000 DAI and 2 WETH, its reserves ratio is 5000:1.

In pool ratio mode, you specify maximum amounts of tokens to provide in your intent submitted to Turbine.

After your intent passes the speedbump, Turbine executes the intent. It provides liquidity on your behalf in the current pool ratio, without exceeding the specified maximum amounts.

The pool ratio can change between the time you submit your intent and the time Turbine executes it.

Turbine gives you a certain amount of LP token, specific to the pool, that represents your share in it. For example, if you provided 1,000 DAI to a pool that held 9,000 DAI (so the pool now holds 10,000 DAI and you own 10% of it), you receive an amount of LP token that represents 10% of its total supply. (The amount of the second token provided is not relevant, because the ratio is the same either way.)

To provide liquidity in pool ratio, specify exact: false in the intent submitted to POST /api/add_liquidity (see the Swagger UI).

Providing liquidity in any ratio

You can provide any amounts of both tokens to a pool, regardless of the current reserve ratio, for a fee.

Providing liquidity in any ratio is equivalent to first making a swap on the pool to bring the pool's reserves and your provided amounts to the same ratio, then providing in pool ratio.

Paying the fee: When you provide liquidity in a ratio different from the pool ratio, you pay the swap fee on the amount the protocol must swap to align reserves with your provided amounts. The fee is subtracted from the LP tokens you receive.

Mathematical Foundation

Notation

  • r0, r1: Current reserves of token0 and token1

  • p0, p1: Amounts user wants to provide

  • Rr = r0/r1: Pool reserve ratio

  • Rp = p0/p1: Provision ratio

  • mp: Mid-price (token0 in terms of token1, units are [token1/token0])

  • f: Swap fee (as a multiplier, e.g., 0.99 for 1% fee)

  • emp: Effective mid-price (accounts for fee)

  • s0, s1: Swapped amounts (amounts that the user gets in a virtual swap)

Conclusion:

All tokens provided by the user are added to pool reserves.

The amount of liquidity tokens minted is calculated as lp_total_supply * (emp*p0 + p1) / (emp*r0 + r1), where emp = mp/f if Rp < Rr and emp = mp*f if Rp > Rr.

To provide liquidity in a ratio different from the pool, the protocol first performs a virtual swap to bring the provided amounts and pool reserves to the same ratio. When making this swap, the pool charges a fee. Then equal ratio provision logic is applied.

The following mathematical derivations calculate the final amount of liquidity tokens to mint, as if the virtual swap happened before provision in equal ratio.

  1. Determine swap direction:

    • If Rp < Rr, swap token1 to token0. s1 is given, and s0 is unknown. Calculate s0 applying swap fee: s0 = -s1 / mp * f, so s1 = -s0 * mp / f

    • If Rp > Rr, swap token0 to token1. s0 is given, and s1 is unknown. Calculate s1 applying swap fee: s1 = -s0 * mp * f

    • This can be simplified to one case by introducing effective mid-price emp:

  2. Calculate swapped amounts:

    • User's provided amounts after swap: p0 + s0 and p1 + s1 i.e. Rp*p1 + s0 and p1 - emp*s0

    • Reserves after swap: r0 - s0 and r1 - s1 i.e. Rr*r1 - s0 and r1 + emp*s0

    • We want the ratio of reserves after swap to equal the ratio of provided amounts after swap. Solving for s0:

  3. Calculate amount of liquidity tokens to mint:

    • Reserve of token0 after swap (before provision): r0 - s0 = r0 - (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)

    • Provided amount of token0 after swap: p0 + s0 = p0 + (p1*r0 - p0*r1) / (emp*p0 + emp*r0 + p1 + r1)

    • Ratio of provided amount to reserve (this, times liquidity token total supply, is the amount of liquidity token that needs to be minted):

      Multiplying numerator and denominator by emp*p0 + emp*r0 + p1 + r1, we get:

    • To avoid numerical integer divisions, assuming that effective mid-price is a fraction emp = emp_num / emp_den, we can multiply numerator and denominator by effective mid-price's denominator:

    • Finally, the amount of LP tokens to mint is:

See also

space
space

Last updated

Was this helpful?