@slvr-labs/sdk 0.1.0

package/examples/strategy-base.ts

@@ -0,0 +1,283 @@
+/**
+ * Base strategy class for creating custom betting strategies
+ * 
+ * This provides a flexible framework for implementing betting strategies.
+ * Extend this class and override methods to customize behavior.
+ */
+
+import { SlvrSDK } from '../src';
+import { parseEther } from 'viem';
+
+// Re-export for convenience
+export { SlvrSDK };
+
+/**
+ * Configuration for a betting strategy
+ */
+export interface StrategyConfig {
+  /** Threshold in wei - only bet when round total wager is below this */
+  threshold?: bigint;
+  /** How often to check rounds (in milliseconds) */
+  checkInterval?: number;
+  /** Whether to start checking immediately */
+  startImmediately?: boolean;
+}
+
+/**
+ * Result of evaluating whether to bet
+ */
+export interface BetDecision {
+  shouldBet: boolean;
+  reason?: string;
+}
+
+/**
+ * Base class for betting strategies
+ * 
+ * Override methods to customize behavior:
+ * - `shouldBet()` - Determine if conditions are met to place a bet
+ * - `selectSquares()` - Choose which squares to bet on
+ * - `calculateAmounts()` - Calculate bet amounts for each square
+ * - `onBetPlaced()` - Called after a successful bet
+ * - `onError()` - Called when an error occurs
+ */
+export abstract class BettingStrategy {
+  protected sdk: SlvrSDK;
+  protected config: Required<StrategyConfig>;
+  protected isRunning: boolean = false;
+  protected intervalId?: NodeJS.Timeout;
+  protected currentRoundId?: bigint;
+
+  constructor(sdk: SlvrSDK, config: StrategyConfig = {}) {
+    this.sdk = sdk;
+    this.config = {
+      threshold: config.threshold ?? parseEther('100'),
+      checkInterval: config.checkInterval ?? 5000,
+      startImmediately: config.startImmediately ?? true,
+    };
+  }
+
+  /**
+   * Start the strategy
+   */
+  async start(): Promise<void> {
+    if (this.isRunning) {
+      console.log('Strategy is already running');
+      return;
+    }
+
+    if (!this.sdk.getWalletClient()) {
+      throw new Error('Wallet client required for betting strategies');
+    }
+
+    this.isRunning = true;
+    console.log('🚀 Strategy started');
+    this.logConfig();
+
+    if (this.config.startImmediately) {
+      await this.checkAndBet();
+    }
+
+    this.intervalId = setInterval(async () => {
+      await this.checkAndBet();
+    }, this.config.checkInterval);
+  }
+
+  /**
+   * Stop the strategy
+   */
+  stop(): void {
+    if (!this.isRunning) {
+      return;
+    }
+
+    this.isRunning = false;
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+    console.log('🛑 Strategy stopped');
+  }
+
+  /**
+   * Check if strategy is running
+   */
+  get running(): boolean {
+    return this.isRunning;
+  }
+
+  /**
+   * Main loop: check round and place bet if conditions are met
+   */
+  protected async checkAndBet(): Promise<void> {
+    try {
+      const roundId = await this.sdk.lottery.currentRoundId();
+      this.currentRoundId = roundId;
+
+      // Check if round is open
+      const isOpen = await this.sdk.lottery.roundOpen(roundId);
+      if (!isOpen) {
+        const timeRemaining = await this.sdk.getTimeRemaining(roundId);
+        if (timeRemaining > 0) {
+          this.onRoundNotOpen(roundId, timeRemaining);
+        } else {
+          this.onRoundEnded(roundId);
+        }
+        return;
+      }
+
+      // Get round data
+      const round = await this.sdk.lottery.getRound(roundId);
+
+      // Check threshold
+      if (round.totalWager >= this.config.threshold) {
+        this.onThresholdNotMet(roundId, round.totalWager);
+        return;
+      }
+
+      // Evaluate if we should bet (custom logic)
+      const decision = await this.shouldBet(roundId, round);
+      if (!decision.shouldBet) {
+        this.onBetSkipped(roundId, decision.reason);
+        return;
+      }
+
+      // Select squares to bet on (custom logic)
+      const squares = await this.selectSquares(roundId, round);
+      if (squares.length === 0) {
+        this.onBetSkipped(roundId, 'No squares selected');
+        return;
+      }
+
+      // Calculate amounts (custom logic)
+      const amounts = await this.calculateAmounts(roundId, round, squares);
+      if (amounts.length !== squares.length) {
+        throw new Error('Amounts array length must match squares array length');
+      }
+
+      // Place the bet
+      this.logBetDetails(roundId, squares, amounts, round);
+      const txHash = await this.sdk.lottery.bet({
+        roundId,
+        squares,
+        amounts,
+      });
+
+      await this.onBetPlaced(roundId, txHash, squares, amounts);
+    } catch (error) {
+      await this.onError(error);
+    }
+  }
+
+  /**
+   * Override this to implement custom bet decision logic
+   * @param roundId Current round ID
+   * @param round Round data
+   * @returns Decision whether to bet
+   */
+  protected async shouldBet(roundId: bigint, round: any): Promise<BetDecision> {
+    // Default: bet if threshold is met
+    return { shouldBet: true };
+  }
+
+  /**
+   * Override this to implement custom square selection
+   * @param roundId Current round ID
+   * @param round Round data
+   * @returns Array of square indices (0-24) to bet on
+   */
+  protected abstract selectSquares(roundId: bigint, round: any): Promise<number[]>;
+
+  /**
+   * Override this to implement custom amount calculation
+   * @param roundId Current round ID
+   * @param round Round data
+   * @param squares Selected squares
+   * @returns Array of bet amounts (one per square, in wei)
+   */
+  protected abstract calculateAmounts(
+    roundId: bigint,
+    round: any,
+    squares: number[]
+  ): Promise<bigint[]>;
+
+  /**
+   * Called after a successful bet
+   * Override to add custom logic (logging, notifications, etc.)
+   */
+  protected async onBetPlaced(
+    roundId: bigint,
+    txHash: `0x${string}`,
+    squares: number[],
+    amounts: bigint[]
+  ): Promise<void> {
+    console.log(`✅ Bet placed! Round ${roundId}, TX: ${txHash}`);
+  }
+
+  /**
+   * Called when an error occurs
+   * Override to add custom error handling
+   */
+  protected async onError(error: unknown): Promise<void> {
+    console.error('❌ Error in strategy:', error);
+    if (error instanceof Error) {
+      console.error('   Message:', error.message);
+    }
+  }
+
+  /**
+   * Called when round is not open yet
+   */
+  protected onRoundNotOpen(roundId: bigint, timeRemaining: number): void {
+    // Override for custom behavior
+  }
+
+  /**
+   * Called when round has ended
+   */
+  protected onRoundEnded(roundId: bigint): void {
+    // Override for custom behavior
+  }
+
+  /**
+   * Called when threshold is not met
+   */
+  protected onThresholdNotMet(roundId: bigint, totalWager: bigint): void {
+    // Override for custom behavior
+  }
+
+  /**
+   * Called when bet is skipped
+   */
+  protected onBetSkipped(roundId: bigint, reason?: string): void {
+    // Override for custom behavior
+  }
+
+  /**
+   * Log configuration
+   */
+  protected logConfig(): void {
+    console.log(`   Threshold: ${SlvrSDK.formatToken(this.config.threshold)} ETH`);
+    console.log(`   Check interval: ${this.config.checkInterval / 1000}s`);
+  }
+
+  /**
+   * Log bet details before placing
+   */
+  protected logBetDetails(
+    roundId: bigint,
+    squares: number[],
+    amounts: bigint[],
+    round: any
+  ): void {
+    const total = amounts.reduce((sum, amt) => sum + amt, 0n);
+    console.log(`\n🎯 Round ${roundId} - Placing bet:`);
+    console.log(`   Total wager: ${SlvrSDK.formatToken(round.totalWager)} ETH`);
+    console.log(`   Squares: ${squares.join(', ')}`);
+    squares.forEach((square, i) => {
+      console.log(`   Square ${square}: ${SlvrSDK.formatToken(amounts[i])} ETH`);
+    });
+    console.log(`   Total bet: ${SlvrSDK.formatToken(total)} ETH`);
+  }
+}
+

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@slvr-labs/sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for interacting with the Slvr protocol on Robinhood Chain",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "examples",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "mirror": "bash scripts/publish-mirror.sh"
+  },
+  "keywords": [
+    "slvr",
+    "blockchain",
+    "ethereum",
+    "robinhood",
+    "lottery",
+    "staking",
+    "defi",
+    "sdk",
+    "typescript"
+  ],
+  "author": "slvr-dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slvr-fun/sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/slvr-fun/sdk/issues"
+  },
+  "homepage": "https://github.com/slvr-fun/sdk#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "viem": "^2.40.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5.0.0",
+    "vitest": "^2.1.9"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": false
+    }
+  }
+}

package/skills/slvr-bot/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: building-slvr-bots
+description: >-
+  Build bots, scripts, keepers, or dApps that interact with SLVR — the on-chain
+  grid lottery / grid-mining game on Robinhood Chain — using the @slvr-labs/sdk
+  TypeScript SDK (built on viem). Use this whenever the user wants to place bets,
+  claim winnings, "grid mine" SLVR, compute expected value (EV) of a round, read
+  the SLVR price, stake veNFTs, automate an executor/keeper, or otherwise script
+  anything involving SLVR, the SLVR grid lottery, @slvr-labs/sdk, or Robinhood
+  Chain (chain id 4663) — even if the user doesn't name the SDK explicitly.
+---
+
+# Building SLVR bots with @slvr-labs/sdk
+
+SLVR is an on-chain game on **Robinhood Chain** (EVM, chain id `4663`). Each
+round has a **5×5 grid (25 squares)**. Players bet native ETH on squares; when the
+round resolves, one square wins **uniformly at random** (`randomnessValue % 25`),
+and that square's bettors split the ETH pot (pro-rata) plus freshly minted **SLVR**
+("grid mining"). `@slvr-labs/sdk` wraps all of this with a typed, `viem`-based API.
+
+This skill teaches you to build against it correctly. For the exhaustive method
+list, read [`references/api.md`](references/api.md). For runnable end-to-end
+programs, read the SDK's `examples/` (`quickstart-read.ts`, `quickstart-bet.ts`,
+`expected-value-strategy.ts`).
+
+## Setup
+
+```bash
+npm install @slvr-labs/sdk viem
+```
+
+The SDK **ships the chain and addresses** — never hand-roll `defineChain` or paste
+contract addresses. Fastest path is `SlvrSDK.connect` (builds resilient clients
+with Multicall3 batching + retries):
+
+```typescript
+import { SlvrSDK } from '@slvr-labs/sdk';
+const sdk = SlvrSDK.connect();                                // read-only
+const bot = SlvrSDK.connect({ privateKey: process.env.PK });  // wallet-backed
+```
+
+Or construct it yourself — read-only needs just a public client; add a wallet
+client for transactions:
+
+```typescript
+import { createPublicClient, createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { SlvrSDK, robinhoodChain, deployments } from '@slvr-labs/sdk';
+
+// Read-only (no key needed — reads only):
+const publicClient = createPublicClient({ chain: robinhoodChain, transport: http() });
+const sdk = new SlvrSDK({ publicClient, addresses: deployments.robinhood.addresses });
+
+// Wallet-backed (for bet/claim/stake/etc.):
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+const walletClient = createWalletClient({ chain: robinhoodChain, transport: http(), account });
+const sdkW = new SlvrSDK({ publicClient, walletClient, addresses: deployments.robinhood.addresses });
+```
+
+`deployments.robinhood.addresses` covers `lottery`, `staking` (the veNFT staker),
+`token`, `autoCommit`, `voteEscrow`, `slvrEthPair`, and `chainlinkEthUsd`. Pass your
+own `addresses` object to target a custom/local deployment.
+
+**Value/units:** on-chain amounts are `bigint` **wei** — use viem's `parseEther`
+(ETH string → wei) and `formatEther` (wei → string) at the boundaries. Squares are
+`0`–`24`. Write methods require the wallet client and return a tx hash; wait for it
+with `publicClient.waitForTransactionReceipt`.
+
+## Recipe: read the current round
+
+```typescript
+const roundId = await sdk.lottery.currentRoundId();
+const [open, squares] = await Promise.all([
+  sdk.lottery.roundOpen(roundId),
+  sdk.lottery.getRoundSquares(roundId), // [{ square, total, bettors }] × 25
+]);
+const pot = squares.reduce((sum, s) => sum + s.total, 0n);
+```
+
+Gate "can I still bet?" on **`bettingEnd(roundId)`** (a unix-seconds timestamp),
+not on `roundEnd` — betting can close before the round ends.
+
+## Recipe: place a bet
+
+Bets are paid in **native ETH** (the SDK sends `value` = sum of `amounts`). **No
+token approval is needed.** Spread a stake across one or more squares:
+
+```typescript
+import { parseEther } from 'viem';
+const txHash = await sdkW.lottery.bet({
+  roundId,
+  squares: [3, 7, 12],
+  amounts: [parseEther('0.001'), parseEther('0.001'), parseEther('0.001')],
+});
+await publicClient.waitForTransactionReceipt({ hash: txHash });
+```
+
+Confirm it landed with `sdk.lottery.getUserBets(roundId, address)`.
+
+## Recipe: claim winnings
+
+You can only claim a round you **won** (held the winning square) and haven't already
+claimed. Let the SDK check for you:
+
+```typescript
+if (await sdk.canClaim(roundId, account.address)) {
+  await sdkW.lottery.claim({ roundId });
+}
+// Multiple rounds:
+const claimable = await sdk.getClaimableRounds(account.address, fromRound, toRound);
+if (claimable.length) await sdkW.lottery.batchClaim(claimable);
+```
+
+To realize accumulated **mined SLVR** (separate from a round claim), use
+`sdkW.lottery.withdrawUnrefinedSlvr()` (pays out SLVR net of the refining fee).
+
+## Recipe: SLVR price in ETH and USD
+
+SLVR/ETH comes from the UniswapV2 pair; USD uses the on-chain Chainlink ETH/USD
+feed (wired for Robinhood Chain).
+
+```typescript
+const { eth, usd } = await sdk.getSlvrPrice();     // { eth: ETH per SLVR, usd: number | null }
+const ethUsd = await sdk.getEthPriceUsd();          // Chainlink ETH/USD
+```
+
+`usd` is `null` only if there's no ETH/USD source; you can also pass one:
+`sdk.getSlvrPrice({ ethUsd: 1815 })`.
+
+## Recipe: bet only when the round is +EV (grid mining)
+
+This is the key strategy. Because the winning square is uniform, mining SLVR is
+profitable **only while the pot is small** — your SLVR reward must beat the ETH you
+bleed to the protocol fee. The SDK ships the exact edge math:
+
+```typescript
+const ev = await sdk.estimateRoundEv({ stake: 0.1 /* ETH */, cashOut: false });
+// ev: { share, ethBleed, slvrMined, slvrValueEth, jackpotEvEth, netEth,
+//       edgeRatio, breakEvenPot, breakEvenSlvrPriceEth, profitable }
+if (ev.profitable) {
+  // pot is below break-even → mine this round
+}
+```
+
+`estimateRoundEv` pulls pot/emission/price on-chain. For a pure calculation (no
+I/O), use `computeGridMiningEv({ stake, pot, emissionPerRound, slvrPriceEth, ... })`.
+Mental model: **ETH is ~a wash minus the ~10% fee; SLVR emission is the real
+yield; bet when `pot < ev.breakEvenPot`.** Bet size cancels out — the edge depends
+on pot vs SLVR price, not how much you bet.
+
+See `examples/expected-value-strategy.ts` for a complete EV bot loop.
+
+## Recipe: veNFT staking
+
+Staking is by veNFT **tokenId** (not a raw ERC20 amount):
+
+```typescript
+await sdkW.staking.stake(tokenId);
+const pending = await sdk.staking.getStakerRewards(tokenId);
+await sdkW.staking.claimStakerRewards(tokenId);
+await sdkW.staking.unstake(tokenId);
+```
+
+## Gotchas that will bite you
+
+- **Bets are native ETH**, not an ERC20 — no `approve` step; the SDK attaches `value`.
+- **Gate on `bettingEnd`**, not `roundEnd`. A closed round's `bet()` reverts.
+- **`getUserBet` returns 0 after a claim** (the bet is zeroed on claim). To tell
+  "didn't bet" from "already claimed", pair it with `getHasClaimed(roundId, user)`.
+- **Emission is hub-gated**: `slvrPerRound` is a *target*; actual minted SLVR can be
+  lower. Treat EV as an estimate, not a guarantee.
+- **Read-only vs write**: reads work without a wallet client; any write throws
+  `WalletClientRequiredError` if you forgot to pass one.
+- The SDK exposes **public-use** methods only. Keeper/admin plumbing (round
+  resolution, fee routing) is intentionally not included.
+
+## Building a long-running bot
+
+1. Poll `currentRoundId` on an interval (5–15s is plenty).
+2. Skip rounds where `!roundOpen(roundId)` or you've already bet this round.
+3. Decide with `estimateRoundEv` (or your own strategy over `getRoundSquares`).
+4. Size + place the bet, wait for the receipt, log it.
+5. Periodically sweep `getClaimableRounds` → `batchClaim`.
+Handle RPC errors per-tick (try/catch) so one failure doesn't kill the loop, and
+start with tiny stakes on a funded burner key.
+
+## Using this skill with Codex (or any agent)
+
+`SKILL.md` is plain, self-contained Markdown. To use it outside Claude Code, point
+your agent at this file — e.g. reference `node_modules/@slvr-labs/sdk/skills/slvr-bot/SKILL.md`
+from your `AGENTS.md`, or paste its contents into the agent's context. The
+[`references/api.md`](references/api.md) file is the full method reference to load
+when you need a signature you don't see above.

package/skills/slvr-bot/references/api.md

@@ -0,0 +1,117 @@
+# @slvr-labs/sdk — API reference
+
+Load this when you need a signature not shown in SKILL.md. All ETH/token amounts
+are `bigint` **wei** unless noted; convert with viem `parseEther`/`formatEther`.
+Squares are `0`–`24`. Write methods need a wallet client and return a tx hash
+(`0x${string}`); wait with `publicClient.waitForTransactionReceipt`.
+
+## Contents
+- [Construction](#construction)
+- [Deployments & chain](#deployments--chain)
+- [SDK-level helpers](#sdk-level-helpers)
+- [lottery](#sdklottery)
+- [token](#sdktoken)
+- [staking (veNFT)](#sdkstaking-venft)
+- [autoCommit (V2)](#sdkautocommit-v2)
+- [price / ethUsd](#sdkprice--sdkethusd)
+- [Expected-value math](#expected-value-math-pure)
+- [Optional read-only: hub / registry / jackpot](#optional-read-only-modules)
+- [Events](#events)
+
+## Construction
+```typescript
+// Fastest — builds resilient clients (multicall batching, timeouts, retries):
+SlvrSDK.connect(opts?: ConnectOptions): SlvrSDK   // opts: { deployment?, rpcUrl?, privateKey?, account?, batchMulticall?, pollingInterval? }
+createSlvrClients(opts?): { chain, publicClient, walletClient? }   // if you want the clients yourself
+
+// Or construct directly:
+new SlvrSDK({ publicClient, walletClient?, addresses })
+```
+- `addresses` shape: `{ lottery, staking, token, autoCommit?, voteEscrow?, slvrEthPair?, chainlinkEthUsd?, multicall3?, hub?, registry?, jackpot? }`
+- **Batching:** `robinhoodChain` registers Multicall3, so `getRoundSquares`/`getUserBets` are one RPC call each. For polling bots, create the client with `batch: { multicall: true }` to auto-batch all concurrent reads.
+- Use `deployments.robinhood.addresses` for mainnet.
+- `sdk.getPublicClient()`, `sdk.getWalletClient()`, `sdk.setWalletClient(wc)`.
+- Static utils: `SlvrSDK.formatToken(value, decimals?, precision?)`, `SlvrSDK.parseToken(str, decimals?)`, `SlvrSDK.calculateBetAmounts(total, percentages[])`.
+
+## Deployments & chain
+- `deployments.robinhood`: `{ chainId: 4663, name, rpcUrl, blockExplorer, subgraphUrl, addresses }`.
+- `robinhoodChain`: a ready-made viem `Chain`.
+- `SlvrDeployment` type describes the shape.
+
+## SDK-level helpers
+- `getTimeRemaining(roundId): Promise<number>` — seconds until round end (0 if past).
+- `canClaim(roundId, user): Promise<boolean>`.
+- `getClaimableRounds(user, startRoundId, endRoundId): Promise<bigint[]>`.
+- `getSlvrPriceInEth(): Promise<number>` — ETH per SLVR (needs `slvrEthPair`).
+- `getSlvrPrice(opts?: { ethUsd?: number }): Promise<{ eth: number, usd: number | null }>`.
+- `getEthPriceUsd(): Promise<number>` — Chainlink feed (needs `chainlinkEthUsd`).
+- `estimateRoundEv(params): Promise<GridMiningEv>` — see [EV](#expected-value-math-pure).
+- `effectiveEmissionRate(gameId)`, `pendingEmission(gameId)` — require `hub`(+`registry`).
+
+## sdk.lottery
+Reads:
+- `currentRoundId()`, `roundStart(id)`, `roundEnd(id)`, `roundOpen(id)`, `bettingEnd(id)`, `latestResolvedRoundId()`.
+- `getRound(id): Promise<RoundInfo>` — flat struct: `{ roundId, requestedAt, resolved, randomnessId, randomnessValue, winningSquare, jackpotHit, singleMinerRound, singleMinerWinner, totalWager, fee, winnerTotal, potForWinners, slvrForWinners, payoutMulWad, slvrMulWad, totalUnclaimedSlvr }`.
+- `getTotalOnSquare(id, square)`, `getBettorsOnSquare(id, square)`, `getUserBet(id, square, bettor)`, `getHasClaimed(id, user)`, `hasAccount(account)`, `getDelegate(user, delegate)`.
+- `getExpectedReward(account, id)` — estimated reward (wei).
+- `getMinerState(account): Promise<MinerState>` — `{ rewardsSlvr, refinedAccrued, indexSnapshot, hasAccount }`.
+- `getRoundSquares(id): Promise<Array<{ square, total, bettors }>>` (25 entries).
+- `getUserBets(id, user): Promise<Array<{ square, amount }>>` (only nonzero).
+- `slvrPerRound()` (emission target — hub-gated), `protocolFeeBps()`, `grid()`, `hasAccount(account)`, carry pools (`carryWinnerNativePool`, `carryStakerNativeOwed`, `carryJackpotNativeOwed`, `carrySlvrPool`).
+
+Writes:
+- `bet({ roundId, squares, amounts, beneficiary? })` — native ETH; `amounts` sum is the `value`.
+- `betFor(...)` via `beneficiary` in `bet` params (bets on someone else's behalf).
+- `claim({ roundId })`.
+- `claimAdvanced({ user, roundId, recipientNative?, recipientSlvr?, bypassFee?, ethOnly? })`.
+- `batchClaim(roundIds[], user?, { waitForReceipt? }?)` → `0x${string}[]`.
+- `approveDelegate(delegate)`, `revokeDelegate(delegate)` — let a delegate claim for you.
+- `donateSlvrToJackpot(amount)`, `addEthToJackpot(value)`.
+- `withdrawUnrefinedSlvr()` — cash out mined SLVR (net of refining fee).
+- `checkpoint(account)` — force-settle miner accrual (rarely needed; claim/withdraw do it).
+
+Reactive (prefer over polling):
+- `waitForResolution(roundId, { pollIntervalMs?, timeoutMs? }): Promise<RoundInfo>` — resolves when the round settles.
+- `watchRoundResolved(cb, { onError? }): () => void` — subscribe to RoundResolved; returns unsubscribe.
+- `watchBets(cb, { roundId?, onError? }): () => void` — subscribe to BetPlaced; returns unsubscribe.
+
+## sdk.token
+Reads: `totalSupply()`, `balanceOf(account)`, `allowance(owner, spender)`, `maxSupply()`, `name()`, `symbol()`, `decimals()`.
+Writes: `transfer(to, amount)`, `approve(spender, amount)`, `transferFrom(from, to, amount)`, `burn(amount)`, `burnFrom(from, amount)`.
+
+## sdk.staking (veNFT)
+Keyed by veNFT `tokenId` (the `SlvrVoteEscrowStaking` contract).
+Reads: `getStakerRewards(tokenId)`, `getTotalWeight()`/`totalWeight()`, `balance(tokenId)`, `rewards(tokenId)`, `rewardPerWeightStored()`, `rewardPerWeightPaid(tokenId)`, `unallocated()`, `lastDistributedRoundId()`, `lottery()`, `getStakingInfo(tokenId): Promise<{ totalWeight, balance, rewards, rewardPerWeightStored }>`.
+Writes: `stake(tokenId)`, `unstake(tokenId)`, `claimStakerRewards(tokenId)`, `checkpoint(tokenId)`, `poke(tokenId)`, `pokeMany(tokenIds[])`.
+> To stake, the veNFT must be owned/approved to the staking contract (`voteEscrow` address).
+
+## sdk.autoCommit (V2)
+A repeating bet plan; a keeper executes plays for you and is reimbursed metered gas
+from your plan balance (`executeFor`/`claimFor` are permissionless — anyone can run
+an executor and earn the fee). Present only if `autoCommit` address is configured.
+- Reads: `planInfo(user)`, `needsExecution(user): { ready, reason }`, `executedRounds(user, roundId)`, `maxFeePerExecution()`, `feePremiumBps()`, consts (`UNLIMITED_PLAYS`, `MAX_PLAYS_PER_EXECUTION`, `MAX_CLAIMS_PER_EXECUTION`), `LOTTERY()`.
+- Writes: `deposit(value)`, `withdraw(amount, to)`, `configurePlan(plays, amountPerPlay, squares, bpsAlloc, autoClaim)`, `configurePlanAndDeposit(..., value)`, `disablePlan()`, `cancelPlan()`, `executeFor(user, maxPlays, claimRounds[])`, `claimFor(user, claimRounds[])`.
+- `bpsAlloc` entries must sum to `10000`.
+
+## sdk.price / sdk.ethUsd
+- `sdk.price` (`SlvrPrice`, present with `slvrEthPair`): `getReserves(): { slvrReserve, ethReserve, token0IsSlvr }`, `getPriceInEth(): number`, `getPriceInEthWad(): bigint`.
+- `sdk.ethUsd` (`ChainlinkPriceFeed`, present with `chainlinkEthUsd`): `getPrice(): number`, `getRoundData(): { answer, decimals, updatedAt }`. Constructor accepts `{ maxStalenessSec }` to reject stale answers.
+
+## Expected-value math (pure)
+`computeGridMiningEv(input): GridMiningEv` — no I/O.
+- Input: `{ stake, pot, emissionPerRound, slvrPriceEth, feeBps?, cashOut?, refineFeeBps?, jackpotPool?, jackpotOdds? }` (ETH-denominated numbers; `slvrPriceEth` = ETH per SLVR).
+- Output `GridMiningEv`: `{ share, ethBleed, slvrMined, slvrValueEth, jackpotEvEth, netEthNoJackpot, netEth, edgeRatio, breakEvenPot, breakEvenSlvrPriceEth, profitable }`.
+- Constants: `GRID_SIZE` (25), `SINGLE_SQUARE_WIN_PROBABILITY` (1/25), `PROTOCOL_FEE_BPS` (1000), `REFINING_FEE_BPS` (1000), `JACKPOT_ODDS` (625).
+- `sdk.estimateRoundEv({ stake, roundId?, cashOut?, jackpotPool?, jackpotOdds?, emissionPerRound?, slvrPriceEth?, pot? })` reads pot/emission/price on-chain then calls `computeGridMiningEv`.
+
+## Optional read-only modules
+Only present when their address is configured (the live Robinhood deployment omits them).
+- `sdk.registry` (`SlvrGameRegistry`): `gameIdOf`, `gameInfo`, `isActive`, `statusOf`, `tierOf`, `weightOf`, `maxWeightBpsOf`, `totalActiveWeight`, `gameCount`. Enums `GameStatus`, `GameTier`.
+- `sdk.jackpot` (`SlvrJackpot`): `jackpotPool()`, `jackpotSlvrPool()`.
+- `sdk.hub` (`SlvrHub`, read-only): `pendingEmission`, `emissionRatePerSec`, `targetSupply`, `maxAccrualSeconds`, `staking`, `jackpot`, `stakerSeq`, `pendingStakerRewards`.
+
+## Events
+Exported ABI groups for decoding logs (via `decodeEvent`/`decodeEvents`):
+`SlvrGridLotteryEvents` (BetPlaced, Claimed, RoundResolved, RandomnessRequested),
+`SlvrStakingEvents` (Staked, Unstaked, RewardClaimed, …, tokenId-keyed),
+`SlvrTokenEvents` (Transfer, Approval), `SlvrAutoCommitEvents`.