Skip to main content

Collateral oracles

Every collateral branch prices its collateral in USD through its own PriceFeed — used for liquidations, redemptions, and ICR/TCR. The ETH/USD and BTC/USD base prices are dual-source (a Chronicle primary with a Chainlink fallback). Derivatives (LSTs, WBTC, tBTC, PAXG) add composite logic that compares a market price against a reference, and every feed has a fallback state machine that ends at a last-good price and a branch shutdown on failure.

This page is the mechanism. The per-branch feed addresses are in Collateral oracle addresses; the risk parameters are in Collateral parameters. The RD market price — a different oracle for a different job — is the RD Market Oracle.

PriceFeed stack​

Each collateral branch has its own price feed. The base contract is PriceFeedBase (Solidity 0.8.24); derivative feeds extend CompositePriceFeedBase, and concrete feeds extend those for the specific collateral.

Concrete feeds​

FeedAssetComposition
WETHPriceFeedWETHETH/USD directly (WETH treated 1:1 with ETH).
WSTETHPriceFeedwstETHstETH/USD (Chainlink) × wstETH canonical rate (stEthPerToken), with ETH/USD used as the redemption comparison.
RETHPriceFeedrETHETH/USD × rETH/ETH market (Chainlink), compared with ETH/USD × rETH canonical rate (getExchangeRate).
WEETHPriceFeedweETHETH/USD × weETH/ETH market (Chainlink), compared with ETH/USD × weETH canonical rate (rate provider getRate).
WBTCPriceFeedWBTCBTC/USD × WBTC/BTC (Chainlink), compared with BTC/USD (1:1).
TBTCPriceFeedtBTCtBTC/USD (Chainlink), compared with BTC/USD (1:1).
PAXGPriceFeedPAXGPAXG/USD (Chainlink), compared with XAU/USD (Chainlink).

WBTC has 8 decimals, so WBTCPriceFeed scales its 18-decimal USD price up by WBTC_PRICE_SCALE_FACTOR = 1e10 for branch math.

Full source addresses per feed: Collateral oracle addresses.

Base feeds: ETH/USD and BTC/USD​

Most branches don't price their collateral against USD directly — they build on a shared base feed. Two do the heavy lifting:

  • ETH/USD backs every ETH derivative: WSTETHPriceFeed, RETHPriceFeed, and WEETHPriceFeed.
  • BTC/USD backs the BTC derivatives: WBTCPriceFeed and TBTCPriceFeed.

Because so many collaterals share them, a fault in one base feed doesn't stay local — it moves every derivative built on it. To keep that foundation honest, each base feed is backed by two independent oracle providers, Chronicle (primary) and Chainlink (fallback), resolved on every fetchPrice:

  • Both healthy → combined. A normal (liquidation / ICR) read takes the lower of the two — the conservative value. A redemption read takes the higher, but only when the two agree within BASE_USD_DEVIATION_THRESHOLD = 2%; if they diverge by more, it drops back to the lower. This gives redeemers a fair price when the providers agree while resisting upward manipulation when they don't.
  • Primary unusable → failover. If Chronicle is stale (beyond its configured staleness window), reverts, or returns an invalid value, the pair switches to serving Chainlink alone. The switch is permanent: the pair does not go back to the primary.
  • Both unusable → last good + shutdown. If neither provider is usable, the feed returns the last cached good price with oracleFailure = true and, in the same call, shuts the branch down through BorrowerOperations.shutdownFromOracleFailure() (see Collateral shutdown).
ChronicleprimaryChainlinkfallbackcombinelower; redemption: higherif within 2%base priceETH/USD · BTC/USDderivativesLSTs, WBTC, tBTCper fetchPrice:both healthy → combineprimary down → fallbackboth down → last-good + shutdown
The ETH/USD and BTC/USD base feeds are each backed by two independent providers — Chronicle (primary) and Chainlink (fallback). While both are healthy, normal reads take the lower of the two and redemption reads take the higher when they agree within BASE_USD_DEVIATION_THRESHOLD = 2%. If the primary goes stale, reverts or returns an invalid value, the pair switches to the fallback alone for good; if both fail, the feed returns the last-good price and shuts the branch down in the same call. Every ETH/BTC derivative builds on one of these base prices.

Primary → fallback → last good​

Each oracle pair carries a status (OracleStatus: Primary, Fallback, Shutdown) and a cached last good price, and fetchPrice advances it as sources fail:

  1. Primary — the configured primary source (Chronicle for ETH/USD and BTC/USD; Chainlink for every other leg — see Collateral oracle addresses).
  2. Fallback — the configured fallback source (Chainlink for ETH/USD and BTC/USD), used once the primary is stale, reverts, or returns a value outside the accepted range (MIN_ORACLE_VALUE = 1e-9 to MAX_ORACLE_VALUE = 1e8, 18-decimal units). For the stETH/USD, rETH/ETH and weETH/ETH pairs the mainnet configuration uses the same Chainlink feed as primary and fallback, so in practice they have a single source. The WBTC/BTC and tBTC/USD market oracles and the XAU/USD reference are single oracles, and the PAXG/USD pair treats a primary failure as a shutdown.
  3. Last good price — if no source is usable, the feed returns the last cached good price with oracleFailure = true and shuts the branch down.

Staleness windows are set per oracle in the deployment: 90,000 s (25 h) for ETH/USD, BTC/USD (both providers) and stETH/USD; 100,800 s (28 h) for rETH/ETH, weETH/ETH, WBTC/BTC, tBTC/USD, PAXG/USD and XAU/USD.

For derivative feeds, the branch shuts down if any input fails — the base pair, the market leg, or the canonical-rate provider. CompositePriceFeedBase then tracks where the price comes from (CompositePriceSource):

  • Market leg failed (stETH/USD, rETH/ETH, weETH/ETH, WBTC/BTC, tBTC/USD) → BaseUSDxCanonical: base price × canonical rate (1:1 for WBTC and tBTC), never above the last good composite price.
  • Base pair or rate provider failed (and PAXG/USD or XAU/USD for PAXG) → LastGoodCompositePrice: the price is frozen at the last good composite price. A BaseUSDxCanonical feed also drops to this if its base pair or rate provider later fails.

Shutdown is permissionless to trigger: any call that fetches the price detects the failure, and anyone can call BorrowerOperations.shutdown(), which does that fetch.

Combine rule for derivatives​

Derivative feeds compare a market price with a reference price using the same rule as the base pair (_combineRedemptionPrice): a redemption read within the feed's threshold takes the higher of the two (mitigating redemption arbitrage on a slightly low price); every other read, and any redemption where they diverge further, takes the lower (resisting upward manipulation).

FeedMarket priceReference priceThreshold
RETHPriceFeedETH/USD × rETH/ETHETH/USD × canonical rateRETH_ETH_DEVIATION_THRESHOLD = 2%
WEETHPriceFeedETH/USD × weETH/ETHETH/USD × canonical rateWEETH_ETH_DEVIATION_THRESHOLD = 2%
WBTCPriceFeedBTC/USD × WBTC/BTCBTC/USDWBTC_BTC_DEVIATION_THRESHOLD = 2%
TBTCPriceFeedtBTC/USDBTC/USDTBTC_USD_DEVIATION_THRESHOLD = 2%
PAXGPriceFeedPAXG/USDXAU/USDPAXG_XAU_DEVIATION_THRESHOLD = 3%

WSTETHPriceFeed is the exception: its price is stETH/USD × canonical rate. On a redemption, if stETH/USD and ETH/USD agree within STETH_USD_DEVIATION_THRESHOLD = 1%, it uses the higher of the two before applying the canonical rate; otherwise (and on every normal read) it uses stETH/USD.

redemption · sources agreeused (higher)marketreferenceΔ 0.5%thr✓ within thresholdtake the higher of the twodiverged, or not a redemptionused (lower)marketreferenceΔ 2.6%thr✕ beyond threshold / normal readtake the lower of the two
Derivative feeds compare two prices — a market feed and a reference (base × canonical rate for rETH and weETH, BTC/USD for WBTC and tBTC, XAU/USD for PAXG). On a redemption read where they agree within the threshold (2%; 3% for PAXG) the feed takes the higher, so redeemers can't profit from a slightly low price. Every other read, and any redemption where they diverge further, takes the lower, so a manipulated high price is never used. wstETH follows the same idea with a 1% band (see text).

Key constants​

ConstantValuePurpose
TARGET_DIGITS18Output precision
BASE_USD_DEVIATION_THRESHOLD2%ETH/USD and BTC/USD primary-vs-fallback band for the redemption "higher" rule
STETH_USD_DEVIATION_THRESHOLD1%wstETH redemption band (stETH/USD vs ETH/USD)
RETH_ETH_DEVIATION_THRESHOLD2%rETH market vs canonical band
WEETH_ETH_DEVIATION_THRESHOLD2%weETH market vs canonical band
WBTC_BTC_DEVIATION_THRESHOLD2%WBTC vs BTC band
TBTC_USD_DEVIATION_THRESHOLD2%tBTC vs BTC band
PAXG_XAU_DEVIATION_THRESHOLD3%PAXG vs XAU band

Read interface​

fetchPrice(bool _isRedemption) returns (uint256 price, bool oracleFailure)
fetchRedemptionPrice() returns (uint256 price, bool oracleFailure)
viewLatestPrice(bool _isRedemption) returns (uint256) // view-only
viewRedemptionPrice() returns (uint256) // view-only
previewWillShutdown(bool _isRedemption) returns (bool)
isShutdown() returns (bool)

fetchPrice is mutating — it resolves primary→fallback, updates the last-good price, and shuts the branch down if the feed fails. View-only callers (off-chain dashboards, helper contracts) use viewLatestPrice. The _isRedemption flag selects the redemption combine rule described above. previewWillShutdown reports whether the next fetchPrice would shut the branch down.

Failure modes​

FailureAffected componentProtocol response
Base primary stale, reverting or out of rangeETH/USD or BTC/USD pairSwitches to the fallback source for good; no shutdown
Base primary wildly offETH/USD or BTC/USD pairNormal reads take the lower of the two providers; redemption reads only take the higher within 2%
Market price and reference divergerETH / weETH / WBTC / tBTC / PAXG feedThe lower price is used, except on redemptions within the threshold
Base pair fully fails, or any market leg / rate provider / reference failsEach branch whose feed uses it (on its next price fetch)Branch shutdown via shutdownFromOracleFailure() in the same call; the feed serves base × canonical rate or the frozen last good price; redemption proceeds on the shutdown discount schedule

The protocol prefers degraded operation over false confidence: if a branch's collateral price isn't trustworthy, the branch is wound down via redemption rather than continuing on bad data.