Skip to main content

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 steer rate and par back 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.
RD/USDC poolown RdStableSwapHookRD/USDT poolown RdStableSwapHookMarketOracleAggregatormean price of contributorssummed liquiditypool membershipRateParControlcheckpointControlResult()GlobalFeeRouteractiveLiquidityResult()priceliquidity
Two Uniswap v4 pools, RD/USDC and RD/USDT. Each is priced by its own 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.
pool activityswap · seedadd / remove LPRdStableSwapHookStableSwap, 1 bp feeobservation ringspot tick + liquidityper transitionup to 8,192 observationsnewestprice TWAP24 hliquidity TWAL24 h and 4 h
Every swap, seed and LP deposit or withdrawal goes through the hook, which commits the new reserves and appends one observation to a Uniswap-V3-style ring: the StableSwap spot price (clamped to [0.75, 1.25]) and the pool's balanced-equivalent liquidity. Reads use windows that end 60 s in the past, so a same-block move can't reach them: a 24-hour price TWAP with a 24-hour liquidity TWAL, plus a 4-hour liquidity TWAL.

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:

  1. 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).
  2. Price. The control price is the mean of the contributors' 24-hour TWAPs.
  3. 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).
RD/USDC24 h liquidity ≥ 250k?RD/USDT24 h liquidity ≥ 250k?price candidatemean of contributor TWAPssum of their liquidityacceptedready latched · sum ≥ 500knot acceptedcontroller skips the step
A pool contributes a price only if it is not shut down and its 24-hour liquidity TWAL is at least 250,000 RD-equivalent. The control price is the mean of the contributors' 24-hour TWAPs. It is accepted for control only after the one-way readiness latch has set and when the contributors together hold at least 500,000 RD-equivalent of 24-hour liquidity. Otherwise the controller skips the step.

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:

FunctionReturns
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.
pool failingempty, invariant < 200,or reserves > 50 : 1failure seconds7 days withina 21-day windowpool shutdownremoved from market;LP rewards stopboth pools shutcontroller shutdown(rate & par decay)
Each pool keeps its own failure clock. A pool is failing while it is empty, its StableSwap invariant is below 200, or one reserve is more than 50× the other. Failing time counts only after bootstrap, at most 48 h per observation, over the current UTC day and the 20 before it. At 7 days the pool shuts down for good and leaves the market. When both pools have shut down, the controller latches its terminal shutdown.

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.

control priceaccepted / not acceptedRateParControlpeg PI controllerrateparliquidity authority (20%–100%)scales error
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%.

liquidityactive poolsLP utilizationliquidity ÷ RD supplyEMAPI controller→ targetLpUtillpAllocFracLP fee share
The router reads 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 lpAllocFrac is 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.