> ## 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

# KuruAMMVault Contract

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

```solidity theme={null}
contract KuruAMMVault is IKuruAMMVault, ERC20, Initializable, UUPSUpgradeable, ReentrancyGuardTransient
```

## State Variables

```solidity theme={null}
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 liquidity
* `SPREAD_CONSTANT` - Spread between bid/ask prices (e.g., 100 = 1% spread)

## Core Functions

### initialize

One-time initialization of the KuruAMMVault contract.

```solidity theme={null}
function initialize(
    address _owner,
    address token1_,
    address token2_,
    address _marginAccount,
    address _market,
    uint96 _spreadConstant
) public initializer
```

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.

```solidity theme={null}
function setMarketParams() public
```

Updates internal `marketParams` struct with current market configuration from the associated OrderBook.

### Liquidity Operations

#### deposit

Deposit tokens and receive LP shares.

```solidity theme={null}
function deposit(
    uint256 baseDeposit,
    uint256 quoteDeposit,
    uint256 minQuoteConsumed,
    address receiver
) external payable returns (uint256)
```

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.

```solidity theme={null}
function mint(uint256 shares, address receiver) external payable returns (uint256, uint256)
```

Calculates required base/quote deposits via `previewMint`, then calls `deposit`.

#### withdraw

Burn LP shares to withdraw tokens.

```solidity theme={null}
function withdraw(
    uint256 _shares,
    address _receiver,
    address _owner
) public returns (uint256, uint256)
```

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.

```solidity theme={null}
function previewDeposit(uint256 asset1, uint256 asset2) public view returns (uint256)
```

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

#### previewMint

Calculate required deposits to mint shares.

```solidity theme={null}
function previewMint(uint256 shares) public view returns (uint256, uint256)
```

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

#### previewWithdraw

Calculate token amounts from burning shares.

```solidity theme={null}
function previewWithdraw(uint256 shares) public view returns (uint256, uint256)
```

Returns base and quote amounts that would be received for the shares.

#### totalAssets

Get vault's total token balances.

```solidity theme={null}
function totalAssets() public view returns (uint256, uint256)
```

Returns vault's current balance of token1 and token2 from margin account.

### Ownership Functions

#### transferOwnership

Transfer vault ownership.

```solidity theme={null}
function transferOwnership(address _newOwner) external
```

Changes the owner address. Owner can authorize contract upgrades.

## Events

### KuruVaultDeposit

```solidity theme={null}
event KuruVaultDeposit(
    uint256 amount1,
    uint256 amount2,
    uint256 shares,
    address userAddress
);
```

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

### KuruVaultWithdraw

```solidity theme={null}
event KuruVaultWithdraw(
    uint256 amount1,
    uint256 amount2,
    uint256 shares,
    address userAddress
);
```

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:

```
shares = min(amount0 * totalSupply / reserve0, amount1 * totalSupply / reserve1)
```

**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