Documentation Index
Fetch the complete documentation index at: https://docs.kuru.io/llms.txt
Use this file to discover all available pages before exploring further.
KuruAMMVault Contract
ERC20 vault for AMM liquidity provision. Users deposit tokens to receive LP shares and earn trading fees.
contract KuruAMMVault is IKuruAMMVault, ERC20, Initializable, UUPSUpgradeable, ReentrancyGuardTransient
State Variables
address public token1;
address public token2;
IMarginAccount public marginAccount;
IOrderBook public market;
MarketParams public marketParams;
uint96 public SPREAD_CONSTANT;
token1 & token2 - The two tokens in the liquidity pair (one may be native)market - Associated OrderBook that uses this vault for AMM liquiditySPREAD_CONSTANT - Spread between bid/ask prices (e.g., 100 = 1% spread)
Core Functions
initialize
One-time initialization of the KuruAMMVault contract.
function initialize(
address _owner,
address token1_,
address token2_,
address _marginAccount,
address _market,
uint96 _spreadConstant
) public initializer
setMarketParams
Fetch and cache market parameters from OrderBook.
function setMarketParams() public
marketParams struct with current market configuration from the associated OrderBook.
Liquidity Operations
deposit
Deposit tokens and receive LP shares.
function deposit(
uint256 baseDeposit,
uint256 quoteDeposit,
uint256 minQuoteConsumed,
address receiver
) external payable returns (uint256)
mint
Mint specific amount of LP shares.
function mint(uint256 shares, address receiver) external payable returns (uint256, uint256)
previewMint, then calls deposit.
withdraw
Burn LP shares to withdraw tokens.
function withdraw(
uint256 _shares,
address _receiver,
address _owner
) public returns (uint256, uint256)
Preview Functions
previewDeposit
Calculate shares for a given deposit.
function previewDeposit(uint256 asset1, uint256 asset2) public view returns (uint256)
previewMint
Calculate required deposits to mint shares.
function previewMint(uint256 shares) public view returns (uint256, uint256)
previewWithdraw
Calculate token amounts from burning shares.
function previewWithdraw(uint256 shares) public view returns (uint256, uint256)
totalAssets
Get vault’s total token balances.
function totalAssets() public view returns (uint256, uint256)
Ownership Functions
transferOwnership
Transfer vault ownership.
function transferOwnership(address _newOwner) external
Events
KuruVaultDeposit
event KuruVaultDeposit(
uint256 amount1,
uint256 amount2,
uint256 shares,
address userAddress
);
amount1 and amount2 are the deposited tokens, shares is the LP tokens minted.
KuruVaultWithdraw
event KuruVaultWithdraw(
uint256 amount1,
uint256 amount2,
uint256 shares,
address userAddress
);
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:
shares = min(amount0 * totalSupply / reserve0, amount1 * totalSupply / reserve1)
- 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') / 2py_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
