@pulsepairs/sdk 0.2.0

package/dist/approve.js

@@ -0,0 +1,69 @@
+const ERC20_ABI = [
+    {
+        type: "function",
+        name: "allowance",
+        stateMutability: "view",
+        inputs: [
+            { name: "owner", type: "address" },
+            { name: "spender", type: "address" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "approve",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "spender", type: "address" },
+            { name: "value", type: "uint256" },
+        ],
+        outputs: [{ name: "", type: "bool" }],
+    },
+];
+export const MAX_UINT256 = (1n << 256n) - 1n;
+/** Default refresh threshold — re-approve if allowance falls below 10k USDT.
+ *  MaxUint256 effectively never decreases with USDT, but if a partial
+ *  approval was set in some flow this guards against drift. */
+const DEFAULT_THRESHOLD = 10000n * 1000000n;
+/**
+ * Ensure the maker has enough USDT allowance on the settlement contract.
+ *
+ * @param args.publicClient — viem `createPublicClient(...)` for reads.
+ * @param args.walletClient — viem `createWalletClient({ account, ... })`
+ *                            with the maker's account (must have ETH for gas).
+ * @param args.usdt — USDT token address (from `cfg.usdtAddress`).
+ * @param args.settlement — Settlement contract address (from
+ *                          `cfg.pairs[0].settlementAddress` for today's
+ *                          single-settlement deploy).
+ * @param args.threshold — Re-approve when current allowance is below this
+ *                         atomic-USDT amount. Default 10,000 USDT.
+ *
+ * Returns `already_ok` if nothing needed to be done, `approved` with the
+ * tx hash if a new approval was sent. Caller can `await
+ * publicClient.waitForTransactionReceipt({ hash })` if it wants to confirm
+ * before placing orders.
+ */
+export async function ensureSettlementAllowance(args) {
+    const account = args.walletClient.account;
+    if (!account)
+        throw new Error("walletClient has no account");
+    const owner = account.address;
+    const threshold = args.threshold ?? DEFAULT_THRESHOLD;
+    const current = (await args.publicClient.readContract({
+        address: args.usdt,
+        abi: ERC20_ABI,
+        functionName: "allowance",
+        args: [owner, args.settlement],
+    }));
+    if (current >= threshold)
+        return { status: "already_ok", allowance: current };
+    const txHash = await args.walletClient.writeContract({
+        account,
+        chain: args.walletClient.chain ?? null,
+        address: args.usdt,
+        abi: ERC20_ABI,
+        functionName: "approve",
+        args: [args.settlement, MAX_UINT256],
+    });
+    return { status: "approved", txHash, allowance: MAX_UINT256 };
+}

package/dist/auth.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Phase 3 / Gate 1 — L2 HMAC auth helpers for the TypeScript SDK.
+ *
+ * Two surfaces:
+ *   - `buildHmacSignature(secret, timestamp, method, path, body?)` — exact
+ *     bytes-level match with the backend's `lib/hmacAuth.ts` and with
+ *     Polymarket's `clob-client/src/signing/hmac.ts`. The pre-merge
+ *     structural diff in the gate-1 commit body side-by-sides both.
+ *   - `clobAuthTypedData(domain, address, timestamp, nonce)` — builds the
+ *     EIP-712 ClobAuth payload bots sign once at session open.
+ *
+ * Bot quickstart:
+ *
+ *     const issued = await fetch('/auth/credentials', { ... });
+ *     const { apiKey, apiSecret, passphrase } = await issued.json();
+ *     // store apiSecret + passphrase out-of-band (env var, KMS, etc).
+ *     // for every subsequent request:
+ *     const ts = Math.floor(Date.now() / 1000);
+ *     const sig = buildHmacSignature(apiSecret, ts, 'DELETE', '/orders/abc');
+ *     await fetch('/orders/abc', {
+ *       method: 'DELETE',
+ *       headers: {
+ *         'X-PP-ADDRESS': address,
+ *         'X-PP-API-KEY': apiKey,
+ *         'X-PP-PASSPHRASE': passphrase,
+ *         'X-PP-TIMESTAMP': String(ts),
+ *         'X-PP-SIGNATURE': sig,
+ *       },
+ *     });
+ *
+ * Browser callers should NEVER hold apiSecret in client-side code. Doc 1.5#2.
+ */
+export declare const CLOB_AUTH_TYPES: {
+    ClobAuth: {
+        name: string;
+        type: string;
+    }[];
+};
+export declare const CLOB_AUTH_MESSAGE = "This message attests that I control the given wallet";
+export interface ClobAuthDomain {
+    name: string;
+    version: string;
+    chainId: number;
+}
+export interface ClobAuthMessage {
+    address: `0x${string}`;
+    timestamp: string;
+    nonce: bigint;
+    message: string;
+}
+export declare function buildClobAuthTypedData(domain: ClobAuthDomain, address: `0x${string}`, timestamp: string, nonce: bigint): {
+    domain: ClobAuthDomain;
+    types: typeof CLOB_AUTH_TYPES;
+    primaryType: "ClobAuth";
+    message: ClobAuthMessage;
+};
+/**
+ * Build the L2 HMAC signature header value.
+ *
+ * @param secretBase64 - the apiSecret returned by POST /auth/credentials
+ * @param timestamp    - unix SECONDS (NOT ms — matches Polymarket clob-client)
+ * @param method       - HTTP method, uppercase
+ * @param requestPath  - path with query string, no host (e.g. "/orders/abc?foo=1")
+ * @param body         - raw JSON-stringified body, or undefined for GET/DELETE
+ *
+ * Bytes-level identical to:
+ *   Polymarket/clob-client/src/signing/hmac.ts ::buildPolyHmacSignature
+ */
+export declare function buildHmacSignature(secretBase64: string, timestamp: number, method: string, requestPath: string, body?: string): string;
+/** Header names. SDK consumers should use these constants rather than literal strings. */
+export declare const HMAC_HEADERS: {
+    readonly ADDRESS: "X-PP-ADDRESS";
+    readonly API_KEY: "X-PP-API-KEY";
+    readonly PASSPHRASE: "X-PP-PASSPHRASE";
+    readonly TIMESTAMP: "X-PP-TIMESTAMP";
+    readonly SIGNATURE: "X-PP-SIGNATURE";
+};

package/dist/auth.js

@@ -0,0 +1,76 @@
+/**
+ * Phase 3 / Gate 1 — L2 HMAC auth helpers for the TypeScript SDK.
+ *
+ * Two surfaces:
+ *   - `buildHmacSignature(secret, timestamp, method, path, body?)` — exact
+ *     bytes-level match with the backend's `lib/hmacAuth.ts` and with
+ *     Polymarket's `clob-client/src/signing/hmac.ts`. The pre-merge
+ *     structural diff in the gate-1 commit body side-by-sides both.
+ *   - `clobAuthTypedData(domain, address, timestamp, nonce)` — builds the
+ *     EIP-712 ClobAuth payload bots sign once at session open.
+ *
+ * Bot quickstart:
+ *
+ *     const issued = await fetch('/auth/credentials', { ... });
+ *     const { apiKey, apiSecret, passphrase } = await issued.json();
+ *     // store apiSecret + passphrase out-of-band (env var, KMS, etc).
+ *     // for every subsequent request:
+ *     const ts = Math.floor(Date.now() / 1000);
+ *     const sig = buildHmacSignature(apiSecret, ts, 'DELETE', '/orders/abc');
+ *     await fetch('/orders/abc', {
+ *       method: 'DELETE',
+ *       headers: {
+ *         'X-PP-ADDRESS': address,
+ *         'X-PP-API-KEY': apiKey,
+ *         'X-PP-PASSPHRASE': passphrase,
+ *         'X-PP-TIMESTAMP': String(ts),
+ *         'X-PP-SIGNATURE': sig,
+ *       },
+ *     });
+ *
+ * Browser callers should NEVER hold apiSecret in client-side code. Doc 1.5#2.
+ */
+import { createHmac } from "crypto";
+export const CLOB_AUTH_TYPES = {
+    ClobAuth: [
+        { name: "address", type: "address" },
+        { name: "timestamp", type: "string" },
+        { name: "nonce", type: "uint256" },
+        { name: "message", type: "string" },
+    ],
+};
+export const CLOB_AUTH_MESSAGE = "This message attests that I control the given wallet";
+export function buildClobAuthTypedData(domain, address, timestamp, nonce) {
+    return {
+        domain,
+        types: CLOB_AUTH_TYPES,
+        primaryType: "ClobAuth",
+        message: { address, timestamp, nonce, message: CLOB_AUTH_MESSAGE },
+    };
+}
+/**
+ * Build the L2 HMAC signature header value.
+ *
+ * @param secretBase64 - the apiSecret returned by POST /auth/credentials
+ * @param timestamp    - unix SECONDS (NOT ms — matches Polymarket clob-client)
+ * @param method       - HTTP method, uppercase
+ * @param requestPath  - path with query string, no host (e.g. "/orders/abc?foo=1")
+ * @param body         - raw JSON-stringified body, or undefined for GET/DELETE
+ *
+ * Bytes-level identical to:
+ *   Polymarket/clob-client/src/signing/hmac.ts ::buildPolyHmacSignature
+ */
+export function buildHmacSignature(secretBase64, timestamp, method, requestPath, body) {
+    const secretBytes = Buffer.from(secretBase64, "base64");
+    const message = `${timestamp}${method}${requestPath}${body ?? ""}`;
+    const sigB64 = createHmac("sha256", secretBytes).update(message, "utf8").digest("base64");
+    return sigB64.split("+").join("-").split("/").join("_");
+}
+/** Header names. SDK consumers should use these constants rather than literal strings. */
+export const HMAC_HEADERS = {
+    ADDRESS: "X-PP-ADDRESS",
+    API_KEY: "X-PP-API-KEY",
+    PASSPHRASE: "X-PP-PASSPHRASE",
+    TIMESTAMP: "X-PP-TIMESTAMP",
+    SIGNATURE: "X-PP-SIGNATURE",
+};

package/dist/eip712.d.ts

@@ -0,0 +1,216 @@
+import type { ApiConfig, Eip712Domain, PairConfig } from "./types.js";
+/**
+ * EIP-712 type schema for the WebSocket auth handshake. Mirrors the
+ * backend's `WS_AUTH_TYPES` in `src/ws/wsAuth.ts` exactly. If these drift,
+ * the server's `verifyTypedData` rejects the signature and gates
+ * `orders:<wallet>` + `balance:<wallet>` shut.
+ *
+ * Distinct domain from order signing (name "PulsePairs WebSocket Auth")
+ * so an order signature can never be replayed as a WS-auth signature
+ * and vice versa.
+ */
+export declare const WS_AUTH_TYPES: {
+    readonly WsAuth: readonly [{
+        readonly name: "wallet";
+        readonly type: "address";
+    }, {
+        readonly name: "timestamp";
+        readonly type: "uint256";
+    }, {
+        readonly name: "sessionId";
+        readonly type: "bytes32";
+    }];
+};
+export type WsAuthMessage = {
+    wallet: `0x${string}`;
+    /** Unix seconds. Server window is ±60s of its clock. */
+    timestamp: bigint;
+    /** 32 random bytes, hex-encoded. Server rejects reuse within the
+     *  timestamp window. Use `freshSessionId()`. */
+    sessionId: `0x${string}`;
+};
+/**
+ * Build typed-data for the WS auth handshake. Domain is fixed
+ * (`PulsePairs WebSocket Auth`, version `1`, chainId from config,
+ * verifyingContract = zero) — does NOT depend on settlement address.
+ *
+ * Pass the result straight to `walletClient.signTypedData({ ...result })`.
+ * Then send `{ type: 'auth', wallet, timestamp, sessionId, signature }`
+ * over the WS. Server replies `{ type: 'auth_ok', token, expiresAt }`
+ * (token TTL 24h) or `{ type: 'auth_error' }`.
+ */
+export declare function buildWsAuthTypedData(args: {
+    cfg: Pick<ApiConfig, "chainId">;
+    wallet: `0x${string}`;
+    timestamp: bigint;
+    sessionId: `0x${string}`;
+}): {
+    domain: Eip712Domain;
+    types: typeof WS_AUTH_TYPES;
+    primaryType: "WsAuth";
+    message: WsAuthMessage;
+};
+/**
+ * Generate a fresh 32-byte sessionId (bytes32 hex) for a WS auth
+ * handshake. Uses `globalThis.crypto.getRandomValues` — present on
+ * browsers and Node 18+ (the SDK's documented runtime baseline).
+ *
+ * Server rejects sessionId reuse within the timestamp window — generate
+ * a fresh one for every initial sign (NOT for token replay, which has
+ * no sessionId).
+ */
+export declare function freshSessionId(): `0x${string}`;
+/**
+ * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
+ * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being
+ * accepted by the on-chain `SignatureChecker`.
+ */
+export declare const ORDER_TYPES: {
+    readonly Order: readonly [{
+        readonly name: "maker";
+        readonly type: "address";
+    }, {
+        readonly name: "market";
+        readonly type: "uint256";
+    }, {
+        readonly name: "option";
+        readonly type: "uint256";
+    }, {
+        readonly name: "side";
+        readonly type: "uint8";
+    }, {
+        readonly name: "type";
+        readonly type: "uint8";
+    }, {
+        readonly name: "price";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "maxFee";
+        readonly type: "uint256";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint256";
+    }];
+};
+export declare const CANCEL_TYPES: {
+    readonly Cancel: readonly [{
+        readonly name: "maker";
+        readonly type: "address";
+    }, {
+        readonly name: "orderId";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "expiry";
+        readonly type: "uint256";
+    }];
+};
+export type OrderSignMessage = {
+    maker: `0x${string}`;
+    /** On-chain market id (uint256), bare number from the composite key
+     *  suffix — NOT the composite string. */
+    market: bigint;
+    option: bigint;
+    side: number;
+    type: number;
+    price: bigint;
+    amount: bigint;
+    /** F-2026-17731: signed fee cap (atomic USDT). */
+    maxFee: bigint;
+    nonce: bigint;
+    expiry: bigint;
+};
+export type CancelSignMessage = {
+    maker: `0x${string}`;
+    orderId: string;
+    /** uint256 nonce — unique per cancel; backend replay-caches for 5 min. */
+    nonce: bigint;
+    /** uint256 unix-sec expiry — backend rejects past-expiry cancels. */
+    expiry: bigint;
+};
+/**
+ * Look up the pair config that owns a settlement contract. The single-
+ * settlement deployment makes this a degenerate one-entry array today, but
+ * code that hard-codes `pairs[0]` will silently break the moment a second
+ * settlement deploys. Always look up by address.
+ */
+export declare function findPairBySettlement(pairs: readonly PairConfig[], settlementAddress: string): PairConfig | null;
+/**
+ * Resolve the EIP-712 domain a maker should sign against for a given
+ * settlement address. Uses `cfg.pairs[]` (preferred), falls back to the
+ * legacy top-level `cfg.eip712.domain` only if no pair matches and the
+ * legacy field's `verifyingContract` matches the requested settlement —
+ * otherwise throws so a misconfiguration produces a clear error instead
+ * of a silently-wrong signature.
+ */
+export declare function domainForSettlement(cfg: ApiConfig, settlementAddress: string): Eip712Domain;
+/**
+ * Build typed-data for `POST /orders`. Pass the settlement address from
+ * the market the order is for; the helper picks the right domain.
+ */
+export declare function buildOrderTypedData(args: {
+    cfg: ApiConfig;
+    settlementAddress: string;
+    message: OrderSignMessage;
+}): {
+    domain: Eip712Domain;
+    types: typeof ORDER_TYPES;
+    primaryType: "Order";
+    message: OrderSignMessage;
+};
+/**
+ * Build typed-data for `DELETE /orders/:id`. The cancel signature uses
+ * the same per-pair domain as the original order — derive from the
+ * order's market composite key.
+ */
+export declare function buildCancelTypedData(args: {
+    cfg: ApiConfig;
+    settlementAddress: string;
+    message: CancelSignMessage;
+}): {
+    domain: Eip712Domain;
+    types: typeof CANCEL_TYPES;
+    primaryType: "Cancel";
+    message: CancelSignMessage;
+};
+export type ParsedComposite = {
+    settlementAddress: `0x${string}`;
+    marketId: string;
+};
+/** Parse a `<settlementAddress>-<marketId>` composite key. */
+export declare function parseCompositeMarketKey(market: string): ParsedComposite | null;
+/**
+ * Cents → bps (1¢ = 100 bps; 50¢ = 5000 bps). Throws on out-of-range.
+ * Accepts integers or half-integer cents (e.g. 50.5 → 5050) for partial-cent
+ * pricing. UI typically clamps to whole cents.
+ */
+export declare function centsToBps(cents: number): number;
+/** Bps → cents (5500 → 55). Inverse of `centsToBps`. */
+export declare function bpsToCents(bps: number): number;
+/** Atomic-USDT denomination of the documented $5–$500 stake window. */
+export declare const MIN_STAKE_ATOMIC = 5000000n;
+export declare const MAX_STAKE_ATOMIC = 500000000n;
+/** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
+ *  Rejects negatives + non-finite. */
+export declare function parseStake(usd: string | number): bigint;
+/**
+ * Defense-in-depth stake clamp. Throws if `amountAtomic` is outside the
+ * documented `$5 ≤ stake ≤ $500` window. Frontend gates these too; backend
+ * enforces only the upper bound today (BUG-S2.1 — see PULSEPAIRS_BACKLOG).
+ * SDK callers should validate before signing so a bad stake never produces
+ * a signed payload at all.
+ */
+export declare function assertStakeBounds(amountAtomic: bigint): void;
+/**
+ * Probability-weighted fee in atomic USDT. Mirrors the backend / contract
+ * formula. Returns the fee for `notionalAtomic` filled at `priceBps`.
+ */
+export declare function feeAtomic(notionalAtomic: bigint, priceBps: number, cfg: Pick<ApiConfig, "platformFeeBps" | "makerFeeBps" | "feeModel">): bigint;

package/dist/eip712.js

@@ -0,0 +1,229 @@
+/* ───────────────────────── WS auth (PR-19) ───────────────────────── */
+/**
+ * EIP-712 type schema for the WebSocket auth handshake. Mirrors the
+ * backend's `WS_AUTH_TYPES` in `src/ws/wsAuth.ts` exactly. If these drift,
+ * the server's `verifyTypedData` rejects the signature and gates
+ * `orders:<wallet>` + `balance:<wallet>` shut.
+ *
+ * Distinct domain from order signing (name "PulsePairs WebSocket Auth")
+ * so an order signature can never be replayed as a WS-auth signature
+ * and vice versa.
+ */
+export const WS_AUTH_TYPES = {
+    WsAuth: [
+        { name: "wallet", type: "address" },
+        { name: "timestamp", type: "uint256" },
+        { name: "sessionId", type: "bytes32" },
+    ],
+};
+const WS_AUTH_VERIFYING_CONTRACT = "0x0000000000000000000000000000000000000000";
+/**
+ * Build typed-data for the WS auth handshake. Domain is fixed
+ * (`PulsePairs WebSocket Auth`, version `1`, chainId from config,
+ * verifyingContract = zero) — does NOT depend on settlement address.
+ *
+ * Pass the result straight to `walletClient.signTypedData({ ...result })`.
+ * Then send `{ type: 'auth', wallet, timestamp, sessionId, signature }`
+ * over the WS. Server replies `{ type: 'auth_ok', token, expiresAt }`
+ * (token TTL 24h) or `{ type: 'auth_error' }`.
+ */
+export function buildWsAuthTypedData(args) {
+    return {
+        domain: {
+            name: "PulsePairs WebSocket Auth",
+            version: "1",
+            chainId: args.cfg.chainId,
+            verifyingContract: WS_AUTH_VERIFYING_CONTRACT,
+        },
+        types: WS_AUTH_TYPES,
+        primaryType: "WsAuth",
+        message: {
+            wallet: args.wallet,
+            timestamp: args.timestamp,
+            sessionId: args.sessionId,
+        },
+    };
+}
+/**
+ * Generate a fresh 32-byte sessionId (bytes32 hex) for a WS auth
+ * handshake. Uses `globalThis.crypto.getRandomValues` — present on
+ * browsers and Node 18+ (the SDK's documented runtime baseline).
+ *
+ * Server rejects sessionId reuse within the timestamp window — generate
+ * a fresh one for every initial sign (NOT for token replay, which has
+ * no sessionId).
+ */
+export function freshSessionId() {
+    const bytes = new Uint8Array(32);
+    const g = globalThis;
+    if (!g.crypto || typeof g.crypto.getRandomValues !== "function") {
+        throw new Error("globalThis.crypto.getRandomValues unavailable; use Node 18+ or a modern browser");
+    }
+    g.crypto.getRandomValues(bytes);
+    let hex = "0x";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/**
+ * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
+ * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being
+ * accepted by the on-chain `SignatureChecker`.
+ */
+export const ORDER_TYPES = {
+    Order: [
+        { name: "maker", type: "address" },
+        { name: "market", type: "uint256" },
+        { name: "option", type: "uint256" },
+        { name: "side", type: "uint8" },
+        { name: "type", type: "uint8" },
+        { name: "price", type: "uint256" },
+        { name: "amount", type: "uint256" },
+        // F-2026-17731 (Hacken remediation V2): signed fee cap — max total fee (platform + maker)
+        // this order pays WHEN FILLED AS THE TAKER. Must match ORDER_TYPEHASH in UpDownSettlement.sol.
+        { name: "maxFee", type: "uint256" },
+        { name: "nonce", type: "uint256" },
+        { name: "expiry", type: "uint256" },
+    ],
+};
+// PR-13 (P1-4): Cancel sigs gained `nonce` + `expiry` so a captured signature
+// can't be replayed forever. Drift here = backend rejects with 404. Mirrors
+// the backend's `EIP712_CANCEL_TYPES` exactly.
+export const CANCEL_TYPES = {
+    Cancel: [
+        { name: "maker", type: "address" },
+        { name: "orderId", type: "string" },
+        { name: "nonce", type: "uint256" },
+        { name: "expiry", type: "uint256" },
+    ],
+};
+const ZERO_ADDR = "0x0000000000000000000000000000000000000000";
+/**
+ * Look up the pair config that owns a settlement contract. The single-
+ * settlement deployment makes this a degenerate one-entry array today, but
+ * code that hard-codes `pairs[0]` will silently break the moment a second
+ * settlement deploys. Always look up by address.
+ */
+export function findPairBySettlement(pairs, settlementAddress) {
+    const target = settlementAddress.trim().toLowerCase();
+    if (!target || target === ZERO_ADDR)
+        return null;
+    return pairs.find((p) => p.settlementAddress.toLowerCase() === target) ?? null;
+}
+/**
+ * Resolve the EIP-712 domain a maker should sign against for a given
+ * settlement address. Uses `cfg.pairs[]` (preferred), falls back to the
+ * legacy top-level `cfg.eip712.domain` only if no pair matches and the
+ * legacy field's `verifyingContract` matches the requested settlement —
+ * otherwise throws so a misconfiguration produces a clear error instead
+ * of a silently-wrong signature.
+ */
+export function domainForSettlement(cfg, settlementAddress) {
+    const pair = findPairBySettlement(cfg.pairs, settlementAddress);
+    if (pair)
+        return pair.eip712.domain;
+    const legacy = cfg.eip712?.domain;
+    if (legacy &&
+        legacy.verifyingContract.toLowerCase() === settlementAddress.trim().toLowerCase()) {
+        return legacy;
+    }
+    throw new Error(`No EIP-712 domain found for settlement ${settlementAddress}. ` +
+        `Available pairs: ${cfg.pairs.map((p) => p.pairId + "@" + p.settlementAddress).join(", ")}`);
+}
+/**
+ * Build typed-data for `POST /orders`. Pass the settlement address from
+ * the market the order is for; the helper picks the right domain.
+ */
+export function buildOrderTypedData(args) {
+    return {
+        domain: domainForSettlement(args.cfg, args.settlementAddress),
+        types: ORDER_TYPES,
+        primaryType: "Order",
+        message: args.message,
+    };
+}
+/**
+ * Build typed-data for `DELETE /orders/:id`. The cancel signature uses
+ * the same per-pair domain as the original order — derive from the
+ * order's market composite key.
+ */
+export function buildCancelTypedData(args) {
+    return {
+        domain: domainForSettlement(args.cfg, args.settlementAddress),
+        types: CANCEL_TYPES,
+        primaryType: "Cancel",
+        message: args.message,
+    };
+}
+const COMPOSITE_RE = /^(0x[a-fA-F0-9]{40})-(\d+)$/;
+/** Parse a `<settlementAddress>-<marketId>` composite key. */
+export function parseCompositeMarketKey(market) {
+    const m = market.trim().match(COMPOSITE_RE);
+    if (!m)
+        return null;
+    return {
+        settlementAddress: m[1].toLowerCase(),
+        marketId: m[2],
+    };
+}
+/* ───────────────────────── Price + stake helpers ───────────────────────── */
+/**
+ * Cents → bps (1¢ = 100 bps; 50¢ = 5000 bps). Throws on out-of-range.
+ * Accepts integers or half-integer cents (e.g. 50.5 → 5050) for partial-cent
+ * pricing. UI typically clamps to whole cents.
+ */
+export function centsToBps(cents) {
+    if (!Number.isFinite(cents) || cents <= 0 || cents >= 100) {
+        throw new Error(`cents out of range (0,100): ${cents}`);
+    }
+    return Math.round(cents * 100);
+}
+/** Bps → cents (5500 → 55). Inverse of `centsToBps`. */
+export function bpsToCents(bps) {
+    if (!Number.isFinite(bps) || bps <= 0 || bps >= 10000) {
+        throw new Error(`bps out of range (0,10000): ${bps}`);
+    }
+    return bps / 100;
+}
+/** Atomic-USDT denomination of the documented $5–$500 stake window. */
+export const MIN_STAKE_ATOMIC = 5000000n;
+export const MAX_STAKE_ATOMIC = 500000000n;
+/** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
+ *  Rejects negatives + non-finite. */
+export function parseStake(usd) {
+    const s = typeof usd === "number" ? String(usd) : usd.trim();
+    const n = Number(s);
+    if (!Number.isFinite(n) || n < 0)
+        throw new Error(`invalid stake: ${usd}`);
+    return BigInt(Math.round(n * 1e6));
+}
+/**
+ * Defense-in-depth stake clamp. Throws if `amountAtomic` is outside the
+ * documented `$5 ≤ stake ≤ $500` window. Frontend gates these too; backend
+ * enforces only the upper bound today (BUG-S2.1 — see PULSEPAIRS_BACKLOG).
+ * SDK callers should validate before signing so a bad stake never produces
+ * a signed payload at all.
+ */
+export function assertStakeBounds(amountAtomic) {
+    if (amountAtomic < MIN_STAKE_ATOMIC) {
+        throw new Error(`stake below $${Number(MIN_STAKE_ATOMIC) / 1e6} minimum`);
+    }
+    if (amountAtomic > MAX_STAKE_ATOMIC) {
+        throw new Error(`stake above $${Number(MAX_STAKE_ATOMIC) / 1e6} maximum`);
+    }
+}
+/**
+ * Probability-weighted fee in atomic USDT. Mirrors the backend / contract
+ * formula. Returns the fee for `notionalAtomic` filled at `priceBps`.
+ */
+export function feeAtomic(notionalAtomic, priceBps, cfg) {
+    const totalBps = BigInt(cfg.platformFeeBps + cfg.makerFeeBps);
+    if (cfg.feeModel === "probability-weighted" || cfg.feeModel == null) {
+        const p = BigInt(priceBps);
+        const weightNumerator = 4n * p * (10000n - p);
+        const effectiveBps = (totalBps * weightNumerator) / (10000n * 10000n);
+        return (notionalAtomic * effectiveBps) / 10000n;
+    }
+    return (notionalAtomic * totalBps) / 10000n;
+}