USDR Implementation 🔧

The reference implementation of the USDR White Paper v3.2: 13 Solidity contracts (~1,700 LoC), a Foundry test suite with 36 tests including fork tests against live Arbitrum One, a triaged Slither report, and a complete audit package — ready to hand to an independent security auditor.

Status — audit-ready package

Solidity contracts — full whitepaper coverage, Solidity 0.8.24 + OpenZeppelin v5

Tests passing: unit, 512-run fuzz of the invariant, and E2E fork tests vs live Arbitrum

6 / 6

Whitepaper stress scenarios covered in tests: S1, S2, S3, S4/S8, S9, S10

Unresolved Slither findings — 41 raw results triaged, none exploitable

Verified against the live chain. The exposure adapter reads real Rain pools on Arbitrum One (via the rain-sdk-v2 ABI). On-chain verification caught two integration bugs no document would have revealed: options are 1-indexed, and baseTokenDecimals() returns the scale factor (1e6), not the digit count. The TWAP reader was fork-verified against the live ARB/USDC Uniswap v3 pool, and the full-system E2E test runs against real USDT and a real live Rain market on an Arbitrum fork.

Architecture

                        ┌─────────────────┐
                        │   Timelock /    │  (risk params only;
                        │   Governance    │   core is immutable)
                        └────────┬────────┘
                                 │
 ┌───────────┐   mint/burn  ┌────┴─────┐   mint/burn   ┌───────────┐
 │    PSM    ├─────────────►│   USDR   │◄──────────────┤ CDPVault  │
 │ (stables) │              │  ERC-20  │               │(volatile) │
 └─────┬─────┘              └──────────┘               └─────┬─────┘
       │ USDT/USDC in                                        │ prices
       ▼                                                     ▼
 ┌───────────────┐  escrow top-up   ┌──────────────┐   ┌──────────┐
 │ReserveManager │─────────────────►│ Settlement   │   │OracleHub │
 │ (USDT/USDC)   │                  │   Escrow     │   │(CL+TWAP+ │
 │ slack ⇄ escrow│                  │(traders only)│   │ breaker) │
 └───────┬───────┘                  └──────────────┘   └──────────┘
         │ invariant check
         ▼
 ┌───────────────┐    exposure reports    ┌──────────────────┐
 │ SolvencyGuard │◄───────────────────────┤ RainMarketAdapter│
 │ MaxLoss/Stress│                        │ (live pools)     │
 └───────────────┘                        └──────────────────┘

Contracts

Contract	Whitepaper section	What it enforces
`SolvencyGuard`	§4.1, §4.3	The invariant. `Stress-MaxLoss + shortfall ≤ Reserve` checked on every exposure increase; depth that would breach the floor is refused. Immutable core — no upgrade path.
`USDR`	§3, §10	ERC-20 + Permit. No admin-mint: minter set finalized at deployment, forever. No owner.
`ReserveManager`	§4.2	Stable reserve accounting. Escrow funded first to exactly Stress-MaxLoss(t); only remaining slack backs redemption.
`SettlementEscrow`	§4.2, §4.4	Traders' winnings only. Payable solely by registered market adapters; no other withdrawal path exists.
`PSM`	§3, §4.4	1:1 stable onramp; redemption best-effort from slack — reverts beyond it, by design. Bounded pause (≤14 days).
`CDPVault`	§3, §5.4, §6	MakerDAO-style CDPs: ETH/wBTC 140%, ARB/RAIN 400% with shared correlated-group ceiling. Debt ceilings with hysteresis. No code path converts collateral to stables — the anti-reflexivity rule.
`OracleHub`	§9	Chainlink (ETH/wBTC/USDC) + Uniswap v3 TWAP (RAIN/ARB) + circuit breaker + Arbitrum sequencer-uptime guard with recovery grace period.
`UniV3TwapReader`	§9	≥30-min TWAP window enforced in the constructor, pool-liquidity floor, canonical TickMath. Fork-verified vs the live ARB/USDC pool.
`LiquidationEngine`	§7, §9, §4.6	Dutch auctions for keepers. Under an active breaker: partial + rate-limited, never frozen; un-cleared stress shortfall is priced into the invariant.
`SurplusBuffer`	§7, §8	Vig fills the buffer to target first; only excess funds buyback-and-burn. Capped, timelock-gated RAIN backstop (waterfall step 4).
`EmergencySettlement`	§7 step 5	One-way global shutdown; holders claim pro-rata share of all collateral at $1.
`RainMarketAdapter`	§4.1	Bridges live Rain pools to the solvency layer: computes worst-case net delta across mutually exclusive outcomes, applies the stress multiplier, reports per correlated group.
`SettlementRouter`	§4.4	Wires market resolution (`optionWinner` / `getClaimableAmount`) to the escrow. Permissionless settle, dispute/appeal-aware, double-pay blocked.

Live-chain integration

Integration was built against the real production surfaces, not assumptions:

ABI source: official rain-sdk-v2 package (MarketsAbi, environments config).
Production factory: 0x38B3Ba1ee001E6785224E31b3031ae96CA06C677 (Arbitrum One), base token USD₮0 0xFd08…Cbb9.
On-chain verification: adapter reads validated against a live pool (0xd190…F363) — caught 1-indexed options and scale-factor decimals.
E2E fork test: deploys the full stack on an Arbitrum One fork, mints USDR against real USDT, registers the live Rain pool, rebalances the escrow to Stress-MaxLoss, and proves the invariant holds end-to-end.

Test suite

Suite	Covers
`USDRProtocol.t.sol`	Core: no-admin-mint, PSM 1:1 + slack-capped redemption (S10), invariant refusal of excess depth, escrow rebalancing, CDP open/borrow/close returns collateral only, ceilings + hysteresis, over-mint attack (S3), breaker blocks borrows, full liquidation flow (S1), 512-run fuzz: the invariant never breaks.
`RainMarketAdapter.t.sol`	Balanced book → ~0 exposure (S2); one-sided longshot → computed and capped (S9); correlated-group aggregation and refusal (S4/S8); retire/sync lifecycle.
`SettlementRouter.t.sol`	Winner paid from escrow, double-pay blocked, unresolved/disputed/unregistered/zero-claim all revert.
`Oracle.t.sol`	Sequencer down blocks prices; recovery grace period; TWAP decimal parity; short-window and low-liquidity rejection.
`TwapFork.t.sol` + `E2EFork.t.sol`	Fork tests vs live Arbitrum One: real ARB/USDC TWAP sanity; full-system E2E with real USDT and a live Rain pool.

# run everything
forge test

# fork tests against live Arbitrum
forge test --mc TwapForkTest --fork-url https://arb1.arbitrum.io/rpc
forge test --mc E2EForkTest  --fork-url https://arb1.arbitrum.io/rpc

Security review (pre-audit)

Slither 0.11.5: 41 raw results across 4 detector classes, all triaged — none exploitable. Full reasoning in the triage document.
Trust model: no token owner; minters finalized forever; immutable invariant core; timelock (48h) for risk params only; guardian limited to a bounded PSM pause.
Formal invariants for auditors (I1–I5) defined in AUDIT-NOTES — e.g. I2: no call sequence moves USDT/USDC out except trader settlement and slack-capped redemption.

📦 The audit package

📋 Specification

SPEC.md — module map, flows, units & precision, audit checklist.

🔍 Audit notes

AUDIT-NOTES.md — trust model, whitepaper→code map, formal invariants, honest open-items list.

🛡️ Slither triage

SLITHER-TRIAGE.md — every static-analysis finding, reviewed and reasoned.

🚀 Deploy script

Deploy.s.sol — full-stack deployment + wiring for Arbitrum.

All source files (contracts, adapters, oracle, tests) are browsable via the links in the tables above — every file on this page is served from /usdr-code/.

Open items before mainnet

Independent security audit — this package is the input to that audit, not a substitute for it.
Governance ratification of White Paper v3.2 (bzr), per the roadmap.
Economic simulation of stress parameters (−50% markdown, 35% depth) against historical RAIN/ARB liquidity data.
Per-market underwriting policy — protocolShareBps defaults, set via timelock.
Solvency Dashboard front-end (all on-chain views — maxLoss(), stressMaxLoss(), headroom(), isSolvent() — are already exposed).
Extended invariant campaign (Echidna/Medusa) as auditor support material.

Sending to audit? Point the auditors at this page. Recommended reading order: whitepaper summary → SPEC → AUDIT-NOTES (invariants I1–I5) → contracts → tests → Slither triage.