rain-sdk-v2 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -3,6 +3,36 @@
 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

package/README.md

@@ -1544,6 +1544,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/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,21 @@
+/** 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.
@@ -25,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

@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rain-sdk-v2",
-    "version": "2.2.0",
+    "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",