Rain Vaults Documentation

Non-custodial strategy vaults on the Rain prediction-market protocol. Written for professional traders, market makers, bots, and AI agents — everything needed to create, fund, manage, trade, and exit vaults, fully on-chain.

1. System overview & guarantees

Rain Vaults lets anyone run a trading strategy on Rain prediction markets with pooled capital, Hyperliquid-style:

• A manager creates a vault, seeds it with their own USDT, and publishes a strategy description.
• Depositors put USDT in and receive shares — a pro-rata claim on the vault's NAV.
• The manager (or their authorized trading keys) trades Rain markets with the vault's funds.
• Profits and losses accrue to the share price. The manager earns a performance fee above a high-water mark.

2. Contract addresses & network

3. Roles

4. Creating a vault

1. Approve the factory to pull your seed: USDT.approve(factory, seedAmount). Minimum seed: 100 USDT (MIN_SEED = 100e6).
2. Call createVault(name, description, performanceFeeBps, managementFeeBps, lockupPeriod, seedAmount):

The factory deploys a new RainVault, credits the seed shares to you, and lists the vault in getAllVaults(). Fees are immutable forever — displayed to every depositor.

5. Depositing & shares math

USDT.approve(vault, amount);
vault.deposit(amount);            // credits msg.sender
// or vault.depositFor(beneficiary, amount);

• Shares minted = amount × totalShares / NAV (first deposit: 1 share per USDT-wei, plus 1000 dead shares as an inflation-attack guard).
• Share price starts at 1.0 and tracks performance: sharePrice = NAV / totalShares (1e18 scale).
• NAV = free USDT + escrowed order funds + positions marked at the best executable bid (firstBuyOrderPrice) + full claim value of resolved options. Conservative marking protects existing depositors from overpriced entries.
• Each deposit restarts your lock-up timer.

6. Trading — UI, bots, and AI agents

6a. Manual (web UI)

Vault page → Manager Panel (visible when connected as manager): register market, place/cancel orders.

6b. Trading keys (bots / AI agents) — the recommended way

1. Manager opens the vault page → Manager Panel → section 3.
2. Generate API Key — creates a fresh keypair locally in the browser and authorizes it on-chain in one step. The private key is shown once; give it to your bot.
3. Or Authorize any existing address (your bot's wallet) via setOperator(address, true).
4. The key needs a little ETH on Arbitrum for gas (~0.001 ETH goes a long way).
5. Revoke instantly anytime: setOperator(address, false).

An authorized key calls the vault's trading functions directly — no manual signing, fully automated, 24/7:

// All trading functions — callable by manager OR authorized operators:
registerMarket(address market)                    // one-time per market; grants USDT approval
tradePlaceBuyOrder(market, option, side, price, amount, postOnly)   // limit buy (USDT amount)
tradePlaceSellOrder(market, option, side, price, shares, postOnly)  // limit sell (shares)
tradeEnterOption(market, option, side, amount, minSharesOut)        // taker/AMM buy
tradeSellOption(market, option, side, shares, minAmountOut)         // market-sell into bids (order-book markets)
tradeCancelBuyOrders(market, option, sides[], prices[], orderIDs[])
tradeCancelSellOrders(market, option, sides[], prices[], orderIDs[])
tradeSplit(market, option, amount)                // USDT → equal YES+NO pairs
tradeMerge(market, option, amount)                // YES+NO pairs → USDT
claimResolved(market, option)                     // anyone; claims resolved winnings to the vault

7. Rain markets: options, sides, prices

• Every Rain market is an EIP-2535 Diamond contract. Get live markets from the Rain API: GET https://prod2-api.rain.one/pools/public-pools?limit=30 (field contractAddress).
• Options are 1-based: a 3-outcome market has options 1, 2, 3.
• Sides: YES = 1, NO = 2.
• Prices are 1e18-scaled: 0.49 (49¢, 49% implied probability) = 490000000000000000. Tick spacing 0.01.
• Amounts are 6-decimals (USDT): $100 = 100000000.
• Best bid/ask per option+side: firstBuyOrderPrice(option, side) / firstSellOrderPrice(option, side) on the market contract.
• Trading models: tradingModel() → 0 = AMM (buy/split/merge only, no sellOption before resolution), 1 = OrderBook (full limit-order trading).
• A winning share redeems for $1 (via claim after resolution). Prices ≈ implied probability.

8. Fees & high-water mark

• Performance fee: charged only on share-price gains above the all-time high (high-water mark). No double-charging, nothing on loss recovery. Paid by minting shares to the manager.
• Management fee: pro-rated per second on AUM, also share-minted.
• Accrual happens automatically on withdrawals, or anyone can call poke().
• Example: 10% perf fee, you deposit $1,000, vault gains 20% → your gross $200 profit pays $20 to the manager, you net $180.

9. Withdrawals & the fairness system

Three paths, fastest first:

1. Instant: requestWithdraw(shares) — if the vault has enough free USDT and your lock-up passed, you're paid immediately at current NAV.
2. Queue: not enough free cash → your request joins a FIFO queue. Any USDT that arrives (sells, merges, claims) services the queue before new trading. The manager has a 48-hour grace period to unwind positions in an orderly way.
3. Force-unwind (permissionless): if the head of the queue has waited > 48h, anyone can call forceUnwind(positionIndex, side, minAmountOut): cancels resting orders / claims resolved options / market-sells up to 20% of a position per call (order-book) or merges YES+NO pairs (AMM) until the queue is paid. Slippage is borne at fill time — those demanding liquidity pay its true market price; remaining depositors are not diluted.

• Lock-up: per-deposit, set at vault creation (shown on the vault card). Attempting early withdrawal reverts LockupActive.
• Manager minimum: the manager cannot withdraw below 5% of total shares while others are invested (ManagerBelowMinimum).
• Cancel a queued request: cancelWithdrawRequest(index).

10. Closing a vault

1. Manager unwinds all positions (NAV must equal free cash).
2. closeVault() — accrues final fees, freezes trading.
3. Everyone (including the manager, no 5% rule anymore) exits via withdrawAfterClose(shares) — no lock-up, no queue.

11. Full ABI reference (RainVault)

Depositor functions

deposit(uint256 amount) → uint256 shares
depositFor(address beneficiary, uint256 amount) → uint256 shares
requestWithdraw(uint256 shares) → bool instant
cancelWithdrawRequest(uint256 index)
withdrawAfterClose(uint256 shares)
processQueue(uint256 maxRequests)      // permissionless crank
poke()                                  // accrue fees + process queue
forceUnwind(uint256 positionIndex, uint8 side, uint256 minAmountOut)  // after 48h grace
forceCancelOrders(uint256 positionIndex, bool buySide, uint8[] sides, uint256[] prices, uint256[] orderIDs)

Manager functions

setOperator(address operator, bool enabled)   // authorize/revoke trading keys
closeVault()

Trading functions (manager + operators)

See section 6b.

Views

vaultInfo() → (name, manager, nav, totalShares, sharePrice, perfFeeBps, mgmtFeeBps, lockup, closed)
nav() → uint256                       // USDT, 6 decimals, conservative mark
sharePrice() → uint256                // 1e18 scale
sharesOf(address) → uint256
lastDepositAt(address) → uint256      // unix; + lockupPeriod() = unlock time
lockupPeriod() → uint256
operators(address) → bool
operatorsCount() / operatorList(uint256)
allowedMarket(address) → bool
marketsCount() / markets(uint256)
trackedPositionsCount() / trackedPositions(uint256) → (market, option)
queueLength() / queueHead() / queue(uint256) → (owner, shares, requestedAt)
highWaterMark() → uint256

Factory

createVault(string name, string desc, uint256 perfBps, uint256 mgmtBps, uint256 lockup, uint256 seed) → address
getAllVaults() → address[]
vaultsByManager(address, uint256) → address
MIN_SEED() → uint256   // 100e6

Events (for indexers / analytics)

Deposit(user, amount, shares, sharePrice)
WithdrawRequested(user, shares, queueIndex)
Withdrawn(user, shares, amount, sharePrice)
MarketRegistered(market)
PositionTracked(market, option)
ManagerTrade(market, selector, option, side, amount)
PerformanceFee(manager, feeShares, newHighWaterMark)
ManagementFee(manager, feeShares)
ForceUnwind(caller, market, option, recovered)
OperatorSet(operator, enabled)
VaultClosedEvent(finalSharePrice)

12. Copy-paste recipes (ethers.js v6)

Bot setup

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider('https://arb1.arbitrum.io/rpc');
const key = new ethers.Wallet(process.env.TRADING_KEY, provider); // authorized via setOperator
const vault = new ethers.Contract(VAULT_ADDR, VAULT_ABI, key);

Read market prices

const market = new ethers.Contract(MARKET_ADDR, [
  'function firstBuyOrderPrice(uint256,uint8) view returns (uint256)',
  'function firstSellOrderPrice(uint256,uint8) view returns (uint256)',
], provider);
const bid = await market.firstBuyOrderPrice(1, 1); // option 1, YES — 1e18 scale
const ask = await market.firstSellOrderPrice(1, 1);

Place a limit buy ($50 on option 1 YES at 48¢)

await vault.registerMarket(MARKET_ADDR);            // once per market
await vault.tradePlaceBuyOrder(
  MARKET_ADDR,
  1,                                   // option (1-based)
  1,                                   // side: YES=1, NO=2
  ethers.parseUnits('0.48', 18),       // price, 1e18
  ethers.parseUnits('50', 6),          // USDT amount, 6 decimals
  false                                // postOnly
);

Market-sell 100 shares into the bids

await vault.tradeSellOption(MARKET_ADDR, 1, 1, ethers.parseUnits('100', 6), 0);

Check vault state

const [name, manager, nav, shares, price] = await vault.vaultInfo();
const myPos = await market.userOptionPerSideShares(1, 1, VAULT_ADDR); // vault's YES shares

Claim after resolution (anyone)

await vault.claimResolved(MARKET_ADDR, 1);

13. Security model & limits

• No withdrawal path for manager/operators — enforced by the contract, not policy.
• Trading only on registered markets whose baseToken() is USDT — the vault cannot approve arbitrary contracts.
• Conservative NAV marking (best-bid) prevents deposit/withdraw gaming around stale prices.
• Dead shares + minimum seed block share-inflation attacks.
• High-water mark blocks fee double-charging.
• Manager ≥5% skin-in-the-game while others are invested.
• 48h grace + permissionless force-unwind: no one can be locked in forever.
• Reentrancy-guarded state changes; USDT-only (no exotic token callbacks).
• Known risks: smart-contract risk (unaudited beta), Rain protocol risk (resolution disputes), market liquidity risk (thin books → wide force-unwind slippage), manager self-dealing on markets they created (disclosed, not blocked in v2).