Oracle Integration

Integrate price oracles for asset valuation in Flux.

Overview

Flux Protocol uses a centralized Oracle Registry architecture to provide consistent USD valuations across all vaults. The registry maps assets to oracle adapters that implement the IPriceOracle interface, enabling standardized price queries for health calculations, liquidations, and position tracking.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        Vault Operations                          │
│                   (borrow, deposit, callback)                    │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Asset Wrappers                              │
│               (ERC20, ERC4626, LP Positions)                     │
│                                                                  │
│   getValue(vault, manager, positionId)                           │
│     └── registry.getValueUSD(asset, balance)                     │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Oracle Registry                              │
│                                                                  │
│   getValueUSD(asset, amount) → USD value (18 decimals)           │
│   getPriceUSD(asset) → price per unit (18 decimals)              │
│   getOracle(asset) → IPriceOracle adapter                        │
└──────────────────────────┬──────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Oracle Adapters                               │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐    │
│  │ Chainlink│ │ Uniswap  │ │  Fixed   │ │ Exchange Rate    │    │
│  │ Adapter  │ │ V3 TWAP  │ │  Price   │ │ Adapter          │    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

---

Core Interfaces

IOracleRegistry

The Oracle Registry is the central hub for all price queries:

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

    /// @notice Get the price of an asset in USD
    /// @param asset The token address
    /// @return priceUSD Price per unit (18 decimals)
    function getPriceUSD(address asset) 
        external view returns (uint256 priceUSD);

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

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

IPriceOracle

All oracle adapters must implement this interface:

interface IPriceOracle {
    /// @notice Get the price of an asset in USD
    /// @param asset The token address to price
    /// @return price Price in USD with 18 decimals
    function getPrice(address asset) external view returns (uint256 price);
}

---

Oracle Adapter Types

1. Chainlink Oracle Adapter

Best For: Major assets with established Chainlink price feeds (WETH, WBTC, USDC, DAI)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IPriceOracle} from "./interfaces/IPriceOracle.sol";
import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/interfaces/AggregatorV3Interface.sol";

contract ChainlinkOracleAdapter is IPriceOracle {
    /// @notice Maps asset addresses to Chainlink price feed addresses
    mapping(address => address) public priceFeeds;
    
    /// @notice Maximum allowed staleness for price data (e.g., 1 hour)
    uint256 public constant MAX_STALENESS = 3600;
    
    /// @notice Owner for feed configuration
    address public owner;

    error StalePrice();
    error InvalidPrice();
    error FeedNotConfigured();

    constructor(address _owner) {
        owner = _owner;
    }

    /// @notice Configure a price feed for an asset
    /// @param asset The token address
    /// @param feed The Chainlink AggregatorV3 address
    function setFeed(address asset, address feed) external {
        require(msg.sender == owner, "Unauthorized");
        priceFeeds[asset] = feed;
    }

    /// @notice Get asset price from Chainlink
    /// @param asset The token to price
    /// @return price USD price with 18 decimals
    function getPrice(address asset) external view override returns (uint256 price) {
        address feed = priceFeeds[asset];
        if (feed == address(0)) revert FeedNotConfigured();

        (
            uint80 roundId,
            int256 answer,
            ,
            uint256 updatedAt,
            uint80 answeredInRound
        ) = AggregatorV3Interface(feed).latestRoundData();

        // Validate price data
        if (answer <= 0) revert InvalidPrice();
        if (block.timestamp - updatedAt > MAX_STALENESS) revert StalePrice();
        if (answeredInRound < roundId) revert StalePrice();

        // Chainlink returns 8 decimals, scale to 18
        price = uint256(answer) * 1e10;
    }
}

Configuration Example:

ChainlinkOracleAdapter chainlink = new ChainlinkOracleAdapter(governance);

// Mainnet Chainlink feed addresses
chainlink.setFeed(WETH, 0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419);  // ETH/USD
chainlink.setFeed(WBTC, 0xF4030086522a5bEEa4988F8cA5B36dbC97BeE88c);  // BTC/USD
chainlink.setFeed(USDC, 0x8fFfFfd4AfB6115b954Bd326cbe7B4BA576818f6);  // USDC/USD
chainlink.setFeed(DAI,  0xAed0c38402a5d19df6E4c03F4E2DceD6e29c1ee9);  // DAI/USD

---

2. Uniswap V3 TWAP Oracle

Best For: Long-tail assets without Chainlink feeds but with sufficient Uniswap V3 liquidity

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IPriceOracle} from "./interfaces/IPriceOracle.sol";
import {IUniswapV3Pool} from "@uniswap/v3-core/contracts/interfaces/IUniswapV3Pool.sol";
import {OracleLibrary} from "@uniswap/v3-periphery/contracts/libraries/OracleLibrary.sol";

contract UniswapV3TWAPOracle is IPriceOracle {
    /// @notice TWAP observation period (e.g., 30 minutes)
    uint32 public constant TWAP_PERIOD = 1800;
    
    /// @notice Pool configurations for each asset
    struct PoolConfig {
        address pool;           // Uniswap V3 pool address
        address quoteToken;     // Quote token (e.g., USDC, WETH)
        bool isToken0;          // Whether the asset is token0 in the pool
    }
    
    mapping(address => PoolConfig) public poolConfigs;
    
    /// @notice Reference to registry for quote token pricing
    IOracleRegistry public immutable registry;

    constructor(IOracleRegistry _registry) {
        registry = _registry;
    }

    /// @notice Configure a pool for an asset
    function setPool(
        address asset, 
        address pool, 
        address quoteToken,
        bool isToken0
    ) external {
        // Add access control in production
        poolConfigs[asset] = PoolConfig({
            pool: pool,
            quoteToken: quoteToken,
            isToken0: isToken0
        });
    }

    /// @notice Get TWAP price for an asset
    function getPrice(address asset) external view override returns (uint256 price) {
        PoolConfig memory config = poolConfigs[asset];
        require(config.pool != address(0), "Pool not configured");

        // Get TWAP tick
        (int24 arithmeticMeanTick, ) = OracleLibrary.consult(
            config.pool, 
            TWAP_PERIOD
        );

        // Convert tick to price ratio
        uint256 quoteAmount = OracleLibrary.getQuoteAtTick(
            arithmeticMeanTick,
            1e18,  // 1 unit of base token
            asset,
            config.quoteToken
        );

        // Convert quote token amount to USD
        // If quote is USDC (6 decimals), scale to 18 decimals
        // If quote is WETH, get WETH/USD price from registry
        if (config.quoteToken == USDC) {
            price = quoteAmount * 1e12;  // 6 decimals → 18 decimals
        } else {
            // Get quote token price and calculate USD value
            uint256 quotePriceUSD = registry.getPriceUSD(config.quoteToken);
            price = (quoteAmount * quotePriceUSD) / 1e18;
        }
    }
}

Security Considerations:

• Use minimum 30-minute TWAP to resist manipulation

• Ensure pool has sufficient liquidity (>$1M TVL recommended)

• Monitor for liquidity withdrawal attacks

---

3. Fixed Price Oracle

Best For: Stablecoins pegged to $1 USD (USDC, USDT, DAI)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IPriceOracle} from "./interfaces/IPriceOracle.sol";

contract FixedPriceOracle is IPriceOracle {
    /// @notice Fixed USD price (18 decimals)
    uint256 public immutable FIXED_PRICE;

    /// @param _price Fixed price in USD with 18 decimals
    constructor(uint256 _price) {
        FIXED_PRICE = _price;
    }

    /// @notice Returns fixed price regardless of asset
    function getPrice(address) external view override returns (uint256) {
        return FIXED_PRICE;
    }
}

// Deployment for $1 stablecoin
FixedPriceOracle stablecoinOracle = new FixedPriceOracle(1e18);

When to Use:

• Highly trusted stablecoins with strong peg guarantees

• Reduces oracle costs and complexity

• Warning: Does not capture depeg events

---

4. Exchange Rate Oracle

Best For: Wrapped/rebasing tokens (wstETH, rETH, cbETH, stETH)

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IPriceOracle} from "./interfaces/IPriceOracle.sol";

interface IWstETH {
    function stEthPerToken() external view returns (uint256);
}

contract WstETHOracle is IPriceOracle {
    IWstETH public immutable wstETH;
    IOracleRegistry public immutable registry;
    address public immutable STETH;

    constructor(address _wstETH, address _stETH, IOracleRegistry _registry) {
        wstETH = IWstETH(_wstETH);
        STETH = _stETH;
        registry = _registry;
    }

    /// @notice Get wstETH price = stETH/wstETH ratio × stETH price
    function getPrice(address) external view override returns (uint256) {
        // 1 wstETH = X stETH
        uint256 stEthPerWstEth = wstETH.stEthPerToken();
        
        // Get stETH/USD price (assumes stETH oracle is configured)
        uint256 stEthPriceUSD = registry.getPriceUSD(STETH);
        
        // wstETH price = stETH per wstETH × stETH price
        return (stEthPerWstEth * stEthPriceUSD) / 1e18;
    }
}

---

5. Composite Oracle with Fallback

Best For: Critical assets requiring high availability

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IPriceOracle} from "./interfaces/IPriceOracle.sol";

contract CompositeOracle is IPriceOracle {
    IPriceOracle public immutable primaryOracle;
    IPriceOracle public immutable fallbackOracle;
    
    /// @notice Maximum deviation allowed between oracles (e.g., 5%)
    uint256 public constant MAX_DEVIATION = 0.05e18;

    constructor(IPriceOracle _primary, IPriceOracle _fallback) {
        primaryOracle = _primary;
        fallbackOracle = _fallback;
    }

    function getPrice(address asset) external view override returns (uint256) {
        // Try primary oracle first
        try primaryOracle.getPrice(asset) returns (uint256 primaryPrice) {
            // Validate against fallback
            try fallbackOracle.getPrice(asset) returns (uint256 fallbackPrice) {
                // Check deviation
                uint256 deviation = _calculateDeviation(primaryPrice, fallbackPrice);
                require(deviation <= MAX_DEVIATION, "Price deviation too high");
            } catch {
                // Fallback unavailable, use primary
            }
            return primaryPrice;
        } catch {
            // Primary failed, use fallback
            return fallbackOracle.getPrice(asset);
        }
    }

    function _calculateDeviation(uint256 a, uint256 b) internal pure returns (uint256) {
        if (a > b) {
            return ((a - b) * 1e18) / a;
        }
        return ((b - a) * 1e18) / b;
    }
}

---

Integrating Oracles with Asset Wrappers

Asset wrappers query the Oracle Registry to determine position values:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;

import {IAsset} from "./interfaces/IAsset.sol";
import {IOracleRegistry} from "./interfaces/IOracleRegistry.sol";
import {IFluxFactory} from "./interfaces/IFluxFactory.sol";
import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";

contract ERC20AssetWrapper is IAsset {
    /// @notice The underlying ERC20 token
    address public immutable underlyingAsset;
    
    /// @notice Reference to factory (provides oracle registry)
    IFluxFactory public immutable factory;
    
    /// @notice Position balances: account => subaccount => positionId => balance
    mapping(address => mapping(address => mapping(bytes32 => uint256))) public balances;

    constructor(address _asset, IFluxFactory _factory) {
        underlyingAsset = _asset;
        factory = _factory;
    }

    /// @notice Get the USD value of a position
    /// @param account The vault address
    /// @param subaccount The manager address
    /// @param positionId The position identifier
    /// @return value USD value with 18 decimals
    function getValue(
        address account,
        address subaccount,
        bytes32 positionId
    ) external view override returns (uint256 value) {
        uint256 balance = balances[account][subaccount][positionId];
        if (balance == 0) return 0;
        
        // Get oracle registry from factory
        IOracleRegistry registry = factory.oracleRegistry();
        
        // Query USD value (registry handles decimal conversion)
        return registry.getValueUSD(underlyingAsset, balance);
    }

    /// @notice Get raw token balance (in asset's native decimals)
    function getBalance(
        address account,
        address subaccount,
        bytes32 positionId
    ) external view override returns (uint256) {
        return balances[account][subaccount][positionId];
    }

    /// @notice Deposit tokens into a position
    function deposit(
        address account,
        address subaccount,
        bytes32 positionId,
        uint256 amount
    ) external override {
        IERC20(underlyingAsset).transferFrom(msg.sender, address(this), amount);
        balances[account][subaccount][positionId] += amount;
    }

    /// @notice Withdraw tokens from a position
    function withdraw(
        address account,
        address subaccount,
        bytes32 positionId,
        address recipient,
        uint256 amount
    ) external override {
        balances[account][subaccount][positionId] -= amount;
        IERC20(underlyingAsset).transfer(recipient, amount);
    }
}

---

Decimal Handling

The Oracle Registry automatically normalizes all values to 18 decimals:

/// @notice Calculate USD value with proper decimal handling
function getValueUSD(address asset, uint256 amount) 
    external view returns (uint256 valueUSD) 
{
    IPriceOracle oracle = oracles[asset];
    uint256 priceUSD = oracle.getPrice(asset);  // 18 decimals
    
    uint8 assetDecimals = IERC20Metadata(asset).decimals();
    
    // value = amount × price / 10^decimals
    valueUSD = (amount * priceUSD) / (10 ** assetDecimals);
}

Examples:

Asset	Balance	Price	Calculation	USD Value
USDC (6 dec)	1_000_000e6	1e18	1_000_000e6 × 1e18 / 1e6	1_000_000e18
WETH (18 dec)	10e18	3000e18	10e18 × 3000e18 / 1e18	30_000e18
WBTC (8 dec)	1e8	60_000e18	1e8 × 60_000e18 / 1e8	60_000e18

---

Health Ratio Calculation Flow

Oracle prices drive health and liquidation calculations:

┌─────────────────────────────────────────────────────────────┐
│                   Manager Position                           │
│                                                              │
│   Bond:              20,000 USDC                             │
│   Working Capital:   10,000 USDC                             │
│   WETH Position:     10 WETH @ $3,000 = $30,000             │
│   ─────────────────────────────────────────────             │
│   Total Value:       $60,000                                 │
│                                                              │
│   Principal Debt:    $45,000                                 │
│   Accrued Interest:  $5,000                                  │
│   ─────────────────────────────────────────────             │
│   True Debt:         $50,000                                 │
│                                                              │
│   Health Ratio:      $60,000 / $50,000 = 1.20 (120%)        │
│                                                              │
│   Liquidation Threshold: 1.10 (110%)                         │
│   Status: HEALTHY ✓                                          │
└─────────────────────────────────────────────────────────────┘

Liquidation Threshold Formula:

liquidationThreshold = 1e18 + minBondRatio - liquidationBuffer

Example:
  minBondRatio = 0.20e18 (20%)
  liquidationBuffer = 0.10e18 (10%)
  liquidationThreshold = 1e18 + 0.20e18 - 0.10e18 = 1.10e18 (110%)

---

Deploying the Oracle System

Step 1: Deploy Oracle Registry

// Deploy registry with governance address
FluxOracleRegistry registry = new FluxOracleRegistry(governanceMultisig);

Step 2: Deploy Oracle Adapters

// Chainlink adapter for major assets
ChainlinkOracleAdapter chainlinkAdapter = new ChainlinkOracleAdapter(governanceMultisig);
chainlinkAdapter.setFeed(WETH, CHAINLINK_ETH_USD_FEED);
chainlinkAdapter.setFeed(WBTC, CHAINLINK_BTC_USD_FEED);

// Fixed price for stablecoins
FixedPriceOracle stablecoinOracle = new FixedPriceOracle(1e18);

// TWAP for long-tail assets
UniswapV3TWAPOracle twapOracle = new UniswapV3TWAPOracle(registry);
twapOracle.setPool(LONG_TAIL_TOKEN, UNISWAP_POOL, USDC, true);

// Exchange rate for LSTs
WstETHOracle wstEthOracle = new WstETHOracle(WSTETH, STETH, registry);

Step 3: Register Oracles in Registry

// Register all oracles
registry.setOracle(WETH, chainlinkAdapter);
registry.setOracle(WBTC, chainlinkAdapter);
registry.setOracle(USDC, stablecoinOracle);
registry.setOracle(DAI, stablecoinOracle);
registry.setOracle(LONG_TAIL_TOKEN, twapOracle);
registry.setOracle(WSTETH, wstEthOracle);

Step 4: Connect Registry to Factory

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

---

Security Best Practices

1. Staleness Checks

Always validate price freshness:

function getPrice(address asset) external view returns (uint256) {
    (, int256 price,, uint256 updatedAt,) = feed.latestRoundData();
    
    // Reject stale prices
    if (block.timestamp - updatedAt > MAX_STALENESS) {
        revert StalePrice();
    }
    
    return uint256(price) * 1e10;
}

2. Price Deviation Monitoring

Detect potential manipulation:

uint256 previousPrice = lastPrices[asset];
uint256 currentPrice = oracle.getPrice(asset);

uint256 deviation = _calculateDeviation(previousPrice, currentPrice);
if (deviation > MAX_ALLOWED_DEVIATION) {
    emit PriceDeviationAlert(asset, previousPrice, currentPrice);
    // Consider pausing or using fallback
}

3. Multi-Oracle Validation

Use multiple sources for critical assets:

uint256 chainlinkPrice = chainlinkOracle.getPrice(asset);
uint256 twapPrice = twapOracle.getPrice(asset);

require(
    _calculateDeviation(chainlinkPrice, twapPrice) <= MAX_DEVIATION,
    "Oracle prices diverged"
);

return chainlinkPrice;  // Prefer Chainlink if both agree

4. Circuit Breakers

Implement emergency pause functionality:

mapping(address => bool) public pausedAssets;

function getPrice(address asset) external view returns (uint256) {
    require(!pausedAssets[asset], "Oracle paused");
    // ... price logic
}

function pauseOracle(address asset) external onlyGovernance {
    pausedAssets[asset] = true;
    emit OraclePaused(asset);
}

---

Oracle Selection Guidelines

Asset Type	Recommended Oracle	Rationale
Major tokens (ETH, BTC)	Chainlink	Decentralized, manipulation-resistant
Stablecoins (USDC, DAI)	Fixed Price or Chainlink	Low volatility, simple
LSTs (wstETH, rETH)	Exchange Rate + Base Oracle	Accurate intrinsic value
Long-tail ERC20	Uniswap V3 TWAP (30min+)	Manipulation-resistant
LP Tokens	Custom (component pricing)	Sum of underlying values
NFTs/ERC721	Floor price oracles	Specialized providers

---

Testing Oracle Integrations

// Test oracle returns expected price
function test_GetPrice_WETH() public {
    uint256 price = registry.getPriceUSD(WETH);
    
    // Price should be reasonable (between $1000 and $10000)
    assertGt(price, 1000e18);
    assertLt(price, 10000e18);
}

// Test value calculation with decimals
function test_GetValueUSD_USDC() public {
    uint256 amount = 1_000_000e6;  // 1M USDC
    uint256 value = registry.getValueUSD(USDC, amount);
    
    // Should be ~$1M
    assertApproxEqRel(value, 1_000_000e18, 0.01e18);  // 1% tolerance
}

// Test staleness protection
function test_RevertWhen_PriceStale() public {
    // Warp time forward past staleness threshold
    vm.warp(block.timestamp + MAX_STALENESS + 1);
    
    vm.expectRevert(StalePrice.selector);
    registry.getPriceUSD(WETH);
}

// Test fallback behavior
function test_Fallback_WhenPrimaryFails() public {
    // Make primary oracle fail
    vm.mockCallRevert(
        address(primaryOracle),
        abi.encodeCall(IPriceOracle.getPrice, (WETH)),
        "Failed"
    );
    
    // Should use fallback
    uint256 price = compositeOracle.getPrice(WETH);
    assertGt(price, 0);
}