Oracle System

TL;DR: XCCY uses two oracle systems — OracleHub for asset prices (USD valuation) and AprOracle for yield rates (VY tracking). These power margin calculations and settlements.

Overview

┌─────────────────────────────────────────────────────────────┐
│                    ORACLE ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────────┐          ┌──────────────────┐         │
│  │    OracleHub     │          │    AprOracle     │         │
│  │    (Prices)      │          │    (Yields)      │         │
│  └────────┬─────────┘          └────────┬─────────┘         │
│           │                             │                   │
│           ▼                             ▼                   │
│  ┌──────────────────┐          ┌──────────────────┐         │
│  │  Price Sources   │          │   APR Adapters   │         │
│  │  • Chainlink     │          │   • Aave         │         │
│  │  • Pendle TWAP   │          │   • Compound     │         │
│  │  • Custom        │          │   • Lido         │         │
│  └──────────────────┘          │   • Pendle       │         │
│                                │   • ERC-4626     │         │
│                                └──────────────────┘         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

OracleHub (Price Oracle)

Purpose

Provides USD prices for all supported assets. Used for:

• Collateral valuation

• Margin calculations

• Cross-asset comparisons

Interface

interface IOracleHub {
    function getPriceUsdWad(address asset) 
        external view 
        returns (
            uint256 priceWad,    // Price in WAD (18 decimals)
            uint256 timestamp,   // Last update time
            bool valid           // Is price reliable
        );
}

Supported Sources

Source	Use Case	Update Frequency
Chainlink	Major assets (ETH, BTC, stablecoins)	Heartbeat + deviation
Pendle TWAP	Yield-bearing tokens	Continuous
Custom	Protocol-specific assets	Configurable

Price Flow Example

User deposits 10 ETH as margin

CollateralEngine calls:
└── OracleHub.getPriceUsdWad(WETH)
    └── Returns: (2000e18, 1704067200, true)
    
Collateral Value:
= 10 ETH × $2,000 × 0.90 (discount factor)
= $18,000 USD value

Source Architecture

// Each asset can have a registered price source
mapping(address => IPriceSource) public sources;

// Sources implement a standard interface
interface IPriceSource {
    function getPrice() external view returns (uint256 price, uint256 timestamp);
}

AprOracle (Yield Oracle)

Purpose

Tracks Variable Yield rates for yield-bearing tokens. Used for:

• Settlement calculations

• Margin requirement estimation

• VY exposure tracking

Interface

interface IAprOracle {
    /// @notice Get accumulated rate between two timestamps
    function getRateFromTo(
        address compoundToken,  // e.g., aUSDC
        uint48 from,            // Start timestamp
        uint48 to               // End timestamp
    ) external view returns (
        uint256 rateWad,        // Accumulated rate in WAD
        bool valid              // Is rate reliable
    );
    
    /// @notice Get current APR
    function getOnAprRay(address compoundToken) 
        external view returns (uint256 aprRay);  // 27 decimals
}

Rate Calculation

Variable Factor = getRateFromTo(termStart, termEnd)

This represents the accumulated yield over the period.

Example:
- Term: 90 days
- Average VY: 5% APY
- Variable Factor ≈ 0.01233 (90/365 × 5% / 100)

APR Adapters

Each yield source has a dedicated adapter:

Adapter	Token Type	Source
AaveAprAdapter	aTokens (aUSDC, aETH)	Aave lending rates
Erc4626AprAdapter	ERC-4626 vaults	Share price growth
WstEthAprAdapter	wstETH	Lido staking rates
WeEthAprAdapter	weETH	EtherFi rates
PendleAprAdapter	PT/YT tokens	Pendle yield

Adapter Interface

interface IAprAdapter {
    function getAprWad() external view returns (uint256 aprWad);
    function getRateFromTo(uint48 from, uint48 to) 
        external view returns (uint256 rateWad, bool valid);
}

Rate Accumulation

How VY is Tracked

The oracle stores periodic rate snapshots:

Time ─────────────────────────────────────────►
     │
     ▼
┌────────┬────────┬────────┬────────┬────────┐
│ t=0    │ t=1d   │ t=2d   │ t=3d   │ t=4d   │
│ 5.2%   │ 5.4%   │ 4.8%   │ 5.1%   │ 5.3%   │
└────────┴────────┴────────┴────────┴────────┘

getRateFromTo(t=0, t=4d):
Returns accumulated rate over 4 days based on snapshots

Oracle Buffer

Rates are stored in a circular buffer for gas efficiency:

struct OracleBuffer {
    uint16 head;           // Current position
    uint16 size;           // Buffer size
    Sample[] samples;      // Rate samples
}

struct Sample {
    uint48 timestamp;
    uint256 cumulativeRate; // Accumulated rate
}

Integration with CollateralEngine

Settlement Calculation

At maturity, CollateralEngine calls:

1. Get variable factor
   └── AprOracle.getRateFromTo(termStart, termEnd)
   
2. Calculate fixed factor
   └── (termEnd - termStart) / SECONDS_IN_YEAR / 100
   
3. Compute cashflow
   └── fixedTokens × fixedFactor + variableTokens × variableFactor

Margin Requirement

For margin calculations:

1. Get worst case VY factors (admin-configured)
   └── worstCaseVariableFactorPositive
   └── worstCaseVariableFactorNegative
   
2. Calculate max potential loss
   └── Based on position direction and worst case VY
   
3. Get USD value
   └── OracleHub.getPriceUsdWad(underlyingAsset)
   
4. Compute margin requirement
   └── Max loss × USD price

Adding New Sources

New Price Source

// 1. Implement IPriceSource
contract NewPriceSource is IPriceSource {
    function getPrice() external view returns (uint256, uint256) {
        // Return price and timestamp
    }
}

// 2. Register with OracleHub
oracleHub.setSource(tokenAddress, newPriceSource);

New APR Adapter

// 1. Implement IAprAdapter
contract NewAprAdapter is IAprAdapter {
    function getAprWad() external view returns (uint256) {
        // Return current APR
    }
    
    function getRateFromTo(uint48 from, uint48 to) 
        external view returns (uint256, bool) {
        // Return accumulated rate
    }
}

// 2. Register with AprOracle
aprOracle.setAdapter(compoundToken, newAdapter);

Error Handling

Price Validation

(uint256 price, uint256 timestamp, bool valid) = oracleHub.getPriceUsdWad(asset);

if (!valid) {
    revert InvalidPrice(asset);
}

// Additional checks
if (timestamp < block.timestamp - MAX_STALENESS) {
    revert StalePrice(asset, timestamp);
}

Rate Validation

(uint256 rate, bool valid) = aprOracle.getRateFromTo(token, from, to);

if (!valid) {
    revert InvalidAprRate(token, from, to);
}

Security Considerations

Oracle Manipulation Protection

Protection	Description
Multiple sources	Cross-reference prices where possible
Staleness checks	Reject old data
Deviation bounds	Reject extreme price movements
TWAP	Time-weighted averages resist flash manipulation

Admin Controls

// Only owner can configure oracles
function setSource(address asset, IPriceSource source) external onlyOwner;
function setAdapter(address token, IAprAdapter adapter) external onlyOwner;

Current Deployments (Polygon)

Contract	Address
OracleHub	0x7a5084DEc5Fd89Ee1079005cE9cEa094c2A66E8E
AprOracle	0xA192144F89edC9fBB3D225856FaF284d9287EDb8

Key Takeaways

1. Two oracle types — Prices (OracleHub) and yields (AprOracle)

2. Multiple sources — Chainlink, Pendle, protocol-specific

3. Adapter pattern — Easy to add new yield sources

4. Validation built-in — Staleness and validity checks

5. Gas optimized — Circular buffers for rate storage

Next Steps

• Margin System — How oracles power margin

• Smart Contracts — Contract references

• Deployed Contracts — All addresses