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.
| Contract | Responsibility |
|---|---|
BorrowerOperations | User-facing API: open / adjust / close / shield-toggle. Enforces ICR/TCR/shield rules. |
TroveManager | Trove state machine: storage, ICR computation, liquidation orchestration entry points. |
Liquidations | Branch-local liquidation logic, offset against SP, redistribute remainder, batch liquidate. |
Redemptions | Branch-local redemption walk over the base list and, during shutdown, the Redemption Shield cohort list. |
Rewards | Tracks pending redistribution rewards (debt and collateral) for active troves. |
StabilityPool | RD deposits that absorb liquidations. Tracks per-depositor collateral and MOAI gains; the branch's share of interest compounds into deposits. |
InterestEngine | Drips 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. |
ActiveShieldedPool | Custody of collateral backing troves with Redemption Shield enabled. |
DefaultPool | Custody of redistributed collateral and debt (from liquidations that couldn't be fully offset). |
CollSurplusPool | Holds 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. |
GasPool | Holds 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. |
PriceFeed | Branch-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. |
FeeRouter | Splits this branch's interest between the local Stability Pool and the singleton GlobalFeeRouter; forwards early-repayment fees to GlobalFeeRouter in full. |
MinTrove | Permissionless 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
| Contract | Responsibility |
|---|---|
Aggregator | Cross-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. |
RDToken | The RD stablecoin (ERC-20). Mint and burn are restricted by role to branch contracts, GlobalFeeRouter and Aggregator. |
MOAIToken | The MOAI token. Fixed 100,000,000 supply minted at deployment. |
RateParControl | The PI controller that produces the system rate and par over time. |
MarketOracleAggregator | The 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. |
GlobalFeeRouter | Splits cross-branch fees between keeper rewards, LP fees, MOAI staking, and bad-debt repayment. |
LpFeeDistributor | Receives 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). |
MOAIStaking | MOAI staking with three lockup tiers; earns RD fees. |
FLXStaking | FLX staking; one-year linear MOAI distribution. |
GlobalHintHelper | Cross-branch helper for computing redemption and insertion hints. |
KeeperRewards | Holds the RD float that pays keepers for drips, controller updates and branch shutdowns. |
V4LpIssuance / SpIssuance | MOAI emission schedules for LP staking and Stability Pool rewards (31.5M MOAI each). |
MOAISablierInitializer | Creates the locked Sablier streams for the team and investor MOAI allocation. |
RateView, SystemView, MultiTroveGetter, RedemptionRankView | Read-only views for frontends and integrators. |
Branch ↔ singleton relationships
- Mint/burn: authorization is role-based on
RDToken. RD can be minted byBorrowerOperations,MinTrove,StabilityPoolandGlobalFeeRouter(fee shares are minted, not transferred). RD can be burned byBorrowerOperations,MinTrove,TroveManager,StabilityPool,RedemptionsandAggregator. - Drip orchestration:
Aggregator.drip()iterates every non-shutdown branch and calls each branch'sInterestEngine.aggDrip(...)with that branch's rate, then routes the batch's fees toGlobalFeeRouteronce. A borrower operation on one branch drips only that branch, throughTroveManagerandInterestEngine.drip(). - Debt EMAs: every state-changing borrower op tells the
Aggregator(throughTroveManager) 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
Aggregatoradds a per-branchdeltaRateOffseton top of the system rate fromRateParControl. The offset is driven by the branch's debt-utilization error. - Redemption: a single
Aggregator.redeemCollateralcall 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'sRedemptions. - Fees: each branch's
FeeRoutersends a (PI-controlled) fraction of its interest to the local SP; the rest reachesGlobalFeeRouter, 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,RDTokenandGlobalFeeRouterregister 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.
RateParControlproduces one system rate and one par for all branches. Per-branch adjustment happens via theAggregator'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.
Where to read next
- Peg control: what
RateParControlactually does. - Interest model: what
InterestEnginedoes. - Redemption mechanism: full walk.
- Liquidation paths: offset/redistribute math.
- Fees,
FeeRouterandGlobalFeeRouter.