@slvr-labs/sdk 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -1,16 +1,1896 @@
-import { PublicClient, WalletClient, Address } from 'viem';
-import { SlvrConfig, PriceQuote } from './types';
-import { SlvrGridLottery } from './contracts/lottery';
-import { SlvrStaking } from './contracts/staking';
-import { SlvrToken } from './contracts/token';
-import { SlvrAutoCommit } from './contracts/autoCommit';
-import { SlvrHub } from './contracts/hub';
-import { SlvrGameRegistry } from './contracts/registry';
-import { SlvrJackpot } from './contracts/jackpot';
-import { SlvrPrice } from './price';
-import { ChainlinkPriceFeed } from './oracle';
-import { GridMiningEv } from './ev';
-import { ConnectOptions } from './connect';
+import * as viem from 'viem';
+import { Address, PublicClient, WalletClient, Log, Transport, Account, Chain } from 'viem';
+
+/**
+ * Configuration for the Slvr SDK
+ */
+interface SlvrConfig {
+    /** Public client for read operations */
+    publicClient: PublicClient;
+    /** Wallet client for write operations (optional, required for transactions) */
+    walletClient?: WalletClient;
+    /** Contract addresses */
+    addresses: {
+        lottery: Address;
+        staking: Address;
+        token: Address;
+        autoCommit?: Address;
+        /** SlvrHub address (optional, for emission/staker/jackpot stats and keeper/admin ops) */
+        hub?: Address;
+        /** SlvrGameRegistry address (optional, for game weight/status stats) */
+        registry?: Address;
+        /** SlvrJackpot address (optional, for jackpot pool reads) */
+        jackpot?: Address;
+        /** SLVR/ETH UniswapV2 pair address (optional, enables `sdk.price` SLVR price reads) */
+        slvrEthPair?: Address;
+        /**
+         * Chainlink-style ETH/USD price feed address (optional, enables `sdk.ethUsd`
+         * and USD-denominated prices). Only set on chains that actually have a feed.
+         */
+        chainlinkEthUsd?: Address;
+    };
+}
+/**
+ * A SLVR price quote in both ETH and USD.
+ */
+interface PriceQuote {
+    /** Price in ETH (ETH per SLVR). */
+    eth: number;
+    /** Price in USD, or `null` if no ETH/USD source was available. */
+    usd: number | null;
+}
+/**
+ * Round information
+ */
+interface RoundInfo {
+    roundId: bigint;
+    requestedAt: bigint;
+    resolved: boolean;
+    randomnessId: `0x${string}`;
+    randomnessValue: bigint;
+    winningSquare: number;
+    jackpotHit: boolean;
+    singleMinerRound: boolean;
+    singleMinerWinner: Address;
+    totalWager: bigint;
+    fee: bigint;
+    winnerTotal: bigint;
+    potForWinners: bigint;
+    slvrForWinners: bigint;
+    payoutMulWad: bigint;
+    slvrMulWad: bigint;
+    totalUnclaimedSlvr: bigint;
+}
+/**
+ * Miner state information
+ */
+interface MinerState {
+    rewardsSlvr: bigint;
+    refinedAccrued: bigint;
+    indexSnapshot: bigint;
+    hasAccount: boolean;
+}
+/**
+ * Treasury state information
+ */
+interface TreasuryState {
+    minerIndex: bigint;
+    totalUnclaimed: bigint;
+    totalRefined: bigint;
+    jackpotPool: bigint;
+}
+/**
+ * Staking information for a staked veNFT tokenId
+ */
+interface StakingInfo {
+    /** Total tracked weight across all staked tokens */
+    totalWeight: bigint;
+    /** Tracked weight (balance) of this tokenId */
+    balance: bigint;
+    /** Claimable rewards for this tokenId */
+    rewards: bigint;
+    /** Accumulated reward per unit of weight (1e18 precision) */
+    rewardPerWeightStored: bigint;
+}
+/**
+ * AutoCommit plan information
+ */
+interface AutoCommitPlan {
+    enabled: boolean;
+    nextRoundId: bigint;
+    playsRemaining: number;
+    amountPerPlay: bigint;
+    balance: bigint;
+    autoClaim: boolean;
+    squares: number[];
+    bpsAlloc: number[];
+    planStartRoundId: bigint;
+}
+/**
+ * Game status in the registry (mirrors ISlvrGameRegistry.Status)
+ */
+declare enum GameStatus {
+    Pending = 0,
+    Active = 1,
+    Paused = 2,
+    Retired = 3
+}
+/**
+ * Game tier in the registry (mirrors ISlvrGameRegistry.Tier)
+ */
+declare enum GameTier {
+    Core = 0,
+    Community = 1,
+    Experimental = 2
+}
+/**
+ * Full registry record for a game (mirrors ISlvrGameRegistry.GameInfo)
+ */
+interface GameInfo {
+    game: Address;
+    gameType: `0x${string}`;
+    status: GameStatus;
+    tier: GameTier;
+    emissionWeight: number;
+    maxWeightBps: number;
+    exists: boolean;
+}
+/**
+ * Optional transaction overrides passed through to viem's `writeContract`
+ * (e.g. to manage gas or nonce in a high-throughput bot).
+ */
+interface TxOverrides {
+    gas?: bigint;
+    nonce?: number;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    gasPrice?: bigint;
+}
+/**
+ * Bet parameters
+ */
+interface BetParams {
+    roundId: bigint;
+    squares: number[];
+    amounts: bigint[];
+    beneficiary?: Address;
+    /** Optional gas/nonce overrides for the transaction. */
+    overrides?: TxOverrides;
+}
+/**
+ * Claim parameters
+ */
+interface ClaimParams {
+    roundId: bigint;
+    /** Optional gas/nonce overrides for the transaction. */
+    overrides?: TxOverrides;
+}
+/**
+ * Advanced claim parameters (unified claim function)
+ */
+interface ClaimParamsAdvanced {
+    user: Address;
+    roundId: bigint;
+    recipientNative?: Address;
+    recipientSlvr?: Address;
+    bypassFee?: boolean;
+    ethOnly?: boolean;
+}
+
+/**
+ * Event ABIs for Slvr contracts
+ */
+declare const SlvrGridLotteryEvents: readonly [{
+    readonly name: "BetPlaced";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "beneficiary";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "total";
+    }, {
+        readonly type: "uint8[]";
+        readonly name: "squares";
+    }];
+}, {
+    readonly name: "Claimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "nativeOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "slvrOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "refinedOut";
+    }, {
+        readonly type: "uint256";
+        readonly name: "refiningFee";
+    }];
+}, {
+    readonly name: "RoundResolved";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint8";
+        readonly name: "winningSquare";
+    }, {
+        readonly type: "bool";
+        readonly name: "jackpotHit";
+    }, {
+        readonly type: "bool";
+        readonly name: "singleMinerRound";
+    }, {
+        readonly type: "address";
+        readonly name: "singleMinerWinner";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "winnerTotal";
+    }, {
+        readonly type: "uint256";
+        readonly name: "potForWinners";
+    }, {
+        readonly type: "uint256";
+        readonly name: "slvrForWinners";
+    }, {
+        readonly type: "uint256";
+        readonly name: "totalUnclaimedSlvr";
+    }];
+}, {
+    readonly name: "RandomnessRequested";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "bytes32";
+        readonly name: "randomnessId";
+    }];
+}];
+/**
+ * Events for the veNFT staker (`SlvrVoteEscrowStaking`). All staking events are
+ * keyed by the veNFT `tokenId`; there are no raw-ERC20-amount stake events.
+ */
+declare const SlvrStakingEvents: readonly [{
+    readonly name: "Staked";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "weight";
+    }];
+}, {
+    readonly name: "Unstaked";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "weight";
+    }];
+}, {
+    readonly name: "RewardClaimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+}, {
+    readonly name: "RewardDistributed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+}, {
+    readonly name: "Checkpoint";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "oldWeight";
+    }, {
+        readonly type: "uint256";
+        readonly name: "newWeight";
+    }];
+}, {
+    readonly name: "RewardsSettledOnBurn";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "uint256";
+        readonly name: "tokenId";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "owner";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+}, {
+    readonly name: "PendingRewardsClaimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+}];
+declare const SlvrTokenEvents: readonly [{
+    readonly name: "Transfer";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "from";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "to";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "value";
+    }];
+}, {
+    readonly name: "Approval";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "owner";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "spender";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "value";
+    }];
+}];
+declare const SlvrAutoCommitEvents: readonly [{
+    readonly name: "PlanConfigured";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "nextRoundId";
+    }, {
+        readonly type: "uint32";
+        readonly name: "plays";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amountPerPlay";
+    }, {
+        readonly type: "bool";
+        readonly name: "autoClaim";
+    }];
+}, {
+    readonly name: "PlanDisabled";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }];
+}, {
+    readonly name: "PlanCancelled";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "refundAmount";
+    }];
+}, {
+    readonly name: "Deposited";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }];
+}, {
+    readonly name: "Withdrawn";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "amount";
+    }, {
+        readonly type: "address";
+        readonly name: "to";
+    }];
+}, {
+    readonly name: "RoundExecuted";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint32";
+        readonly name: "playsRemaining";
+    }];
+}, {
+    readonly name: "Claimed";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "roundId";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "nativeAmount";
+    }, {
+        readonly type: "uint256";
+        readonly name: "addedToBalance";
+    }];
+}, {
+    readonly name: "BalanceUpdated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "newBalance";
+    }, {
+        readonly type: "uint256";
+        readonly name: "amountAdded";
+    }];
+}, {
+    readonly name: "ExecutorFeePaid";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "user";
+        readonly indexed: true;
+    }, {
+        readonly type: "address";
+        readonly name: "executor";
+        readonly indexed: true;
+    }, {
+        readonly type: "uint256";
+        readonly name: "fee";
+    }, {
+        readonly type: "uint256";
+        readonly name: "gasUsed";
+    }];
+}];
+/**
+ * Decode a log using the provided ABI
+ * @param abi Contract ABI
+ * @param log Log to decode
+ * @returns Decoded event or null if decoding fails
+ */
+declare function decodeEvent<T = unknown>(abi: readonly unknown[], log: Log): T | null;
+/**
+ * Filter and decode events from logs
+ * @param abi Contract ABI
+ * @param logs Array of logs
+ * @param eventName Optional event name to filter by
+ * @returns Array of decoded events
+ */
+declare function decodeEvents<T = unknown>(abi: readonly unknown[], logs: Log[], eventName?: string): T[];
+/**
+ * BetPlaced event data
+ */
+interface BetPlacedEvent {
+    eventName: 'BetPlaced';
+    args: {
+        roundId: bigint;
+        beneficiary: Address;
+        total: bigint;
+        squares: readonly number[];
+    };
+}
+/**
+ * Claimed event data
+ */
+interface ClaimedEvent {
+    eventName: 'Claimed';
+    args: {
+        roundId: bigint;
+        user: Address;
+        nativeOut: bigint;
+        slvrOut: bigint;
+        refinedOut: bigint;
+        refiningFee: bigint;
+    };
+}
+/**
+ * Round resolved event data
+ */
+interface RoundResolvedEvent {
+    eventName: 'RoundResolved';
+    args: {
+        roundId: bigint;
+        winningSquare: number;
+        jackpotHit: boolean;
+        singleMinerRound: boolean;
+        singleMinerWinner: Address;
+        winnerTotal: bigint;
+        potForWinners: bigint;
+        slvrForWinners: bigint;
+        totalUnclaimedSlvr: bigint;
+    };
+}
+/**
+ * RandomnessRequested event data
+ */
+interface RandomnessRequestedEvent {
+    eventName: 'RandomnessRequested';
+    args: {
+        roundId: bigint;
+        randomnessId: `0x${string}`;
+    };
+}
+
+/**
+ * SlvrGridLottery contract interface
+ */
+declare class SlvrGridLottery {
+    private publicClient;
+    private walletClient?;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, address: Address);
+    /**
+     * Update the wallet client
+     * @param walletClient New wallet client
+     */
+    setWalletClient(walletClient: WalletClient | undefined): void;
+    /**
+     * Get the current round ID
+     */
+    currentRoundId(): Promise<bigint>;
+    /**
+     * Get round start time
+     */
+    roundStart(roundId: bigint): Promise<bigint>;
+    /**
+     * Get round end time
+     */
+    roundEnd(roundId: bigint): Promise<bigint>;
+    /**
+     * Check if round is open for betting
+     */
+    roundOpen(roundId: bigint): Promise<boolean>;
+    /**
+     * Get the betting cutoff timestamp (unix seconds) for a round.
+     *
+     * Bets are only accepted until this time, which can be earlier than
+     * {@link roundEnd}. Bots deciding whether they can still bet should gate on
+     * this rather than on `roundEnd`.
+     */
+    bettingEnd(roundId: bigint): Promise<bigint>;
+    /**
+     * Estimate the reward an account would receive for a round, in wei.
+     *
+     * Thin pass-through to the contract's `getExpectedReward`. Useful for sizing
+     * bets or deciding whether a claim is worth the gas.
+     */
+    getExpectedReward(account: Address, roundId: bigint): Promise<bigint>;
+    /**
+     * Get the latest resolved round ID (type(uint256).max sentinel when none resolved yet)
+     */
+    latestResolvedRoundId(): Promise<bigint>;
+    /**
+     * Get full round information
+     */
+    getRound(roundId: bigint): Promise<RoundInfo>;
+    /**
+     * Get a compact, batched snapshot of a round's live state — the fields a bot
+     * checks every tick — in one shot. Defaults to the current round.
+     *
+     * `secondsUntilBettingClose` is computed from the chain's `block.timestamp`
+     * (not the local clock), so it's accurate even if your device clock drifts.
+     * With a multicall-batching client the reads collapse into ~2 RPC calls.
+     */
+    getRoundState(roundId?: bigint): Promise<{
+        roundId: bigint;
+        open: boolean;
+        resolved: boolean;
+        bettingEnd: bigint;
+        roundEnd: bigint;
+        totalWager: bigint;
+        winningSquare: number;
+        secondsUntilBettingClose: number;
+    }>;
+    /**
+     * Get the jackpot contract address for a round (zero address if no jackpot is
+     * set). Read that contract's `jackpotPool()` for the pool balance — or use the
+     * SDK helper `getJackpotPool(roundId)`.
+     */
+    getRoundJackpot(roundId: bigint): Promise<Address>;
+    /**
+     * Get total amount bet on a square for a round
+     */
+    getTotalOnSquare(roundId: bigint, square: number): Promise<bigint>;
+    /**
+     * Get number of bettors on a square for a round
+     */
+    getBettorsOnSquare(roundId: bigint, square: number): Promise<bigint>;
+    /**
+     * Get a user's bet amount on a square for a round
+     */
+    getUserBet(roundId: bigint, square: number, bettor: Address): Promise<bigint>;
+    /**
+     * Check if a user has claimed rewards for a round
+     */
+    getHasClaimed(roundId: bigint, user: Address): Promise<boolean>;
+    /**
+     * Get miner state for an account
+     */
+    getMinerState(account: Address): Promise<MinerState>;
+    /**
+     * Check if an account exists
+     */
+    hasAccount(account: Address): Promise<boolean>;
+    /**
+     * Get carry-over winner native pool (when no winners)
+     */
+    carryWinnerNativePool(): Promise<bigint>;
+    /**
+     * Get staker rewards that failed to distribute (owed)
+     */
+    carryStakerNativeOwed(): Promise<bigint>;
+    /**
+     * Get jackpot funds that failed to add (owed)
+     */
+    carryJackpotNativeOwed(): Promise<bigint>;
+    /**
+     * Get carry-over SLVR pool
+     */
+    carrySlvrPool(): Promise<bigint>;
+    /**
+     * Get the configured SLVR-per-round value.
+     *
+     * NOTE: This is no longer the authoritative emission number. Emission is hub-gated: the amount
+     * actually minted each round is bounded by the game's streamed emission budget on SlvrHub
+     * (see SlvrHub.pendingEmission / mintReward). Treat this only as the requested/target value.
+     */
+    slvrPerRound(): Promise<bigint>;
+    /**
+     * Get protocol fee in basis points
+     */
+    protocolFeeBps(): Promise<number>;
+    /**
+     * Get grid size (should be 25)
+     */
+    grid(): Promise<number>;
+    /**
+     * Get account deposit amount
+     */
+    accountDeposit(): Promise<bigint>;
+    /**
+     * Place a bet on the current round
+     * Note: The contract will automatically handle account deposit for new accounts.
+     * If the beneficiary is a new account, ensure msg.value >= ACCOUNT_DEPOSIT + total bet amount.
+     * @param params Bet parameters
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    bet(params: BetParams): Promise<`0x${string}`>;
+    /**
+     * Preflight a bet with `eth_call` (no transaction sent). Resolves if the bet
+     * would succeed; otherwise throws a {@link SlvrRevertError} with the decoded
+     * custom error (e.g. `RoundNotOpen`, `InsufficientValue`). Catch reverts before
+     * spending gas.
+     */
+    simulateBet(params: BetParams): Promise<void>;
+    /**
+     * Claim rewards for a round
+     * @param params Claim parameters
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    claim(params: ClaimParams): Promise<`0x${string}`>;
+    /**
+     * Advanced claim function covering all claim variants
+     * Handles: user vs delegate, native/SLVR recipients, bypassFee, ethOnly
+     * @param params Advanced claim parameters
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    claimAdvanced(params: ClaimParamsAdvanced): Promise<`0x${string}`>;
+    /**
+     * Batch claim rewards for multiple rounds
+     * Note: This sends multiple transactions sequentially. For better UX, consider
+     * using a multicall contract or batching in your application layer.
+     * @param roundIds Array of round IDs to claim
+     * @param user User address to claim for (defaults to wallet client account)
+     * @param options Optional configuration
+     * @param options.waitForReceipt Whether to wait for each transaction receipt (default: false)
+     * @returns Array of transaction hashes
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    batchClaim(roundIds: bigint[], user?: Address, options?: {
+        waitForReceipt?: boolean;
+    }): Promise<`0x${string}`[]>;
+    /**
+     * Approve a delegate to claim rewards on your behalf
+     */
+    approveDelegate(delegate: Address): Promise<`0x${string}`>;
+    /**
+     * Revoke a delegate's approval to claim on your behalf
+     */
+    revokeDelegate(delegate: Address): Promise<`0x${string}`>;
+    /**
+     * Check if a delegate is approved for a user
+     */
+    getDelegate(user: Address, delegate: Address): Promise<boolean>;
+    /**
+     * Donate SLVR tokens directly to the jackpot pool.
+     * Note: caller must have approved the lottery to spend `amount` of SLVR beforehand.
+     */
+    donateSlvrToJackpot(amount: bigint): Promise<`0x${string}`>;
+    /**
+     * Add ETH (native) tokens to the jackpot pool
+     * @param value Amount of native ETH to deposit
+     */
+    addEthToJackpot(value: bigint): Promise<`0x${string}`>;
+    /**
+     * Withdraw your accumulated mined SLVR (the "refine and cash out" path).
+     *
+     * Settles your miner accrual (auto-checkpoints) and transfers your SLVR out,
+     * net of the refining fee. This is the function a mining bot wants to realize
+     * SLVR rewards outside of a specific round claim. Reverts if you have nothing to
+     * withdraw. The exact `(totalPayout, refiningFee)` are in the emitted `Claimed`
+     * event; this returns the transaction hash.
+     */
+    withdrawUnrefinedSlvr(): Promise<`0x${string}`>;
+    /**
+     * Force on-chain settlement of a miner's refined-reward accrual (lazy
+     * "checkpoint"). Permissionless — you can checkpoint any account.
+     *
+     * This only updates accounting (rolls index growth into `refinedAccrued`); it
+     * moves no tokens. You rarely need it: `claim` and {@link withdrawUnrefinedSlvr}
+     * both checkpoint internally, and the up-to-date figure can be derived off-chain
+     * from {@link getMinerState}. Use it when you want state settled without a
+     * claim/withdraw — e.g. to make a subsequent `getMinerState` read exact.
+     */
+    checkpoint(account: Address): Promise<`0x${string}`>;
+    /**
+     * Get all square data for a round
+     */
+    getRoundSquares(roundId: bigint): Promise<Array<{
+        square: number;
+        total: bigint;
+        bettors: bigint;
+    }>>;
+    /**
+     * Get user's bets for a round
+     */
+    getUserBets(roundId: bigint, user: Address): Promise<Array<{
+        square: number;
+        amount: bigint;
+    }>>;
+    /**
+     * Wait until a round is resolved, resolving with its final {@link RoundInfo}.
+     * Polls `getRound` on an interval — handy for "bet, then claim once it settles".
+     *
+     * @param opts.pollIntervalMs how often to check (default 4000)
+     * @param opts.timeoutMs give up after this long (default: wait indefinitely)
+     * @throws {Error} if `timeoutMs` elapses before resolution
+     */
+    waitForResolution(roundId: bigint, opts?: {
+        pollIntervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<RoundInfo>;
+    /**
+     * Subscribe to `RoundResolved` events. Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const stop = sdk.lottery.watchRoundResolved((e) => {
+     *   console.log(`round ${e.roundId} won by square ${e.winningSquare}`);
+     * });
+     * // later: stop();
+     * ```
+     */
+    watchRoundResolved(onResolved: (event: RoundResolvedEvent['args']) => void, opts?: {
+        onError?: (error: Error) => void;
+    }): () => void;
+    /**
+     * Subscribe to `BetPlaced` events (optionally for one round). Returns an
+     * unsubscribe function. Useful for reacting to pot changes in real time.
+     */
+    watchBets(onBet: (event: BetPlacedEvent['args']) => void, opts?: {
+        roundId?: bigint;
+        onError?: (error: Error) => void;
+    }): () => void;
+}
+
+/**
+ * SlvrVoteEscrowStaking contract interface.
+ *
+ * This is a veNFT-based staker: stakers deposit a vote-escrow NFT (by tokenId) rather than a raw
+ * ERC20 amount. Rewards accrue per unit of the token's tracked weight and are claimed per tokenId.
+ */
+declare class SlvrStaking {
+    private publicClient;
+    private walletClient?;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, address: Address);
+    /**
+     * Update the wallet client
+     * @param walletClient New wallet client
+     */
+    setWalletClient(walletClient: WalletClient | undefined): void;
+    /**
+     * Get claimable rewards for a staked veNFT tokenId
+     */
+    getStakerRewards(tokenId: bigint): Promise<bigint>;
+    /**
+     * Get the total tracked weight across all staked tokens
+     */
+    getTotalWeight(): Promise<bigint>;
+    /**
+     * Get the accumulated reward per unit of weight (1e18 precision)
+     */
+    rewardPerWeightStored(): Promise<bigint>;
+    /**
+     * Get the last rewardPerWeightStored snapshot recorded for a tokenId
+     */
+    rewardPerWeightPaid(tokenId: bigint): Promise<bigint>;
+    /**
+     * Get the tracked weight (balance) for a staked tokenId
+     */
+    balance(tokenId: bigint): Promise<bigint>;
+    /**
+     * Get the accrued (checkpointed) claimable rewards stored for a tokenId
+     */
+    rewards(tokenId: bigint): Promise<bigint>;
+    /**
+     * Get the total tracked weight (public storage var)
+     */
+    totalWeight(): Promise<bigint>;
+    /**
+     * Get unallocated rewards (distributed while no weight was staked)
+     */
+    unallocated(): Promise<bigint>;
+    /**
+     * Get the last distributed round ID (type(uint256).max sentinel when none)
+     */
+    lastDistributedRoundId(): Promise<bigint>;
+    /**
+     * Get the lottery address authorized to distribute rewards
+     */
+    lottery(): Promise<Address>;
+    /**
+     * Get complete staking info for a staked veNFT tokenId
+     */
+    getStakingInfo(tokenId: bigint): Promise<StakingInfo>;
+    /**
+     * Stake a vote-escrow NFT by tokenId
+     * @param tokenId The veNFT token ID to stake
+     * @returns Transaction hash
+     */
+    stake(tokenId: bigint): Promise<`0x${string}`>;
+    /**
+     * Unstake a vote-escrow NFT by tokenId
+     * @param tokenId The veNFT token ID to unstake
+     * @returns Transaction hash
+     */
+    unstake(tokenId: bigint): Promise<`0x${string}`>;
+    /**
+     * Claim staker rewards for a tokenId
+     * @param tokenId The veNFT token ID to claim rewards for
+     * @returns Transaction hash
+     */
+    claimStakerRewards(tokenId: bigint): Promise<`0x${string}`>;
+    /**
+     * Checkpoint a token's reward accounting
+     * @param tokenId The veNFT token ID to checkpoint
+     * @returns Transaction hash
+     */
+    checkpoint(tokenId: bigint): Promise<`0x${string}`>;
+    /**
+     * Poke a token to refresh its tracked weight
+     * @param tokenId The veNFT token ID to poke
+     * @returns Transaction hash
+     */
+    poke(tokenId: bigint): Promise<`0x${string}`>;
+    /**
+     * Poke many tokens to refresh their tracked weight in one call
+     * @param tokenIds The veNFT token IDs to poke
+     * @returns Transaction hash
+     */
+    pokeMany(tokenIds: bigint[]): Promise<`0x${string}`>;
+}
+
+/**
+ * SlvrToken contract interface
+ */
+declare class SlvrToken {
+    private publicClient;
+    private walletClient?;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, address: Address);
+    /**
+     * Update the wallet client
+     * @param walletClient New wallet client
+     */
+    setWalletClient(walletClient: WalletClient | undefined): void;
+    /**
+     * Get total supply
+     */
+    totalSupply(): Promise<bigint>;
+    /**
+     * Get balance of an account
+     */
+    balanceOf(account: Address): Promise<bigint>;
+    /**
+     * Get allowance
+     */
+    allowance(owner: Address, spender: Address): Promise<bigint>;
+    /**
+     * Get token name
+     */
+    name(): Promise<string>;
+    /**
+     * Get token symbol
+     */
+    symbol(): Promise<string>;
+    /**
+     * Get token decimals
+     */
+    decimals(): Promise<number>;
+    /**
+     * Get maximum supply
+     */
+    maxSupply(): Promise<bigint>;
+    /**
+     * Transfer tokens
+     * @param to Recipient address
+     * @param amount Amount to transfer
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    transfer(to: Address, amount: bigint): Promise<`0x${string}`>;
+    /**
+     * Approve spender
+     * @param spender Address to approve
+     * @param amount Amount to approve
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    approve(spender: Address, amount: bigint): Promise<`0x${string}`>;
+    /**
+     * Transfer from (requires approval)
+     * @param from Sender address
+     * @param to Recipient address
+     * @param amount Amount to transfer
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    transferFrom(from: Address, to: Address, amount: bigint): Promise<`0x${string}`>;
+    /**
+     * Burn tokens
+     * @param amount Amount to burn
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if amount is invalid
+     * @throws ContractCallError if contract call fails
+     */
+    burn(amount: bigint): Promise<`0x${string}`>;
+    /**
+     * Burn tokens from account
+     * @param account Account to burn from
+     * @param amount Amount to burn
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    burnFrom(account: Address, amount: bigint): Promise<`0x${string}`>;
+}
+
+/**
+ * SlvrAutoCommitV2 contract interface
+ *
+ * V2 economics: executors calling executeFor/claimFor are reimbursed their
+ * metered gas (plus a premium, capped at maxFeePerExecution — both owner-tunable
+ * within hard ceilings) from the user's plan balance — there is no flat
+ * AUTOMATION_FEE and the execution functions are nonpayable. Claimable winning
+ * rounds are discovered off-chain and passed in explicitly via claimRounds.
+ */
+declare class SlvrAutoCommit {
+    private publicClient;
+    private walletClient?;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, walletClient: WalletClient | undefined, address: Address);
+    /**
+     * Update the wallet client
+     * @param walletClient New wallet client
+     */
+    setWalletClient(walletClient: WalletClient | undefined): void;
+    /**
+     * Get plan information for a user
+     */
+    planInfo(user: Address): Promise<AutoCommitPlan>;
+    /**
+     * Check whether a plan is ready to execute, and if not, why
+     */
+    needsExecution(user: Address): Promise<{
+        ready: boolean;
+        reason: string;
+    }>;
+    /**
+     * Check whether a specific round has already been executed for a user
+     */
+    executedRound(user: Address, roundId: bigint): Promise<boolean>;
+    /**
+     * Get lottery contract address
+     */
+    lottery(): Promise<Address>;
+    /**
+     * Get the sentinel plays value meaning "unlimited plays"
+     */
+    unlimitedPlays(): Promise<number>;
+    /**
+     * Get max plays per execution
+     */
+    maxPlaysPerExecution(): Promise<number>;
+    /**
+     * Get max claim rounds accepted per execution
+     */
+    maxClaimsPerExecution(): Promise<bigint>;
+    /**
+     * Get the current cap on the executor fee reimbursed per execution
+     * (owner-tunable within the contract's hard ceiling)
+     */
+    maxFeePerExecution(): Promise<bigint>;
+    /**
+     * Get the current executor-fee premium in basis points
+     * (owner-tunable within the contract's hard ceiling)
+     */
+    feePremiumBps(): Promise<number>;
+    /**
+     * Deposit native tokens to auto-commit plan
+     * @param value Amount to deposit
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if amount is invalid
+     * @throws ContractCallError if contract call fails
+     */
+    deposit(value: bigint): Promise<`0x${string}`>;
+    /**
+     * Withdraw from auto-commit plan
+     * @param amount Amount to withdraw
+     * @param to Recipient address
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    withdraw(amount: bigint, to: Address): Promise<`0x${string}`>;
+    /**
+     * Configure auto-commit plan
+     * @param plays Number of plays (UNLIMITED_PLAYS = 4294967295 for unlimited;
+     *              forced to unlimited on-chain when autoClaim is true)
+     * @param amountPerPlay Amount per play
+     * @param squares Square indices to bet on
+     * @param bpsAlloc Basis points allocation for each square (must sum to 10000)
+     * @param autoClaim Whether the keeper should claim winnings back into the plan balance
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    configurePlan(plays: number, amountPerPlay: bigint, squares: number[], bpsAlloc: number[], autoClaim: boolean): Promise<`0x${string}`>;
+    /**
+     * Configure auto-commit plan and deposit funds in a single transaction
+     * @param plays Number of plays (see configurePlan)
+     * @param amountPerPlay Amount per play
+     * @param squares Square indices to bet on
+     * @param bpsAlloc Basis points allocation for each square (must sum to 10000)
+     * @param autoClaim Whether the keeper should claim winnings back into the plan balance
+     * @param value Amount to deposit
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    configurePlanAndDeposit(plays: number, amountPerPlay: bigint, squares: number[], bpsAlloc: number[], autoClaim: boolean, value: bigint): Promise<`0x${string}`>;
+    /**
+     * Disable auto-commit plan
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ContractCallError if contract call fails
+     */
+    disablePlan(): Promise<`0x${string}`>;
+    /**
+     * Cancel the plan and refund the entire remaining balance to the caller
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ContractCallError if contract call fails
+     */
+    cancelPlan(): Promise<`0x${string}`>;
+    /**
+     * Execute auto-commit plan for a user (anyone can call).
+     * The caller is reimbursed metered gas + premium from the user's plan balance.
+     * @param user User address
+     * @param maxPlays Maximum number of plays to execute
+     * @param claimRounds Winning round ids to claim into the plan balance before
+     *        betting (discovered off-chain; non-claimable entries are no-ops)
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    executeFor(user: Address, maxPlays: number, claimRounds?: bigint[]): Promise<`0x${string}`>;
+    /**
+     * Claim winning rounds into a user's plan balance without betting (anyone can
+     * call). Useful when the plan balance is too low to bet until winnings land.
+     * @param user User address
+     * @param claimRounds Winning round ids to claim (discovered off-chain)
+     * @returns Transaction hash
+     * @throws WalletClientRequiredError if wallet client is not available
+     * @throws ValidationError if inputs are invalid
+     * @throws ContractCallError if contract call fails
+     */
+    claimFor(user: Address, claimRounds: bigint[]): Promise<`0x${string}`>;
+    private validatePlanConfig;
+}
+
+/**
+ * SlvrHub contract interface (read-only).
+ *
+ * The hub is the protocol emission/sink router: it gates per-game SLVR emission, fans many games
+ * into one shared veNFT staker stream, and into one shared jackpot. These bindings expose the
+ * informational view surface (emission rate, pending emission, sink addresses); the hub's
+ * fee-routing writes are keeper/protocol operations and are intentionally not included.
+ */
+declare class SlvrHub {
+    private publicClient;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, _walletClient: WalletClient | undefined, address: Address);
+    setWalletClient(_walletClient: WalletClient | undefined): void;
+    /**
+     * Accrued-but-unminted SLVR emission currently available to a game (its bucket + streamed since
+     * last accrual, hard-capped at one maxAccrualSeconds window of the game's effective rate).
+     */
+    pendingEmission(gameId: bigint): Promise<bigint>;
+    /**
+     * Base SLVR/sec emission rate across the whole active game set
+     */
+    emissionRatePerSec(): Promise<bigint>;
+    /**
+     * Soft-cap target supply (0 => use token MAX_SUPPLY)
+     */
+    targetSupply(): Promise<bigint>;
+    /**
+     * Idle-forfeiture window: cap on dt per accrual (seconds)
+     */
+    maxAccrualSeconds(): Promise<bigint>;
+    /**
+     * Address of the shared veNFT staking contract
+     */
+    staking(): Promise<Address>;
+    /**
+     * Address of the shared jackpot contract
+     */
+    jackpot(): Promise<Address>;
+    /**
+     * Hub-owned sequential counter used to feed the staking contract's round numbering
+     */
+    stakerSeq(): Promise<bigint>;
+    /**
+     * Native staker rewards received but not yet flushed to the staking stream
+     */
+    pendingStakerRewards(): Promise<bigint>;
+}
+
+/**
+ * SlvrGameRegistry contract interface (read-only surface).
+ *
+ * Single source of truth for which games exist, their status/tier, and their share of the shared
+ * emission stream.
+ */
+declare class SlvrGameRegistry {
+    private publicClient;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, _walletClient: WalletClient | undefined, address: Address);
+    /** Read-only contract: no wallet client needed. Kept for a consistent SDK surface. */
+    setWalletClient(_walletClient: WalletClient | undefined): void;
+    /**
+     * Registry id for a game address (0 if not registered; ids are 1-based)
+     */
+    gameIdOf(game: Address): Promise<bigint>;
+    /**
+     * Full record for a game id
+     */
+    gameInfo(gameId: bigint): Promise<GameInfo>;
+    /**
+     * Is this address a registered, Active game?
+     */
+    isActive(game: Address): Promise<boolean>;
+    /**
+     * Status enum for a game id
+     */
+    statusOf(gameId: bigint): Promise<GameStatus>;
+    /**
+     * Tier enum for a game id
+     */
+    tierOf(gameId: bigint): Promise<GameTier>;
+    /**
+     * Emission weight (relative share of the global stream) for a game id
+     */
+    weightOf(gameId: bigint): Promise<bigint>;
+    /**
+     * Max realized-fraction ceiling (bps of 10000) for a game id
+     */
+    maxWeightBpsOf(gameId: bigint): Promise<number>;
+    /**
+     * Sum of emissionWeight across all Active games (denominator for the split)
+     */
+    totalActiveWeight(): Promise<bigint>;
+    /**
+     * Number of registered games
+     */
+    gameCount(): Promise<bigint>;
+}
+
+/**
+ * SlvrJackpot contract interface (read-only pool surface).
+ */
+declare class SlvrJackpot {
+    private publicClient;
+    private address;
+    private static readonly ABI;
+    constructor(publicClient: PublicClient, _walletClient: WalletClient | undefined, address: Address);
+    /** Read-only contract: no wallet client needed. Kept for a consistent SDK surface. */
+    setWalletClient(_walletClient: WalletClient | undefined): void;
+    /**
+     * Native (ETH) jackpot pool balance
+     */
+    jackpotPool(): Promise<bigint>;
+    /**
+     * SLVR jackpot pool balance
+     */
+    jackpotSlvrPool(): Promise<bigint>;
+}
+
+/**
+ * Reserves of the SLVR/ETH UniswapV2 pair, with the token ordering resolved.
+ */
+interface SlvrReserves {
+    /** SLVR reserve, in wei (18 decimals). */
+    slvrReserve: bigint;
+    /** ETH (WETH) reserve, in wei (18 decimals). */
+    ethReserve: bigint;
+    /** Whether SLVR is `token0` in the pair (ordering is resolved for you). */
+    token0IsSlvr: boolean;
+}
+/**
+ * Reads the SLVR price from the SLVR/ETH UniswapV2 pair.
+ *
+ * Mirrors the web app's price logic: it reads the pair's `getReserves()` and
+ * `token0()`, figures out which reserve is SLVR (never assumes ordering), and
+ * prices SLVR as `ethReserve / slvrReserve`. Both tokens are 18-decimal, so the
+ * raw reserve ratio is already ETH-per-SLVR.
+ *
+ * This is a **spot** price straight from reserves — no TWAP, no slippage model.
+ * Fine for sizing bets and EV estimates; do not use it as an oracle for anything
+ * that must resist manipulation.
+ *
+ * @example
+ * ```typescript
+ * import { SlvrPrice } from '@slvr-labs/sdk';
+ * const price = new SlvrPrice(publicClient, pairAddress, slvrTokenAddress);
+ * const ethPerSlvr = await price.getPriceInEth();
+ * ```
+ */
+declare class SlvrPrice {
+    private publicClient;
+    private pairAddress;
+    private slvrTokenAddress;
+    private static readonly PAIR_ABI;
+    constructor(publicClient: PublicClient, pairAddress: Address, slvrTokenAddress: Address);
+    /** Read the pair reserves and resolve which side is SLVR. */
+    getReserves(): Promise<SlvrReserves>;
+    /**
+     * SLVR price in ETH (ETH per SLVR), as a floating-point number.
+     * @throws {Error} if the pair has no SLVR liquidity (zero reserve).
+     */
+    getPriceInEth(): Promise<number>;
+    /**
+     * SLVR price in ETH as a WAD (1e18-scaled `bigint`), for callers that want to
+     * stay in integer math: `priceWad = ethReserve * 1e18 / slvrReserve`.
+     * @throws {Error} if the pair has no SLVR liquidity (zero reserve).
+     */
+    getPriceInEthWad(): Promise<bigint>;
+}
+
+/**
+ * Reads a Chainlink-style price feed (`AggregatorV3Interface`).
+ *
+ * Works with any standard aggregator — the canonical use here is an **ETH/USD**
+ * feed, which lets the SDK convert the pair-derived SLVR/ETH price into USD.
+ *
+ * Robinhood Chain has a Chainlink ETH/USD feed (`ETH / USD`, 8 decimals), wired
+ * into `deployments.robinhood.addresses.chainlinkEthUsd`, so `sdk.ethUsd` and USD
+ * prices work out of the box there. On chains without a feed, pass a USD price
+ * into {@link SlvrSDK.getSlvrPrice} instead, or wire your own off-chain source.
+ *
+ * @example
+ * ```typescript
+ * import { ChainlinkPriceFeed } from '@slvr-labs/sdk';
+ * const ethUsd = new ChainlinkPriceFeed(publicClient, ethUsdFeedAddress);
+ * const price = await ethUsd.getPrice(); // e.g. 1797.35
+ * ```
+ */
+declare class ChainlinkPriceFeed {
+    private publicClient;
+    private feedAddress;
+    private maxStalenessSec?;
+    private static readonly ABI;
+    /**
+     * @param publicClient viem public client
+     * @param feedAddress the aggregator address
+     * @param opts.maxStalenessSec if set, {@link getPrice} throws when the feed's
+     *   `updatedAt` is older than this many seconds (checked against the local
+     *   clock). Off by default — enable it only where the local clock is trusted.
+     */
+    constructor(publicClient: PublicClient, feedAddress: Address, opts?: {
+        maxStalenessSec?: number;
+    });
+    /** Raw `latestRoundData` answer plus the feed's decimals. */
+    getRoundData(): Promise<{
+        answer: bigint;
+        decimals: number;
+        updatedAt: bigint;
+    }>;
+    /**
+     * The feed price as a floating-point number (`answer / 10 ** decimals`).
+     * @throws {Error} if the answer is non-positive, or (when `maxStalenessSec` is
+     *   set) if the feed is stale.
+     */
+    getPrice(): Promise<number>;
+}
+
+/**
+ * Expected-value math for SLVR grid mining.
+ *
+ * This is a direct port of the protocol's "grid-mining edge" model — the same
+ * math the web calculator uses — so an SDK bot and the site agree.
+ *
+ * ## The model
+ *
+ * The winning square each round is chosen **uniformly** at random over the
+ * {@link GRID_SIZE}-square grid (`randomnessValue % 25`), independent of how much
+ * was wagered where. Wagers only decide how the pot is split *among* the winners.
+ *
+ * The strategy this models is **grid mining**: spread your stake across the grid
+ * in proportion to the current pot so you always hold a `share = stake / pot`
+ * slice of whichever square wins. Under that strategy, per round:
+ *
+ * - **ETH is a wash minus the protocol fee.** The whole pot minus the fee is paid
+ *   pro-rata to the winning square, and your slice of it equals your slice of the
+ *   pot — i.e. you get back `(1 - fee) * stake` in expectation. So your ETH cost
+ *   ("bleed") is exactly `feeFraction * stake`.
+ * - **SLVR is mined pro-rata:** `slvrMined = share * emissionPerRound`. (Whether a
+ *   round is "single-miner" — winner-take-all SLVR — changes the *variance*, not
+ *   the mean, so it does not affect EV.)
+ * - **Jackpot** pays your `share` of the pool with probability `1 / jackpotOdds`.
+ *
+ * Net EV per round (in ETH):
+ *
+ * ```
+ * netEth = slvrMined * slvrPriceEth * realize   // SLVR value (realize = 1 - refineFee when cashing out)
+ *        - feeFraction * stake                   // ETH bleed
+ *        + (1 / jackpotOdds) * share * jackpotPool
+ * ```
+ *
+ * Because both the SLVR reward and the bleed scale with `stake`, **the edge does
+ * not depend on how much you bet** — only on `pot` vs `slvrPriceEth`. A smaller
+ * pot means a bigger `share`, so mining is profitable while the pot is *below* the
+ * {@link GridMiningEv.breakEvenPot break-even pot}.
+ */
+/** Grid size — the winning square is `randomnessValue % GRID_SIZE`. */
+declare const GRID_SIZE = 25;
+/** Probability any one square wins a round (uniform selection). */
+declare const SINGLE_SQUARE_WIN_PROBABILITY: number;
+/** Default protocol fee in basis points (10%), taken out of the pot before winners. */
+declare const PROTOCOL_FEE_BPS = 1000;
+/** Default SLVR refining fee in basis points (10%), charged when you cash SLVR out to ETH. */
+declare const REFINING_FEE_BPS = 1000;
+/** Default jackpot odds — the jackpot fires when `randomnessValue % JACKPOT_ODDS == 0`. */
+declare const JACKPOT_ODDS = 625;
+/**
+ * Inputs to {@link computeGridMiningEv}. All ETH-denominated values are plain
+ * numbers in whole ETH (not wei) and `slvrPriceEth` is ETH per SLVR — use
+ * `Number(formatEther(...))` to convert on-chain `bigint` wei.
+ */
+interface GridMiningEvInput {
+    /** ETH you would commit to the round. */
+    stake: number;
+    /** Total ETH currently wagered in the round (the pot). */
+    pot: number;
+    /** SLVR minted to the winning square this round (the emission target). */
+    emissionPerRound: number;
+    /** Price of SLVR in ETH (ETH per SLVR). */
+    slvrPriceEth: number;
+    /** Protocol fee in bps. Defaults to {@link PROTOCOL_FEE_BPS} (1000 = 10%). */
+    feeBps?: number;
+    /**
+     * If `true`, value mined SLVR net of the refining fee (you intend to cash out
+     * to ETH). If `false` (default), value it at full price (you hold/stake it).
+     */
+    cashOut?: boolean;
+    /** Refining fee in bps, applied only when `cashOut` is true. Defaults to {@link REFINING_FEE_BPS}. */
+    refineFeeBps?: number;
+    /** ETH currently in the jackpot pool. Defaults to 0 (jackpot ignored). */
+    jackpotPool?: number;
+    /** Jackpot odds (1-in-N per round). Defaults to {@link JACKPOT_ODDS} (625). */
+    jackpotOdds?: number;
+}
+/** Result of {@link computeGridMiningEv}. All ETH-denominated. */
+interface GridMiningEv {
+    /** Your fraction of the pot, `stake / pot`. */
+    share: number;
+    /** ETH lost per round to the protocol fee, `feeFraction * stake`. */
+    ethBleed: number;
+    /** SLVR mined per round, `share * emissionPerRound`. */
+    slvrMined: number;
+    /** ETH value of the mined SLVR after the realize factor. */
+    slvrValueEth: number;
+    /** Expected jackpot contribution per round, in ETH. */
+    jackpotEvEth: number;
+    /** Net EV per round excluding the jackpot, in ETH. */
+    netEthNoJackpot: number;
+    /** Net EV per round including the jackpot, in ETH. */
+    netEth: number;
+    /** Net EV as a fraction of stake (`netEth / stake`) — the per-round edge. */
+    edgeRatio: number;
+    /** Pot size at which `netEth` crosses zero. Mining is profitable below this. */
+    breakEvenPot: number;
+    /** SLVR price (ETH) at which `netEth` crosses zero for the current pot. */
+    breakEvenSlvrPriceEth: number;
+    /** Whether the round is +EV (`netEth > 0`). */
+    profitable: boolean;
+}
+/**
+ * Compute the per-round expected value of grid mining for a given stake, pot,
+ * emission and SLVR price. Pure function — does no I/O.
+ *
+ * @throws {Error} if `stake` or `pot` is not positive.
+ *
+ * @example
+ * ```typescript
+ * import { computeGridMiningEv } from '@slvr-labs/sdk';
+ *
+ * const ev = computeGridMiningEv({
+ *   stake: 0.1,            // 0.1 ETH per round
+ *   pot: 0.5,              // 0.5 ETH in the pot
+ *   emissionPerRound: 1,   // 1 SLVR minted/round
+ *   slvrPriceEth: 0.0005,  // SLVR price in ETH
+ *   jackpotPool: 5,        // 5 ETH jackpot
+ * });
+ * if (ev.profitable) console.log(`+${ev.netEth} ETH/round, edge ${(ev.edgeRatio * 100).toFixed(1)}%`);
+ * ```
+ */
+declare function computeGridMiningEv(input: GridMiningEvInput): GridMiningEv;
+
+/**
+ * A known Slvr deployment: chain metadata plus the on-chain addresses the SDK needs.
+ *
+ * Addresses mirror the canonical values the production interface ships
+ * (`interface/config/constants.ts`). `hub`, `registry`, and `jackpot` are only
+ * present on deployments that run the emission/sink hub architecture — they are
+ * omitted here for deployments that don't, and the corresponding `sdk.hub` /
+ * `sdk.registry` / `sdk.jackpot` bindings will be `undefined`.
+ */
+interface SlvrDeployment {
+    /** EVM chain id */
+    chainId: number;
+    /** Human-readable network name */
+    name: string;
+    /** Default JSON-RPC endpoint */
+    rpcUrl: string;
+    /** Block explorer base URL, if any */
+    blockExplorer?: string;
+    /** Goldsky/hosted subgraph GraphQL endpoint, if any */
+    subgraphUrl?: string;
+    /** Contract addresses, shaped to drop straight into `new SlvrSDK({ addresses })` */
+    addresses: {
+        /** SlvrGridLottery */
+        lottery: Address;
+        /** SlvrVoteEscrowStaking (the veNFT staker) */
+        staking: Address;
+        /** SlvrToken (ERC20) */
+        token: Address;
+        /** SlvrAutoCommitV2 (optional) */
+        autoCommit?: Address;
+        /** SlvrVoteEscrow NFT — needed to approve/own the tokenIds you stake (optional) */
+        voteEscrow?: Address;
+        /** SLVR/ETH UniswapV2 pair — enables SLVR price reads via `sdk.price` (optional) */
+        slvrEthPair?: Address;
+        /**
+         * Chainlink-style ETH/USD feed — enables USD prices via `sdk.ethUsd` (optional).
+         * Absent on deployments (like Robinhood Chain) that have no on-chain feed.
+         */
+        chainlinkEthUsd?: Address;
+        /** Multicall3 — lets the SDK batch multi-square reads into a single RPC call (optional). */
+        multicall3?: Address;
+        /** SlvrHub emission/sink router (optional; only on hub deployments) */
+        hub?: Address;
+        /** SlvrGameRegistry (optional; only on hub deployments) */
+        registry?: Address;
+        /** SlvrJackpot (optional; only on hub deployments) */
+        jackpot?: Address;
+    };
+}
+/**
+ * Robinhood Chain mainnet — the canonical production Slvr deployment.
+ *
+ * Addresses populated from `DeployRobinhood.s.sol` (2026-07-09); `autoCommit`
+ * is SlvrAutoCommitV2. The live deployment does not run the hub architecture,
+ * so `hub`/`registry`/`jackpot` are intentionally absent.
+ */
+declare const robinhood: SlvrDeployment;
+/**
+ * All known Slvr deployments, keyed by a short network slug.
+ *
+ * @example
+ * ```typescript
+ * import { deployments } from '@slvr-labs/sdk';
+ * const { addresses, rpcUrl } = deployments.robinhood;
+ * ```
+ */
+declare const deployments: {
+    readonly robinhood: SlvrDeployment;
+};
+/**
+ * A ready-to-use viem `Chain` for Robinhood Chain mainnet, so you don't have to
+ * hand-roll `defineChain`.
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { robinhoodChain } from '@slvr-labs/sdk';
+ *
+ * const publicClient = createPublicClient({ chain: robinhoodChain, transport: http() });
+ * ```
+ */
+declare const robinhoodChain: {
+    blockExplorers: {
+        readonly default: {
+            readonly name: "Blockscout";
+            readonly url: "https://robinhoodchain.blockscout.com";
+        };
+    };
+    blockTime?: number | undefined | undefined;
+    contracts: {
+        readonly multicall3: {
+            readonly address: `0x${string}`;
+        };
+    };
+    ensTlds?: readonly string[] | undefined;
+    id: number;
+    name: string;
+    nativeCurrency: {
+        readonly decimals: 18;
+        readonly name: "Ether";
+        readonly symbol: "ETH";
+    };
+    experimental_preconfirmationTime?: number | undefined | undefined;
+    rpcUrls: {
+        readonly default: {
+            readonly http: readonly [string];
+        };
+    };
+    sourceId?: number | undefined | undefined;
+    testnet?: boolean | undefined | undefined;
+    custom?: Record<string, unknown> | undefined;
+    fees?: viem.ChainFees<undefined> | undefined;
+    formatters?: undefined;
+    serializers?: viem.ChainSerializers<undefined, viem.TransactionSerializable> | undefined;
+};
+
+/**
+ * Options for {@link createSlvrClients} / {@link SlvrSDK.connect}.
+ */
+interface ConnectOptions {
+    /** Which deployment to target. Defaults to `robinhood`. */
+    deployment?: SlvrDeployment;
+    /** RPC URL. Defaults to the deployment's `rpcUrl`. Ignored if `transport` is given. */
+    rpcUrl?: string;
+    /** A fully-custom viem transport (overrides `rpcUrl`). */
+    transport?: Transport;
+    /** A private key to build a wallet client from (for sending transactions). */
+    privateKey?: `0x${string}`;
+    /** …or an already-built viem `Account` (alternative to `privateKey`). */
+    account?: Account;
+    /** Auto-batch concurrent reads through Multicall3. Defaults to `true`. */
+    batchMulticall?: boolean;
+    /** viem polling interval (ms) used by event watchers. */
+    pollingInterval?: number;
+}
+/**
+ * Build a viem `Chain` for a deployment. Returns the shipped `robinhoodChain`
+ * (which already registers Multicall3) for the Robinhood deployment; otherwise
+ * synthesizes one, wiring `multicall3` when the deployment provides it.
+ */
+declare function chainFromDeployment(deployment: SlvrDeployment): Chain;
+/** Clients returned by {@link createSlvrClients}. */
+interface SlvrClients {
+    chain: Chain;
+    publicClient: PublicClient;
+    /** Present only when a `privateKey` or `account` was supplied. */
+    walletClient?: WalletClient;
+}
+/**
+ * Create ready-to-use viem clients for a Slvr deployment with sensible, resilient
+ * defaults — Multicall3 auto-batching, a longer timeout, and retries — so you
+ * don't have to hand-tune the transport for a polling bot.
+ *
+ * @example
+ * ```typescript
+ * import { createSlvrClients } from '@slvr-labs/sdk';
+ * const { publicClient, walletClient } = createSlvrClients({ privateKey: process.env.PRIVATE_KEY });
+ * ```
+ */
+declare function createSlvrClients(opts?: ConnectOptions): SlvrClients;
+
+/**
+ * Base error class for all SDK errors
+ */
+declare class SlvrSDKError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+/**
+ * Error thrown when wallet client is required but not provided
+ */
+declare class WalletClientRequiredError extends SlvrSDKError {
+    constructor(operation: string);
+}
+/**
+ * Error thrown when contract call fails
+ */
+declare class ContractCallError extends SlvrSDKError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Error thrown when input validation fails
+ */
+declare class ValidationError extends SlvrSDKError {
+    readonly field?: string | undefined;
+    constructor(message: string, field?: string | undefined);
+}
+/**
+ * Error thrown when transaction fails
+ */
+declare class TransactionError extends SlvrSDKError {
+    readonly txHash?: `0x${string}` | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, txHash?: `0x${string}` | undefined, cause?: unknown | undefined);
+}
+/**
+ * A decoded on-chain revert. `errorName` is the protocol's custom error (e.g.
+ * `InsufficientValue`) when it could be decoded from the ABI.
+ */
+declare class SlvrRevertError extends SlvrSDKError {
+    readonly errorName: string | undefined;
+    readonly args?: readonly unknown[] | undefined;
+    readonly cause?: unknown | undefined;
+    constructor(errorName: string | undefined, message: string, args?: readonly unknown[] | undefined, cause?: unknown | undefined);
+}
+/**
+ * Decode a viem contract error into a {@link SlvrRevertError} with the protocol's
+ * custom error name and a plain-English hint. Returns `null` if `err` isn't a
+ * decodable contract revert (so you can rethrow the original). Useful around
+ * `simulateBet`, reads, or any caught write error.
+ *
+ * @example
+ * ```typescript
+ * try { await sdk.lottery.simulateBet(params); }
+ * catch (e) { const r = decodeSlvrRevert(e); if (r) console.log(r.errorName, r.message); }
+ * ```
+ */
+declare function decodeSlvrRevert(err: unknown): SlvrRevertError | null;
+
+/**
+ * Validate and normalize an Ethereum address
+ * @param address Address to validate
+ * @param fieldName Field name for error message
+ * @returns Checksummed address
+ * @throws ValidationError if address is invalid
+ */
+declare function validateAddress(address: string, fieldName?: string): Address;
+/**
+ * Validate that an amount is positive
+ * @param amount Amount to validate
+ * @param fieldName Field name for error message
+ * @throws ValidationError if amount is invalid
+ */
+declare function validateAmount(amount: bigint, fieldName?: string): void;
+/**
+ * Validate square indices are within valid range
+ * @param squares Array of square indices
+ * @param gridSize Grid size (default 25)
+ * @throws ValidationError if squares are invalid
+ */
+declare function validateSquares(squares: number[], gridSize?: number): void;
+/**
+ * Validate that arrays have matching lengths
+ * @param arrays Arrays to validate
+ * @param fieldNames Field names for error message
+ * @throws ValidationError if arrays don't match
+ */
+declare function validateArrayLengths(arrays: unknown[][], fieldNames: string[]): void;
+/**
+ * Validate basis points (0-10000)
+ * @param bps Basis points value
+ * @param fieldName Field name for error message
+ * @throws ValidationError if bps is invalid
+ */
+declare function validateBps(bps: number, fieldName?: string): void;
+/**
+ * Validate that basis points array sums to 10000
+ * @param bpsArray Array of basis points
+ * @param fieldName Field name for error message
+ * @throws ValidationError if bps don't sum to 10000
+ */
+declare function validateBpsSum(bpsArray: number[], fieldName?: string): void;
+/**
+ * Wait for transaction receipt with timeout
+ * @param publicClient Public client
+ * @param hash Transaction hash
+ * @param timeout Timeout in milliseconds (default 120000 = 2 minutes)
+ * @returns Transaction receipt
+ */
+declare function waitForTransactionReceipt(publicClient: {
+    waitForTransactionReceipt?: (args: {
+        hash: `0x${string}`;
+        timeout?: number;
+    }) => Promise<unknown>;
+}, hash: `0x${string}`, timeout?: number): Promise<unknown>;
+
+/**
+ * Options for transaction execution
+ */
+interface TransactionOptions {
+    /** Maximum gas to use */
+    gas?: bigint;
+    /** Gas price (legacy) */
+    gasPrice?: bigint;
+    /** Max fee per gas (EIP-1559) */
+    maxFeePerGas?: bigint;
+    /** Max priority fee per gas (EIP-1559) */
+    maxPriorityFeePerGas?: bigint;
+    /** Whether to wait for transaction receipt */
+    waitForReceipt?: boolean;
+    /** Timeout for waiting for receipt (milliseconds) */
+    receiptTimeout?: number;
+}
+/**
+ * Estimate gas for a contract write operation
+ * @param publicClient Public client
+ * @param address Contract address
+ * @param abi Contract ABI
+ * @param functionName Function name
+ * @param args Function arguments
+ * @param value Optional value to send
+ * @param account Optional account address
+ * @returns Estimated gas
+ */
+declare function estimateGas(publicClient: PublicClient, address: Address, abi: readonly unknown[], functionName: string, args: unknown[], value?: bigint, account?: Address): Promise<bigint>;
+/**
+ * Wait for transaction receipt with error handling
+ * @param publicClient Public client
+ * @param hash Transaction hash
+ * @param timeout Timeout in milliseconds
+ * @returns Transaction receipt
+ * @throws TransactionError if transaction fails or times out
+ */
+declare function waitForReceipt(publicClient: PublicClient, hash: `0x${string}`, timeout?: number): Promise<unknown>;
+/**
+ * Execute a contract write with options
+ * @param walletClient Wallet client
+ * @param publicClient Public client
+ * @param address Contract address
+ * @param abi Contract ABI
+ * @param functionName Function name
+ * @param args Function arguments
+ * @param options Transaction options
+ * @returns Transaction hash or receipt
+ */
+declare function executeTransaction(walletClient: WalletClient, publicClient: PublicClient, address: Address, abi: readonly unknown[], functionName: string, args: unknown[], options?: TransactionOptions & {
+    value?: bigint;
+}): Promise<`0x${string}` | unknown>;
+
 /**
  * Main Slvr SDK class
  *
@@ -51,7 +1931,7 @@ import { ConnectOptions } from './connect';
  * });
  * ```
  */
-export declare class SlvrSDK {
+declare class SlvrSDK {
     readonly lottery: SlvrGridLottery;
     readonly staking: SlvrStaking;
     readonly token: SlvrToken;
@@ -225,24 +2105,13 @@ export declare class SlvrSDK {
         /** Override the pot (ETH). Defaults to the sum of the round's squares. */
         pot?: number;
     }): Promise<GridMiningEv>;
+    /**
+     * Helper: current jackpot pool for a round, in wei (0 if no jackpot is set).
+     *
+     * Resolves the round's jackpot contract via `getRoundJackpot` and reads its
+     * `jackpotPool()`. Defaults to the current round.
+     */
+    getJackpotPool(roundId?: bigint): Promise<bigint>;
 }
-export * from './types';
-export * from './deployments';
-export * from './ev';
-export { SlvrPrice } from './price';
-export type { SlvrReserves } from './price';
-export { ChainlinkPriceFeed } from './oracle';
-export { createSlvrClients, chainFromDeployment } from './connect';
-export type { ConnectOptions, SlvrClients } from './connect';
-export { SlvrGridLottery } from './contracts/lottery';
-export { SlvrStaking } from './contracts/staking';
-export { SlvrToken } from './contracts/token';
-export { SlvrAutoCommit } from './contracts/autoCommit';
-export { SlvrHub } from './contracts/hub';
-export { SlvrGameRegistry } from './contracts/registry';
-export { SlvrJackpot } from './contracts/jackpot';
-export * from './errors';
-export * from './utils';
-export * from './transaction';
-export * from './events';
-//# sourceMappingURL=index.d.ts.map
+
+export { type AutoCommitPlan, type BetParams, type BetPlacedEvent, ChainlinkPriceFeed, type ClaimParams, type ClaimParamsAdvanced, type ClaimedEvent, type ConnectOptions, ContractCallError, GRID_SIZE, type GameInfo, GameStatus, GameTier, type GridMiningEv, type GridMiningEvInput, JACKPOT_ODDS, type MinerState, PROTOCOL_FEE_BPS, type PriceQuote, REFINING_FEE_BPS, type RandomnessRequestedEvent, type RoundInfo, type RoundResolvedEvent, SINGLE_SQUARE_WIN_PROBABILITY, SlvrAutoCommit, SlvrAutoCommitEvents, type SlvrClients, type SlvrConfig, type SlvrDeployment, SlvrGameRegistry, SlvrGridLottery, SlvrGridLotteryEvents, SlvrHub, SlvrJackpot, SlvrPrice, type SlvrReserves, SlvrRevertError, SlvrSDK, SlvrSDKError, SlvrStaking, SlvrStakingEvents, SlvrToken, SlvrTokenEvents, type StakingInfo, TransactionError, type TransactionOptions, type TreasuryState, type TxOverrides, ValidationError, WalletClientRequiredError, chainFromDeployment, computeGridMiningEv, createSlvrClients, decodeEvent, decodeEvents, decodeSlvrRevert, deployments, estimateGas, executeTransaction, robinhood, robinhoodChain, validateAddress, validateAmount, validateArrayLengths, validateBps, validateBpsSum, validateSquares, waitForReceipt, waitForTransactionReceipt };