RD Market Oracle
The MarketOracleAggregator is a single, protocol-wide oracle that measures two things about RD's market: its price (an RD/USD TWAP) and the depth of its market (TWALs — time-weighted average liquidity). It is the shared input for two controllers:
- The system rate controller (
RateParControl) reads the RD price to steerrateandparback toward the peg. - The GlobalFeeRouter reads the pool liquidity to measure LP utilization and steer the LP share of protocol fees.
The measurements are taken inside the RD market pools themselves: each pool's Uniswap v4 hook records an observation whenever its reserves change, so the oracle is refreshed by trading rather than by a keeper poke. For collateral pricing — a separate oracle for a separate job — see Collateral oracles.
The RD market pools
The protocol's RD market is two Uniswap v4 pools, RD/USDC and RD/USDT (V4_MARKET_POOL_COUNT = 2). Together they are the source of truth for both signals, and they are where LP staking earns rewards (see LP staking).
- Pricing. Each pool is run by its own
RdStableSwapHook, which prices every swap itself on a two-token StableSwap curve (amplification 320) concentrated around $1, and keeps a 1 basis point fee on the swap input for LPs. The pool's native Uniswap fee is zero. - LP shares. Liquidity is added and removed through the hook (
addLiquidity,removeLiquidity), which mints and burns a fungible ERC-20 LP share; native Uniswap v4 positions are rejected. Addresses on Deployed addresses. - Price the protocol uses. The mean of the qualifying pools' 24-hour TWAPs, read only from windows that end at least 60 s in the past (see below), not the spot price at any single block.
- Liquidity the protocol watches. Parallel 24-hour and 4-hour liquidity TWALs, used to qualify pools for the price, to scale the controller's authority, and to drive LP utilization.
RdStableSwapHook (a StableSwap curve concentrated around $1), which also records that pool's price and liquidity. MarketOracleAggregator combines the two: the price goes to RateParControl, the liquidity to GlobalFeeRouter.Per-pool observations
Each RdStableSwapHook extends V4PoolOracle, which keeps one Uniswap-V3-style observation ring (up to 8,192 slots) holding both price and liquidity.
What is recorded
Every reserve change — a swap, the initial seed, an LP deposit or withdrawal, or a checkpoint from the aggregator — commits the new reserves and writes an observation:
- Price: the StableSwap spot price of RD in the pool's stablecoin, stored as a tick and clamped to [0.75, 1.25] (
MIN_RECORDED_PRICE_WAD,MAX_RECORDED_PRICE_WAD). A price outside the band is recorded at the band edge, not rejected. - Liquidity: half of the StableSwap invariant, i.e. the per-side balanced-equivalent depth in 18-decimal RD-at-peg units, with a floor of 10,000 (
MIN_RECORDED_RD_LIQUIDITY). Liquidity TWALs are harmonic means, so brief spikes in depth count for little.
Finalized windows
oracleResult() reads three windows that all end MIN_OBSERVATION_AGE = 60 seconds before the current block: a 24-hour price TWAP and 24-hour liquidity TWAL (the deployment's quotePeriod = 86,400 s), and a 4-hour liquidity TWAL (SHORT_LIQUIDITY_TWAL_PERIOD). This blocks same-block manipulation: a flash-loaner moving the pool price in the same block as the read can't reach the reading. A window counts as available only if the ring's history covers it.
Organic flow keeps the rings fresh. For quiet periods, anyone can call MarketOracleAggregator.checkpoint(), which checkpoints every pool that is not shut down; RateParControl does this on every update through checkpointControlResult().
Building the control price
The aggregator turns the two pool readings into one controller input:
- Contributors. A pool contributes a price only if it is not shut down, its 24-hour window is available, and its 24-hour liquidity TWAL is at least 250,000 RD-equivalent (
MIN_CONTRIBUTOR_RD_LIQUIDITY, half of the market floor). - Price. The control price is the mean of the contributors' 24-hour TWAPs.
- Acceptance. The price is accepted for control only if the one-way readiness latch has set (below) and the contributors' 24-hour liquidity sums to at least 500,000 RD-equivalent (
RD_LIQUIDITY_FLOOR).
Readiness. bootstrapMarketReady is a one-way latch. It sets once every pool that is not shut down has reported at least one lifecycle observation and is structurally ready (its ring has 8,192 slots and covers both the 24-hour and 4-hour windows), with at least one such pool. Liquidity amounts play no part. Until it sets, no price is accepted.
The aggregator's read functions:
| Function | Returns |
|---|---|
checkpointControlResult() | Checkpoints every pool, then returns the control result (price, contributors' 4-hour liquidity, accepted flag) and whether controller shutdown is required. Used by RateParControl. |
controlResult() | The same result as a view, without checkpointing. |
getResultWithValidity() | The candidate price, whether any pool contributes (valid), and whether it would be accepted. |
activeLiquidityResult() | 24-hour and 4-hour liquidity summed over the pools that are not shut down (no contributor floor). Used by GlobalFeeRouter. |
Pool lifecycle and shutdown
Each pool keeps its own failure clock (FailureWindow). A pool is failing while it is empty, its StableSwap invariant is below 200 (MIN_FUNCTIONAL_INVARIANT), or one normalized reserve is more than 50 times the other (MAX_LIFECYCLE_RESERVE_RATIO). Failing time is credited only after the bootstrap period, at most 48 hours per observation (SHUTDOWN_MAX_CREDIT_STEP), and only over the current UTC day and the 20 days before it (SHUTDOWN_EVIDENCE_WINDOW = 21 days). When credited failing time reaches 7 days (SHUTDOWN_FAILURE_THRESHOLD), the pool shuts down irreversibly:
- It leaves the market (
activePoolMask): it no longer contributes a price or liquidity. - Its LP issuance and LP fee distribution are deactivated (
finalizeShutdown, retried on later checkpoints if a push fails), and the LP share of fees goes to the remaining pool.
When both pools have shut down, the aggregator reports that controller shutdown is required. The next RateParControl update latches controllerShutdown and emits ControllerShutdown; from then on rate and par only decay toward their biases (see Peg control and Controller shutdown). Low liquidity, an off-peg price or low RD supply never trigger shutdown; they only make the controller skip steps or act more weakly.
Input to the system rate controller
RateParControl reads checkpointControlResult() and uses the accepted price to drive rate and par. If the price is not accepted, or RD total supply is below 5,000,000, the controller skips the step and holds its state. The contributors' 4-hour liquidity feeds a liquidity-authority scalar between 20% and 100% that scales how strongly the controller acts: a thinner market produces a noisier TWAP, so the controller trusts it less. A separate seven-day sustained-error dwell guarantees the baton can still pass to PAR even when reduced authority keeps rate short of its bound. The rate/par math itself is on Peg control.
RateParControl calls checkpointControlResult() on every update. If the price is accepted (and RD supply is at least 5,000,000), it drives rate and par back toward the peg; otherwise it skips the step and holds its state. A liquidity-authority scalar between 20% and 100%, built from the contributors' 4-hour liquidity and the LP-utilization EMA, scales how strongly it acts.Input to the GlobalFeeRouter
The GlobalFeeRouter reads activeLiquidityResult() to compute LP utilization = min(24-hour, 4-hour liquidity) ÷ RD total supply, capped at 37.5% per sample. It runs that through an EMA and a PI controller that sets lpAllocFrac — the share of protocol fees routed to LP stakers — steering utilization toward targetLpUtil = 12.5%.
activeLiquidityResult() — the 24-hour and 4-hour liquidity TWALs summed over the pools that are not shut down — and forms LP utilization = min(24 h, 4 h) ÷ RD supply, capped at 37.5%. It smooths that through an EMA and a PI controller that steers utilization toward targetLpUtil = 12.5% by setting lpAllocFrac, the LP share of protocol fees. An unavailable reading leaves lpAllocFrac unchanged; 4-hour liquidity below 500,000 counts as zero utilization.Contingencies:
- No liquidity reading (a window not yet covered, or zero RD supply) — elapsed time is consumed but
lpAllocFracis left unchanged (no sample, no drift). - 4-hour liquidity below the 500,000 floor — treated as a valid zero-utilization sample, so a genuinely thin market pushes the LP allocation up rather than freezing it.
See Fees for how lpAllocFrac combines with the Stability Pool split.
Deep dive
- Peg control — how the controller consumes the RD price.
- Fees — the LP / SP fee split driven by LP utilization.
- Controller shutdown — the terminal market-retirement path.
- Risks — oracle-specific risks and mitigations.