rain-sdk-v2 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -3,6 +3,66 @@
 All notable changes to `rain-sdk-v2` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## Deprecation policy
+
+APIs slated for removal are marked `@deprecated` in the type declarations for at
+least one minor release before they are removed, with the replacement named in
+the deprecation notice. Breaking removals land only in a major version.
+
+## [2.4.0] - Production readiness
+
+No breaking changes to the public API.
+
+### Fixed
+- **Docs correctness:** the `deadline` examples and parameter tables in the README
+  no longer show `deadline: 600n` (a duration), which the builders reject since
+  2.2.0. They now show an absolute unix timestamp and note the default 10-min window.
+
+### Changed
+- **viem-only (dropped `ethers`):** `utils/helpers.ts` (allowance + decimals reads,
+  `parseUnits`, RPC liveness) is ported to viem. `ethers` is removed from
+  dependencies — one web3 stack, smaller install/bundle. The redundant
+  per-call `getNetwork()` RPC round-trip before allowance checks is gone.
+- **`RainAA` browser-only, documented + guarded:** session methods now throw a
+  clear error when `indexedDB` is unavailable (Node/SSR) instead of a cryptic
+  `ReferenceError`. Documented in the README and class JSDoc. Use `Rain` for
+  server-side flows.
+
+### Added
+- **Test suite (vitest):** unit tests for the validators and encoders, plus a
+  gated Arbitrum integration test (`npm run test:integration`) exercising the
+  on-chain read path. Scripts: `test`, `test:watch`, `test:integration`.
+- **CI:** GitHub Actions — build + test on push/PR, and publish-on-release
+  (`.github/workflows/`).
+
+### Removed
+- Dead `getRandomRpc` export (superseded by `getDefaultRpc` in 2.3.0).
+- Committed `*.tgz` tarball removed from the repo and gitignored.
+
+## [2.3.0] - Developer experience
+
+Additive, non-breaking. Fills in the untyped core data model and adds the
+convenience helpers the docs previously pushed onto the caller.
+
+### Added
+- **Typed pool DTOs (F-05):** exported `Pool`, `SubPool`, `PaginatedPools`, and
+  `TradingModelName`. `getPublicPools` / `getPrivatePools` now return
+  `ApiResponse<PaginatedPools>` instead of `unknown`. Socket `*EventData`
+  payloads now type their `pool` / `subPool` / `subMarkets` fields as
+  `Pool` / `SubPool`. Interfaces carry an index signature, so they are a safe
+  superset of the wire (dynamic field access still works).
+- **`rain.execute(txs, executor)` (F-07):** sequences the `[approval, main]`
+  arrays the builders return — sends each tx and awaits its receipt before the
+  next. Pluggable `TxExecutor` (`{ send, wait? }`) adapts to viem, ethers, or
+  RainAA. Also exported as the standalone `executeTxs`.
+- **`rain.parseAmount` / `rain.formatAmount` (F-14):** convert between
+  human-readable amounts and base units using the token's configured decimals
+  (no more hand-tracking that USDT is 6 and RAIN is 18).
+- **`RAIN_SOCKET_EVENTS` (F-16):** correctly-spelled camelCase aliases for the
+  raw wire event names (including the upstream-misspelled `dispute-time-extented`).
+- **Token expiry (F-13):** `LoginResult.expiresAt` exposes the decoded JWT `exp`
+  (unix seconds) so apps can renew proactively.
+
 ## [2.2.0] - Guardrails
 
 Adds fail-fast validation and structured errors. These surface mistakes

package/README.md

@@ -71,6 +71,8 @@ const rain = new Rain(config?: RainCoreConfig);
 
 Stateful class for smart account (Account Abstraction) management with Alchemy gas sponsorship.
 
+> ⚠️ **Browser-only.** `RainAA` persists session keys in `indexedDB`, so it is **not supported in Node.js or SSR** — session methods throw a descriptive error in those environments. For server-side flows use the stateless `Rain` class (transaction building and on-chain reads), which runs anywhere.
+
 #### Constructor
 
 ```typescript
@@ -213,7 +215,7 @@ const txs = await rain.buildEnterOptionTx({
   buyAmountInWei: parseUnits('5', 6), // 5 USDT (or parseUnits('5', 18) for RAIN)
   walletAddress: '0x...', // user's wallet address
   slippageTolerance: 5n, // optional, default 5% — percentage tolerance for minSharesOut
-  deadline: 600n, // optional, default 600 (10 min) — duration in seconds
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 600), // optional — absolute unix timestamp; omit for a default 10-min window
 });
 // Returns [approveTx?, enterOptionTx]
 ```
@@ -227,7 +229,7 @@ const txs = await rain.buildEnterOptionTx({
 | `walletAddress` | `0x${string}` | User's wallet address (for allowance check) |
 | `minSharesOut` | `bigint` | *(Optional)* Minimum shares to receive. Auto-calculated from `getEntryShares` with slippage if not set |
 | `slippageTolerance` | `bigint` | *(Optional)* Slippage percentage (e.g. `5n` = 5%). Default: 5% |
-| `deadline` | `bigint` | *(Optional)* Duration in seconds (e.g. `600n` = 10 min). Default: 600 |
+| `deadline` | `bigint` | *(Optional)* Absolute unix timestamp in seconds, e.g. `BigInt(Math.floor(Date.now()/1000) + 600)`. Omit for a default 10-min window. A small duration like `600n` is **rejected** (`RainValidationError`). |
 
 > **Note:** Approval is handled automatically. The SDK reads `baseToken` from the market contract and checks allowance before building transactions. Slippage protection is auto-calculated: the SDK calls `getEntryShares` on-chain to get expected shares, then applies the slippage tolerance.
 
@@ -244,7 +246,7 @@ const tx = await rain.buildSellOptionTx({
   optionSide: OptionSide.Yes, // Yes = 1, No = 2
   sharesAmount: parseUnits('10', 6), // shares to sell
   slippageTolerance: 5n, // optional, default 5%
-  deadline: 600n, // optional, default 600 (10 min) — duration in seconds
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 600), // optional — absolute unix timestamp; omit for a default 10-min window
 });
 // Returns a single RawTransaction (no approval needed)
 ```
@@ -257,7 +259,7 @@ const tx = await rain.buildSellOptionTx({
 | `sharesAmount` | `bigint` | Number of shares to sell |
 | `minAmountOut` | `bigint` | *(Optional)* Minimum base tokens to receive. Auto-calculated from `getCurrentPrice` with slippage if not set |
 | `slippageTolerance` | `bigint` | *(Optional)* Slippage percentage (e.g. `5n` = 5%). Default: 5% |
-| `deadline` | `bigint` | *(Optional)* Duration in seconds (e.g. `600n` = 10 min). Default: 600 |
+| `deadline` | `bigint` | *(Optional)* Absolute unix timestamp in seconds, e.g. `BigInt(Math.floor(Date.now()/1000) + 600)`. Omit for a default 10-min window. A small duration like `600n` is **rejected** (`RainValidationError`). |
 
 ---
 
@@ -308,7 +310,7 @@ const txs = await rain.buildAddLiquidityTx({
   totalAmountInWei: parseUnits('10', 6), // 10 USDT
   walletAddress: '0x...', // user's wallet address
   slippageTolerance: 5n, // optional, default 5%
-  deadline: 600n, // optional, default 600 (10 min) — duration in seconds
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 600), // optional — absolute unix timestamp; omit for a default 10-min window
 });
 // Returns [approveTx?, addLiquidityTx]
 ```
@@ -322,7 +324,7 @@ const txs = await rain.buildAddLiquidityTx({
 | `minYesToDeposit` | `bigint` | *(Optional)* Min yes tokens to deposit. Auto-calculated from reserves if not set |
 | `minNoToDeposit` | `bigint` | *(Optional)* Min no tokens to deposit. Auto-calculated from reserves if not set |
 | `slippageTolerance` | `bigint` | *(Optional)* Slippage percentage (e.g. `5n` = 5%). Default: 5% |
-| `deadline` | `bigint` | *(Optional)* Duration in seconds (e.g. `600n` = 10 min). Default: 600 |
+| `deadline` | `bigint` | *(Optional)* Absolute unix timestamp in seconds, e.g. `BigInt(Math.floor(Date.now()/1000) + 600)`. Omit for a default 10-min window. A small duration like `600n` is **rejected** (`RainValidationError`). |
 
 > **Note:** Approval is handled automatically. Slippage protection is auto-calculated from `ammYesReserve`/`ammNoReserve` proportionally.
 
@@ -342,7 +344,7 @@ const tx = await rain.buildRemoveLiquidityTx({
   option: 1n,
   lpShares, // raw LP shares amount
   slippageTolerance: 5n, // optional, default 5%
-  deadline: 600n, // optional, default 600 (10 min) — duration in seconds
+  deadline: BigInt(Math.floor(Date.now() / 1000) + 600), // optional — absolute unix timestamp; omit for a default 10-min window
 });
 ```
 
@@ -354,7 +356,7 @@ const tx = await rain.buildRemoveLiquidityTx({
 | `minYesOut` | `bigint` | *(Optional)* Min yes tokens to receive. Auto-calculated from `getRemovedLiquidity` if not set |
 | `minNoOut` | `bigint` | *(Optional)* Min no tokens to receive. Auto-calculated if not set |
 | `slippageTolerance` | `bigint` | *(Optional)* Slippage percentage (e.g. `5n` = 5%). Default: 5% |
-| `deadline` | `bigint` | *(Optional)* Duration in seconds (e.g. `600n` = 10 min). Default: 600 |
+| `deadline` | `bigint` | *(Optional)* Absolute unix timestamp in seconds, e.g. `BigInt(Math.floor(Date.now()/1000) + 600)`. Omit for a default 10-min window. A small duration like `600n` is **rejected** (`RainValidationError`). |
 
 ---
 
@@ -1544,6 +1546,67 @@ socket.disconnect();
 
 ---
 
+## Helpers & Execution
+
+### Executing transactions
+
+Builders return unsigned `RawTransaction[]` where index 0 may be an ERC-20
+approval. `rain.execute()` sends them in order and waits for each receipt before
+the next — so the main transaction never front-runs its approval:
+
+```typescript
+const txs = await rain.buildEnterOptionTx({ /* ... */ });
+
+await rain.execute(txs, {
+  send: (tx) => walletClient.sendTransaction({ to: tx.to, data: tx.data, value: tx.value ?? 0n }),
+  wait: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+});
+```
+
+The executor is pluggable — adapt `{ send, wait? }` to viem, ethers, RainAA, or
+your own KMS. Also available as the standalone `executeTxs(txs, executor)`.
+
+### Amount conversion
+
+Convert between human-readable amounts and base units using the token's
+configured decimals — no need to track that USDT is 6 and RAIN is 18:
+
+```typescript
+rain.parseAmount('5', usdtAddress);        // 5_000_000n
+rain.formatAmount(5_000_000n, usdtAddress); // '5'
+```
+
+### Typed pool data
+
+`getPublicPools` / `getPrivatePools` return `ApiResponse<PaginatedPools>`, and
+socket event payloads type their `pool` / `subPool` fields as `Pool` / `SubPool`.
+Import the DTOs to annotate your own code:
+
+```typescript
+import type { Pool, SubPool, PaginatedPools } from 'rain-sdk-v2';
+```
+
+### Socket event names
+
+Use `RAIN_SOCKET_EVENTS` for correctly-spelled event identifiers with the
+low-level `.on()` API (some raw wire names are misspelled upstream):
+
+```typescript
+import { RAIN_SOCKET_EVENTS } from 'rain-sdk-v2';
+socket.on(RAIN_SOCKET_EVENTS.disputeTimeExtended, poolId, handler);
+```
+
+### Token expiry
+
+`login()` returns `expiresAt` (unix seconds, decoded from the JWT) so you can
+renew before it lapses:
+
+```typescript
+const { accessToken, expiresAt } = await rain.login({ /* ... */ });
+```
+
+---
+
 ## Error Handling & Validation
 
 ### Build-time validation

package/dist/Rain.d.ts

@@ -6,6 +6,7 @@ import { LoginParams, LoginResult } from './auth/types.js';
 import { SellProceedsResult } from './markets/getSellProceeds.js';
 import { OptionDisputeInfo, OptionAppealInfo } from './markets/getDisputeState.js';
 import { EntrySharesResult } from './markets/getEntryShares.js';
+import { TxExecutor } from './tx/execute.js';
 import type { UserProfileUpdateParams, UserHistoryParams, CreateCommentParams, CommentsListingParams, UpdateCommentParams, CommentCountParams, PublicPoolsParams, PrivatePoolsParams, PoolListingByCreatorParams, VerifyAccessCodeParams, PoolTotalParticipantsParams, SearchPoolParams, RelatedPoolsParams, UpdateStreamingParams, UpdatePoolResolutionTimeParams, FindPoolFallbackParams, SignOraclesExtendTimeParams, TrendingTagsParams, UserTotalInvestmentParams, OptionsTotalVolumeParams, PoolActivityParams, TopHoldersParams, UserInvestedPoolsParams, InvestmentVolumeGraphParams, UserPnlGraphParams, TopWinnersLosersParams, PnlByPoolIdParams, UserPositionsParams, OpenPositionsParams, UserSharePositionsParams, SearchInvestedPoolsParams, PriceDataParams, AddReviewParams, GetUserOrdersParams, OrderBookParams, GetUserOrderByPoolIdParams, OrdersListingByPoolParams, AddUserPointsParams, UserOnboardingParams, PointsGraphParams, GetNotificationsParams, MarkNotificationAsReadParams, CreateDisputeMessageParams, GetPoolDisputeConvoParams, FollowToggleParams, FollowCheckParams, FollowListParams, FollowStatsParams, RainBurnPerPoolParams, ToggleBookmarkParams, GetBookmarksParams, CheckBookmarkParams, LeaderboardParams, LeaderboardSearchParams, TraderRecentTradesParams } from './api/types.js';
 export declare class Rain {
     readonly environment: RainEnvironment;
@@ -19,6 +20,31 @@ export declare class Rain {
      */
     getTokenConfig(tokenAddress: `0x${string}`): import("./config/environments.js").TokenConfig | null;
     buildApprovalTx(params: ApproveTxParams): RawTransaction;
+    /**
+     * Sequences an ordered list of raw transactions through a pluggable executor,
+     * awaiting each receipt before the next send. Use this for the `[approval, main]`
+     * arrays the builders return so the main tx never front-runs its approval.
+     *
+     * @example
+     * const txs = await rain.buildEnterOptionTx({ ... });
+     * await rain.execute(txs, {
+     *   send: (tx) => walletClient.sendTransaction({ to: tx.to, data: tx.data, value: tx.value ?? 0n }),
+     *   wait: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+     * });
+     */
+    execute(txs: RawTransaction[], executor: TxExecutor): Promise<`0x${string}`[]>;
+    /**
+     * Convert a human-readable amount to base units (wei) using the token's
+     * configured decimals. Throws if the token is not in the environment config.
+     * @example rain.parseAmount('5', usdtAddress) // 5_000_000n for 6-decimal USDT
+     */
+    parseAmount(value: string | number, tokenAddress: `0x${string}`): bigint;
+    /**
+     * Convert a base-unit (wei) amount to a human-readable string using the
+     * token's configured decimals. Throws if the token is not in the config.
+     * @example rain.formatAmount(5_000_000n, usdtAddress) // '5' for 6-decimal USDT
+     */
+    formatAmount(amount: bigint, tokenAddress: `0x${string}`): string;
     getCreateMarketFees(tokenAddress: `0x${string}`, inputAmountWei: bigint): Promise<{
         oracleFeePerOption: bigint;
         liquidityFee: bigint;
@@ -233,8 +259,8 @@ export declare class Rain {
         poolId: string;
         accessCode: string;
     }, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
-    getPublicPools(params: PublicPoolsParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
-    getPrivatePools(params: PrivatePoolsParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
+    getPublicPools(params: PublicPoolsParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").PaginatedPools>>;
+    getPrivatePools(params: PrivatePoolsParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").PaginatedPools>>;
     getPoolById(params: {
         id: string;
     }, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;

package/dist/Rain.js

@@ -28,7 +28,8 @@ import { getResolverBondAmount } from './markets/getResolverBondAmount.js';
 import { getDisputeAppealFee } from './markets/getDisputeFee.js';
 import { optionResolverBond, optionResolutionProposer, isOptionDisputed, isOptionAppealed, optionDispute, optionAppeal } from './markets/getDisputeState.js';
 import { getEntryShares } from './markets/getEntryShares.js';
-import { createPublicClient, http, parseAbi } from 'viem';
+import { executeTxs } from './tx/execute.js';
+import { createPublicClient, http, parseAbi, parseUnits, formatUnits } from 'viem';
 import { arbitrum } from 'viem/chains';
 import * as usersApi from './api/users.js';
 import * as commentsApi from './api/comments.js';
@@ -98,6 +99,43 @@ export class Rain {
     buildApprovalTx(params) {
         return buildApproveRawTx(params);
     }
+    /**
+     * Sequences an ordered list of raw transactions through a pluggable executor,
+     * awaiting each receipt before the next send. Use this for the `[approval, main]`
+     * arrays the builders return so the main tx never front-runs its approval.
+     *
+     * @example
+     * const txs = await rain.buildEnterOptionTx({ ... });
+     * await rain.execute(txs, {
+     *   send: (tx) => walletClient.sendTransaction({ to: tx.to, data: tx.data, value: tx.value ?? 0n }),
+     *   wait: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+     * });
+     */
+    async execute(txs, executor) {
+        return executeTxs(txs, executor);
+    }
+    /**
+     * Convert a human-readable amount to base units (wei) using the token's
+     * configured decimals. Throws if the token is not in the environment config.
+     * @example rain.parseAmount('5', usdtAddress) // 5_000_000n for 6-decimal USDT
+     */
+    parseAmount(value, tokenAddress) {
+        const cfg = this.getTokenConfig(tokenAddress);
+        if (!cfg)
+            throw new Error(`Unknown token ${tokenAddress}; not in the ${this.environment} environment config`);
+        return parseUnits(String(value), cfg.decimals);
+    }
+    /**
+     * Convert a base-unit (wei) amount to a human-readable string using the
+     * token's configured decimals. Throws if the token is not in the config.
+     * @example rain.formatAmount(5_000_000n, usdtAddress) // '5' for 6-decimal USDT
+     */
+    formatAmount(amount, tokenAddress) {
+        const cfg = this.getTokenConfig(tokenAddress);
+        if (!cfg)
+            throw new Error(`Unknown token ${tokenAddress}; not in the ${this.environment} environment config`);
+        return formatUnits(amount, cfg.decimals);
+    }
     async getCreateMarketFees(tokenAddress, inputAmountWei) {
         const pc = createPublicClient({ chain: arbitrum, transport: http(this.rpcUrl) });
         const [oracleFeeRaw, liquidityFee, factoryBaseToken] = await Promise.all([

package/dist/RainAA.d.ts

@@ -1,5 +1,12 @@
 import { RainConfig } from './types.js';
 import { RawTransaction } from './tx/types.js';
+/**
+ * Smart-account (Account Abstraction) manager with Alchemy gas sponsorship.
+ *
+ * ⚠️ **Browser-only.** Session persistence uses `indexedDB`, so `RainAA` is not
+ * supported in Node.js or SSR — session methods throw a descriptive error there.
+ * The stateless `Rain` class works in any environment; use it for server-side flows.
+ */
 export declare class RainAA {
     private config;
     private _client;

package/dist/RainAA.js

@@ -3,6 +3,10 @@ const SESSION_DURATION_SEC = 60 * 60 * 24; // 24 hours
 const DB_NAME = 'RainSDKV2';
 const STORE_NAME = 'sessions';
 function openSessionDB() {
+    if (typeof indexedDB === 'undefined') {
+        return Promise.reject(new Error('RainAA requires a browser environment: session persistence uses indexedDB, ' +
+            'which is unavailable in Node.js/SSR. RainAA is browser-only.'));
+    }
     return new Promise((resolve, reject) => {
         const req = indexedDB.open(DB_NAME, 1);
         req.onupgradeneeded = () => {
@@ -42,6 +46,13 @@ async function deleteSession(key) {
         tx.onerror = () => reject(tx.error);
     });
 }
+/**
+ * Smart-account (Account Abstraction) manager with Alchemy gas sponsorship.
+ *
+ * ⚠️ **Browser-only.** Session persistence uses `indexedDB`, so `RainAA` is not
+ * supported in Node.js or SSR — session methods throw a descriptive error there.
+ * The stateless `Rain` class works in any environment; use it for server-side flows.
+ */
 export class RainAA {
     config;
     _client = null; // EOA-signed client (for grantPermissions)

package/dist/api/pools.d.ts

@@ -1,10 +1,10 @@
-import { ApiConfig, ApiResponse, PublicPoolsParams, PrivatePoolsParams, PoolListingByCreatorParams, VerifyAccessCodeParams, PoolTotalParticipantsParams, SearchPoolParams, RelatedPoolsParams, UpdateStreamingParams, UpdatePoolResolutionTimeParams, FindPoolFallbackParams, SignOraclesExtendTimeParams, TrendingTagsParams } from './types.js';
+import { ApiConfig, ApiResponse, PublicPoolsParams, PrivatePoolsParams, PoolListingByCreatorParams, VerifyAccessCodeParams, PoolTotalParticipantsParams, SearchPoolParams, RelatedPoolsParams, UpdateStreamingParams, UpdatePoolResolutionTimeParams, FindPoolFallbackParams, SignOraclesExtendTimeParams, TrendingTagsParams, PaginatedPools } from './types.js';
 export declare function accessPool(params: {
     poolId: string;
     accessCode: string;
 }, config: ApiConfig): Promise<ApiResponse>;
-export declare function getPublicPools(params: PublicPoolsParams, config: ApiConfig): Promise<ApiResponse>;
-export declare function getPrivatePools(params: PrivatePoolsParams, config: ApiConfig): Promise<ApiResponse>;
+export declare function getPublicPools(params: PublicPoolsParams, config: ApiConfig): Promise<ApiResponse<PaginatedPools>>;
+export declare function getPrivatePools(params: PrivatePoolsParams, config: ApiConfig): Promise<ApiResponse<PaginatedPools>>;
 export declare function getPoolById(params: {
     id: string;
 }, config: ApiConfig): Promise<ApiResponse>;

package/dist/api/pools.js

@@ -9,7 +9,7 @@ export async function getPublicPools(params, config) {
         method: 'GET',
         headers: buildHeaders(config),
     });
-    return handleResponse(res);
+    return handleResponse(res, '/pools/public-pools');
 }
 export async function getPrivatePools(params, config) {
     const qs = buildQuery({ limit: params.limit, offset: params.offset, tag: params.tag, status: params.status });
@@ -17,7 +17,7 @@ export async function getPrivatePools(params, config) {
         method: 'GET',
         headers: buildHeaders(config),
     });
-    return handleResponse(res);
+    return handleResponse(res, '/pools/pools-private');
 }
 export async function getPoolById(params, config) {
     const res = await fetch(`${config.apiUrl}/pools/pool/${encodeURIComponent(params.id)}`, {

package/dist/api/types.d.ts

@@ -87,6 +87,53 @@ export interface PoolToken {
     tokenLogo?: string;
 }
 export type PoolStatus = 'New' | 'Live' | 'Closing_Soon' | 'Pending_Finalization' | 'Waiting_for_Result' | 'Dispute_Window_Open' | 'Under_Dispute' | 'Appeal_Window_Open' | 'Under_Appeal' | 'Closed';
+export type TradingModelName = 'AMM' | 'OrderBook';
+/**
+ * A sub-market (option group) within a Pool. Known fields are typed; the
+ * `[key: string]: any` index signature preserves access to the long tail of
+ * server fields not yet enumerated here, so this is a safe superset — never a
+ * contradiction of the wire.
+ */
+export interface SubPool {
+    _id?: string;
+    subPoolIndex?: number;
+    question?: string;
+    options?: PoolOption[];
+    contractAddress?: string;
+    [key: string]: any;
+}
+/**
+ * The central pool data model. Known fields are typed; the index signature keeps
+ * additional server fields accessible without a cast.
+ */
+export interface Pool {
+    _id: string;
+    contractAddress?: string;
+    question?: string;
+    status?: PoolStatus;
+    tradingModel?: TradingModelName;
+    token?: PoolToken;
+    tags?: string[];
+    options?: PoolOption[];
+    subPools?: SubPool[];
+    isPrivate?: boolean;
+    startDate?: string;
+    endDate?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: any;
+}
+/** Paginated pool listing returned by `getPublicPools` / `getPrivatePools`. */
+export interface PaginatedPools {
+    pools: Pool[];
+    pagination?: {
+        total: number;
+        offset: number;
+        limit: number;
+        totalPages: number;
+    };
+    [key: string]: any;
+}
 export interface CreatePoolParams {
     question: string;
     isPrivate: boolean;

package/dist/auth/login.js

@@ -1,3 +1,18 @@
+/** Decode the `exp` (unix seconds) claim from a JWT without verifying it. Uses `atob` (browser + Node 18+). */
+function decodeJwtExp(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part || typeof atob !== 'function')
+            return undefined;
+        const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+        const payload = JSON.parse(atob(padded));
+        return typeof payload?.exp === 'number' ? payload.exp : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function loginUser(params) {
     const { signature, walletAddress, smartWalletAddress, referredBy, apiUrl } = params;
     // Plain-EOA integrations may omit smartWalletAddress; fall back to the EOA.
@@ -25,5 +40,5 @@ export async function loginUser(params) {
     if (!accessToken || !userId) {
         throw new Error('Login response missing token or user id');
     }
-    return { accessToken, userId };
+    return { accessToken, userId, expiresAt: decodeJwtExp(accessToken) };
 }

package/dist/auth/types.d.ts

@@ -13,4 +13,6 @@ export interface LoginResult {
     accessToken: string;
     /** Backend user ID */
     userId: string;
+    /** Token expiry as a unix timestamp (seconds), decoded from the JWT `exp` claim. Undefined if the token has no `exp`. */
+    expiresAt?: number;
 }

package/dist/config/environments.d.ts

@@ -1,6 +1,5 @@
 export declare const ALLOWED_ENVIRONMENTS: readonly ["development", "stage", "production"];
 export declare const DEFAULT_RPCS: string[];
-export declare function getRandomRpc(): string;
 /** Deterministic default RPC — every instance resolves to the same endpoint. */
 export declare function getDefaultRpc(): string;
 export declare const USDT_SYMBOL_DEV = "USDTm";

package/dist/config/environments.js

@@ -4,10 +4,6 @@ export const DEFAULT_RPCS = [
     "https://arbitrum-one.publicnode.com",
     "https://rpc.sentio.xyz/arbitrum-one"
 ];
-export function getRandomRpc() {
-    const index = Math.floor(Math.random() * DEFAULT_RPCS.length);
-    return DEFAULT_RPCS[index];
-}
 /** Deterministic default RPC — every instance resolves to the same endpoint. */
 export function getDefaultRpc() {
     return DEFAULT_RPCS[0];

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export type { EntrySharesResult } from './markets/getEntryShares.js';
 export type { SellProceedsResult } from './markets/getSellProceeds.js';
 export type { OrderLevelInfo } from './markets/getOrderInfo.js';
 export { RainValidationError, assertDeadline, assertSlippage, assertOption } from './tx/validation.js';
+export { executeTxs } from './tx/execute.js';
+export type { TxExecutor } from './tx/execute.js';
 export type { LoginParams, LoginResult } from './auth/types.js';
 export { signLoginMessage } from './auth/signMessage.js';
 export type { ExtendTimeTxParams } from './tx/buildExtendTimeRawTx.js';
@@ -15,5 +17,5 @@ export type { TokenConfig } from './config/environments.js';
 export type { OptionDisputeInfo, OptionAppealInfo } from './markets/getDisputeState.js';
 export { USDRAbi } from './abi/USDRAbi.js';
 export * from './api/index.js';
-export { RainSocket } from './socket/RainSocket.js';
+export { RainSocket, RAIN_SOCKET_EVENTS } from './socket/RainSocket.js';
 export type { RainSocketEvent, EnterOptionEventData, ExitOptionEventData, LiquidityEventData, SplitEventData, MergeEventData, RemoveLiquidityEventData, SyncPriceEventData, OrderCreatedEventData, OrderCancelledEventData, OrderFilledEventData, PoolClosedEventData, PoolEventData, WinnerEventData, DisputeOpenedEventData, OracleCreatedEventData, AppealOpenedEventData, DisputeWinnerEventData, AppealWinnerEventData, ClaimRewardEventData, DisputeRefundEventData } from './socket/RainSocket.js';

package/dist/index.js

@@ -3,7 +3,8 @@ export { RainAA } from './RainAA.js';
 export * from './types.js';
 export { TradingModel, OptionSide } from './tx/types.js';
 export { RainValidationError, assertDeadline, assertSlippage, assertOption } from './tx/validation.js';
+export { executeTxs } from './tx/execute.js';
 export { signLoginMessage } from './auth/signMessage.js';
 export { USDRAbi } from './abi/USDRAbi.js';
 export * from './api/index.js';
-export { RainSocket } from './socket/RainSocket.js';
+export { RainSocket, RAIN_SOCKET_EVENTS } from './socket/RainSocket.js';

package/dist/socket/RainSocket.d.ts

@@ -1,33 +1,72 @@
+import type { Pool, SubPool } from '../api/types.js';
 export type RainSocketEvent = 'enter-option' | 'exit-option' | 'liquidity' | 'split' | 'merge' | 'remove-liquidity' | 'sync-price' | 'order-created' | 'order-cancelled' | 'order-filled' | 'pool-closed' | 'pool-reverted' | 'pool-token-set' | 'streamingStatusChanged' | 'winner' | 'winner-proposer' | 'reveal-winner-available' | 'dispute-opened' | 'oracle-created' | 'dispute-time-extented' | 'appeal-opened' | 'appeal-winner-calculated' | 'dispute-winner' | 'appeal-winner' | 'claim-reward' | 'dispute-refund' | 'appeal-refund' | 'resolution-refund' | 'resolver-reward' | 'notifications' | 'pool';
+/**
+ * Correctly-spelled, camelCase aliases for the raw wire event names — use these
+ * with the low-level `.on()` API instead of hand-typing the wire strings (some
+ * of which are misspelled upstream, e.g. `dispute-time-extented`).
+ */
+export declare const RAIN_SOCKET_EVENTS: {
+    readonly enterOption: "enter-option";
+    readonly exitOption: "exit-option";
+    readonly liquidity: "liquidity";
+    readonly split: "split";
+    readonly merge: "merge";
+    readonly removeLiquidity: "remove-liquidity";
+    readonly syncPrice: "sync-price";
+    readonly orderCreated: "order-created";
+    readonly orderCancelled: "order-cancelled";
+    readonly orderFilled: "order-filled";
+    readonly poolClosed: "pool-closed";
+    readonly poolReverted: "pool-reverted";
+    readonly poolTokenSet: "pool-token-set";
+    readonly streamingStatusChanged: "streamingStatusChanged";
+    readonly winner: "winner";
+    readonly winnerProposer: "winner-proposer";
+    readonly revealWinnerAvailable: "reveal-winner-available";
+    readonly disputeOpened: "dispute-opened";
+    readonly oracleCreated: "oracle-created";
+    readonly disputeTimeExtended: "dispute-time-extented";
+    readonly appealOpened: "appeal-opened";
+    readonly appealWinnerCalculated: "appeal-winner-calculated";
+    readonly disputeWinner: "dispute-winner";
+    readonly appealWinner: "appeal-winner";
+    readonly claimReward: "claim-reward";
+    readonly disputeRefund: "dispute-refund";
+    readonly appealRefund: "appeal-refund";
+    readonly resolutionRefund: "resolution-refund";
+    readonly resolverReward: "resolver-reward";
+    readonly notifications: "notifications";
+    readonly pool: "pool";
+};
 export interface EnterOptionEventData {
     enterOption: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface ExitOptionEventData {
     exitOption: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface LiquidityEventData {
     enterLiquidity: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface SplitEventData {
     split: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface MergeEventData {
     merge: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface RemoveLiquidityEventData {
     removeLiquidity: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface SyncPriceEventData {
     prices: Array<{
@@ -36,67 +75,67 @@ export interface SyncPriceEventData {
         percentage: number;
         subPoolIndex: number;
     }>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface OrderCreatedEventData {
     order: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface OrderCancelledEventData {
     order: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface OrderFilledEventData {
     filledOrder: Record<string, any>;
     pendingOrder?: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface PoolClosedEventData {
-    pool: Record<string, any>;
-    subPool?: Record<string, any>;
+    pool: Pool;
+    subPool?: SubPool;
 }
 export interface PoolEventData {
-    pool: Record<string, any>;
-    subMarkets?: Record<string, any>[];
+    pool: Pool;
+    subMarkets?: SubPool[];
 }
 export interface WinnerEventData {
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface DisputeOpenedEventData {
-    subPool: Record<string, any>;
+    subPool: SubPool;
     eventType: string;
 }
 export interface OracleCreatedEventData {
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface AppealOpenedEventData {
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface DisputeWinnerEventData {
-    subPool: Record<string, any>;
+    subPool: SubPool;
     eventType: string;
 }
 export interface AppealWinnerEventData {
-    subPool: Record<string, any>;
+    subPool: SubPool;
     eventType: string;
     winnerFinalized: boolean;
 }
 export interface ClaimRewardEventData {
     claimReward: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export interface DisputeRefundEventData {
     claimReward: Record<string, any>;
-    pool: Record<string, any>;
-    subPool: Record<string, any>;
+    pool: Pool;
+    subPool: SubPool;
 }
 export declare class RainSocket {
     private socket;
@@ -153,12 +192,12 @@ export declare class RainSocket {
     onDisputeOpened(poolId: string, callback: (data: DisputeOpenedEventData) => void): () => void;
     onOracleCreated(poolId: string, callback: (data: OracleCreatedEventData) => void): () => void;
     onDisputeTimeExtended(poolId: string, callback: (data: {
-        pool: Record<string, any>;
-        subPool: Record<string, any>;
+        pool: Pool;
+        subPool: SubPool;
     }) => void): () => void;
     onAppealOpened(poolId: string, callback: (data: AppealOpenedEventData) => void): () => void;
     onAppealWinnerCalculated(poolId: string, callback: (data: {
-        subPool: Record<string, any>;
+        subPool: SubPool;
     }) => void): () => void;
     onDisputeWinner(poolId: string, callback: (data: DisputeWinnerEventData) => void): () => void;
     onAppealWinner(poolId: string, callback: (data: AppealWinnerEventData) => void): () => void;

package/dist/socket/RainSocket.js

@@ -1,4 +1,42 @@
 import { io } from 'socket.io-client';
+/**
+ * Correctly-spelled, camelCase aliases for the raw wire event names — use these
+ * with the low-level `.on()` API instead of hand-typing the wire strings (some
+ * of which are misspelled upstream, e.g. `dispute-time-extented`).
+ */
+export const RAIN_SOCKET_EVENTS = {
+    enterOption: 'enter-option',
+    exitOption: 'exit-option',
+    liquidity: 'liquidity',
+    split: 'split',
+    merge: 'merge',
+    removeLiquidity: 'remove-liquidity',
+    syncPrice: 'sync-price',
+    orderCreated: 'order-created',
+    orderCancelled: 'order-cancelled',
+    orderFilled: 'order-filled',
+    poolClosed: 'pool-closed',
+    poolReverted: 'pool-reverted',
+    poolTokenSet: 'pool-token-set',
+    streamingStatusChanged: 'streamingStatusChanged',
+    winner: 'winner',
+    winnerProposer: 'winner-proposer',
+    revealWinnerAvailable: 'reveal-winner-available',
+    disputeOpened: 'dispute-opened',
+    oracleCreated: 'oracle-created',
+    disputeTimeExtended: 'dispute-time-extented',
+    appealOpened: 'appeal-opened',
+    appealWinnerCalculated: 'appeal-winner-calculated',
+    disputeWinner: 'dispute-winner',
+    appealWinner: 'appeal-winner',
+    claimReward: 'claim-reward',
+    disputeRefund: 'dispute-refund',
+    appealRefund: 'appeal-refund',
+    resolutionRefund: 'resolution-refund',
+    resolverReward: 'resolver-reward',
+    notifications: 'notifications',
+    pool: 'pool',
+};
 export class RainSocket {
     socket = null;
     url;

package/dist/tx/execute.d.ts

@@ -0,0 +1,30 @@
+import { RawTransaction } from "./types.js";
+/**
+ * Pluggable executor for sending the raw transactions the builders produce.
+ * Adapt it to viem, ethers, RainAA, or your own KMS — the SDK stays key-agnostic.
+ *
+ * @example viem
+ * const executor = {
+ *   send: (tx) => walletClient.sendTransaction({ to: tx.to, data: tx.data, value: tx.value ?? 0n }),
+ *   wait: (hash) => publicClient.waitForTransactionReceipt({ hash }),
+ * };
+ *
+ * @example RainAA (session key)
+ * const executor = { send: (tx) => rainAA.sendTransaction(tx) };
+ */
+export interface TxExecutor {
+    /** Broadcast one transaction and resolve with its hash. */
+    send: (tx: RawTransaction) => Promise<`0x${string}`>;
+    /** Optional: wait for a hash to be mined before the next send. Strongly recommended for approval→main sequences. */
+    wait?: (hash: `0x${string}`) => Promise<unknown>;
+}
+/**
+ * Sequences an ordered list of raw transactions through an executor, awaiting
+ * each receipt (when `wait` is provided) before sending the next. This is the
+ * correct way to handle the `[approval, main]` arrays the builders return —
+ * sending the main tx before the approval lands is the most common integration
+ * bug.
+ *
+ * @returns the transaction hashes, in order.
+ */
+export declare function executeTxs(txs: RawTransaction[], executor: TxExecutor): Promise<`0x${string}`[]>;

package/dist/tx/execute.js

@@ -0,0 +1,25 @@
+/**
+ * Sequences an ordered list of raw transactions through an executor, awaiting
+ * each receipt (when `wait` is provided) before sending the next. This is the
+ * correct way to handle the `[approval, main]` arrays the builders return —
+ * sending the main tx before the approval lands is the most common integration
+ * bug.
+ *
+ * @returns the transaction hashes, in order.
+ */
+export async function executeTxs(txs, executor) {
+    if (!txs || txs.length === 0)
+        return [];
+    if (typeof executor?.send !== 'function') {
+        throw new Error("executor.send is required");
+    }
+    const hashes = [];
+    for (const tx of txs) {
+        const hash = await executor.send(tx);
+        hashes.push(hash);
+        if (executor.wait) {
+            await executor.wait(hash);
+        }
+    }
+    return hashes;
+}

package/dist/utils/helpers.d.ts

@@ -1,7 +1,8 @@
 import { CreateMarketTxParams } from "../tx/types.js";
 export declare const convertToWeiEthers: (value: string | bigint, decimals: number) => bigint;
+/** Lightweight RPC liveness check via viem `getChainId`. Kept for callers that want a pre-flight probe. */
 export declare function isRpcValid(rpcUrl: string | undefined): Promise<boolean>;
-export declare function getUserAllowance(params: CreateMarketTxParams): Promise<number>;
+export declare function getUserAllowance(params: CreateMarketTxParams): Promise<bigint>;
 /**
  * Checks allowance for a market's base token.
  * Reads baseToken from the market contract, then checks the ERC20 allowance.

package/dist/utils/helpers.js

@@ -1,31 +1,36 @@
-import { ethers, JsonRpcProvider, Contract } from "ethers";
+import { parseUnits, createPublicClient, http } from "viem";
+import { arbitrum } from "viem/chains";
 import { ERC20Abi } from "../abi/ERC20Abi.js";
 import { getMarketBaseToken } from "../markets/getResolverBondAmount.js";
+const erc20Abi = ERC20Abi;
 export const convertToWeiEthers = (value, decimals) => {
-    return ethers.parseUnits(value.toString(), decimals);
+    return parseUnits(value.toString(), decimals);
 };
+/** Lightweight RPC liveness check via viem `getChainId`. Kept for callers that want a pre-flight probe. */
 export async function isRpcValid(rpcUrl) {
     if (!rpcUrl)
         return false;
-    const provider = new JsonRpcProvider(rpcUrl);
     try {
-        await provider.getNetwork();
+        const client = createPublicClient({ chain: arbitrum, transport: http(rpcUrl) });
+        await client.getChainId();
         return true;
     }
-    catch (error) {
+    catch {
         return false;
     }
 }
 export async function getUserAllowance(params) {
     const { factoryContractAddress, baseToken, creator, rpcUrl } = params;
-    const isRpcWorking = await isRpcValid(rpcUrl);
-    if (!rpcUrl || !isRpcWorking) {
+    if (!rpcUrl)
         throw new Error("Provided RPC URL is not valid or not working");
-    }
-    const provider = new JsonRpcProvider(rpcUrl);
-    const ERC20ApprovalContract = new Contract(baseToken, ERC20Abi, provider);
-    const userAllowance = await ERC20ApprovalContract.allowance(creator, factoryContractAddress);
-    return userAllowance;
+    const client = createPublicClient({ chain: arbitrum, transport: http(rpcUrl) });
+    const allowance = await client.readContract({
+        address: baseToken,
+        abi: erc20Abi,
+        functionName: 'allowance',
+        args: [creator, factoryContractAddress],
+    });
+    return allowance;
 }
 /**
  * Checks allowance for a market's base token.
@@ -34,19 +39,16 @@ export async function getUserAllowance(params) {
  */
 export async function checkMarketTokenAllowance(params) {
     const { marketContractAddress, owner, rpcUrl } = params;
-    const isRpcWorking = await isRpcValid(rpcUrl);
-    if (!rpcUrl || !isRpcWorking) {
+    if (!rpcUrl)
         throw new Error("Provided RPC URL is not valid or not working");
-    }
     const baseToken = await getMarketBaseToken({ marketContractAddress, rpcUrl });
-    const provider = new JsonRpcProvider(rpcUrl);
-    const tokenContract = new Contract(baseToken, ERC20Abi, provider);
+    const client = createPublicClient({ chain: arbitrum, transport: http(rpcUrl) });
     const [userAllowance, tokenDecimals] = await Promise.all([
-        tokenContract.allowance(owner, marketContractAddress),
-        tokenContract.decimals(),
+        client.readContract({ address: baseToken, abi: erc20Abi, functionName: 'allowance', args: [owner, marketContractAddress] }),
+        client.readContract({ address: baseToken, abi: erc20Abi, functionName: 'decimals' }),
     ]);
     return {
-        allowance: BigInt(userAllowance),
+        allowance: userAllowance,
         baseToken,
         decimals: Number(tokenDecimals),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rain-sdk-v2",
-    "version": "2.2.0",
+    "version": "2.4.0",
     "type": "module",
     "description": "Rain SDK V2 — TypeScript SDK for Rain prediction markets on Arbitrum. Market creation, trading, liquidity, order book, split/merge, dispute, and smart account support.",
     "main": "dist/index.js",
@@ -19,6 +19,9 @@
     "scripts": {
         "build": "tsc",
         "dev": "tsc -w",
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:integration": "RUN_INTEGRATION=1 vitest run test/integration.test.ts",
         "prepublishOnly": "npm run build"
     },
     "repository": {
@@ -57,11 +60,11 @@
         }
     },
     "dependencies": {
-        "ethers": "^6.16.0",
         "socket.io-client": "^4.8.3"
     },
     "devDependencies": {
         "typescript": "^5.9.3",
-        "viem": "^2.48.8"
+        "viem": "^2.48.8",
+        "vitest": "^5.0.1"
     }
 }