rain-sdk-v2 2.1.7 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to `rain-sdk-v2` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## [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,54 @@ socket.disconnect();
 
 ---
 
+## 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

@@ -21,7 +21,8 @@ export declare class Rain {
     buildApprovalTx(params: ApproveTxParams): RawTransaction;
     getCreateMarketFees(tokenAddress: `0x${string}`, inputAmountWei: bigint): Promise<{
         oracleFeePerOption: bigint;
-        liquidityFeeBps: bigint;
+        liquidityFee: bigint;
+        feeMagnification: bigint;
         useBufferApproval: boolean;
         perOptionBuffer: bigint;
     }>;

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';
@@ -51,6 +51,12 @@ const factoryViewAbi = parseAbi([
     'function liquidityFee() view returns (uint256)',
     'function baseToken() view returns (address)',
 ]);
+// Scale of the factory's liquidityFee(). Matches the market contracts'
+// FEE_MAGNIFICATION constant (verified on-chain = 1000 on dev and production
+// markets; the factory itself does not expose it). liquidityFee() = 12 means
+// a 1.2% fee — the unit is per-mille, NOT basis points: dividing by 10000
+// computes every fee 10x too small.
+const FEE_MAGNIFICATION = 1000n;
 export class Rain {
     environment;
     marketFactory;
@@ -66,7 +72,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;
@@ -90,26 +100,26 @@ export class Rain {
     }
     async getCreateMarketFees(tokenAddress, inputAmountWei) {
         const pc = createPublicClient({ chain: arbitrum, transport: http(this.rpcUrl) });
-        const [oracleFeeRaw, liquidityFeeBps, factoryBaseToken] = await Promise.all([
+        const [oracleFeeRaw, liquidityFee, factoryBaseToken] = await Promise.all([
             pc.readContract({ address: this.marketFactory, abi: factoryViewAbi, functionName: 'oracleFixedFee' }),
             pc.readContract({ address: this.marketFactory, abi: factoryViewAbi, functionName: 'liquidityFee' }),
             pc.readContract({ address: this.marketFactory, abi: factoryViewAbi, functionName: 'baseToken' }),
         ]);
         if (tokenAddress.toLowerCase() === factoryBaseToken.toLowerCase()) {
-            return { oracleFeePerOption: oracleFeeRaw, liquidityFeeBps: liquidityFeeBps, useBufferApproval: false, perOptionBuffer: 0n };
+            return { oracleFeePerOption: oracleFeeRaw, liquidityFee: liquidityFee, feeMagnification: FEE_MAGNIFICATION, useBufferApproval: false, perOptionBuffer: 0n };
         }
         // For non-base tokens (e.g. RAIN): approval = initialLiquidity + (numberOfOptions * 20% of initialLiquidity)
         const perOptionBuffer = inputAmountWei * 20n / 100n;
-        return { oracleFeePerOption: 0n, liquidityFeeBps: liquidityFeeBps, useBufferApproval: true, perOptionBuffer };
+        return { oracleFeePerOption: 0n, liquidityFee: liquidityFee, feeMagnification: FEE_MAGNIFICATION, useBufferApproval: true, perOptionBuffer };
     }
     async buildCreateMarketTx(params) {
         const tokenConfig = this.getTokenConfig(params.baseToken);
         const tokenDecimals = params.tokenDecimals ?? tokenConfig?.decimals ?? 6;
-        const { oracleFeePerOption, liquidityFeeBps, useBufferApproval, perOptionBuffer } = await this.getCreateMarketFees(params.baseToken, params.inputAmountWei);
+        const { oracleFeePerOption, liquidityFee, feeMagnification, useBufferApproval, perOptionBuffer } = await this.getCreateMarketFees(params.baseToken, params.inputAmountWei);
         if (useBufferApproval) {
             return buildCreateMarketRawTx({ ...params, tokenDecimals, factoryContractAddress: this.marketFactory, apiUrl: this.apiUrl, rpcUrl: this.rpcUrl, disputeTimer: this.distute_initial_timer, oracleFixedFeePerOption: perOptionBuffer });
         }
-        const liquidityFeeAmount = params.inputAmountWei * liquidityFeeBps / 10000n;
+        const liquidityFeeAmount = params.inputAmountWei * liquidityFee / feeMagnification;
         const totalOracleFee = oracleFeePerOption * BigInt(params.no_of_options) + liquidityFeeAmount;
         return buildCreateMarketRawTx({ ...params, tokenDecimals, factoryContractAddress: this.marketFactory, apiUrl: this.apiUrl, rpcUrl: this.rpcUrl, disputeTimer: this.distute_initial_timer, oracleFixedFeePerOption: totalOracleFee / BigInt(params.no_of_options) + 1n });
     }

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/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,7 @@
 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 +11,7 @@ export async function loginUser(params) {
         body: JSON.stringify({
             sign: signature,
             walletAddress,
-            userSmartAddress: smartWalletAddress,
+            userSmartAddress: resolvedSmartWalletAddress,
             ...(referredBy ? { referredBy } : {}),
         }),
     });

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;
 }

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,11 @@ 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 type { LoginParams, LoginResult } from './auth/types.js';
 export { signLoginMessage } from './auth/signMessage.js';
 export type { ExtendTimeTxParams } from './tx/buildExtendTimeRawTx.js';

package/dist/index.js

@@ -2,6 +2,7 @@ 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 { signLoginMessage } from './auth/signMessage.js';
 export { USDRAbi } from './abi/USDRAbi.js';
 export * from './api/index.js';

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/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.7",
+    "version": "2.2.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",
@@ -63,4 +64,4 @@
         "typescript": "^5.9.3",
         "viem": "^2.48.8"
     }
-}
+}