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. Unlike a traditional AMM pool, it does not hold real assets. Instead, it maintains a pricing state (e.g., price, ticks, and virtual liquidity) and uses that state to quote trades and update the implied rate/price as trades occur.

Traditional AMM vs vAMM

In a traditional AMM, the pool holds the funds (e.g., Token A and Token B reserves). Pricing and custody are coupled: the pool both makes the price and holds the money.

In a vAMM, pricing and custody are separated:

• The vAMM handles pricing mechanics (price/ticks/liquidity accounting).

• The Collateral Engine (or margin system) holds the funds and enforces margin/risk constraints.

Key insight: the vAMM handles pricing; the Collateral Engine handles money.

Fixed Yield price discovery

The vAMM discovers a market-implied Fixed Yield (FY) rate through supply and demand between fixed-yield and variable-yield takers.

• More FY demand (people want certainty) → users pay more for fixed → FY rate decreases (higher “price for FY”).

• More VY demand (people expect rates to rise) → fixed becomes less scarce → FY rate increases (lower “price for FY”).

In short: the vAMM continuously updates the implied FY rate as traders shift between wanting certainty (fixed) and wanting rate exposure (variable).

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

With concentrated liquidity, LPs do not provide liquidity across the entire possible Fixed Yield (FY) curve. Instead, they choose a specific FY range and allocate their liquidity only inside that band.

Traditional LP vs Concentrated LP

Traditional LP (full-range):

• Liquidity is spread thinly across all possible FY values (e.g., 0% → 100%).

• This is capital-inefficient, because most of the liquidity sits where the market is not trading.

Concentrated LP (range-bound):

• Liquidity is provided only within a chosen FY band (e.g., 4% → 8%).

• This is more capital-efficient, because the same capital is focused where trades actually happen.

• In practice, this can be orders of magnitude more efficient than full-range liquidity (range-dependent).

LP Position Example

An LP position is defined by a liquidity amount and a tick range. The tick range maps to an FY interval.

Example position parameters:

• FY range: 5% → 8% (configured via ticks; example ticks below map to ~5% and ~7.5%)

• Liquidity: 100,000 USDC equivalent

• Tick lower: 4055 (≈ 5% FY)

• Tick upper: 5662 (≈ 7.5% FY)

How it behaves

• The position earns fees on trades as long as the market FY stays inside its tick range.

• If the market FY moves outside the range, the position becomes inactive and stops earning fees until the price returns into range.

• The position’s final token balances can become directionally skewed depending on where FY ends up (i.e., the LP takes price/rate exposure as the market moves across the range).

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

A user locks 5% Fixed Yield (FY) on a 100,000 USDC notional.

Internal representation

• fixedTokenBalance = +100,000 (receives FY)

• variableTokenBalance = -100,000 (pays / gives up VY)

Settlement intuition (example VY = 3%)

Let time = termDays / 365.

The position cashflow over the term is:

cashflow = fixedTokenBalance * FY * time + variableTokenBalance * VY * time

Substitute values:

cashflow = 100,000 * 5% * time + (-100,000) * 3% * time cashflow = 100,000 * (5% - 3%) * time

Since (5% - 3%) > 0, the cashflow is positive → 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