Collateral Engine V1

TL;DR: The Collateral Engine is XCCY's central bank — it holds all user funds, manages positions, calculates margin requirements, handles settlements, and executes liquidations.

Overview

The Collateral Engine is the custodian and risk manager of the protocol:

┌─────────────────────────────────────────────────────────────┐
│                    COLLATERAL ENGINE                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   CUSTODY   │  │  POSITIONS  │  │    RISK     │        │
│  │             │  │             │  │             │        │
│  │ Holds all   │  │ Tracks all  │  │ Margin      │        │
│  │ user funds  │  │ open trades │  │ requirements│        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │ SETTLEMENT  │  │ LIQUIDATION │  │   ORACLES   │        │
│  │             │  │             │  │             │        │
│  │ Process at  │  │ Force close │  │ Price and   │        │
│  │ maturity    │  │ if needed   │  │ rate feeds  │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Account Structure

Account ID

Users are identified by a composite key:

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

Sub-Accounts

Users can create multiple isolated sub-accounts:

Wallet: 0xABC...

┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│ Sub-Account 0  │  │ Sub-Account 1  │  │ Sub-Account 2  │
│ (Cross Margin) │  │ (USDC Isolated)│  │ (ETH Isolated) │
├────────────────┤  ├────────────────┤  ├────────────────┤
│ USDC: 10,000   │  │ USDC: 5,000    │  │ ETH: 3.0       │
│ ETH: 2.5       │  │                │  │                │
│ Positions: 3   │  │ Positions: 1   │  │ Positions: 1   │
└────────────────┘  └────────────────┘  └────────────────┘

Benefits:
- Risk isolation between strategies
- Different collateral types per sub-account
- Independent margin and liquidation

Margin Management

Depositing Margin

function updateAccountMargin(
    AccountId calldata account,
    address token,
    int256 marginDelta  // Positive = deposit, Negative = withdraw
) external;

Example:

// Deposit 5,000 USDC
await collateralEngine.updateAccountMargin(
    { owner: userAddress, id: 0, isolatedMarginToken: ethers.ZeroAddress },
    USDC_ADDRESS,
    ethers.parseUnits("5000", 6)  // Positive = deposit
);

// Withdraw 1,000 USDC
await collateralEngine.updateAccountMargin(
    { owner: userAddress, id: 0, isolatedMarginToken: ethers.ZeroAddress },
    USDC_ADDRESS,
    ethers.parseUnits("-1000", 6)  // Negative = withdraw
);

Collateral Valuation

Not all collateral is valued equally:

Collateral Value = Balance × Price × Discount Factor

Discount Factors (Example):
━━━━━━━━━━━━━━━━━━━━━━━━━━━
USDC:  100% (1.0)  - Full value
USDT:   98% (0.98) - Minor haircut
ETH:    90% (0.90) - Volatility haircut
WBTC:   85% (0.85) - Higher volatility

Why Discount Factors?

Volatile assets may lose value quickly. Haircuts ensure there's buffer for liquidators.

Position Tracking

Position Structure

struct PositionInfo {
    uint128 _liquidity;           // LP liquidity (if any)
    int256 fixedTokenBalance;     // Fixed leg balance
    int256 variableTokenBalance;  // Variable leg balance
    uint256 accumulatedFees;      // Earned fees (LPs)
    // ... growth checkpoints
}

Position Updates

When traders swap or LPs mint/burn, the CollateralEngine updates positions:

Trade Execution:
━━━━━━━━━━━━━━━━

VAMMManager.swap()
       │
       ▼
CollateralEngine.updatePositionPostVAMMAction()
       │
       ├── Update fixed/variable token balances
       ├── Deduct trading fees from margin
       ├── Update fee growth for LPs
       └── Check margin requirement

Margin Requirements

Calculation

The protocol calculates how much margin each position needs:

Position Margin Requirement = Worst Case Loss × Price

Where:
- Worst Case Loss = Max potential loss at maturity
- Considers: notional, term length, FY locked, VY bounds

Worst Case Variable Factor

The protocol uses conservative VY estimates:

// For positive variableTokenBalance (receiving VY)
// Use low VY estimate (worst case = VY drops)
worstCaseVariableFactorPositive

// For negative variableTokenBalance (paying VY)
// Use high VY estimate (worst case = VY rises)
worstCaseVariableFactorNegative

Health Check

function checkMarginRequirement(AccountId calldata account) 
    external returns (uint256 positionMarginRequirement);

Health = Collateral Value / Margin Requirement

Health > 1.0: Safe
Health = 1.0: At risk
Health < 1.0: Liquidatable

Settlement

At Maturity

When a pool's term ends, positions can be settled:

function settlePosition(
    AccountId calldata account, 
    PoolKey calldata poolKey
) external;

Settlement Flow

1. Verify pool has matured
   └── block.timestamp >= termEndTimestampWad

2. Get final Variable Factor from AprOracle
   └── Accumulated VY over the term

3. Calculate settlement cashflow
   └── cashflow = fixedTokens × fixedFactor 
                + variableTokens × variableFactor

4. Process cashflow
   ├── If positive: Add to user's margin balance
   └── If negative: Deduct from margin or trigger settler exchange

5. Clear position
   └── Reset balances, return remaining margin

Settlement Example

Position:
- Notional: 100,000 USDC
- fixedTokenBalance: +100,000 (receiving 5% FY)
- variableTokenBalance: -100,000 (paying VY)
- Term: 90 days

At maturity:
- fixedFactor: 0.247 × 5% = 0.01235
- variableFactor: 0.247 × 3% = 0.00741 (VY averaged 3%)

Cashflow:
= 100,000 × 0.01235 + (-100,000) × 0.00741
= 1,235 - 741
= +494 USDC profit

Liquidation

When Liquidation Occurs

Accounts are liquidatable when:

Collateral Value < Margin Requirement

Liquidation Process

function liquidateAccount(
    AccountId calldata account,           // Account to liquidate
    AccountId calldata liquidatorAccount  // Liquidator's account
) external;

Flow:

1. Check account is liquidatable
   └── _isLiquidatableAccount(account) == true

2. Close all LP positions (burn liquidity)
   └── For each position with liquidity > 0

3. Transfer positions to liquidator
   └── Liquidator inherits all fixed/variable balances

4. Transfer margin to liquidator
   └── All remaining collateral goes to liquidator

5. Clear original account
   └── Reset all balances and positions

Liquidator Incentive

Liquidators receive:

• All remaining margin from liquidated account

• All positions (which may have value)

• Opportunity to profit if positions are profitable

Oracle Integration

Price Oracle (OracleHub)

function getPriceUsdWad(address asset) 
    external view returns (uint256 priceWad, uint256 timestamp, bool valid);

Used for:

• Collateral valuation

• Cross-asset margin calculations

Rate Oracle (AprOracle)

function getRateFromTo(address compoundToken, uint48 from, uint48 to)
    external view returns (uint256 rateWad, bool valid);

Used for:

• Settlement calculations (final VY)

• Margin requirement estimation

Key Functions

Function	Purpose
updateAccountMargin()	Deposit/withdraw collateral
updatePositionPostVAMMAction()	Update positions after trades
checkMarginRequirement()	Verify margin sufficiency
settlePosition()	Process maturity settlement
liquidateAccount()	Force close underwater accounts
setMarginTokenWhitelist()	Admin: configure collateral
setWorstCaseVariableFactor()	Admin: set VY bounds

Storage Layout

struct CollateralEngineStorage {
    IOracleHub _oracleHub;
    IAprOracle _aprOracle;
    IVAMMManager _vammManager;
    
    // Account state: accountHash => AccountInfo
    mapping(bytes32 => Account.Info) accounts;
    
    // Position state
    mapping(bytes32 => Position.Info) positions;
    
    // Collateral configuration
    mapping(address => bool) marginTokenWhitelist;
    mapping(address => uint256) marginTokenDiscountFactorWad;
    
    // Pool configuration
    mapping(bytes32 => PoolKey) poolIdToPoolKey;
    mapping(bytes32 => uint256) worstCaseVariableFactorPositiveWad;
    mapping(bytes32 => uint256) worstCaseVariableFactorNegativeWad;
}

Security Considerations

Access Control

updateAccountMargin()
└── Only account owner can deposit/withdraw

updatePositionPostVAMMAction()
└── Only VAMMManager can call

liquidateAccount()
└── Anyone can liquidate (if account is underwater)

Admin functions
└── Only contract owner

Safety Checks

Withdrawal:
1. Update position growth (mark to market)
2. Check margin requirement
3. Revert if insufficient margin post-withdrawal

Trade:
1. Check pool not expired
2. Check isolated margin mode compliance
3. Update positions
4. Verify margin requirement

Key Takeaways

1. Central custody — All funds held by CollateralEngine

2. Sub-accounts — Isolate risk between strategies

3. Discount factors — Volatile collateral has haircuts

4. Worst case VY — Conservative margin calculations

5. Automatic settlement — At maturity, positions settle

Next Steps

• Margin System — Detailed margin mechanics

• Liquidations — Liquidation deep dive

• API Reference — Full function reference