Security Audit HubARBITRUM ONE · MAINNET

AUDIT PACKAGE v4.1.0

🛡 RAIN CHANNELS — AUDIT PACKAGE

Everything an external security auditor needs, in one place: contracts in scope with verified source, system architecture, the invariants to try to break, the threat model, test & coverage summary, known incidents, and accepted risks. Prepared honestly — including the gaps.

⚠ PRE-AUDIT — NOT YET EXTERNALLY AUDITED SOURCIFY EXACT-MATCH VERIFIED FORGE 140/140 · INTEGRATION 24/24 DEMO STAKES (RUSD PLAY-MONEY)

1 · SCOPE 2 · ARCHITECTURE 3 · ADDRESSES 4 · INVARIANTS 5 · THREAT MODEL 6 · TESTS 7 · INCIDENTS 8 · ACCEPTED RISKS 9 · READINESS 10 · DOCUMENTS

1CONTRACTS IN SCOPE

Solidity 0.8.24 · Foundry · via_ir=true · ~1,470 raw lines (~1,100 SLoC) · protocol/src/channels/

CONTRACT	SLOC	STATUS	SOURCIFY
ChannelManager.sol (V3) — simulator-parity limits, incl. reclaimStale	635	ACTIVE	exact_match ✅
ChannelManager.sol (V2)	635	RETIRED	exact_match ✅
ChannelManager.sol (V1, commit e7da239)	601	RETIRED / DRAINED	exact_match ✅
HouseBond.sol	116	ACTIVE	exact_match ✅
BlackjackRulesVerifier.sol	330	ACTIVE	exact_match ✅
RouletteRulesVerifier.sol — European roulette channel rules (13 bet types, exact casino payouts, solvency check)	296	ACTIVE	exact_match ✅
GameMuxVerifier.sol — action-range dispatcher (0–31 blackjack, 32–63 roulette); manager's active verifier	45	ACTIVE	exact_match ✅
IRulesVerifier.sol (interface)	51	IN SCOPE	—
MockEntropyLocal.sol (test-only)	27	OUT OF SCOPE	—

External dependencies: OpenZeppelin (SafeERC20, ReentrancyGuard, Ownable), Pyth Entropy (provider callback), RUSD ERC-20 (6 decimals, standard).

Off-chain components (threat-model context, not in on-chain scope): services/house-node/ (TS house node: WAL, checkpointing, grace timers, reconciliation, recover_close) and app/channels-sdk.js (browser SDK: session keys, hash chains, EIP-712 signing, snapshot/restore persistence).

2SYSTEM SUMMARY

FunFair-style state channels for casino games

Player deposits RUSD; the operator allocates house float. Hands are played off-chain via dual-signed EIP-712 ChannelStates (domain "RAIN ChannelManager" v1). Randomness = mutual commit-reveal hash chains (N=4096) + a Pyth Entropy session seed mixed per card: card_k = keccak(pRev_k, hRev_k, sessionSeed, channelId, k) % 52, house-reveals-first ordering.

On-chain surface: open (entropy seed request) · checkpoint (nonce floor) · cooperative close · forced close + challenge window + finalize · reveal verification (submitReveals/demandReveal) · fraud proof (proveBadTransition) · stale-channel recovery (reclaimStale, V2 only, 30-day) · fee waterfall at close (1.25% of lost gross → burn 4000 / rebate 1700 / standby 500 / residual 6300 ppm).

Key parameters: 180s player grace → forfeit of open hand's gross · house fault → hand void + comp max(2× gross, 5 RUSD) from HouseBond + equal penalty burned · tiered challenge windows (≤10,000 RUSD → 10 min; above → 24 h) · exposure caps (Σ allocations ≤ 2% vault float, single ≤ 0.25%, 8×maxUnitStake ≤ allocation) · HouseBond 7-day withdrawal delay, pending withdrawals remain slashable · funds always pay out to playerOwner wallet, never session keys.

3DEPLOYED ADDRESSES — ARBITRUM ONE (42161)

All active contracts verified on Sourcify (exact_match); links open Arbiscan

ChannelManager V3 (active)	0xe13DC056111906aA4d3659880EBDC67138c76DA7
ChannelManager V2 (retired)	0xacbfCf3523DDA59419a181Afb2e17A80BE453fEb
ChannelManager V1 (retired)	0x82698e4C14DC5D144bdA2a028aDe60d886681AFb
HouseBond (2×100k RUSD bonds)	0x37E41E1d1EE2F96cE0203af06d639448547ade84
BlackjackRulesVerifier	0xFdcCE2DE2F8A28cBBdBaB01131C3bab138Eb9293
RouletteRulesVerifier	0x5239969ff32e5733F319d3e80eD64D19adF4962f
GameMuxVerifier (manager.verifier)	0x14155583112F87777B95AB0EA76786bf079c6A83
Blackjack V3 (Pyth fallback)	0x2E7747E9c4c18511A4F9e79C6bD38061e1443F7A
RUSD token (demo, 6 dec)	0x260c7019E760763988843Bc5b873d749b5937469
Pyth Entropy	0x7698E925FfC29655576D0b361D75Af579e20AdAc

House node: wss://api.rainsandbox.xyz · health: api.rainsandbox.xyz/health · Arbiscan API verification pending (no API key); Sourcify metadata renders on Arbiscan/Blockscout regardless.

4KEY INVARIANTS — WHAT TO TRY TO BREAK

The 10 properties the audit should attack. Breaking any one is a valid finding.

I1 · CONSERVATIONFor any settling state: playerBal + houseBal + feeAccrued + grossAtRisk == deposit + allocation. No path may mint or destroy escrowed RUSD.

I2 · NONCE MONOTONICITYA checkpointed nonce is a hard floor — no close (cooperative/forced/final) may settle on a lower nonce; a challenge must strictly increase the closing nonce.

I3 · DUAL SIGNATURE INTEGRITYEvery settlement-bearing state requires valid player-session AND house-session signatures bound to the channel's registered keys, chainId, and verifying contract. No cross-channel or cross-chain replay (fuzz-tested).

I4 · FUNDS DESTINATIONSPlayer payouts only to playerOwner (never session keys); house payouts only to operator; fee waterfall split is exact and applied exactly once.

I5 · RECLAIMSTALE CONSERVATISM (V2)Only after ≥30 days of zero on-chain activity; settles at the last on-chain checkpoint (or opening balances); never better for the caller than the last anchored state; permissionless; cannot grief an active channel (any on-chain touch resets the clock).

I6 · FORFEIT / FAULT PATHSPlayer-forfeit only after grace, and only the open hand's gross; house-fault pays void + comp max(2× gross, 5 RUSD) from HouseBond + equal penalty burned — never from other channels' escrow.

I7 · HOUSEBOND7-day withdrawal delay; pending withdrawals remain slashable; slash pays compensation before burn when underfunded; only the manager may slash; setManager only owner.

I8 · ENTROPYOnly the Pyth Entropy contract may invoke _entropyCallback; voidOpen full-refund only in SeedPending after 1h; exposure caps enforced at open.

I9 · REENTRANCYAll fund-moving functions are nonReentrant; RUSD is standard but assume-hostile analysis welcome.

I10 · RULES VERIFIERproveBadTransition accepts only a dual-signed prev and an accused-signed illegal next; a legal transition must never be punishable; card derivation must be unbiased given one honest party.

5THREAT MODEL

Adversaries and the mitigations they must defeat

😈 MALICIOUS PLAYER

Stale-state forceClose → challenge window + checkpoint floor
Mid-hand stall → 180s grace → forfeit of open gross
Fake reveals → on-chain hash-chain verification
Session-key theft → irrelevant: funds only pay to playerOwner

🏠 MALICIOUS OPERATOR / HOUSE

Stale-state close → player challenge
Withholding reveals → demandReveal escalation
Refusing to countersign → player forceClose from last dual-signed state
Node death → V2 reclaimStale after 30d guarantees escrow release

👥 THIRD PARTIES

Griefing via permissionless functions (finalizeClose, reclaimStale, submitReveals) → must not worsen an honest party's outcome

🌐 INFRASTRUCTURE

Arbitrum sequencer outage vs challenge windows → tiered 10 min / 24 h — accepted risk at demo stakes
Pyth Entropy liveness → voidOpen full refund after 1h

6TEST & COVERAGE SUMMARY

Test-to-code ratio ≈ 1.9:1 by lines

140/140

FORGE (UNIT + FUZZ)

24/24

INTEGRATION (ANVIL E2E)

✅

MAINNET E2E + DISPUTE DRILL

N/A

FORGE COVERAGE % (TOOLING)

Forge: bond mechanics, open/seed/void, exposure caps, cooperative close + waterfall exactness, conservation, stale-state challenge, checkpoint floor, forfeit, comp+burn, tiered windows, reveal chains, demandReveal, fraud proof both directions, reclaimStale suite, fuzz conservation + cross-channel replay.
Integration (house-node E2E on Anvil): happy path, waterfall, stale-close attack, mid-hand stall forfeit, checkpoint floor, refresh/restore, abandoned-channel reconciliation, WAL-loss recover_close.
Mainnet: open/close happy path (39ms/action local, 313ms over wss) + real forced-close dispute drill with full 10-min window on Arbitrum One.
Honest gap: forge coverage is unobtainable — via_ir + coverage instrumentation hits "stack too deep" even with --ir-minimum. Line-coverage numbers unavailable.

7INCIDENT LOG

Full disclosure — what broke, what it cost, how it was fixed. Details in DEPLOYMENT.md.

✅ Abandoned-escrow recovery (v4.0.1)

v4.0.0 kept session material in memory only — page refresh abandoned open channels. 4 channels (2,400 RUSD) recovered via operator cooperativeClose from WAL states. Fix: localStorage snapshot/restore, auto-resume, recover_close, 30-min reconciliation sweep.

⚠ Stuck V1 channel 0xdd64aa43… — 2,500 RUSD locked permanently

Opened mid-maintenance; WAL wiped by redeploys, no dual-signed state on either side. V1 has no recovery path by design (re-audited: all settle paths need dual signatures). Player's 500 RUSD deposit refunded from treasury; 2,000 RUSD house allocation written off. This failure mode is exactly why V2's reclaimStale exists.

✅ House-node durability (v4.1.0)

Bar: a redeploy mid-session must never destroy the only copy of a signed state. Three layers now: per-hand on-chain checkpoints (~130k gas, default ON), checkpoint-on-disconnect, SIGTERM flush — plus client snapshots and reclaimStale as the durable floor.

8ACCEPTED RISKS & KNOWN LIMITATIONS

Auditors: please do not re-report these — they are known and accepted for v1 / demo stakes

Demo/play-money deployment (RUSD faucet token). The 24h tier window < Arbitrum force-inclusion delay is accepted at these stakes (spec §4.4).
Single foundation-run house node; HA / watchtower / HSM out of scope for v1.
House-node WAL on ephemeral /tmp — mitigated in v4.1.0 by per-hand checkpoints, disconnect checkpoints, SIGTERM flush, client snapshots + recover_close. On-chain checkpoint + reclaimStale is the durable floor.
Statistical fairness is transparency-only in v1 (no on-chain statistical slashing).
proveBadReveal intentionally subsumed by submitReveals chain verification.
Per-hand checkpoints put hand-level P&L cadence on-chain (privacy = transparency tradeoff, fine for demo).
If the operator wallet runs dry of ETH, the node degrades to WAL-only durability (alerts on checkpoint failure).
V1 ChannelManager is retired with one stranded channel documented above. Nothing should ever point at V1 again.