Skip to main content

Architecture

RAI Dollar's contracts are organized in two layers: a per-branch layer that owns trove state and pools for a single collateral, and a singleton layer above that coordinates across branches. The diagram below shows both layers — hover any contract for its responsibility:

Per-branch contracts​

A branch is everything needed to run one collateral type. Branches don't share state; they share singletons.

ContractResponsibility
BorrowerOperationsUser-facing API: open / adjust / close / shield-toggle. Enforces ICR/TCR/shield rules.
TroveManagerTrove state machine: storage, ICR computation, liquidation orchestration entry points.
LiquidationsBranch-local liquidation logic, offset against SP, redistribute remainder, batch liquidate.
RedemptionsBranch-local redemption walk over the base list and, during shutdown, the Redemption Shield cohort list.
RewardsTracks pending redistribution rewards (debt and collateral) for active troves.
StabilityPoolRD deposits that absorb liquidations. Tracks per-depositor collateral and MOAI gains; the branch's share of interest compounds into deposits.
InterestEngineDrips branch debt interest. Maintains two per-second accumulators: accumulatedRate for the base book (branch_rate − v) and accumulatedShieldRate for the Redemption Shield cohort book (branch_rate + u), where the same shield-share curve produces the signed adjustment for each.
ActivePool (base)Custody of collateral backing troves without Redemption Shield.
ActiveShieldedPoolCustody of collateral backing troves with Redemption Shield enabled.
DefaultPoolCustody of redistributed collateral and debt (from liquidations that couldn't be fully offset).
CollSurplusPoolHolds collateral surplus owed back to borrowers: the remainder after a trove is fully redeemed, the excess above the Stability Pool cap in a liquidation, and the collateral of a swept mini-dwarf trove.
GasPoolHolds the per-trove 200 RD gas-compensation reserve.
SortedTroves (base)Doubly-linked list of troves without Redemption Shield, ordered by NICR.
SortedTroves (Redemption Shield cohort)Same, for troves with Redemption Shield enabled.
PriceFeedBranch-specific collateral USD price feed. ETH- and BTC-based branches use Chronicle as primary and Chainlink as fallback for the ETH/USD or BTC/USD leg, composed with Chainlink feeds for the asset-specific leg (stETH, WBTC/BTC, rETH, weETH, tBTC); PAXG uses Chainlink PAXG/USD checked against XAU/USD.
FeeRouterSplits this branch's interest between the local Stability Pool and the singleton GlobalFeeRouter; forwards early-repayment fees to GlobalFeeRouter in full.
MinTrovePermissionless peg-arbitrage helper: opens a trove at exactly ICR = MCR at the current oracle price, with net debt between 1,800 and 10,000 RD.

Singleton contracts​

ContractResponsibility
AggregatorCross-branch control plane: redemption routing and quotas, drip orchestration, issuance quotas, per-branch debt EMAs, delta-rate offsets, branch shutdown and the bad-debt sink.
RDTokenThe RD stablecoin (ERC-20). Mint and burn are restricted by role to branch contracts, GlobalFeeRouter and Aggregator.
MOAITokenThe MOAI token. Fixed 100,000,000 supply minted at deployment.
RateParControlThe PI controller that produces the system rate and par over time.
MarketOracleAggregatorThe RD market oracle: combines price and liquidity observations from the two Uniswap v4 pools (RD/USDC and RD/USDT) into the readings used by RateParControl and GlobalFeeRouter.
RdStableSwapHook (one per pool)Uniswap v4 hook for each RD market pool: StableSwap pricing, the pool's LP share token, and the price/liquidity observations the oracle reads.
GlobalFeeRouterSplits cross-branch fees between keeper rewards, LP fees, MOAI staking, and bad-debt repayment.
LpFeeDistributorReceives the LP share of fees in RD and splits it equally across the pools that are not shut down.
LPStaking (one per pool)Stakes a pool's LP shares; pays MOAI (from V4LpIssuance) and RD (from LpFeeDistributor).
MOAIStakingMOAI staking with three lockup tiers; earns RD fees.
FLXStakingFLX staking; one-year linear MOAI distribution.
GlobalHintHelperCross-branch helper for computing redemption and insertion hints.
KeeperRewardsHolds the RD float that pays keepers for drips, controller updates and branch shutdowns.
V4LpIssuance / SpIssuanceMOAI emission schedules for LP staking and Stability Pool rewards (31.5M MOAI each).
MOAISablierInitializerCreates the locked Sablier streams for the team and investor MOAI allocation.
RateView, SystemView, MultiTroveGetter, RedemptionRankViewRead-only views for frontends and integrators.

Branch ↔ singleton relationships​

  • Mint/burn: authorization is role-based on RDToken. RD can be minted by BorrowerOperations, MinTrove, StabilityPool and GlobalFeeRouter (fee shares are minted, not transferred). RD can be burned by BorrowerOperations, MinTrove, TroveManager, StabilityPool, Redemptions and Aggregator.
  • Drip orchestration: Aggregator.drip() iterates every non-shutdown branch and calls each branch's InterestEngine.aggDrip(...) with that branch's rate, then routes the batch's fees to GlobalFeeRouter once. A borrower operation on one branch drips only that branch, through TroveManager and InterestEngine.drip().
  • Debt EMAs: every state-changing borrower op tells the Aggregator (through TroveManager) to refresh that branch's debt EMA and the global debt EMA. The Aggregator also keeps a per-branch base debt EMA for redemption basket weights.
  • Rate offsets: the Aggregator adds a per-branch deltaRateOffset on top of the system rate from RateParControl. The offset is driven by the branch's debt-utilization error.
  • Redemption: a single Aggregator.redeemCollateral call iterates all non-shutdown branches with non-zero base debt, splits the requested RD across them in proportion to each branch's base debt EMA, and calls each branch's Redemptions.
  • Fees: each branch's FeeRouter sends a (PI-controlled) fraction of its interest to the local SP; the rest reaches GlobalFeeRouter, which fans out to keeper rewards, LP fees, MOAI staking, and bad-debt repayment.

Common message flows​

Opening a trove (Redemption Shield disabled):

Redeeming RD (multi-branch):

Liquidating a trove:

Why this shape​

  • Branches are isolated. Branches don't read each other's pools. The branch set is fixed at deployment: Aggregator, RDToken and GlobalFeeRouter register every branch in their constructors and have no function for adding one later.
  • The Aggregator does not touch branch storage. It calls into branches via well-typed interfaces; branches push debt-change notifications back via authorized calls. No shared storage.
  • The controller is a singleton. RateParControl produces one system rate and one par for all branches. Per-branch adjustment happens via the Aggregator's additive delta-rate offset (a separate PI loop on each branch's debt utilization), not by giving each branch its own peg controller.
  • Redemptions are multi-branch but per-branch internally. The Aggregator owns the basket-weight logic; each branch owns its own walk.