Overview

TL;DR: XCCY consists of four core components — VAMMManager for trading, CollateralEngine for margin and positions, OracleHub for prices, and AprOracle for yield rates. Together they enable efficient interest rate swap markets.

System Architecture

Core Components

Component	Purpose	Key Responsibility
VAMMManager	Trading engine	Price discovery, swap execution
CollateralEngine	Asset custody	Margin, positions, settlement
OracleHub	Price oracle	Asset prices in USD
AprOracle	Yield oracle	Variable Yield tracking

Component Details

VAMMManager

The trading engine that handles all market operations.

┌─────────────────────────────────────────────────────────────┐
│                     VAMMManager                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Functions:                                                 │
│  ─────────                                                  │
│  • createPool()   - Deploy new IRS markets                  │
│  • swap()         - Execute FY/VY trades                    │
│  • mint()         - Add liquidity                           │
│  • burn()         - Remove liquidity                        │
│                                                             │
│  Key Features:                                              │
│  ─────────────                                              │
│  • Singleton pattern (one contract for all pools)           │
│  • Concentrated liquidity (like Uniswap v3)                 │
│  • Tick-based FY pricing                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Design Pattern: Follows Uniswap v4's PoolManager singleton approach — all pools managed by one contract for gas efficiency.

CollateralEngine

The "bank" of the protocol — holds all funds and manages positions.

┌─────────────────────────────────────────────────────────────┐
│                   CollateralEngine                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Functions:                                                 │
│  ─────────                                                  │
│  • updateAccountMargin()  - Deposit/withdraw collateral     │
│  • checkMarginRequirement() - Verify position health        │
│  • settlePosition()       - Process maturity settlement     │
│  • liquidateAccount()     - Handle liquidations             │
│                                                             │
│  Key Features:                                              │
│  ─────────────                                              │
│  • Custodian for all user funds                             │
│  • Sub-account support (isolated positions)                 │
│  • Multi-collateral with discount factors                   │
│  • Automatic settlement at maturity                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Important: VAMMs do NOT hold funds. All assets are held by CollateralEngine.

OracleHub

Provides USD price feeds for margin calculations.

┌─────────────────────────────────────────────────────────────┐
│                      OracleHub                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Supported Sources:                                         │
│  ─────────────────                                          │
│  • Chainlink price feeds                                    │
│  • Pendle TWAP oracles                                      │
│  • Custom price sources                                     │
│                                                             │
│  Functions:                                                 │
│  ─────────                                                  │
│  • getPriceUsdWad() - Get asset price in USD (WAD format)   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

AprOracle

Tracks Variable Yield rates for settlement calculations.

┌─────────────────────────────────────────────────────────────┐
│                      AprOracle                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Adapters:                                                  │
│  ─────────                                                  │
│  • AaveAprAdapter      - Aave aToken rates                  │
│  • Erc4626AprAdapter   - Any ERC-4626 vault                 │
│  • WstEthAprAdapter    - Lido staking rates                 │
│  • WeEthAprAdapter     - EtherFi rates                      │
│  • PendleAprAdapter    - Pendle yield tokens                │
│                                                             │
│  Functions:                                                 │
│  ─────────                                                  │
│  • getRateFromTo() - Get accumulated VY between timestamps  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Data Flow: Opening a Position

Step 1: User deposits margin
━━━━━━━━━━━━━━━━━━━━━━━━━━━

User ──► CollateralEngine.updateAccountMargin()
         │
         └──► Transfers tokens to CollateralEngine
         └──► Updates account balance


Step 2: User executes swap
━━━━━━━━━━━━━━━━━━━━━━━━━━

User ──► VAMMManager.swap()
         │
         ├──► Calculates trade in VAMM
         ├──► Determines fixed/variable token deltas
         │
         └──► CollateralEngine.updatePositionPostVAMMAction()
              │
              └──► Updates position balances
              └──► Deducts fees
              └──► Checks margin requirement


Step 3: Margin check
━━━━━━━━━━━━━━━━━━━━

CollateralEngine.checkMarginRequirement()
         │
         ├──► Calculates position obligations
         ├──► OracleHub.getPriceUsdWad() for asset prices
         ├──► Compares collateral value vs requirements
         │
         └──► Reverts if insufficient margin

Data Flow: Settlement

At Maturity:
━━━━━━━━━━━━

User ──► CollateralEngine.settlePosition()
         │
         ├──► Verify pool has matured
         │
         ├──► Get final Variable Factor from AprOracle
         │    │
         │    └──► AprOracle.getRateFromTo(termStart, termEnd)
         │
         ├──► Calculate settlement cashflow
         │    │
         │    └──► cashflow = fixedTokens × fixedFactor
         │                  + variableTokens × variableFactor
         │
         ├──► If positive: Add to user margin
         │    If negative: Handle settler exchange
         │
         └──► Clear position, return remaining margin

Pool Structure

Each XCCY pool is defined by a unique key:

struct PoolKey {
    address underlyingAsset;      // e.g., USDC
    address compoundToken;        // e.g., aUSDC
    uint256 termStartTimestampWad; // When term begins
    uint256 termEndTimestampWad;   // When term ends (maturity)
    uint256 feeWad;               // Trading fee
    int24 tickSpacing;            // FY granularity
}

Pool Lifecycle

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  CREATE  │────►│  ACTIVE  │────►│ MATURED  │────►│ SETTLED  │
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     │                │                │                │
  Pool created    Trading open    Settlement      All positions
  by admin        Positions       begins          closed
                  can open

Account System

XCCY supports sub-accounts for isolated positions:

struct AccountId {
    address owner;           // Wallet address
    uint96 id;              // Sub-account ID (0, 1, 2...)
    address isolatedMarginToken; // For isolated margin mode
}

Use Cases

Mode	Description
Cross Margin	Share margin across positions (id=0, isolatedMarginToken=0)
Isolated Margin	Separate margin per position (unique id, specific token)

Security Model

┌─────────────────────────────────────────────────────────────┐
│                    Security Layers                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Access Control                                          │
│     • Owner-only admin functions                            │
│     • Only VAMMManager can update positions                 │
│     • Only account owner can withdraw margin                │
│                                                             │
│  2. Reentrancy Protection                                   │
│     • ReentrancyGuard on all state-changing functions       │
│                                                             │
│  3. Upgradeability                                          │
│     • TransparentUpgradeableProxy pattern                   │
│     • Allows fixing bugs without migration                  │
│                                                             │
│  4. Oracle Security                                         │
│     • Multiple source validation                            │
│     • Staleness checks                                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Gas Efficiency

XCCY is optimized for low gas costs:

Optimization	Benefit
Singleton pattern	No per-pool deployment costs
Storage packing	Reduced storage reads/writes
Custom errors	Cheaper than require strings
Immutable variables	Lower read costs

Next Steps

• VAMM Explained — Deep dive into the trading engine

• Collateral Engine — Margin and position management

• Oracle System — Price and yield feeds