vAMM Explained

TL;DR: The Virtual AMM (VAMM) is XCCY's trading engine. It uses concentrated liquidity to discover fair Fixed Yield rates and execute trades between FY and VY positions.

What is a VAMM?

A Virtual AMM (VAMM) is an AMM that exists purely for price discovery — it doesn't hold actual assets.

Traditional AMM:                    VAMM:
━━━━━━━━━━━━━━━━                    ━━━━━━
                                    
┌────────────┐                    ┌────────────┐
│   Pool     │                    │   VAMM     │
│  Holds:    │                    │  Tracks:   │
│  - Token A │                    │  - Price   │
│  - Token B │                    │  - Ticks   │
└────────────┘                    │  - Liquidity│
                                  └────────────┘
                                         │
                                         ▼
                                  ┌────────────┐
                                  │ Collateral │
                                  │  Engine    │
                                  │ Holds all  │
                                  │   funds    │
                                  └────────────┘

Key Insight: The VAMM handles pricing; CollateralEngine handles money.

Fixed Yield Price Discovery

The VAMM discovers fair Fixed Yield rates through supply and demand:

More FY demand                    More VY demand
(People want certainty)           (People expect rates to rise)
        │                                │
        ▼                                ▼
  FY rate DECREASES               FY rate INCREASES
  (Higher price for FY)           (Lower price for FY)

How Ticks Encode FY

Like Uniswap v3, XCCY uses ticks to represent prices:

Fixed Yield = 1.0001 ^ tick

Examples:
━━━━━━━━━
tick = 4055  →  FY ≈ 5.00%
tick = 4879  →  FY ≈ 6.00%
tick = 5662  →  FY ≈ 7.00%
tick = 6931  →  FY ≈ 10.00%

Tick Spacing

Pools define how granular FY rates can be:

Tick Spacing	FY Precision	Use Case
1	~0.01%	High precision markets
10	~0.1%	Standard markets
60	~0.6%	Gas-optimized markets

Concentrated Liquidity

LPs provide liquidity at specific FY ranges, not across all possible rates.

Traditional LP:                    Concentrated LP:
━━━━━━━━━━━━━━━                    ━━━━━━━━━━━━━━━

Liquidity                          Liquidity
    │                                  │
    │ ████████████████████             │     ████████
    │ ████████████████████             │     ████████
    │ ████████████████████             │     ████████
    └──────────────────────► FY       └──────────────────► FY
      0%                 100%            4%    8%
      
    Spread thin everywhere            Concentrated in range
    (Capital inefficient)             (Up to 3000x efficient)

LP Position Example

LP Position:
━━━━━━━━━━━━━
FY Range:    5% — 8%
Liquidity:   100,000 USDC equivalent
Tick Lower:  4055 (5% FY)
Tick Upper:  5662 (7.5% FY)

Behavior:
- Earns fees on all trades between 5-7.5% FY
- If FY moves outside range, stops earning
- Has directional exposure based on where FY ends

Swap Mechanics

Opening an FY Position (Lock Fixed Yield)

// Negative amountSpecified = Lock Fixed Yield
swap({
    amountSpecified: -100000e6,  // Negative = FY position
    sqrtPriceLimitX96: MIN_SQRT_RATIO + 1,
    // ...
})

What happens:

1. User wants to lock FY

2. VAMM matches against LP liquidity

3. Price (FY rate) moves based on trade size

4. Position is recorded with fixed/variable token balances

Opening a VY Position (Trade Variable Yield)

// Positive amountSpecified = Trade Variable Yield
swap({
    amountSpecified: 100000e6,  // Positive = VY position
    sqrtPriceLimitX96: MAX_SQRT_RATIO - 1,
    // ...
})

What happens:

1. User wants VY exposure

2. VAMM matches against LP liquidity

3. Price (FY rate) moves based on trade size

4. Position is recorded with opposite fixed/variable token balances

Internal Accounting

Fixed and Variable Token Balances

Positions are tracked using "notional" tokens:

Token Type	Represents	Sign Convention
Fixed Token	FY leg of the swap	+ = Receive FY, - = Pay FY
Variable Token	VY leg of the swap	+ = Receive VY, - = Pay VY

Example: FY Position

User locks 5% FY on 100,000 USDC notional

Internal Representation:
━━━━━━━━━━━━━━━━━━━━━━━━
fixedTokenBalance:    +100,000  (Receives FY)
variableTokenBalance: -100,000  (Gives up VY)

At settlement (if VY = 3%):
cashflow = 100,000 × 5% × time + (-100,000) × 3% × time
         = 100,000 × (5% - 3%) × time
         = Profit

VAMM State

Each pool maintains state:

struct VAMMState {
    int24 tick;              // Current FY as tick
    uint160 sqrtPriceX96;    // Price in Q96 format
    uint128 liquidity;       // Active liquidity at current tick
    // ... growth accumulators for fees/tokens
}

Reading Current FY

const [tick, sqrtPriceX96] = await vammManager.getVAMMState(poolId);

// Convert tick to FY percentage
const fixedYield = Math.pow(1.0001, tick) * 100;
console.log(`Current FY: ${fixedYield.toFixed(2)}%`);

Fees

Trades incur fees that go to LPs:

Trade Size: 100,000 USDC
Fee Rate:   0.01% (1 basis point)
Fee:        10 USDC

Fee Distribution:
━━━━━━━━━━━━━━━━━
→ Goes to LPs with active liquidity
→ Distributed proportionally to liquidity share
→ Accumulated in position, claimable anytime

Fee Calculation

Fee = |amountSpecified| × feeWad / 1e18

Example:
amountSpecified = 100,000 USDC
feeWad = 1e14 (0.01%)
fee = 100,000 × 1e14 / 1e18 = 10 USDC

Pool Key Structure

Each pool is uniquely identified:

struct PoolKey {
    address underlyingAsset;       // e.g., USDC
    address compoundToken;         // e.g., aUSDC (yield source)
    uint256 termStartTimestampWad; // Term start (WAD format)
    uint256 termEndTimestampWad;   // Maturity date (WAD format)
    uint256 feeWad;               // Fee in WAD
    int24 tickSpacing;            // Tick granularity
}

Pool ID

bytes32 poolId = keccak256(abi.encode(poolKey));

VAMMManager Functions

Function	Purpose
createPool()	Deploy new IRS market
swap()	Execute FY/VY trade
mint()	Add LP liquidity
burn()	Remove LP liquidity
getVAMMState()	Read current tick/price
computeGrowthInside()	Get LP fee/token growth

Integration Example

import { ethers } from "ethers";

// Get current pool state
const [tick, sqrtPriceX96] = await vammManager.getVAMMState(poolId);
const currentFY = Math.pow(1.0001, tick) * 100;
console.log(`Current Fixed Yield: ${currentFY.toFixed(2)}%`);

// Execute swap to lock FY
const tx = await vammManager.swap(
    poolKey,
    {
        account: { owner: userAddress, id: 0, isolatedMarginToken: ethers.ZeroAddress },
        amountSpecified: ethers.parseUnits("-100000", 6), // 100k USDC, negative = lock FY
        sqrtPriceLimitX96: MIN_SQRT_RATIO + 1n,
        tickLower: MIN_TICK,
        tickUpper: MAX_TICK
    }
);

await tx.wait();
console.log("FY position opened!");

Key Takeaways

1. VAMM is for pricing, not custody — CollateralEngine holds funds

2. Ticks encode FY rates — FY = 1.0001^tick

3. Concentrated liquidity — LPs provide at specific FY ranges

4. Negative amount = FY position — Sign determines direction

5. Fees go to LPs — Proportional to active liquidity

Next Steps

• Collateral Engine — Position and margin management

• Provide Liquidity — Become an LP

• API Reference — Full function reference