rain-sdk-v2 2.1.8 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+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.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
+synchronously (before broadcast) instead of as on-chain reverts or parsed
+strings. Existing `catch (e)` blocks keep working — the new errors extend `Error`.
+
+### Added
+- **Build-time parameter validation (F-03):** every transaction builder now
+  rejects the documented footguns before encoding — a `deadline` that looks like
+  a duration (`< 1_000_000_000`) or is already expired, a `slippageTolerance`
+  outside `0–100` (whole percent, not bps), and a 0-based `option`/`selectedOption`
+  (options are 1-based). Throws the new `RainValidationError`. Exported helpers:
+  `assertDeadline`, `assertSlippage`, `assertOption`.
+- **Structured API errors (F-06):** non-2xx REST responses now throw
+  `RainApiError` carrying `status`, `endpoint`, `body`, and a stable `code`
+  (`NOT_FOUND` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `SERVER_ERROR` |
+  `UNKNOWN`) — branch on `err.code` instead of parsing message strings.
+
+### Changed
+- **Empty states are no longer errors (F-06):** `getPnlByPoolId` (no position)
+  and `getTokenPrice` (non-whitelisted token) now return
+  `{ statusCode: 200, data: null }` on a 404 instead of throwing.
+- **Deterministic default RPC (F-09):** omitting `rpcUrl` now resolves to a
+  single fixed public RPC (previously random per instance). In `production`
+  without an `rpcUrl`, the SDK emits a `console.warn` recommending a dedicated
+  endpoint.
+
+## [2.1.9] - Correctness patch
+
+Addresses findings from the September 2026 independent technical review. No
+behaviour change for correct callers.
+
+### Fixed
+- **Missing type exports (F-10):** `SellOptionTxParams`, `EntrySharesResult`,
+  `SellProceedsResult`, and `OrderLevelInfo` are now exported from the package
+  root, so consumers can annotate their own functions with them.
+- **`RainConfig` type honesty (F-04):** `alchemyApiKey` and `paymasterPolicyId`
+  are now required in the type — the `RainAA` constructor already threw without
+  them. The type now matches runtime behaviour.
+- **`smartWalletAddress` optional (F-08):** `LoginParams.smartWalletAddress` is
+  now optional and defaults to `walletAddress`, so plain-EOA integrations no
+  longer have to pass the address twice.
+
+### Notes
+- Two review findings (F-01 reverting order reads, F-02 REST type/wire
+  mismatches) require verification against the live dev API/contracts before any
+  change and are intentionally not addressed in this release.

package/README.md

@@ -24,7 +24,7 @@ import { arbitrum } from 'viem/chains';
 // Initialize SDK
 const rain = new Rain({
   environment: 'development', // 'development' | 'stage' | 'production'
-  rpcUrl: 'https://arb1.arbitrum.io/rpc', // optional, uses random public RPC if omitted
+  rpcUrl: 'https://arb1.arbitrum.io/rpc', // optional; falls back to a public RPC (pass your own in production)
 });
 
 // Get environment config
@@ -62,7 +62,7 @@ const rain = new Rain(config?: RainCoreConfig);
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `environment` | `'development' \| 'stage' \| 'production'` | `'development'` | Target environment |
-| `rpcUrl` | `string` | Random public RPC | Custom Arbitrum RPC URL |
+| `rpcUrl` | `string` | Fixed public RPC | Custom Arbitrum RPC URL. Omitting it uses a single deterministic public RPC; in `production` this also emits a `console.warn` — pass a dedicated endpoint. |
 | `apiUrl` | `string` | From environment | Custom API URL |
 
 ---
@@ -852,7 +852,7 @@ const signature = await signLoginMessage(walletClient, '0x...' as `0x${string}`)
 const result = await rain.login({
   signature, // from signLoginMessage
   walletAddress: '0x...', // EOA address
-  smartWalletAddress: '0x...', // Smart account address
+  smartWalletAddress: '0x...', // optional — defaults to walletAddress for plain-EOA integrations
   referredBy: 'CODE', // optional referral code
 });
 
@@ -1544,6 +1544,115 @@ 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
+
+Transaction builders validate their inputs synchronously — before any encoding
+or broadcast — and throw `RainValidationError` on the common footguns:
+
+- `deadline` must be an **absolute unix timestamp** (seconds), not a duration.
+  `deadline: 600n` is rejected; use `BigInt(Math.floor(Date.now()/1000) + 600)`.
+- `slippageTolerance` is a **whole percent** (`5n` = 5%), and must be `0–100`.
+- `option` / `selectedOption` are **1-based** (the first option is `1`, never `0`).
+
+```typescript
+import { RainValidationError } from 'rain-sdk-v2';
+
+try {
+  await rain.buildEnterOptionTx({ /* ... */, deadline: 600n });
+} catch (err) {
+  if (err instanceof RainValidationError) {
+    console.error(err.field, err.message); // 'deadline', 'Invalid deadline: ...'
+  }
+}
+```
+
+### API errors
+
+REST methods throw `RainApiError` (a subclass of `Error`) on non-2xx responses,
+carrying structured fields so you can branch on `code` instead of parsing strings:
+
+```typescript
+import { RainApiError } from 'rain-sdk-v2';
+
+try {
+  await rain.getSomeData(/* ... */);
+} catch (err) {
+  if (err instanceof RainApiError) {
+    console.error(err.status, err.code, err.endpoint, err.body);
+    // code: 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN'
+  }
+}
+```
+
+Legitimate empty states are **not** errors: `getPnlByPoolId` (no position) and
+`getTokenPrice` (non-whitelisted token) return `{ statusCode: 200, data: null }`
+rather than throwing on a 404.
+
+---
+
 ## License
 
 MIT

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

@@ -14,7 +14,7 @@ import { buildCancelBuyOrdersRawTx, buildCancelSellOrdersRawTx } from './tx/buil
 import { buildCalculateWinnerRawTx } from './tx/buildCalculateWinnerRawTx.js';
 import { buildExtendTimeRawTx } from './tx/buildExtendTimeRawTx.js';
 import { getUserActiveBuyOrders, getUserActiveSellOrders, getFirstBuyOrderPrice, getFirstSellOrderPrice, getBuyOrdersAtPrice, getSellOrdersAtPrice, checkOrderExists } from './markets/getOrderInfo.js';
-import { ALLOWED_ENVIRONMENTS, ENV_CONFIG, getRandomRpc } from './config/environments.js';
+import { ALLOWED_ENVIRONMENTS, ENV_CONFIG, getDefaultRpc } from './config/environments.js';
 import { loginUser } from './auth/login.js';
 import { getUserOptionLPShares } from './markets/getUserOptionLPShares.js';
 import { getUserOptionShares } from './markets/getUserOptionShares.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';
@@ -72,7 +73,11 @@ export class Rain {
             throw new Error(`Invalid environment "${environment}". Allowed values: ${ALLOWED_ENVIRONMENTS.join(", ")}`);
         }
         this.environment = environment;
-        this.rpcUrl = rpcUrl ?? getRandomRpc();
+        if (!rpcUrl && environment === "production") {
+            console.warn("[rain-sdk-v2] No rpcUrl provided in production; falling back to a public Arbitrum RPC. " +
+                "Public RPCs have shared rate limits and varying reliability — pass a dedicated rpcUrl.");
+        }
+        this.rpcUrl = rpcUrl ?? getDefaultRpc();
         const envConfig = ENV_CONFIG[this.environment];
         this.marketFactory = envConfig.market_factory_address;
         this.apiUrl = apiUrl ?? envConfig.apiUrl;
@@ -94,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/api/helpers.d.ts

@@ -1,4 +1,18 @@
 import { ApiConfig } from './types.js';
 export declare function buildHeaders(config: ApiConfig, contentType?: string): Record<string, string>;
 export declare function buildQuery(params: Record<string, string | number | boolean | undefined | null>): string;
-export declare function handleResponse<T>(res: Response): Promise<T>;
+export type RainApiErrorCode = 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'UNKNOWN';
+/**
+ * Structured error thrown by every REST wrapper on a non-2xx response.
+ * Extends `Error` (so existing `catch` blocks keep working) but adds
+ * `status`, `endpoint`, `body`, and a stable `code` to branch on instead of
+ * parsing message strings.
+ */
+export declare class RainApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    readonly endpoint?: string | undefined;
+    readonly code: RainApiErrorCode;
+    constructor(status: number, body: unknown, endpoint?: string | undefined, code?: RainApiErrorCode);
+}
+export declare function handleResponse<T>(res: Response, endpoint?: string): Promise<T>;

package/dist/api/helpers.js

@@ -17,10 +17,44 @@ export function buildQuery(params) {
         return '';
     return '?' + entries.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join('&');
 }
-export async function handleResponse(res) {
+/**
+ * Structured error thrown by every REST wrapper on a non-2xx response.
+ * Extends `Error` (so existing `catch` blocks keep working) but adds
+ * `status`, `endpoint`, `body`, and a stable `code` to branch on instead of
+ * parsing message strings.
+ */
+export class RainApiError extends Error {
+    status;
+    body;
+    endpoint;
+    code;
+    constructor(status, body, endpoint, code = 'UNKNOWN') {
+        super(`Rain API error ${status}${endpoint ? ` on ${endpoint}` : ''}`);
+        this.status = status;
+        this.body = body;
+        this.endpoint = endpoint;
+        this.code = code;
+        this.name = 'RainApiError';
+    }
+}
+function codeForStatus(status) {
+    switch (status) {
+        case 401: return 'UNAUTHORIZED';
+        case 403: return 'FORBIDDEN';
+        case 404: return 'NOT_FOUND';
+        case 429: return 'RATE_LIMITED';
+        default: return status >= 500 ? 'SERVER_ERROR' : 'UNKNOWN';
+    }
+}
+export async function handleResponse(res, endpoint) {
     if (!res.ok) {
         const text = await res.text().catch(() => res.statusText);
-        throw new Error(`API error (${res.status}): ${text}`);
+        let body = text;
+        try {
+            body = JSON.parse(text);
+        }
+        catch { /* not JSON — keep raw text */ }
+        throw new RainApiError(res.status, body, endpoint, codeForStatus(res.status));
     }
     return res.json();
 }

package/dist/api/investments.js

@@ -91,11 +91,16 @@ export async function calculateUserPNLPerPool(config) {
     return handleResponse(res);
 }
 export async function getPnlByPoolId(params, config) {
-    const res = await fetch(`${config.apiUrl}/investments/pnl/${encodeURIComponent(params.poolId)}`, {
+    const endpoint = `/investments/pnl/${encodeURIComponent(params.poolId)}`;
+    const res = await fetch(`${config.apiUrl}${endpoint}`, {
         method: 'GET',
         headers: buildHeaders(config),
     });
-    return handleResponse(res);
+    // No position in this pool is a legitimate empty state, not an error.
+    if (res.status === 404) {
+        return { statusCode: 200, message: 'No position for this pool', data: null };
+    }
+    return handleResponse(res, endpoint);
 }
 export async function getTopWinnersLosers(params, config) {
     const qs = buildQuery({ timeFilter: params.timeFilter });

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/api/whitelistedTokens.js

@@ -1,8 +1,13 @@
 import { buildHeaders, handleResponse } from './helpers.js';
 export async function getTokenPrice(tokenAddress, config) {
-    const res = await fetch(`${config.apiUrl}/whitelisted-tokens/get-token-price?tokenAddress=${encodeURIComponent(tokenAddress)}`, {
+    const endpoint = '/whitelisted-tokens/get-token-price';
+    const res = await fetch(`${config.apiUrl}${endpoint}?tokenAddress=${encodeURIComponent(tokenAddress)}`, {
         method: 'GET',
         headers: buildHeaders(config),
     });
-    return handleResponse(res);
+    // A non-whitelisted token is a legitimate empty state, not an error.
+    if (res.status === 404) {
+        return { statusCode: 200, message: 'Token not whitelisted or no price available', data: null };
+    }
+    return handleResponse(res, endpoint);
 }

package/dist/auth/login.js

@@ -1,5 +1,25 @@
+/** Decode the `exp` (unix seconds) claim from a JWT without verifying it. Cross-environment (browser + Node). */
+function decodeJwtExp(token) {
+    try {
+        const part = token.split('.')[1];
+        if (!part)
+            return undefined;
+        const b64 = part.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = b64 + '='.repeat((4 - (b64.length % 4)) % 4);
+        const json = typeof atob === 'function'
+            ? atob(padded)
+            : Buffer.from(padded, 'base64').toString('binary');
+        const payload = JSON.parse(json);
+        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.
+    const resolvedSmartWalletAddress = smartWalletAddress ?? walletAddress;
     const res = await fetch(`${apiUrl}/auth/login-or-register-with-walletAddress`, {
         method: 'POST',
         headers: {
@@ -9,7 +29,7 @@ export async function loginUser(params) {
         body: JSON.stringify({
             sign: signature,
             walletAddress,
-            userSmartAddress: smartWalletAddress,
+            userSmartAddress: resolvedSmartWalletAddress,
             ...(referredBy ? { referredBy } : {}),
         }),
     });
@@ -23,5 +43,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

@@ -3,8 +3,8 @@ export interface LoginParams {
     signature: string;
     /** EOA wallet address */
     walletAddress: string;
-    /** Smart account / AA wallet address */
-    smartWalletAddress: string;
+    /** Smart account / AA wallet address. Defaults to `walletAddress` for plain-EOA integrations. */
+    smartWalletAddress?: string;
     /** Optional referral code */
     referredBy?: string;
 }
@@ -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,8 @@
 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";
 export interface TokenConfig {
     address: `0x${string}`;

package/dist/config/environments.js

@@ -8,6 +8,10 @@ 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];
+}
 export const USDT_SYMBOL_DEV = "USDTm";
 export const ENV_CONFIG = {
     development: {

package/dist/index.d.ts

@@ -2,7 +2,13 @@ export { Rain } from './Rain.js';
 export { RainAA } from './RainAA.js';
 export * from './types.js';
 export { TradingModel, OptionSide } from './tx/types.js';
-export type { CreateMarketTxParams, EnterOptionTxParams, AddLiquidityTxParams, RemoveLiquidityTxParams, SplitTxParams, MergeTxParams, ClosePoolAITxParams, ClosePoolManualTxParams, ChooseWinnerTxParams, PlaceBuyOrderTxParams, PlaceSellOrderTxParams, OpenDisputeTxParams, ClaimTxParams, CancelBuyOrdersTxParams, CancelSellOrdersTxParams, RawTransaction, ApproveTxParams } from './tx/types.js';
+export type { CreateMarketTxParams, EnterOptionTxParams, AddLiquidityTxParams, RemoveLiquidityTxParams, SplitTxParams, MergeTxParams, ClosePoolAITxParams, ClosePoolManualTxParams, ChooseWinnerTxParams, PlaceBuyOrderTxParams, PlaceSellOrderTxParams, OpenDisputeTxParams, ClaimTxParams, CancelBuyOrdersTxParams, CancelSellOrdersTxParams, RawTransaction, ApproveTxParams, SellOptionTxParams } from './tx/types.js';
+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';
@@ -11,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

@@ -2,7 +2,9 @@ export { Rain } from './Rain.js';
 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/buildAddLiquidityRawTx.js

@@ -4,6 +4,7 @@ import { MarketsAbi } from "../abi/MarketsAbi.js";
 import { ENTER_LIQUIDITY } from "../constants/contractmethods.js";
 import { checkMarketTokenAllowance } from "../utils/helpers.js";
 import { buildApproveRawTx } from "./buildApprovalRawTx.js";
+import { assertOption, assertSlippage, assertDeadline } from "./validation.js";
 const DEFAULT_SLIPPAGE = 5n; // 5%
 const DEFAULT_DEADLINE_DURATION = 600; // 10 minutes
 export async function buildAddLiquidityRawTx(params) {
@@ -16,6 +17,9 @@ export async function buildAddLiquidityRawTx(params) {
         throw new Error("totalAmountInWei is required");
     if (totalAmountInWei <= 0n)
         throw new Error("totalAmountInWei must be greater than 0");
+    assertOption(option);
+    assertSlippage(slippageTolerance);
+    assertDeadline(deadline);
     const { allowance, baseToken } = await checkMarketTokenAllowance({ marketContractAddress, owner: walletAddress, rpcUrl });
     const txs = [];
     if (allowance < totalAmountInWei) {

package/dist/tx/buildEnterOptionRawTx.js

@@ -4,6 +4,7 @@ import { MarketsAbi } from "../abi/MarketsAbi.js";
 import { ENTER_OPTION } from "../constants/contractmethods.js";
 import { checkMarketTokenAllowance } from "../utils/helpers.js";
 import { buildApproveRawTx } from "./buildApprovalRawTx.js";
+import { assertOption, assertSlippage, assertDeadline } from "./validation.js";
 const DEFAULT_SLIPPAGE = 5n; // 5%
 const DEFAULT_DEADLINE_DURATION = 600; // 10 minutes
 export async function buildEnterOptionRawTx(params) {
@@ -18,6 +19,9 @@ export async function buildEnterOptionRawTx(params) {
         throw new Error("buyAmountInWei is required");
     if (buyAmountInWei <= 0n)
         throw new Error("buyAmountInWei must be greater than 0");
+    assertOption(selectedOption, "selectedOption");
+    assertSlippage(slippageTolerance);
+    assertDeadline(deadline);
     const { allowance, baseToken } = await checkMarketTokenAllowance({ marketContractAddress, owner: walletAddress, rpcUrl });
     const txs = [];
     if (allowance < buyAmountInWei) {

package/dist/tx/buildPlaceOrderRawTx.js

@@ -3,6 +3,7 @@ import { MarketsAbi } from "../abi/MarketsAbi.js";
 import { PLACE_BUY_ORDER, PLACE_SELL_ORDER } from "../constants/contractmethods.js";
 import { checkMarketTokenAllowance } from "../utils/helpers.js";
 import { buildApproveRawTx } from "./buildApprovalRawTx.js";
+import { assertOption } from "./validation.js";
 export async function buildPlaceBuyOrderRawTx(params) {
     const { marketContractAddress, option, optionSide, price, amount, postOnly = false, walletAddress, rpcUrl } = params;
     if (!marketContractAddress)
@@ -15,6 +16,7 @@ export async function buildPlaceBuyOrderRawTx(params) {
         throw new Error("price must be greater than 0");
     if (!amount || amount <= 0n)
         throw new Error("amount must be greater than 0");
+    assertOption(option);
     const { allowance, baseToken } = await checkMarketTokenAllowance({ marketContractAddress, owner: walletAddress, rpcUrl });
     const txs = [];
     if (allowance < amount) {
@@ -43,6 +45,7 @@ export function buildPlaceSellOrderRawTx(params) {
         throw new Error("price must be greater than 0");
     if (!shares || shares <= 0n)
         throw new Error("shares must be greater than 0");
+    assertOption(option);
     return {
         to: marketContractAddress,
         data: encodeFunctionData({

package/dist/tx/buildRemoveLiquidityRawTx.js

@@ -2,6 +2,7 @@ import { encodeFunctionData, createPublicClient, http } from "viem";
 import { arbitrum } from "viem/chains";
 import { MarketsAbi } from "../abi/MarketsAbi.js";
 import { REMOVE_LIQUIDITY } from "../constants/contractmethods.js";
+import { assertOption, assertSlippage, assertDeadline } from "./validation.js";
 const DEFAULT_SLIPPAGE = 5n; // 5%
 const DEFAULT_DEADLINE_DURATION = 600; // 10 minutes
 export async function buildRemoveLiquidityRawTx(params) {
@@ -14,6 +15,9 @@ export async function buildRemoveLiquidityRawTx(params) {
         throw new Error("lpShares is required");
     if (lpShares <= 0n)
         throw new Error("lpShares must be greater than 0");
+    assertOption(option);
+    assertSlippage(slippageTolerance);
+    assertDeadline(deadline);
     let effectiveMinYes = minYesOut;
     let effectiveMinNo = minNoOut;
     if ((effectiveMinYes === undefined || effectiveMinYes === null) && (effectiveMinNo === undefined || effectiveMinNo === null)) {

package/dist/tx/buildSellOptionRawTx.js

@@ -1,6 +1,7 @@
 import { encodeFunctionData } from "viem";
 import { MarketsAbi } from "../abi/MarketsAbi.js";
 import { SELL_OPTION } from "../constants/contractmethods.js";
+import { assertOption, assertDeadline } from "./validation.js";
 const DEFAULT_DEADLINE_DURATION = 600; // 10 minutes
 export function buildSellOptionRawTx(params) {
     const { marketContractAddress, selectedOption, optionSide, sharesAmount, minAmountOut, deadline } = params;
@@ -15,6 +16,8 @@ export function buildSellOptionRawTx(params) {
         throw new Error("sharesAmount is required");
     if (sharesAmount <= 0n)
         throw new Error("sharesAmount must be greater than 0");
+    assertOption(selectedOption, "selectedOption");
+    assertDeadline(deadline);
     return {
         to: marketContractAddress,
         data: encodeFunctionData({

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/tx/validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Synchronous, build-time parameter guards shared across the transaction
+ * builders. These convert documented footguns (durations passed as deadlines,
+ * slippage in the wrong unit, 0-based option indices) into immediate, descriptive
+ * errors — before any encoding or broadcast.
+ */
+export declare class RainValidationError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Deadlines are absolute unix timestamps (seconds), not durations. Optional — skipped when omitted. */
+export declare function assertDeadline(deadline?: bigint | null): void;
+/** slippageTolerance is a whole percent (e.g. 5 = 5%), not basis points. Optional — skipped when omitted. */
+export declare function assertSlippage(slippageTolerance?: bigint | null): void;
+/** Option indices are 1-based across the SDK (the first option is 1, never 0). */
+export declare function assertOption(option: bigint | undefined | null, field?: string): void;

package/dist/tx/validation.js

@@ -0,0 +1,45 @@
+/**
+ * Synchronous, build-time parameter guards shared across the transaction
+ * builders. These convert documented footguns (durations passed as deadlines,
+ * slippage in the wrong unit, 0-based option indices) into immediate, descriptive
+ * errors — before any encoding or broadcast.
+ */
+export class RainValidationError extends Error {
+    field;
+    constructor(field, message) {
+        super(`Invalid ${field}: ${message}`);
+        this.field = field;
+        this.name = 'RainValidationError';
+    }
+}
+// Any value below this looks like a duration (seconds) rather than an absolute
+// unix timestamp. 1_000_000_000 = 2001-09-09; any real deadline is far larger.
+const MIN_PLAUSIBLE_TIMESTAMP = 1000000000n;
+/** Deadlines are absolute unix timestamps (seconds), not durations. Optional — skipped when omitted. */
+export function assertDeadline(deadline) {
+    if (deadline === undefined || deadline === null)
+        return;
+    if (deadline < MIN_PLAUSIBLE_TIMESTAMP) {
+        throw new RainValidationError('deadline', `${deadline} looks like a duration; pass an absolute unix timestamp in seconds`);
+    }
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    if (deadline <= now) {
+        throw new RainValidationError('deadline', `${deadline} is already in the past`);
+    }
+}
+/** slippageTolerance is a whole percent (e.g. 5 = 5%), not basis points. Optional — skipped when omitted. */
+export function assertSlippage(slippageTolerance) {
+    if (slippageTolerance === undefined || slippageTolerance === null)
+        return;
+    if (slippageTolerance < 0n || slippageTolerance > 100n) {
+        throw new RainValidationError('slippageTolerance', `${slippageTolerance} must be between 0 and 100 (whole percent, not basis points)`);
+    }
+}
+/** Option indices are 1-based across the SDK (the first option is 1, never 0). */
+export function assertOption(option, field = 'option') {
+    if (option === undefined || option === null)
+        return;
+    if (option < 1n) {
+        throw new RainValidationError(field, `${option} is invalid; options are 1-based (the first option is 1)`);
+    }
+}

package/dist/types.d.ts

@@ -2,8 +2,10 @@ import { WalletClient } from 'viem';
 import { Chain } from 'viem/chains';
 export interface RainConfig {
     walletClient: WalletClient;
-    alchemyApiKey?: string;
-    paymasterPolicyId?: string;
+    /** Required: the RainAA constructor throws without it (gas-sponsored AA). */
+    alchemyApiKey: string;
+    /** Required: the RainAA constructor throws without it (paymaster policy). */
+    paymasterPolicyId: string;
     chain: Chain;
     rpcUrl?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rain-sdk-v2",
-    "version": "2.1.8",
+    "version": "2.3.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",
@@ -13,7 +13,8 @@
     },
     "files": [
         "dist",
-        "README.md"
+        "README.md",
+        "CHANGELOG.md"
     ],
     "scripts": {
         "build": "tsc",