Abstract Interface (V3)

📘 Join: joins X and Y amounts to pool
📘 Swap: swaps X for Y (and vice verse)
📘 AddLiquidity: double-sided deposit; adds liquidity using only X or Y amounts
📘 RemoveLiquidity: double-sided withdrawal; removes liquidity using only X or Y amounts
📘 SwapDeposit: single-sided deposit; deposit exact x or y by coming to pool with just one token from trading pair to make a deposit
📘 WithdrawSwap: single-sided withdrawal; withdraw exact x or y by leaving pool with desired token from trading pair
📘 LPQuote: Quote liquidity pool, via either: (a) token price; (b) LP token amount to token amount; or (c) token amount to LP token amount

To download notebook to this tutorial, see here

from defipy import *

user_nm = 'user0'
eth_amount = 1000
tkn_amount = 100000

fee = UniV3Utils.FeeAmount.MEDIUM
tick_spacing = UniV3Utils.TICK_SPACINGS[fee]
lwr_tick = UniV3Utils.getMinTick(tick_spacing)
upr_tick = UniV3Utils.getMaxTick(tick_spacing)

📘 Join

Class: 📘 defipy.process.Join
- Purpose: Simplifies initial liquidity addition to Uniswap V3 pools.
- Methods:
  - apply(pool, user: str, amount0: float, amount1: float)
    - Parameters:
      - pool: Pool instance (e.g., created via Primitive Interface).
      - user: User address.
      - amount0: Amount of token0.
      - amount1: Amount of token1.
      - lwr_tick: Lower tick of the position.
      - upr_tick: Upper tick of the position.
- Output: Liquidity added to the pool.

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0

📘 Swap

Class: 📘 defipy.process.Swap
- Purpose: Facilitates token swaps on Uniswap V3 pools with slippage tolerance and deadline control.
- Methods:
  - apply(pool, token_in: ERC20, user: str, amount_in: float)
    - Parameters:
      - pool: Pool instance to perform the swap on.
      - token_in: ERC20 token to swap from.
      - user: User address (string) executing the swap.
      - amount_in: Amount of token_in to swap.
  - Output: Executes the swap from token_in to token_out for the user

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

Swap().apply(lp, tkn, user_nm, 1000)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 990.1284196560293, TKN = 101000.0 Gross Liquidity: 10000.0

Swap: tkn1 for tkn0

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

Swap().apply(lp, eth, user_nm, 10)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1010.0, TKN = 99012.84196560294 Gross Liquidity: 10000.0

📘 AddLiquidity

Class: 📘 defipy.process.AddLiquidity
- Purpose: Double-sided deposit; adds liquidity to existing Uniswap V3 pools, handling token amounts and liquidity tokens minting; input one token amount and the other token amount is calculated
- Methods:
  - apply(pool, token_in: ERC20, user: str, amount_in: float)
    - Parameters:
      - pool: Pool instance to perform token addition.
      - user: ERC20 token to add.
      - user: User address (string) providing liquidity.
      - amount_in: Amount of token_in to add; the other token amount is calculated
      - lwr_tick: Lower tick of the position.
      - upr_tick: Upper tick of the position.
  - Output: Adds the specified token amounts to the pool and mints liquidity tokens to the user.

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

AddLiquidity().apply(lp, tkn, user_nm, 1000, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1010.0, TKN = 101000.0 Gross Liquidity: 10100.0

Add: tkn0 and determine tkn1

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

AddLiquidity().apply(lp, eth, user_nm, 100, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1100.0, TKN = 110000.0 Gross Liquidity: 11000.0

📘 RemoveLiquidity

Class: 📘 defipy.process.RemoveLiquidity
- Purpose: Double-sided withdraw; removes liquidity from Uniswap V3 pools, returning underlying tokens to the user; input one token amount and the other token amount is calculated
- Methods:
  - apply(pool, token_out: ERC20, user: str, amount_out: float)
    - Parameters:
      - pool: Pool instance to perform token removal.
      - token_out: ERC20 token to remove.
      - user: User address (string) withdrawing liquidity.
      - amount_out: Amount of token_out to remove; the other token amount is calculated
      - lwr_tick: Lower tick of the position.
      - upr_tick: Upper tick of the position.
  - Output: Removes the specified liquidity tokens and transfers the corresponding amounts of underlying tokens back to the user.

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

RemoveLiquidity().apply(lp, tkn, user_nm, 1000, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 990.0, TKN = 99000.0 Gross Liquidity: 9900.0

Remove: tkn0 and determine tkn1

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

RemoveLiquidity().apply(lp, eth, user_nm, 10, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 990.0, TKN = 99000.0 Gross Liquidity: 9900.0

📘 SwapDeposit

Class: 📘 uniswappy.process.SwapDeposit
- Purpose: Single-sided deposit; combines token swapping and liquidity deposit into a single operation on Uniswap V3 pools.
- Methods:
  - apply(pool, token_in: ERC20, user: str, amount_in: float)
    - Parameters:
      - pool: Pool instance from which liquidity will be removed.
      - token_in: ERC20 object of the token to remove from.
      - user: User address (string) withdrawing liquidity.
      - amount_in: Amount of token to swap in.
      - lwr_tick: Lower tick of the position.
      - upr_tick: Upper tick of the position.
  - Output: Executes the swap of token_in and deposits the specified amounts of token0 and token1 into the pool as liquidity for the user.

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

SwapDeposit().apply(lp, tkn, user_nm, 100, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100100.00000001659 Gross Liquidity: 10004.991244978852

Swap exact tkn0 for tkn1

deposit desired token -> perform 50% swap -> perform 50/50 deposit

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

SwapDeposit().apply(lp, eth, user_nm, 10, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1009.9999999867499, TKN = 100000.0 Gross Liquidity: 10049.801066245287

📘 WithdrawSwap

Class: 📘 uniswappy.process.WithdrawSwap
- Purpose: Single-sided withdraw; facilitates withdrawing liquidity from a Uniswap V3 pool and swapping the withdrawn tokens into a desired token.
- Methods:
  - apply(pool, token_in: ERC20, user: str, amount_in: float)
    - Parameters:
      - pool: Pool instance from which liquidity will be removed.
      - token_in: ERC20 object of the token to remove from.
      - user: User address (string) withdrawing liquidity.
      - amount_in:Amount of token to swap out.
      - lwr_tick: Lower tick of the position.
      - upr_tick: Upper tick of the position.
  - Output: Removes liquidity from the pool, swaps the underlying tokens to token_out, and transfers the resulting tokens to the user, respecting slippage and deadline constraints.

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

WithdrawSwap().apply(lp, eth, user_nm, 1, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 999.0000000000001, TKN = 100000.0 Gross Liquidity: 9994.991239989282

Withdraw: exact tkn0

withdraw LP based upon expected amount of tkn

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

expected_amount_out = WithdrawSwap().apply(lp, tkn, user_nm, 100,lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0 Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 99900.00000000001 Gross Liquidity: 9994.991239989282

📘 LPQuote

Class: 📘 defipy.cpt.index.LPQuote
- Purpose: Liquidity pool token quotes (ie, price, reserve and liquidity).
- Methods:
  - get_price(pool, token_in: ERC20)
  - get_amount(pool, token_in: ERC20, amount_tkn: float, lwr_tick: int, upr_tick: int)
  - get_amount_from_lp(pool, token_in: ERC20, amount_lp: float, lwr_tick: int, upr_tick: int)
  - get_lp_from_amount(pool, token_in: ERC20, amount_tkn: float, lwr_tick: int, upr_tick: int)

eth = ERC20("ETH", "0x09")
tkn = ERC20("TKN", "0x111")

exchg_data = UniswapExchangeData(tkn0 = eth, tkn1 = tkn, symbol="LP",
                                   address="0x011", version = 'V3',
                                   tick_spacing = tick_spacing,
                                   fee = fee)

factory = UniswapFactory("ETH pool factory", "0x2")
lp = factory.deploy(exchg_data)

Join().apply(lp, user_nm, eth_amount, tkn_amount, lwr_tick, upr_tick)
lp.summary()

Exchange ETH-TKN (LP) Real Reserves: ETH = 1000.0, TKN = 100000.0 Gross Liquidity: 10000.0

Retrieve LP prices

p_eth = LPQuote().get_price(lp, eth)
p_tkn = LPQuote().get_price(lp, tkn)
print(f'The price of {eth.token_name} in {tkn.token_name} is {p_eth}')
print(f'The price of {tkn.token_name} in {eth.token_name} is {p_tkn}')

The price of ETH in TKN is 100.0 The price of TKN in ETH is 0.01

Retrieve token settlement amount given opposing token amount

amt_eth = LPQuote().get_amount(lp, eth, 1, lwr_tick, upr_tick)
amt_tkn = LPQuote().get_amount(lp, tkn, 1, lwr_tick, upr_tick)
print(f'1 {eth.token_name} token is worth {amt_tkn} {tkn.token_name}')
print(f'1 {tkn.token_name} token is worth {amt_eth} {eth.token_name}')

1 ETH token is worth 0.009969900600093062 TKN 1 TKN token is worth 99.60069810398764 ETH

Retrieve rebased token settlement amount given amount of LP token

amt_eth = LPQuote(False).get_amount_from_lp(lp, eth, 1, lwr_tick, upr_tick)
amt_tkn = LPQuote().get_amount_from_lp(lp, eth, 1, lwr_tick, upr_tick)
print(f'1 LP token is worth {amt_eth} {eth.token_name} after swap fees')
print(f'1 LP token is worth {amt_tkn} {tkn.token_name} after swap fees')

1 LP token is worth 0.19969005990709154 ETH after swap fees 1 LP token is worth 19.905136039497506 TKN after swap fees

Retrieve LP token settlement amount given amount of asset token

amt_eth_lp = LPQuote(False).get_lp_from_amount(lp, eth, 1, lwr_tick, upr_tick)
amt_tkn_lp = LPQuote(False).get_lp_from_amount(lp, tkn, 1, lwr_tick, upr_tick)
print(f'1 {eth.token_name} token is worth {amt_eth_lp} LP tokens')
print(f'1 {tkn.token_name} token is worth {amt_tkn_lp} LP tokens')

1 ETH token is worth 5.008760010717809 LP tokens 1 TKN token is worth 0.05007523748208768 LP tokens