Oracle Registry

The Oracle Registry is a centralized price oracle system that provides USD valuations for all assets in the Flux protocol. It maps assets to oracle adapters and ensures consistent pricing across all vaults.

What is the Oracle Registry?

The Oracle Registry is a smart contract that:

• Maps asset addresses to oracle adapter contracts

• Provides standardized USD price queries

• Supports multiple oracle types (Chainlink, Uniswap, Euler, etc.)

• Is governance-controlled for security

• Shared across all Flux vaults

Think of it as a "price feed router" that asset wrappers query to determine position values.

---

Why Centralized Oracle Management?

Consistent Pricing

All vaults and wrappers use the same price feeds:

VaultA → WETHWrapper → OracleRegistry → Chainlink
VaultB → WETHWrapper → OracleRegistry → Chainlink
                                         ↑
                                   Same price!

Upgradeable Feeds

Oracle sources can be updated without redeploying wrappers:

// Governance switches WETH from Chainlink to Pyth
oracleRegistry.setOracle(WETH, pythAdapter);

// All existing wrappers automatically use new feed

Simplified Wrapper Logic

Wrappers don't need oracle logic - they just query the registry:

contract ERC20AssetWrapper {
    function getValue(...) external view returns (uint256) {
        uint256 balance = balances[account][subaccount][positionId];

        // Simple query to registry
        return factory.oracleRegistry().getValueUSD(asset, balance);
    }
}

Governance Control

Only trusted governance can add/update oracle feeds:

• Prevents malicious price manipulation

• Ensures quality oracle sources

• Centralizes security review process

---

The IOracleRegistry Interface

interface IOracleRegistry {
    /**
     * @notice Get USD value for an asset amount
     * @param asset The asset address
     * @param amount The amount in asset's native decimals
     * @return valueUSD The USD value (18 decimals)
     */
    function getValueUSD(address asset, uint256 amount)
        external view returns (uint256 valueUSD);

    /**
     * @notice Get price of asset in USD
     * @param asset The asset address
     * @return priceUSD The price in USD (18 decimals)
     */
    function getPriceUSD(address asset)
        external view returns (uint256 priceUSD);

    /**
     * @notice Get oracle adapter for an asset
     * @param asset The asset address
     * @return oracle The oracle adapter contract
     */
    function getOracle(address asset)
        external view returns (IPriceOracle oracle);

    /**
     * @notice Set oracle adapter for an asset (governance only)
     * @param asset The asset address
     * @param oracle The oracle adapter contract
     */
    function setOracle(address asset, IPriceOracle oracle) external;
}

---

How It Works

Price Query Flow

1. Wrapper needs WETH position value
      ↓
2. Wrapper.getValue(vault, manager, positionId)
      ↓
3. balance = balances[vault][manager][positionId]  // e.g., 10 WETH
      ↓
4. registry = factory.oracleRegistry()
      ↓
5. valueUSD = registry.getValueUSD(WETH, balance)
      ↓
6. oracle = oracles[WETH]  // Get Chainlink adapter
      ↓
7. price = oracle.getPrice(WETH)  // $3000 per WETH
      ↓
8. valueUSD = balance × price / (10 ** assetDecimals)
      ↓
9. return 30_000e18  // $30,000 USD (18 decimals)

Code Example

// In ERC20AssetWrapper
function getValue(address account, address subaccount, bytes32 positionId)
    external view returns (uint256)
{
    // Step 1: Get position balance
    uint256 balance = balances[account][subaccount][positionId];

    if (balance == 0) return 0;

    // Step 2: Query oracle registry via factory
    IOracleRegistry registry = factory.oracleRegistry();

    // Step 3: Get USD value (registry handles decimals)
    return registry.getValueUSD(underlyingAsset, balance);
}

// In OracleRegistry
function getValueUSD(address asset, uint256 amount)
    external view returns (uint256)
{
    if (amount == 0) return 0;

    // Get oracle adapter for this asset
    IPriceOracle oracle = oracles[asset];
    require(address(oracle) != address(0), "No oracle");

    // Get price from adapter
    uint256 priceUSD = oracle.getPrice(asset);

    // Calculate value accounting for decimals
    uint8 decimals = IERC20Metadata(asset).decimals();
    return (amount * priceUSD) / (10 ** decimals);
}

---

Oracle Adapters

Oracle adapters implement the IPriceOracle interface:

interface IPriceOracle {
    /**
     * @notice Get USD price for an asset
     * @param asset The asset address
     * @return price The price in USD (18 decimals)
     */
    function getPrice(address asset) external view returns (uint256 price);
}

Supported Oracle Types

1. Chainlink Oracle Adapter

Uses Chainlink price feeds for reliable, decentralized prices.

contract ChainlinkOracleAdapter is IPriceOracle {
    mapping(address => address) public priceFeeds;  // asset → Chainlink feed

    function getPrice(address asset) external view returns (uint256) {
        address feed = priceFeeds[asset];
        require(feed != address(0), "No feed");

        (, int256 price,,,) = AggregatorV3Interface(feed).latestRoundData();
        require(price > 0, "Invalid price");

        // Chainlink feeds are typically 8 decimals
        // Scale to 18 decimals
        return uint256(price) * 1e10;
    }
}

Use Case: Established assets with Chainlink feeds (WETH, WBTC, USDC, etc.).

2. Uniswap V3 TWAP Oracle

Uses Uniswap V3 time-weighted average price.

contract UniswapV3TWAPOracle is IPriceOracle {
    IUniswapV3Pool public pool;
    uint32 public twapPeriod;  // e.g., 30 minutes

    function getPrice(address asset) external view returns (uint256) {
        // Get TWAP from Uniswap pool
        (int24 tick,) = OracleLibrary.consult(pool, twapPeriod);

        // Convert tick to price
        uint256 price = OracleLibrary.getQuoteAtTick(
            tick,
            uint128(1e18),  // 1 token
            asset,
            WETH
        );

        // Convert WETH price to USD
        return convertToUSD(price);
    }
}

Use Case: Long-tail assets without Chainlink feeds but with Uniswap liquidity.

3. Euler Oracle

Uses Euler's oracle system (combination of Chainlink and Uniswap).

contract EulerOracleAdapter is IPriceOracle {
    IEulerOracle public eulerOracle;

    function getPrice(address asset) external view returns (uint256) {
        // Euler provides prices in native quote asset
        (uint256 price,) = eulerOracle.getPrice(asset);

        return price;  // Already 18 decimals
    }
}

Use Case: Assets supported by Euler's vetted oracle system.

4. Fixed Price Oracle

For stablecoins or known pegs.

contract FixedPriceOracle is IPriceOracle {
    uint256 public immutable FIXED_PRICE;

    constructor(uint256 _price) {
        FIXED_PRICE = _price;
    }

    function getPrice(address) external view returns (uint256) {
        return FIXED_PRICE;  // e.g., 1e18 for $1 stablecoin
    }
}

Use Case: USDC/USDT/DAI pegged to $1.00.

5. Exchange Rate Oracle

For wrapped/rebasing tokens with deterministic exchange rates.

contract ExchangeRateOracle is IPriceOracle {
    function getPrice(address asset) external view returns (uint256) {
        // Example: wstETH → stETH exchange rate
        if (asset == WSTETH) {
            uint256 stEthPerWstEth = IWstETH(WSTETH).stEthPerToken();
            uint256 stEthPrice = getStEthPrice();  // Get from another oracle
            return (stEthPerWstEth * stEthPrice) / 1e18;
        }

        revert("Unsupported asset");
    }
}

Use Case: wstETH, rETH, cbETH, etc.

---

Managing the Oracle Registry

Setting Oracle Adapters (Governance)

// Governance sets Chainlink adapter for WETH
IPriceOracle chainlinkAdapter = new ChainlinkOracleAdapter(
    WETH,
    CHAINLINK_ETH_USD_FEED
);

oracleRegistry.setOracle(WETH, chainlinkAdapter);

emit OracleSet(WETH, address(chainlinkAdapter));

Updating Oracle Feeds

// Switch WETH from Chainlink to Pyth
IPriceOracle pythAdapter = new PythOracleAdapter(WETH, PYTH_FEED_ID);

oracleRegistry.setOracle(WETH, pythAdapter);

// All wrappers automatically use new feed on next query

Why Safe?

• Only governance can update

• Changes take effect immediately (use timelock if desired)

• Existing positions unaffected

• Wrappers don't need redeployment

Querying Oracle Status

// Check if asset has oracle
IPriceOracle oracle = oracleRegistry.getOracle(WETH);
require(address(oracle) != address(0), "No oracle for WETH");

// Get current price
uint256 price = oracleRegistry.getPriceUSD(WETH);
console.log("WETH price:", price);  // e.g., 3000e18 ($3000)

// Get value for amount
uint256 value = oracleRegistry.getValueUSD(WETH, 10e18);
console.log("10 WETH value:", value);  // e.g., 30000e18 ($30,000)

---

Decimal Handling

The registry handles decimal conversions automatically:

Asset Decimals → 18 Decimals USD

// USDC (6 decimals)
balance = 1_000_000e6;  // 1M USDC
price = 1e18;           // $1.00
value = (balance * price) / 10**6 = 1_000_000e18  // $1M USD (18 decimals)

// WETH (18 decimals)
balance = 10e18;        // 10 WETH
price = 3000e18;        // $3000
value = (balance * price) / 10**18 = 30_000e18  // $30K USD (18 decimals)

// WBTC (8 decimals)
balance = 1e8;          // 1 WBTC
price = 60_000e18;      // $60,000
value = (balance * price) / 10**8 = 60_000e18  // $60K USD (18 decimals)

Result: All values returned as 18-decimal USD amounts for consistency.

---

Oracle Security Considerations

1. Price Manipulation

Risk: Oracle feeds can be manipulated (especially on-chain oracles like Uniswap).

Mitigations:

• Use Chainlink for established assets (decentralized, manipulation-resistant)

• Use TWAP for on-chain oracles (time-weighted resists flash loan attacks)

• Set conservative liquidation buffers

• Monitor for suspicious price movements

2. Stale Prices

Risk: Oracle feeds stop updating, providing stale prices.

Mitigations:

• Oracle adapters should check staleness:

function getPrice(address asset) external view returns (uint256) {
    (, int256 price,, uint256 updatedAt,) = feed.latestRoundData();

    require(block.timestamp - updatedAt < MAX_STALENESS, "Stale price");
    require(price > 0, "Invalid price");

    return uint256(price) * 1e10;
}

3. Oracle Failure

Risk: Oracle adapter reverts, preventing liquidations/health checks.

Mitigations:

• Fallback oracle logic:

function getPrice(address asset) external view returns (uint256) {
    try primaryOracle.getPrice(asset) returns (uint256 price) {
        return price;
    } catch {
        // Fall back to secondary oracle
        return secondaryOracle.getPrice(asset);
    }
}

• Emergency circuit breakers in vaults

4. Governance Control Risk

Risk: Malicious governance could set bad oracle to manipulate prices.

Mitigations:

• Multi-sig governance

• Timelock on oracle changes

• Community monitoring

• Immutable strategies (LPs can exit before oracle change)

---

Integration with Vaults

Health Check Flow

// During manager unlock callback
vault.unlock(data);
  ↓
// Manager modifies positions
manager.fluxUnlockCallback(data)
  ↓
// Vault checks health at end of callback
strategy.evaluateLiquidation(vault, manager)
  ↓
// Strategy queries wrapper values
for each wrapper in manager.registeredWrappers:
    value += wrapper.getValue(vault, manager, positionId)
          ↓
          // Wrapper queries oracle registry
          factory.oracleRegistry().getValueUSD(asset, balance)
                ↓
                // Registry queries oracle adapter
                oracle.getPrice(asset)
  ↓
// Strategy compares to liquidation threshold
healthRatio = totalValue / trueDebt
require(healthRatio >= liquidationThreshold)

Liquidation Flow

// Liquidator calls
vault.liquidate(manager, additionalWrappers, data);
  ↓
// Vault checks position is liquidatable
(bool canLiquidate, uint256 minPayment,) = strategy.evaluateLiquidation(vault, manager);
require(canLiquidate);
  ↓
// Liquidator pays minPayment
// (calculated using oracle prices)
  ↓
// Liquidator extracts collateral
vault.locked_withdrawFromWrapper(wrapper, positionId, amount);

---

Oracle Registry Deployment

Initial Setup

// 1. Deploy oracle registry
FluxOracleRegistry registry = new FluxOracleRegistry(governance);

// 2. Deploy oracle adapters
ChainlinkOracleAdapter chainlink = new ChainlinkOracleAdapter();
chainlink.setFeed(WETH, CHAINLINK_ETH_USD);
chainlink.setFeed(WBTC, CHAINLINK_BTC_USD);
chainlink.setFeed(USDC, CHAINLINK_USDC_USD);

// 3. Set oracles in registry
registry.setOracle(WETH, chainlink);
registry.setOracle(WBTC, chainlink);
registry.setOracle(USDC, chainlink);

// 4. Set registry in factory
fluxVaultFactory.setOracleRegistry(registry);

// Now all vaults use this registry

Adding New Assets

// Developer deploys wrapper for new asset
address newAssetWrapper = assetWrapperFactory.deployERC20Wrapper(newAsset);

// Governance sets oracle for new asset
IPriceOracle oracle = getOrCreateOracle(newAsset);
oracleRegistry.setOracle(newAsset, oracle);

// Governance whitelists wrapper
fluxVaultFactory.whitelistAsset(newAssetWrapper);

// Now vaults can use this asset

---

Best Practices

For Governance

1. Vet oracle sources: Only use proven, secure oracle feeds

2. Monitor staleness: Set reasonable staleness thresholds

3. Implement fallbacks: Have backup oracles where possible

4. Communicate changes: Announce oracle updates in advance

5. Test thoroughly: Test new oracle adapters on testnet first

For Vault Creators

1. Understand oracle risks: Know what oracles your allowed assets use

2. Conservative parameters: Account for oracle volatility in liquidation buffers

3. Monitor prices: Watch for unusual price movements

4. Diversify sources: Prefer assets with multiple oracle options

5. Emergency plans: Have plan for oracle failures

For Managers

1. Trust the oracle: Position health based on oracle prices, not market prices

2. Account for lag: Oracle prices may lag market prices

3. Maintain buffer: Don't rely on exact oracle prices staying stable

4. Monitor feeds: Watch for staleness or manipulation

5. Diversify assets: Don't concentrate in assets with weak oracles

---

Comparison with Other Protocols

Feature	Flux Oracle Registry	Morpho Oracle	Aave Oracle
Architecture	Centralized registry	Per-market oracle	Centralized registry
Governance	Factory owner	Per-market (immutable)	Aave governance
Oracle Types	Multi-source adapters	Any IOracle implementation	Primarily Chainlink
Upgradeability	✓ Governance can update	✗ Immutable per market	✓ Governance can update
Shared Pricing	✓ All vaults use same registry	✗ Each market independent	✓ All pools use same oracle
Wrapper Integration	✓ Wrappers query registry	N/A	N/A

---

Advanced Topics

Custom Oracle Adapters

You can develop custom oracle adapters:

contract MyCustomOracle is IPriceOracle {
    function getPrice(address asset) external view returns (uint256) {
        // Custom price logic
        // - Combine multiple sources
        // - Apply custom transformations
        // - Implement fallback logic

        return calculatedPrice;  // Must be 18 decimals USD
    }
}

Requirements:

• Implement IPriceOracle.getPrice()

• Return 18-decimal USD price

• Handle edge cases (asset not supported, feed failure, etc.)

• Gas efficient (called frequently)

• Security audited

Multi-Hop Oracles

For assets without direct USD feeds:

// Example: Get USDC price for SHIB/USDC pool LP token
function getPrice(address lpToken) external view returns (uint256) {
    // 1. Get reserves from pool
    (uint256 shibReserve, uint256 usdcReserve) = getReserves(lpToken);

    // 2. Get SHIB price in USDC from pool
    uint256 shibPriceInUsdc = (usdcReserve * 1e18) / shibReserve;

    // 3. Get USDC price in USD from oracle
    uint256 usdcPriceUSD = oracleRegistry.getPriceUSD(USDC);

    // 4. Calculate SHIB price in USD
    uint256 shibPriceUSD = (shibPriceInUsdc * usdcPriceUSD) / 1e18;

    // 5. Calculate LP token price
    uint256 totalShibValueUSD = (shibReserve * shibPriceUSD) / 1e18;
    uint256 totalUsdcValueUSD = (usdcReserve * usdcPriceUSD) / 1e6;
    uint256 totalLiquidity = totalShibValueUSD + totalUsdcValueUSD;
    uint256 totalSupply = IERC20(lpToken).totalSupply();

    return (totalLiquidity * 1e18) / totalSupply;
}