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
| Feed | Asset | Composition |
|---|---|---|
WETHPriceFeed | WETH | ETH/USD directly (WETH treated 1:1 with ETH). |
WSTETHPriceFeed | wstETH | stETH/USD (Chainlink) × wstETH canonical rate (stEthPerToken), with ETH/USD used as the redemption comparison. |
RETHPriceFeed | rETH | ETH/USD × rETH/ETH market (Chainlink), compared with ETH/USD × rETH canonical rate (getExchangeRate). |
WEETHPriceFeed | weETH | ETH/USD × weETH/ETH market (Chainlink), compared with ETH/USD × weETH canonical rate (rate provider getRate). |
WBTCPriceFeed | WBTC | BTC/USD × WBTC/BTC (Chainlink), compared with BTC/USD (1:1). |
TBTCPriceFeed | tBTC | tBTC/USD (Chainlink), compared with BTC/USD (1:1). |
PAXGPriceFeed | PAXG | PAXG/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, andWEETHPriceFeed. - BTC/USD backs the BTC derivatives:
WBTCPriceFeedandTBTCPriceFeed.
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 = trueand, in the same call, shuts the branch down throughBorrowerOperations.shutdownFromOracleFailure()(see Collateral shutdown).
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:
- Primary — the configured primary source (Chronicle for ETH/USD and BTC/USD; Chainlink for every other leg — see Collateral oracle addresses).
- 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-9toMAX_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. - Last good price — if no source is usable, the feed returns the last cached good price with
oracleFailure = trueand 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. ABaseUSDxCanonicalfeed 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).
| Feed | Market price | Reference price | Threshold |
|---|---|---|---|
RETHPriceFeed | ETH/USD × rETH/ETH | ETH/USD × canonical rate | RETH_ETH_DEVIATION_THRESHOLD = 2% |
WEETHPriceFeed | ETH/USD × weETH/ETH | ETH/USD × canonical rate | WEETH_ETH_DEVIATION_THRESHOLD = 2% |
WBTCPriceFeed | BTC/USD × WBTC/BTC | BTC/USD | WBTC_BTC_DEVIATION_THRESHOLD = 2% |
TBTCPriceFeed | tBTC/USD | BTC/USD | TBTC_USD_DEVIATION_THRESHOLD = 2% |
PAXGPriceFeed | PAXG/USD | XAU/USD | PAXG_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.
Key constants
| Constant | Value | Purpose |
|---|---|---|
TARGET_DIGITS | 18 | Output precision |
BASE_USD_DEVIATION_THRESHOLD | 2% | ETH/USD and BTC/USD primary-vs-fallback band for the redemption "higher" rule |
STETH_USD_DEVIATION_THRESHOLD | 1% | wstETH redemption band (stETH/USD vs ETH/USD) |
RETH_ETH_DEVIATION_THRESHOLD | 2% | rETH market vs canonical band |
WEETH_ETH_DEVIATION_THRESHOLD | 2% | weETH market vs canonical band |
WBTC_BTC_DEVIATION_THRESHOLD | 2% | WBTC vs BTC band |
TBTC_USD_DEVIATION_THRESHOLD | 2% | tBTC vs BTC band |
PAXG_XAU_DEVIATION_THRESHOLD | 3% | 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
| Failure | Affected component | Protocol response |
|---|---|---|
| Base primary stale, reverting or out of range | ETH/USD or BTC/USD pair | Switches to the fallback source for good; no shutdown |
| Base primary wildly off | ETH/USD or BTC/USD pair | Normal reads take the lower of the two providers; redemption reads only take the higher within 2% |
| Market price and reference diverge | rETH / weETH / WBTC / tBTC / PAXG feed | The lower price is used, except on redemptions within the threshold |
| Base pair fully fails, or any market leg / rate provider / reference fails | Each 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.