@slvr-labs/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,248 @@
+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';
+/**
+ * Main Slvr SDK class
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, createWalletClient, http } from 'viem';
+ * import { SlvrSDK } from '@slvr-labs/sdk';
+ *
+ * const publicClient = createPublicClient({
+ *   chain: robinhoodChain,
+ *   transport: http(),
+ * });
+ *
+ * const walletClient = createWalletClient({
+ *   chain: robinhoodChain,
+ *   transport: http(),
+ *   account: yourAccount,
+ * });
+ *
+ * const sdk = new SlvrSDK({
+ *   publicClient,
+ *   walletClient,
+ *   addresses: {
+ *     lottery: '0x...',
+ *     staking: '0x...',
+ *     token: '0x...',
+ *   },
+ * });
+ *
+ * // Get current round
+ * const roundId = await sdk.lottery.currentRoundId();
+ *
+ * // Place a bet
+ * await sdk.lottery.bet({
+ *   roundId,
+ *   squares: [0, 1, 2],
+ *   amounts: [1000000000000000000n, 2000000000000000000n, 3000000000000000000n],
+ * });
+ * ```
+ */
+export declare class SlvrSDK {
+    readonly lottery: SlvrGridLottery;
+    readonly staking: SlvrStaking;
+    readonly token: SlvrToken;
+    readonly autoCommit?: SlvrAutoCommit;
+    readonly hub?: SlvrHub;
+    readonly registry?: SlvrGameRegistry;
+    readonly jackpot?: SlvrJackpot;
+    /** SLVR/ETH spot price reader — present when a `slvrEthPair` address is configured. */
+    readonly price?: SlvrPrice;
+    /** Chainlink ETH/USD feed reader — present when a `chainlinkEthUsd` address is configured. */
+    readonly ethUsd?: ChainlinkPriceFeed;
+    private config;
+    constructor(config: SlvrConfig);
+    /**
+     * One-line setup: build clients (with Multicall3 batching + resilient transport
+     * defaults) and an SDK for a deployment. Pass a `privateKey`/`account` to enable
+     * writes; omit it for a read-only SDK.
+     *
+     * @example
+     * ```typescript
+     * import { SlvrSDK } from '@slvr-labs/sdk';
+     * const sdk = SlvrSDK.connect();                                   // read-only, Robinhood Chain
+     * const bot = SlvrSDK.connect({ privateKey: process.env.PK });     // wallet-backed
+     * ```
+     */
+    static connect(opts?: ConnectOptions): SlvrSDK;
+    /**
+     * Get the public client
+     */
+    getPublicClient(): PublicClient;
+    /**
+     * Get the wallet client (if available)
+     */
+    getWalletClient(): WalletClient | undefined;
+    /**
+     * Update the wallet client and reinitialize contracts
+     * @param walletClient New wallet client (or undefined to remove)
+     */
+    setWalletClient(walletClient: WalletClient | undefined): void;
+    /**
+     * Helper: Calculate bet amounts from percentages
+     * @param totalAmount Total amount to bet
+     * @param percentages Array of percentages (0-100) for each square
+     * @returns Array of amounts in wei
+     * @throws ValidationError if percentages don't sum to 100 or if totalAmount is invalid
+     */
+    static calculateBetAmounts(totalAmount: bigint, percentages: number[]): bigint[];
+    /**
+     * Helper: Format bigint to human-readable string.
+     *
+     * `precision` caps the number of decimal places shown; trailing zeros are
+     * stripped (like viem's `formatEther`), so `formatToken(1.5e18)` is `"1.5"`,
+     * not `"1.5000"`.
+     * @param value Value in wei
+     * @param decimals Number of decimals (default 18)
+     * @param precision Max decimal places to show (default 4)
+     */
+    static formatToken(value: bigint, decimals?: number, precision?: number): string;
+    /**
+     * Helper: Parse human-readable string to bigint
+     * @param value Human-readable value (e.g., "1.5")
+     * @param decimals Number of decimals (default 18)
+     */
+    static parseToken(value: string, decimals?: number): bigint;
+    /**
+     * Helper: Calculate time remaining until round ends
+     * @param roundId Round ID
+     * @returns Time remaining in seconds, or 0 if round has ended
+     */
+    getTimeRemaining(roundId: bigint): Promise<number>;
+    /**
+     * Helper: Check if user can claim rewards for a round
+     * @param roundId Round ID
+     * @param user User address
+     * @returns True if user can claim
+     */
+    canClaim(roundId: bigint, user: Address): Promise<boolean>;
+    /**
+     * Helper: Get user's claimable rounds
+     * @param user User address
+     * @param startRoundId Start round ID to check from
+     * @param endRoundId End round ID to check to
+     * @returns Array of round IDs that can be claimed
+     */
+    getClaimableRounds(user: Address, startRoundId: bigint, endRoundId: bigint): Promise<bigint[]>;
+    /**
+     * Helper: Compute a game's effective SLVR/sec emission rate.
+     *
+     * Mirrors SlvrHub._effectiveRatePerSec: the game's weighted share of the global emission stream,
+     * i.e. emissionRatePerSec * weightOf(gameId) / totalActiveWeight. NOTE: this does not apply the
+     * per-game maxWeightBps ceiling that the contract also enforces; it is the pre-cap weighted rate.
+     *
+     * Requires both `hub` and `registry` addresses to be configured.
+     * @param gameId Registry game id
+     * @returns Effective emission rate in SLVR/sec (0 if there is no active weight)
+     */
+    effectiveEmissionRate(gameId: bigint): Promise<bigint>;
+    /**
+     * Helper: Get the accrued-but-unminted SLVR emission currently available to a game.
+     *
+     * Thin pass-through to SlvrHub.pendingEmission. Requires `hub` to be configured.
+     * @param gameId Registry game id
+     */
+    pendingEmission(gameId: bigint): Promise<bigint>;
+    /**
+     * Helper: current SLVR spot price in ETH (ETH per SLVR).
+     *
+     * Requires a `slvrEthPair` address to be configured (so `sdk.price` exists).
+     * @throws ValidationError if no pair address was configured.
+     */
+    getSlvrPriceInEth(): Promise<number>;
+    /**
+     * Helper: current ETH price in USD from the configured Chainlink feed.
+     *
+     * Requires a `chainlinkEthUsd` address (so `sdk.ethUsd` exists). This is wired
+     * for Robinhood Chain in `deployments.robinhood`; on chains without a feed,
+     * supply one or pass `ethUsd` to {@link getSlvrPrice}.
+     * @throws ValidationError if no ETH/USD feed was configured.
+     */
+    getEthPriceUsd(): Promise<number>;
+    /**
+     * Helper: current SLVR price in **both ETH and USD**.
+     *
+     * SLVR/ETH comes from the UniswapV2 pair (`sdk.price`). The USD value uses, in
+     * order: an explicit `opts.ethUsd`, else the configured Chainlink ETH/USD feed
+     * (`sdk.ethUsd`), else `usd` is `null`.
+     *
+     * @param opts.ethUsd override the ETH/USD price (e.g. from your own off-chain source)
+     * @throws ValidationError if no `slvrEthPair` was configured.
+     *
+     * @example
+     * ```typescript
+     * const { eth, usd } = await sdk.getSlvrPrice();              // uses Chainlink feed if configured
+     * const q = await sdk.getSlvrPrice({ ethUsd: 1797.35 });      // or supply ETH/USD yourself
+     * ```
+     */
+    getSlvrPrice(opts?: {
+        ethUsd?: number;
+    }): Promise<PriceQuote>;
+    /**
+     * Helper: estimate the per-round expected value of grid mining for the given
+     * stake, pulling live pot, emission and SLVR price on-chain.
+     *
+     * This is the SDK-level convenience around {@link computeGridMiningEv}: it reads
+     * the round's pot (sum of all squares), the emission target (`slvrPerRound`), the
+     * protocol fee (`protocolFeeBps`), and the SLVR price (via `sdk.price`), then
+     * returns the full EV breakdown. Any of those can be overridden via `params`.
+     *
+     * The jackpot pool is **not** auto-read (it isn't exposed as a single call on the
+     * live lottery) — pass `jackpotPool` if you want the jackpot term included.
+     *
+     * @remarks `slvrPerRound` is the emission *target*; actual emission is hub-gated
+     * and may be lower, so treat the result as an upper-ish estimate. Requires a
+     * configured `slvrEthPair` unless you pass `slvrPriceEth`.
+     */
+    estimateRoundEv(params: {
+        /** ETH to commit to the round. */
+        stake: number;
+        /** Round to price. Defaults to the current round. */
+        roundId?: bigint;
+        /** Value SLVR net of the refining fee (cashing out) vs at full price (holding). Default false. */
+        cashOut?: boolean;
+        /** ETH in the jackpot pool. Default 0 (jackpot term omitted). */
+        jackpotPool?: number;
+        /** Jackpot odds (1-in-N). Defaults to the protocol default (625). */
+        jackpotOdds?: number;
+        /** Override the emission target (SLVR/round). Defaults to `slvrPerRound()`. */
+        emissionPerRound?: number;
+        /** Override the SLVR price (ETH per SLVR). Defaults to `sdk.price`. */
+        slvrPriceEth?: number;
+        /** Override the pot (ETH). Defaults to the sum of the round's squares. */
+        pot?: number;
+    }): Promise<GridMiningEv>;
+}
+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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,OAAO,EAAe,MAAM,MAAM,CAAC;AACxE,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAuB,YAAY,EAAE,MAAM,MAAM,CAAC;AACzD,OAAO,EAAqB,cAAc,EAAE,MAAM,WAAW,CAAC;AAI9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,OAAO;IAClB,SAAgB,OAAO,EAAE,eAAe,CAAC;IACzC,SAAgB,OAAO,EAAE,WAAW,CAAC;IACrC,SAAgB,KAAK,EAAE,SAAS,CAAC;IACjC,SAAgB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5C,SAAgB,GAAG,CAAC,EAAE,OAAO,CAAC;IAC9B,SAAgB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5C,SAAgB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtC,uFAAuF;IACvF,SAAgB,KAAK,CAAC,EAAE,SAAS,CAAC;IAClC,8FAA8F;IAC9F,SAAgB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAE5C,OAAO,CAAC,MAAM,CAAa;gBAEf,MAAM,EAAE,UAAU;IAsE9B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO;IAMlD;;OAEG;IACH,eAAe,IAAI,YAAY;IAI/B;;OAEG;IACH,eAAe,IAAI,YAAY,GAAG,SAAS;IAI3C;;;OAGG;IACH,eAAe,CAAC,YAAY,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAqB7D;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IA6BhF;;;;;;;;;OASG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,EAAE,SAAS,GAAE,MAAU,GAAG,MAAM;IAcvF;;;;OAIG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAW,GAAG,MAAM;IAO/D;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOxD;;;;;OAKG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAehE;;;;;;OAMG;IACG,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAYpG;;;;;;;;;;OAUG;IACG,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAqB5D;;;;;OAKG;IACG,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOtD;;;;;OAKG;IACG,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAO1C;;;;;;;OAOG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAOvC;;;;;;;;;;;;;;;OAeG;IACG,YAAY,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAYnE;;;;;;;;;;;;;;;OAeG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,kCAAkC;QAClC,KAAK,EAAE,MAAM,CAAC;QACd,qDAAqD;QACrD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,kGAAkG;QAClG,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,iEAAiE;QACjE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,qEAAqE;QACrE,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,+EAA+E;QAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,uEAAuE;QACvE,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,0EAA0E;QAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC,YAAY,CAAC;CA6B1B;AAGD,cAAc,SAAS,CAAC;AAGxB,cAAc,eAAe,CAAC;AAG9B,cAAc,MAAM,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAG9C,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AACnE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGlD,cAAc,UAAU,CAAC;AAGzB,cAAc,SAAS,CAAC;AAGxB,cAAc,eAAe,CAAC;AAG9B,cAAc,UAAU,CAAC"}