Skip to main content

KuruAMMVault Contract

ERC20 vault for AMM liquidity provision. Users deposit tokens to receive LP shares and earn trading fees.

State Variables

  • token1 & token2 - The two tokens in the liquidity pair (one may be native)
  • market - Associated OrderBook that uses this vault for AMM liquidity
  • SPREAD_CONSTANT - Spread between bid/ask prices (e.g., 100 = 1% spread)

Core Functions

initialize

One-time initialization of the KuruAMMVault contract.
Sets up the vault with token pair, market reference, and spread constant. Approves margin account for unlimited transfers. Can only be called once.

setMarketParams

Fetch and cache market parameters from OrderBook.
Updates internal marketParams struct with current market configuration from the associated OrderBook.

Liquidity Operations

deposit

Deposit tokens and receive LP shares.
Deposits base and quote assets. Mints LP shares based on current reserves and price. For first deposit, mints minimum liquidity (10^3 shares) to margin account. Returns shares minted. Updates vault order sizes in the OrderBook.

mint

Mint specific amount of LP shares.
Calculates required base/quote deposits via previewMint, then calls deposit.

withdraw

Burn LP shares to withdraw tokens.
Burns shares and returns proportional base and quote tokens. Supports approval-based withdrawals. Updates vault order sizes in the OrderBook.

Preview Functions

previewDeposit

Calculate shares for a given deposit.
Returns how many LP shares would be minted for the deposit amounts.

previewMint

Calculate required deposits to mint shares.
Returns required base and quote amounts to mint the specified shares.

previewWithdraw

Calculate token amounts from burning shares.
Returns base and quote amounts that would be received for the shares.

totalAssets

Get vault’s total token balances.
Returns vault’s current balance of token1 and token2 from margin account.

Ownership Functions

transferOwnership

Transfer vault ownership.
Changes the owner address. Owner can authorize contract upgrades.

Events

KuruVaultDeposit

Emitted when liquidity is deposited. amount1 and amount2 are the deposited tokens, shares is the LP tokens minted.

KuruVaultWithdraw

Emitted when liquidity is withdrawn. amount1 and amount2 are the withdrawn tokens, shares is the LP tokens burned.

Key Mechanics

Virtual Rebalancing

Unlike traditional AMMs that rebalance continuously, the Kuru vault accrues profits in base and quote tokens without rebalancing on-chain. This creates reserve skew where actual reserves may differ from the curve’s implied reserves. Problem: Standard Uniswap V2 share calculation would penalize depositors when reserves are skewed:
Solution: Virtual rebalancing assumes vault ask price is the fair price and calculates shares as if reserves were rebalanced at that price. Given:
  • Actual reserves: x' = x + profitInBase, y' = y + profitInQuote
  • Current vault price: p
  • Total value: value = x'*p + y'
Virtually rebalanced reserves:
  • x_rebalanced = (x'*p + y') / 2p
  • y_rebalanced = (x'*p + y') / 2
Shares are calculated using these virtual reserves, preventing depositor disadvantage while maintaining fairness. Note: Withdrawal ratios may differ from deposit ratios due to skew. This creates arbitrage opportunities that help reduce skew over time.

Share Calculation

  • First deposit: Shares = sqrt(baseDeposit * quoteDeposit) - MIN_LIQUIDITY
  • Subsequent deposits: Proportional to virtually rebalanced reserves
  • Uses fixed-point math to handle decimal precision

Vault Rebalancing

Vault maintains bid/ask spread around current price:
  • Ask size: (SPREAD_CONSTANT * baseAmount) / (20000 + SPREAD_CONSTANT)
  • Bid size: (SPREAD_CONSTANT * baseAmount) / 20000

Price Updates

  • On deposit: Recalculates ask price and updates OrderBook
  • On withdraw: Updates sizes only (prices set on first deposit)
  • Vault prices: vaultBestAsk and vaultBestBid stored in OrderBook

Partial Fills

When withdrawing with pending partial fills:
  • Adjusts owed amounts based on vault’s profit/loss from fills
  • Returns _nullifyPartialFills flag to clear OrderBook state