RAIN

We express our gratitude to the RAIN team for the collaborative engagement that enabled the execution of this Smart Contract Security Assessment.

RAIN V2 is a decentralized prediction-market protocol deployed on Arbitrum One, enabling users to create binary-option markets (each subdivided into multiple independent options) and trade outcome shares via either an internal Constant Product Market Maker (CPMM) or a fully on-chain order book, with post-resolution fund distribution and a two-tier AI-plus-oracle dispute system.

The system users should acknowledge all the risks summed up in the risks section of the report

Documentation quality

• Functional requirements are detailed.

• • Project overview is detailed

  • All roles in the system are described.

  • Use cases are described and detailed.

  • For each contract, all futures are described.

  • All interactions are described.

• Technical description is detailed.

• • Run instructions are provided.

  • Technical specification is provided.

  • The NatSpec documentation is sufficient.

Code quality

• The development environment is configured.

Test coverage

Code coverage of the project is 43.22% (branch coverage).

• Deployment and basic user interactions are covered with tests.

• Negative cases coverage is partially missed.

• Interactions by several users are tested.

The protocol is organized around three deployment-time layers. The first layer is RainDeployer, a UUPS-upgradeable singleton that holds all protocol configuration—fee parameters, oracle factory address, platform address, and the implementation addresses of all eleven diamond facets. When a pool creator calls createPool, RainDeployer assembles a FacetCut[] array and delegates to RainDiamondFactory, which deploys a new RainPoolDiamond instance. The deployer then transfers the oracle-fixed-fee and initial liquidity from the creator into the newly deployed pool. Every deployed RainPoolDiamond records RainDeployer as its FACTORY address, granting it the sole authority to invoke diamondCut on the pool.

Each RainPoolDiamond is an EIP-2535 Diamond proxy. Its constructor calls LibDiamond.initializeDiamond to write pool parameters into the shared DiamondStorage struct, then calls LibDiamond.diamondCut to install all eleven facets. Because diamondCut sets isInitialized = true permanently, individual pools are immutable after deployment; only future pools created by the deployer reflect updated facet addresses. All protocol state—AMM reserves, LP shares, order book linked lists, resolution outcomes, dispute records, and fee accumulators—lives in the single DiamondStorage struct managed by LibDiamond.

Trading and resolution are handled by facets that delegate-call into this shared storage. TradingFacet supports two trading models per pool: an AMM phase using constant-product math on per-option YES/NO reserves, and an order-book phase backed by doubly-linked price queues managed by LinkedListLogic. ResolutionFacet allows anyone to finalize an option after its end time by posting a resolver bond; the designated per-option resolver then calls chooseWinner to confirm the outcome. Disputed outcomes trigger DisputeFacet: the initial openDispute call collects a computed dispute fee in base tokens and reassigns the resolver to the protocol's dispute resolver, entering the Disputed state. If the resolution is subsequently contested again, a second openDispute call enters the Appealed state—swapping the resolver-fee share to USDT via LibUtils, calling createOracle on the deployer to provision an external oracle, and commencing a second appeal cycle. Once resolution is complete and the dispute window has elapsed, ClaimFacet distributes payouts and routes fee shares—including a swap-and-burn path for the RAIN token.

Files in Scope

• RainDeployer.sol — UUPS-upgradeable protocol coordinator; stores all fee parameters and eleven facet implementation addresses; exposes createPool for permissionless market creation and a suite of onlyOwner configuration setters; transfers initial liquidity and oracle fees from pool creators; restricts createOracle to pools it has deployed.

• RainDiamondFactory.sol — Thin factory contract; deploys a new RainPoolDiamond with the provided FacetCut[] array and pool parameters, returning its address to the caller.

• RainPoolDiamond.sol — EIP-2535 Diamond proxy entry point; constructor applies initial facet cuts via LibDiamond (permanently setting isInitialized = true); fallback delegates every unknown function selector to the corresponding facet address stored in DiamondStorage.

• DiamondCutFacet.sol — Exposes the EIP-2535 diamondCut function gated to the deployer factory; in practice immutable because isInitialized is set during construction.

• DiamondLoupeFacet.sol — Read-only EIP-2535 loupe implementation; exposes facets, facetFunctionSelectors, facetAddresses, facetAddress, and supportsInterface.

• TradingFacet.sol — Core trading facet; implements AMM-phase enterOption, enterLiquidity, enterLiquidityBatch, and removeLiquidity using constant-product math, and order-book-phase placeSellOrder and placeBuyOrder with linked-list order matching and fee routing.

• CancelOrderFacet.sol — Implements cancelSellOrders and cancelBuyOrders, allowing order makers to cancel their resting orders in batch; buy-order cancellations refund escrowed base tokens.

• SplitMergeFacet.sol — Implements split (collateral → equal YES+NO share accounting, bypassing AMM reserves) and merge (symmetric YES+NO shares → collateral refund); available during AMM and order-book phases while the option is not finalized.

• DisputeFacet.sol — Implements permissionless openDispute, which serves two phases: in the initial dispute phase it collects a computed fee in base tokens and reassigns the per-option resolver to the protocol's dispute resolver; in the appeal phase it additionally swaps the resolver-fee share to USDT via LibUtils and calls createOracle on the deployer factory to provision an external oracle. Also implements unlockCallback for Uniswap V4 PoolManager callbacks during V4 swap execution.

• ClaimFacet.sol — Implements permissionless claim; on the first invocation per option distributes platform fees via swap-and-burn, creator and referrer shares, resolver bond, and dispute fees; on every invocation transfers the caller's proportional payout of LP fees and winning pool share.

• ResolutionFacet.sol — Manages option lifecycle closure; closePool (AI path) and closePool with a proposed winner (human path) are permissionless but require a resolver bond from non-owner/resolver callers; chooseWinner and tooEarly are restricted to the per-option resolver address.

• OracleFeeFacet.sol — Exposes a permissionless fee-quote helper (calculateBaseTokenOracleFixedFee) and a factory-only sweep function (swapOracleFixedFee) that converts the pool's accumulated base-token balance to USDT via LibUtils, transferring the output to the designated platform or oracle-fee recipient.

• InfoFacet.sol — Read-oriented query façade providing simulated share-entry quotes, LP-return previews, order-book sizing helpers, and dispute-fee and resolver-bond calculators; getDisputeAppealFee and getResolverBondAmount are non-view because they invoke Uniswap quoter contracts.

• GetterFacet.sol — Pure view getter façade exposing all DiamondStorage fields: protocol constants, address configuration, AMM reserves, LP state, order-book linked-list metadata, and resolution and dispute records.

• LibDiamond.sol — Core library defining the DiamondStorage struct stored at a deterministic slot; implements pool initialization with parameter validation, the EIP-2535 cut/add/replace/remove mechanics, and all per-option phase and trading-mode guard functions.

• LibUtils.sol — Swap utility library; implements swapAndBurn (base token → WETH via the token's configured V2/V3/V4 pool, then WETH → RAIN via Uniswap V3 at the hardcoded router address, then IRainToken.burn with a platform-transfer fallback), referrerCreatorClaim (creator-fee split), and Uniswap V2/V3/V4 quoting and swap helpers for base-token ↔ USDT/WETH routing.

• PathKey.sol — Local copy of the Uniswap V4 PathKey struct and PathKeyLibrary.getPoolAndSwapDirection; used by LibUtils for V4 multi-hop swap construction.

• Types.sol — Shared type definitions: PoolState enum (NotDisputed, Disputed, Appealed, Refunded) and TradingModel enum (None, AMM, OrderBook).

• LinkedList.sol — LinkedListLogic library implementing a doubly-linked list for order-book queues; supports initialize, append, insert, remove, pop-FIFO, and traversal operations.

• UniswapV2Library.sol — Local copy of Uniswap V2 pair math helpers: pairFor, getReserves, quote, getAmountOut, getAmountIn, getAmountsOut, getAmountsIn; used by LibUtils for V2 routing.

• SafeMath.sol — Overflow-safe arithmetic library (add, sub, mul) used by UniswapV2Library.

• Constants.sol — File-level constants specifying Arbitrum One addresses: USDT, WETH, RAINTOKEN, Uniswap V4 `POOLMANAGER, MINSQRTPRICE, MAXSQRTPRICE, and RAINWETHFEE`; referenced throughout LibUtils and DisputeFacet.

• Globals.sol — Provides the assembly-based _revert(bytes4 selector) helper used protocol-wide to revert with a four-byte custom-error selector.

Privileged roles

• Owner (inherited from OwnableUpgradeable): Holds complete administrative authority over the protocol's configuration and upgrade path.

• • Can call setDiamondFactory to update the factory address used for future pool deployments.

  • Can call setResolverAI to update the default AI resolver address assigned to new pools.

  • Can call setOracleFactoryAddress to replace the external oracle factory used for dispute resolution.

  • Can call setBaseToken to change the default base-token address for new pools.

  • Can call setOracleFixedFee to modify the fixed oracle fee charged at pool creation.

  • Can call setCreatorFee to adjust the creator fee rate applied to trading activity.

  • Can call setClosingFee to adjust the fee deducted at option closure.

  • Can call setResultResolverFee to adjust the fee share allocated to result resolvers.

  • Can call setPlatformAddress to redirect the platform fee recipient.

  • Can call setLiquidityFee to modify the fee rate charged on LP operations.

  • Can call setPlatformFee to adjust the platform fee share of trading revenue.

  • Can call setDisputeResolverAI to change the AI address used for dispute resolution.

  • Can call setNewDiamondCutFacet, setNewDiamondLoupeFacet, setNewDiamondTradingFacet, setNewDiamondResolutionFacet, setNewDiamondDisputeFacet, setNewDiamondClaimFacet, setNewDiamondCancelOrderFacet, setNewDiamondInfoFacet, setNewDiamondGetterFacet, setNewOracleFeeFacet, and setNewSplitMergeFacet to update the implementation addresses and function selectors for each of the eleven diamond facets used in all future pool deployments.

  • Can call allowNewToken to whitelist a new ERC-20 token as an accepted pool base token.

  • Can call disallowExistingToken to remove an ERC-20 token from the accepted base-token list.

  • Can call _authorizeUpgrade (invoked internally by the UUPS mechanism) to authorize replacement of the RainDeployer proxy implementation with a new logic contract.

• Created Pool (runtime check: createdPools[msg.sender] true): Granted only to RainPoolDiamond instances deployed through createPool.

• • Can call createOracle to provision an external resolution oracle; the call transfers base tokens from the pool to the deployer and onwards to the oracle factory.

• DiamondCutFacet.sol

• • Factory (runtime check via LibDiamond.enforceIsFactory: msg.sender ds.FACTORY): Restricted to the RainDeployer address recorded in DiamondStorage at pool initialization.

  • • Can call diamondCut to add, replace, or remove facet function selectors; in practice this path is unreachable for existing pools because isInitialized is set to true during construction.

• CancelOrderFacet.sol

• • Order Maker (runtime check: msg.sender order.maker per order): Restricted to the address that placed each individual order.

  • • Can call cancelSellOrders to cancel one or more of their own resting sell orders, releasing the corresponding share escrow.

    • Can call cancelBuyOrders to cancel one or more of their own resting buy orders and receive a refund of the escrowed base tokens.

• DisputeFacet.sol

• • Pool Manager (runtime check: msg.sender POOL_MANAGER): Restricted to the hardcoded Uniswap V4 PoolManager address defined in Constants.sol.

  • • Can call unlockCallback to execute Uniswap V4 swap settlement steps (swap, sync, settle, take) during V4 swap execution initiated by the protocol's fee-routing paths.

• ResolutionFacet.sol

• • Per-option Resolver (runtime check: msg.sender ds.optionResolver[option]): A per-option address recorded in DiamondStorage at pool initialization; this address is reassigned to the dispute resolver upon a successful openDispute call.

  • • Can call chooseWinner to designate the winning outcome side for a finalized option, computing the fee split between platform and winning-share pools.

    • Can call tooEarly to roll back an option's finalization, transferring the escrowed resolver bond to the calling resolver and, if the option was in a Disputed state, refunding the dispute fee to the original disputer; effectively reopens the option for further resolution attempts.

• OracleFeeFacet.sol

• • Factory (runtime check via LibDiamond.enforceIsFactory: msg.sender ds.FACTORY): Restricted to the RainDeployer address.

  • • Can call swapOracleFixedFee to sweep the pool's entire base-token balance and convert it to USDT via LibUtils, transferring the output to the designated platform or oracle-fee recipient.

The scope of the project includes the following smart contracts from the provided repository:

Assets in Scope