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

Vet oracle sources: Only use proven, secure oracle feeds
Monitor staleness: Set reasonable staleness thresholds
Implement fallbacks: Have backup oracles where possible
Communicate changes: Announce oracle updates in advance
Test thoroughly: Test new oracle adapters on testnet first

For Vault Creators

Understand oracle risks: Know what oracles your allowed assets use
Conservative parameters: Account for oracle volatility in liquidation buffers
Monitor prices: Watch for unusual price movements
Diversify sources: Prefer assets with multiple oracle options
Emergency plans: Have plan for oracle failures

For Managers

Trust the oracle: Position health based on oracle prices, not market prices
Account for lag: Oracle prices may lag market prices
Maintain buffer: Don't rely on exact oracle prices staying stable
Monitor feeds: Watch for staleness or manipulation
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

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;
}

PreviousStrategies NextLiquidation

Last updated 1 month ago

hashtagWhat is the Oracle Registry?

hashtagWhy Centralized Oracle Management?

hashtagConsistent Pricing

hashtagUpgradeable Feeds

hashtagSimplified Wrapper Logic

hashtagGovernance Control

hashtagThe IOracleRegistry Interface

hashtagHow It Works

hashtagPrice Query Flow

hashtagCode Example

hashtagOracle Adapters

hashtagSupported Oracle Types

hashtagManaging the Oracle Registry

hashtagSetting Oracle Adapters (Governance)

hashtagUpdating Oracle Feeds

hashtagQuerying Oracle Status

hashtagDecimal Handling

hashtagAsset Decimals → 18 Decimals USD

hashtagOracle Security Considerations

hashtag1. Price Manipulation

hashtag2. Stale Prices

hashtag3. Oracle Failure

hashtag4. Governance Control Risk

hashtagIntegration with Vaults

hashtagHealth Check Flow

hashtagLiquidation Flow

hashtagOracle Registry Deployment

hashtagInitial Setup

hashtagAdding New Assets

hashtagBest Practices

hashtagFor Governance

hashtagFor Vault Creators

hashtagFor Managers

hashtagComparison with Other Protocols

hashtagAdvanced Topics

hashtagCustom Oracle Adapters

hashtagMulti-Hop Oracles

What is the Oracle Registry?

Why Centralized Oracle Management?

Consistent Pricing

Upgradeable Feeds

Simplified Wrapper Logic

Governance Control

The IOracleRegistry Interface

How It Works

Price Query Flow

Code Example

Oracle Adapters

Supported Oracle Types

Managing the Oracle Registry

Setting Oracle Adapters (Governance)

Updating Oracle Feeds

Querying Oracle Status

Decimal Handling

Asset Decimals → 18 Decimals USD

Oracle Security Considerations

1. Price Manipulation

2. Stale Prices

3. Oracle Failure

4. Governance Control Risk

Integration with Vaults

Health Check Flow

Liquidation Flow

Oracle Registry Deployment

Initial Setup

Adding New Assets

Best Practices

For Governance

For Vault Creators

For Managers

Comparison with Other Protocols

Advanced Topics

Custom Oracle Adapters

Multi-Hop Oracles