Overview
TL;DR: XCCY Protocol consists of four core components working together: VAMMManager handles trading and price discovery, CollateralEngine manages positions and margin, Risk Engine calculates worst-case scenarios for margin requirements, and OracleHub provides price and yield data.
High-Level Architecture
How to read the diagram
This diagram shows the protocol as a pipeline with a strict separation between pricing and custody/risk.
1) User Layer (who interacts)
Traders (FY/VY): swap exposure between Fixed Yield and Variable Yield.
Liquidity Providers (LPs): add/remove concentrated liquidity (range-based).
Liquidators: act when accounts become unsafe (HF < 1).
All users enter through VAMMManager methods (swap, mint, burn), plus liquidation entrypoints.
2) VAMM Manager (the entrypoint + coordinator)
VAMMManager is the main router:
Validates the pool state (exists, not expired).
Executes pricing logic in the vAMM (moves price/ticks).
Computes position deltas (how fixed/variable balances change) and fees.
Forwards those deltas to the Collateral Engine to be applied to real accounts.
3) Collateral Engine (where money and positions live)
The Collateral Engine is the source of truth for:
Custody of user collateral (real funds).
Account/position bookkeeping (fixedTokenBalance, variableTokenBalance, LP positions).
Fee accounting (fees accrue to active LPs).
Settlement at maturity and liquidation execution.
In other words: vAMM produces deltas; Collateral Engine applies them to accounts.
4) Risk Engine (safety check on every state change)
After any position update, the Collateral Engine triggers a margin validation:
Computes margin requirement using worst-case VY assumptions.
For LPs, evaluates both tick-boundary scenarios (range extremes).
Outputs a single decision: safe or revert / liquidatable.
5) Oracle Hub (inputs with guards)
The Risk Engine relies on Oracle Hub for:
USD prices of collateral assets.
APR / rate data used in worst-case cashflow calculations.
Staleness / validity checks so margin calculations are not based on stale inputs.
One-sentence takeaway
VAMMManager + vAMM discover price; Collateral Engine holds funds and state; Risk Engine + Oracle Hub ensure every update stays collateralized.
End-to-end flow: one swap
The sequence diagram below shows what happens when a user executes a trade (e.g., locking fixed yield or taking variable yield) through VAMMManager.swap().
Component Summary
VAMMManager
Trading engine
swap(), mint(), burn(), createPool()
CollateralEngine
Asset custody & positions
updateAccountMargin(), settlePosition(), liquidateAccount()
Risk Engine
Margin calculations
checkMarginRequirement(), worst-case scenarios
OracleHub
Price data
getPriceUsdWad(), getOnAprRay()
AprOracle
Yield tracking
getRateFromTo() per adapter (Aave, Compound, etc.)
Design Principles
1. Singleton Pattern
VAMMManager is a single contract managing all pools (like Uniswap v4), not one contract per pool.
2. Separation of Concerns
VAMMManager: Only handles trading logic
CollateralEngine: Only handles money and positions
Risk Engine: Only handles risk calculations
OracleHub: Only handles external data
3. Non-Custodial by Design
All user funds are held in CollateralEngine. VAMMs never hold assets.
4. Worst-Case Conservative
Risk Engine uses pessimistic VY assumptions to ensure protocol solvency.
Next Steps
vAMM Explained — How price discovery works
Risk Engine V1 — Worst case APR mechanism
Collateral Engine V1 — Position and margin management
Oracle Hub — Price and yield data
Last updated