@pulsepairs/sdk 0.2.0 → 0.4.0

package/README.md

@@ -65,11 +65,14 @@ import { createPublicClient, createWalletClient, http } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { arbitrum } from "viem/chains";
 import {
-  UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance,
+  UpDownHttpClient, buildOrderTypedData, ensureSettlementAllowance, freshNonce,
   parseCompositeMarketKey, parseStake, OrderType, OrderSide, Option,
 } from "@pulsepairs/sdk";
 
-const api = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+// Point the bot at a matcher YOU chose. Don't hardcode ours into a process
+// that holds a funded key — and assert the chain matches your RPC's chain
+// before you approve anything (see "Handling a funded key" below).
+const api = new UpDownHttpClient(process.env.UPND_API!);
 const cfg = await api.getConfig();                    // never hardcode addresses
 const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
@@ -77,8 +80,18 @@ const [live] = (await api.getMarkets({ pair: "BTC-USD", timeframe: 300 }))
 const { settlementAddress, marketId } = parseCompositeMarketKey(live.address)!;
 
 const amount = parseStake("5");
+
+// BOUNDED approve. `settlementAddress` is server-supplied (it came from the
+// matcher's market list), so cap its reach at what you actually intend to
+// spend. `amount` = how much to approve; `threshold` = when to top back up.
+// Omitting `amount` still approves MAX_UINT256 — that default is legacy.
+await ensureSettlementAllowance({
+  publicClient, walletClient, usdt: cfg.usdtAddress, settlement: settlementAddress,
+  amount: amount * 20n, threshold: amount,
+});
+
 const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n; // peak fee
-const nonce = BigInt(Math.floor(Math.random() * 1e12));
+const nonce = freshNonce();                           // CSPRNG; never Math.random/Date.now
 const typedData = buildOrderTypedData({
   cfg, settlementAddress,
   message: { maker: account.address, market: BigInt(marketId), option: BigInt(Option.UP),
@@ -91,8 +104,54 @@ await api.postOrder({ maker: account.address, market: live.address, option: Opti
   maxFee: maxFee.toString(), nonce: Number(nonce), expiry: live.endTime, signature });
 ```
 
-Full runnable scripts: `examples/simple-taker.ts` (MARKET), `examples/simple-maker.ts`
-(LIMIT + authed WS), `examples/full-dmm-bot.ts` (two-sided quoting).
+Full runnable scripts live in the **repo** under `examples/` — `simple-taker.ts`
+(MARKET), `simple-maker.ts` (LIMIT + authed WS), `full-dmm-bot.ts` (two-sided
+quoting). They are **not in the npm tarball** (`files: ["dist","README.md"]`), so
+if you installed from npm without repo access, this README is your reference —
+the safe patterns are inlined here on purpose.
+
+---
+
+## Handling a funded key
+
+This SDK is normally driven by a hot key that holds real USDT. Three rules,
+each of which exists because the failure is silent:
+
+**1. Never default your endpoints.** A bot signs orders for whatever matcher you
+point it at, and then grants that matcher's *server-supplied* settlement address
+a USDT allowance. A defaulted `UPND_API` plus a defaulted mainnet RPC means a
+real funded key trading against a box you never chose. Require both explicitly:
+
+```ts
+const API = process.env.UPND_API;
+if (!API) throw new Error("Set UPND_API — refusing to default a funded key to a third-party endpoint");
+const RPC = process.env.ARBITRUM_RPC_URL;
+if (!RPC) throw new Error("Set ARBITRUM_RPC_URL");
+```
+
+**2. Assert the matcher and the RPC agree on the chain**, before the approve.
+This one check catches the whole class — a testnet/demo matcher paired with a
+mainnet key can't survive it:
+
+```ts
+const cfg = await api.getConfig();
+const rpcChainId = await publicClient.getChainId();
+if (cfg.chainId !== rpcChainId) {
+  throw new Error(`chain mismatch: matcher says ${cfg.chainId}, RPC says ${rpcChainId}`);
+}
+```
+
+**3. Bound the allowance.** Pass `amount` to `ensureSettlementAllowance` (EOA) /
+`onboard`/`approve` (Account Kit) / `buildApproveSettlementTx` (raw-tx tier).
+All four default to `MAX_UINT256` for backwards compatibility; that default is
+an unbounded claim on your balance by an address the server named. A bounded
+allowance is consumed by fills, so re-run the helper on a timer — if it runs dry
+mid-session your fills revert with `insufficient allowance`.
+
+Use `freshNonce()` for order/cancel nonces. It draws from `crypto.getRandomValues`
+and stays under 2^53 so `Number(nonce)` on the wire matches the value you signed.
+`Math.random()`/`Date.now()` nonces are guessable, which lets anyone pre-burn your
+next nonce against the replay store and block your order flow.
 
 ---
 
@@ -138,6 +197,45 @@ const signOrder = bareErc1271Signer((td) => rainSmartWalletClient.signTypedData(
 const signature = await signOrder(buildOrderTypedData({ cfg, settlementAddress, message }));
 ```
 
+### Low-level "raw tx" tier (v0.3.0) — send with your own AA session
+
+If you run your own Account-Abstraction send path (like rain.trade's `sendTxs`
+through their root session), use the **transport-free primitives** instead of the
+signer class. They return rain's exact `RawTransaction` shape (`{ to, data, value? }`)
+for the on-chain setup, and sign orders **locally** with the popup-less
+order-session key — the part your send-only session structurally cannot do
+(a root session packs the *owner* entity → `isValidSignature` returns `0xffffffff`).
+
+The one mental-model flip: **placing an order is not a transaction.** It is an
+off-chain EIP-712 signature POSTed to the matcher; the relayer transacts the fill.
+So there is no `buildPlaceOrderTx` — you `signWithOrderSession(...)` and `postOrder`.
+
+```ts
+import {
+  buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession,
+  buildOrderTypedData,
+} from "@pulsepairs/sdk";
+import { arbitrum } from "viem/chains";
+
+// Onboard once — batch both raw txs into ONE userOp through YOUR session:
+const approveTx = buildApproveSettlementTx({ usdt: cfg.usdtAddress, settlement });
+const { tx: installTx, session } = await buildInstallOrderSessionTx({ sca, chain: arbitrum });
+await sendTxs([approveTx, installTx]);   // your batched, gasless send
+persist(session);                        // { v, privateKey, entityId, expirySec }
+
+// Every order after that — no chain, no gas, no popup:
+const typedData = buildOrderTypedData({ cfg, settlementAddress, message /* maker: sca, maxFee, … */ });
+const signature = await signWithOrderSession({ session, sca, chain: arbitrum, alchemyApiKey, typedData });
+await api.postOrder({ maker: sca, /* … */, signature });
+```
+
+Two tiers, adopt in order: **MVP** = `approve` (1 raw tx) + `bareErc1271Signer`
+owner-path (1 popup/order, zero new code) → **Production** = `approve` + install
+(batched) + `signWithOrderSession` (popup-less). Full walkthrough in
+[`examples/rain-taker.ts`](examples/rain-taker.ts); rationale in
+`UPDOWN_RAIN_RAWTX_SDK_DESIGN.md`. The on-chain acceptance of these bytes on
+rain's exact MA-v2 impl is proven by `updown-contracts/test/OrderSessionForkTest.t.sol`.
+
 ---
 
 ## Account Kit: the two rules you cannot break
@@ -222,8 +320,8 @@ this cap across partial fills.
 Clients          UpDownHttpClient, UpDownWsClient, wsUrlFromHttpBase
 EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
                  buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData,
-                 freshSessionId, domainForSettlement, findPairBySettlement,
-                 parseCompositeMarketKey
+                 freshSessionId, freshNonce, domainForSettlement,
+                 findPairBySettlement, parseCompositeMarketKey
 Trade-math       centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic,
                  MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC
 Approve (EOA)    ensureSettlementAllowance, MAX_UINT256
@@ -231,6 +329,8 @@ Account Kit      UpDownAccountKitSigner (connect, onboard, approve, withdraw,
                  signTypedDataBare, signWsAuth, isDeployed, grantSession,
                  ensureOrderSession, revokeOrderSession, hasOrderSession),
                  bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature
+Raw-tx tier      buildApproveSettlementTx, buildInstallOrderSessionTx,
+(v0.3.0)         signWithOrderSession, RawTransaction, OrderSessionRecord
 L2 HMAC auth     CLOB_AUTH_TYPES, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS
 Enums/types      OrderType, OrderSide, Option, ApiConfig, PairConfig, PostOrderBody, …
 ```

package/dist/accountKit.d.ts

@@ -64,6 +64,17 @@ export declare function isErc6492Signature(signature: Hex): boolean;
  */
 export declare function stripErc6492Wrapper(signature: Hex): Hex;
 export type RawTypedDataSigner = (typedData: TypedDataDefinition) => Promise<Hex>;
+/**
+ * A pending on-chain call, shaped EXACTLY like rain.trade's `RawTransaction`
+ * (`rain-sdk/tx/*` → `{ to, data, value? }`) so the low-level builders below
+ * drop straight into their `sendTxs`/`sendCalls` without any adapter. `value`
+ * is optional and defaults to 0 for the UpDown setup calls (approve / install).
+ */
+export type RawTransaction = {
+    to: Address;
+    data: Hex;
+    value?: bigint;
+};
 /**
  * Wrap ANY raw typed-data signer so its output is a BARE ERC-1271 signature
  * the UpDown settlement can verify. Use this when the host app already owns an
@@ -126,6 +137,17 @@ export type GrantSessionResult = {
     context: Hex;
     expirySec: number;
 };
+export type OrderSessionRecord = {
+    v: 1;
+    /** Session private key — browser/host custody, same trust class as RainAA's
+     *  IndexedDB session keys but with a strictly narrower blast radius (1271
+     *  signing only, no UserOp execution). */
+    privateKey: Hex;
+    /** MA-v2 validation entity id the key is installed under on the SCA. */
+    entityId: number;
+    /** Client-side expiry (unix sec). NOT enforced on-chain. */
+    expirySec: number;
+};
 /**
  * Owner-key ERC-1271 order signer + gasless custody sends on an Alchemy SCA.
  *
@@ -202,7 +224,9 @@ export declare class UpDownAccountKitSigner {
     /**
      * Build the `installValidation` self-call that registers a fresh session
      * key on the SCA as a signature-validation-ONLY entity (validated flow:
-     * updown-frontend/scripts/poc-session-key-fe-flow.mjs).
+     * updown-frontend/scripts/poc-session-key-fe-flow.mjs). Delegates to the
+     * shared, transport-free `buildOrderSessionInstall(...)` so the class and the
+     * standalone `buildInstallOrderSessionTx(...)` emit byte-identical calldata.
      */
     private buildOrderSessionInstallCall;
     /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
@@ -229,15 +253,22 @@ export declare class UpDownAccountKitSigner {
      * popup-less. Order-session prep failures degrade to plain deploy+approve
      * (owner-key signing per order). Uses the owner client so it works before
      * any session exists; deployment is carried by the account init-code.
+     *
+     * `amount` bounds the allowance (default unlimited) — see
+     * `ensureSettlementAllowance`'s notes; the same argument applies here,
+     * since `settlement` comes from the matcher's own config.
      */
     onboard(args: {
         usdt: Address;
         settlement: Address;
+        amount?: bigint;
     }): Promise<Hex>;
-    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    /** Idempotent USDT approve to the settlement (gasless UserOp). `amount`
+     *  bounds the allowance; defaults to unlimited (MAX_UINT256). */
     approve(args: {
         usdt: Address;
         settlement: Address;
+        amount?: bigint;
     }): Promise<Hex>;
     /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
     withdraw(args: {
@@ -263,3 +294,46 @@ export declare class UpDownAccountKitSigner {
     /** Clear in-memory state (persisted sessions, if any, are left intact). */
     disconnect(): void;
 }
+/**
+ * Raw `approve(settlement, amount)` on the USDT contract as a `RawTransaction`.
+ * Defaults to an unlimited (MAX_UINT256) allowance — the amount `enterPosition`
+ * needs — matching what `UpDownAccountKitSigner.onboard/approve` send. Push it
+ * straight into rain's `sendTxs` (batched with `buildInstallOrderSessionTx`).
+ * Pure calldata: synchronous, no peer deps, no network.
+ */
+export declare function buildApproveSettlementTx(args: {
+    usdt: Address;
+    settlement: Address;
+    amount?: bigint;
+}): RawTransaction;
+/**
+ * Build the one-time popup-less-order-session install as a `RawTransaction`
+ * (the `installValidation` self-call) plus the `OrderSessionRecord` the host
+ * must persist and later feed to `signWithOrderSession`. Send `tx` through the
+ * host's own AA session — batched with `buildApproveSettlementTx` it costs one
+ * userOp. Requires the `@account-kit/*` peer deps (lazy-imported). The `sca`
+ * MUST be the account the session installs on (order.maker); `chain` is the
+ * viem chain the SCA lives on (Arbitrum One / Sepolia).
+ */
+export declare function buildInstallOrderSessionTx(args: {
+    sca: Address;
+    chain: Chain;
+}): Promise<{
+    tx: RawTransaction;
+    session: OrderSessionRecord;
+}>;
+/**
+ * Sign EIP-712 typed data (an Order / Cancel / WS-auth) LOCALLY with a
+ * persisted order-session key, yielding the BARE ERC-1271 signature the UpDown
+ * matcher accepts. Pure local ECDSA over a MA-v2 `signerEntity` — no bundler,
+ * gas, popup, or network. The `sca` must be deployed and carry the session
+ * entity (via `buildInstallOrderSessionTx`'s tx) before the signature is used
+ * in a fill. This is the piece rain's send-only session structurally cannot do.
+ */
+export declare function signWithOrderSession(args: {
+    session: OrderSessionRecord;
+    sca: Address;
+    chain: Chain;
+    alchemyApiKey: string;
+    typedData: TypedDataDefinition;
+}): Promise<Hex>;

package/dist/accountKit.js

@@ -356,24 +356,12 @@ export class UpDownAccountKitSigner {
         }
         this._orderSession = rec;
         if (!this._orderSessionClient) {
-            const [aaCore, scMod, infraMod] = await Promise.all([
-                // @ts-ignore peer dep
-                import("@aa-sdk/core"),
-                // @ts-ignore peer dep
-                import("@account-kit/smart-contracts"),
-                // @ts-ignore peer dep
-                import("@account-kit/infra"),
-            ]);
-            const { LocalAccountSigner } = aaCore;
-            const { createModularAccountV2Client } = scMod;
-            const { alchemy } = infraMod;
-            this._orderSessionClient = await createModularAccountV2Client({
-                mode: "default",
-                chain: await this.infraChain(),
-                transport: alchemy({ apiKey: this.config.alchemyApiKey }),
-                signer: LocalAccountSigner.privateKeyToAccountSigner(rec.privateKey),
-                accountAddress: this._address,
-                signerEntity: { entityId: rec.entityId, isGlobalValidation: false },
+            this._orderSessionClient = await buildOrderSessionClient({
+                sca: this._address,
+                chainId: this.config.chain.id,
+                alchemyApiKey: this.config.alchemyApiKey,
+                privateKey: rec.privateKey,
+                entityId: rec.entityId,
             });
         }
         return this._orderSessionClient.account;
@@ -400,51 +388,17 @@ export class UpDownAccountKitSigner {
     /**
      * Build the `installValidation` self-call that registers a fresh session
      * key on the SCA as a signature-validation-ONLY entity (validated flow:
-     * updown-frontend/scripts/poc-session-key-fe-flow.mjs).
+     * updown-frontend/scripts/poc-session-key-fe-flow.mjs). Delegates to the
+     * shared, transport-free `buildOrderSessionInstall(...)` so the class and the
+     * standalone `buildInstallOrderSessionTx(...)` emit byte-identical calldata.
      */
     async buildOrderSessionInstallCall() {
-        const [viemAccounts, expMod, viemMod] = await Promise.all([
-            // @ts-ignore viem subpath
-            import("viem/accounts"),
-            // @ts-ignore peer dep
-            import("@account-kit/smart-contracts/experimental"),
-            // @ts-ignore viem
-            import("viem"),
-        ]);
-        const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
-        const { getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule, serializeValidationConfig, semiModularAccountBytecodeAbi, } = expMod;
-        const privateKey = generatePrivateKey();
-        const sessionAddress = privateKeyToAccount(privateKey).address;
-        // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
-        // id that already exists on the account reverts — random keeps collisions
-        // with prior sessions (lost storage, other hosts) vanishingly unlikely.
-        const entityId = 2 + Math.floor(Math.random() * 0x7ffffff0);
-        const data = viemMod.encodeFunctionData({
-            abi: semiModularAccountBytecodeAbi,
-            functionName: "installValidation",
-            args: [
-                serializeValidationConfig({
-                    moduleAddress: getDefaultSingleSignerValidationModuleAddress(await this.infraChain()),
-                    entityId,
-                    isGlobal: false,
-                    isSignatureValidation: true, // can answer ERC-1271…
-                    isUserOpValidation: false, // …but can never execute a UserOp
-                }),
-                [],
-                SingleSignerValidationModule.encodeOnInstallData({ entityId, signer: sessionAddress }),
-                [],
-            ],
-        });
-        return {
-            call: { to: this.address, data },
-            record: { v: 1, privateKey, entityId, expirySec: Math.floor(Date.now() / 1000) + ORDER_SESSION_TTL_SEC },
-        };
+        const { tx, session } = await buildOrderSessionInstall(this.address, await this.infraChain());
+        return { call: { to: tx.to, data: tx.data }, record: session };
     }
     /** The @account-kit/infra chain (Alchemy RPC config baked in) for MA-v2 clients. */
-    async infraChain() {
-        // @ts-ignore peer dep
-        const infra = (await import("@account-kit/infra"));
-        return this.config.chain.id === 421614 ? infra.arbitrumSepolia : infra.arbitrum;
+    infraChain() {
+        return infraChainFor(this.config.chain.id);
     }
     /**
      * Build + owner-sign a WS-auth handshake and package it as `WsAuthCredentials`
@@ -529,10 +483,14 @@ export class UpDownAccountKitSigner {
      * popup-less. Order-session prep failures degrade to plain deploy+approve
      * (owner-key signing per order). Uses the owner client so it works before
      * any session exists; deployment is carried by the account init-code.
+     *
+     * `amount` bounds the allowance (default unlimited) — see
+     * `ensureSettlementAllowance`'s notes; the same argument applies here,
+     * since `settlement` comes from the matcher's own config.
      */
     async onboard(args) {
         const calls = [
-            { to: args.usdt, data: encodeApprove(args.settlement) },
+            { to: args.usdt, data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256) },
         ];
         let record = null;
         if (this.orderSessionsEnabled && !(await this.orderSessionAccount().catch(() => null))) {
@@ -550,9 +508,13 @@ export class UpDownAccountKitSigner {
             this.persistOrderSession(record);
         return txHash;
     }
-    /** Idempotent USDT approve to the settlement (gasless UserOp). */
+    /** Idempotent USDT approve to the settlement (gasless UserOp). `amount`
+     *  bounds the allowance; defaults to unlimited (MAX_UINT256). */
     async approve(args) {
-        return this.sendCall({ to: args.usdt, data: encodeApprove(args.settlement) });
+        return this.sendCall({
+            to: args.usdt,
+            data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256),
+        });
     }
     /** Transfer USDT out of the SCA to `to` (gasless UserOp). */
     async withdraw(args) {
@@ -621,11 +583,157 @@ export class UpDownAccountKitSigner {
         this._mods = null;
     }
 }
+/* ═══════════════════════════════════════════════════════════════════════
+ *  Low-level ("raw tx") tier — transport-free primitives (design doc §4)
+ *
+ *  These surface the exact calldata + local-signing logic the
+ *  `UpDownAccountKitSigner` class uses privately, so a host that owns its own
+ *  Account-Abstraction send path (rain.trade's shared session) can:
+ *    1. get UpDown's setup calls as `RawTransaction`s and push them through
+ *       ITS batched userOp (`sendTxs`),  and
+ *    2. sign UpDown orders LOCALLY with the popup-less order-session key.
+ *  The class delegates to the same `buildOrderSessionInstall` /
+ *  `buildOrderSessionClient` helpers, guaranteeing identical bytes.
+ * ═══════════════════════════════════════════════════════════════════════ */
+/** The @account-kit/infra chain (Alchemy RPC baked in) for MA-v2 clients. */
+async function infraChainFor(chainId) {
+    // @ts-ignore peer dep
+    const infra = (await import("@account-kit/infra"));
+    return chainId === 421614 ? infra.arbitrumSepolia : infra.arbitrum;
+}
+/**
+ * Build the `installValidation` self-call that registers a fresh order-session
+ * key on `sca` as a signature-validation-ONLY MA-v2 entity, plus the session
+ * material to persist. Transport-free: pure local key-gen + calldata encoding —
+ * no bundler, gas, popup, or network. `moduleChain` only selects the
+ * `SingleSignerValidationModule` address (a constant across chains today), so
+ * either an `@account-kit/infra` chain or a viem `Chain` works.
+ */
+async function buildOrderSessionInstall(sca, moduleChain) {
+    const [viemAccounts, expMod, viemMod] = await Promise.all([
+        // @ts-ignore viem subpath
+        import("viem/accounts"),
+        // @ts-ignore peer dep
+        import("@account-kit/smart-contracts/experimental"),
+        // @ts-ignore viem
+        import("viem"),
+    ]);
+    const { generatePrivateKey, privateKeyToAccount } = viemAccounts;
+    const { getDefaultSingleSignerValidationModuleAddress, SingleSignerValidationModule, serializeValidationConfig, semiModularAccountBytecodeAbi, } = expMod;
+    const privateKey = generatePrivateKey();
+    const sessionAddress = privateKeyToAccount(privateKey).address;
+    // Random 4-byte entity id (≥2): 0 is the owner entity, and installing an
+    // id that already exists on the account reverts — random keeps collisions
+    // with prior sessions (lost storage, other hosts) vanishingly unlikely.
+    // CSPRNG-drawn: a predictable id lets an observer front-run the install
+    // and brick onboarding by burning the id we're about to claim (the revert
+    // is the whole failure mode this randomness exists to avoid).
+    const entityId = 2 + randomUint31();
+    const data = viemMod.encodeFunctionData({
+        abi: semiModularAccountBytecodeAbi,
+        functionName: "installValidation",
+        args: [
+            serializeValidationConfig({
+                moduleAddress: getDefaultSingleSignerValidationModuleAddress(moduleChain),
+                entityId,
+                isGlobal: false,
+                isSignatureValidation: true, // can answer ERC-1271…
+                isUserOpValidation: false, // …but can never execute a UserOp
+            }),
+            [],
+            SingleSignerValidationModule.encodeOnInstallData({ entityId, signer: sessionAddress }),
+            [],
+        ],
+    });
+    return {
+        tx: { to: sca, data },
+        session: { v: 1, privateKey, entityId, expirySec: Math.floor(Date.now() / 1000) + ORDER_SESSION_TTL_SEC },
+    };
+}
+/**
+ * Build a MA-v2 smart-wallet client bound to an order-session key's validation
+ * entity. Used only for LOCAL ERC-1271 signing (`account.signTypedData`) — the
+ * entity cannot execute UserOps — so no bundler/gas/network is exercised by the
+ * signing path. Shared by the class and the standalone `signWithOrderSession`.
+ */
+async function buildOrderSessionClient(args) {
+    const [aaCore, scMod, infraMod] = await Promise.all([
+        // @ts-ignore peer dep
+        import("@aa-sdk/core"),
+        // @ts-ignore peer dep
+        import("@account-kit/smart-contracts"),
+        // @ts-ignore peer dep
+        import("@account-kit/infra"),
+    ]);
+    const { LocalAccountSigner } = aaCore;
+    const { createModularAccountV2Client } = scMod;
+    const { alchemy } = infraMod;
+    return createModularAccountV2Client({
+        mode: "default",
+        chain: await infraChainFor(args.chainId),
+        transport: alchemy({ apiKey: args.alchemyApiKey }),
+        signer: LocalAccountSigner.privateKeyToAccountSigner(args.privateKey),
+        accountAddress: args.sca,
+        signerEntity: { entityId: args.entityId, isGlobalValidation: false },
+    });
+}
+/**
+ * Raw `approve(settlement, amount)` on the USDT contract as a `RawTransaction`.
+ * Defaults to an unlimited (MAX_UINT256) allowance — the amount `enterPosition`
+ * needs — matching what `UpDownAccountKitSigner.onboard/approve` send. Push it
+ * straight into rain's `sendTxs` (batched with `buildInstallOrderSessionTx`).
+ * Pure calldata: synchronous, no peer deps, no network.
+ */
+export function buildApproveSettlementTx(args) {
+    return { to: args.usdt, data: encodeApprove(args.settlement, args.amount ?? MAX_UINT256) };
+}
+/**
+ * Build the one-time popup-less-order-session install as a `RawTransaction`
+ * (the `installValidation` self-call) plus the `OrderSessionRecord` the host
+ * must persist and later feed to `signWithOrderSession`. Send `tx` through the
+ * host's own AA session — batched with `buildApproveSettlementTx` it costs one
+ * userOp. Requires the `@account-kit/*` peer deps (lazy-imported). The `sca`
+ * MUST be the account the session installs on (order.maker); `chain` is the
+ * viem chain the SCA lives on (Arbitrum One / Sepolia).
+ */
+export function buildInstallOrderSessionTx(args) {
+    return buildOrderSessionInstall(args.sca, args.chain);
+}
+/**
+ * Sign EIP-712 typed data (an Order / Cancel / WS-auth) LOCALLY with a
+ * persisted order-session key, yielding the BARE ERC-1271 signature the UpDown
+ * matcher accepts. Pure local ECDSA over a MA-v2 `signerEntity` — no bundler,
+ * gas, popup, or network. The `sca` must be deployed and carry the session
+ * entity (via `buildInstallOrderSessionTx`'s tx) before the signature is used
+ * in a fill. This is the piece rain's send-only session structurally cannot do.
+ */
+export async function signWithOrderSession(args) {
+    const client = await buildOrderSessionClient({
+        sca: args.sca,
+        chainId: args.chain.id,
+        alchemyApiKey: args.alchemyApiKey,
+        privateKey: args.session.privateKey,
+        entityId: args.session.entityId,
+    });
+    return (await client.account.signTypedData(args.typedData));
+}
 /* ───────────────────────── calldata encoders ───────────────────────── */
 const MAX_UINT256 = (1n << 256n) - 1n;
-function encodeApprove(spender) {
+/** Uniform CSPRNG draw in [0, 0x7ffffff0). Mirrors `freshSessionId`'s
+ *  contract: throws rather than silently degrading to a weak source. */
+function randomUint31() {
+    const bytes = new Uint8Array(4);
+    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);
+    const raw = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+    return raw % 0x7ffffff0;
+}
+function encodeApprove(spender, amount = MAX_UINT256) {
     // approve(address,uint256) selector 0x095ea7b3
-    return ("0x095ea7b3" + pad(spender) + pad(MAX_UINT256));
+    return ("0x095ea7b3" + pad(spender) + pad(amount));
 }
 function encodeTransfer(to, amount) {
     // transfer(address,uint256) selector 0xa9059cbb

package/dist/approve.d.ts

@@ -1,16 +1,32 @@
 /**
- * One-time USDT.approve(settlement, MaxUint256) helper.
+ * USDT.approve(settlement, …) helper.
  *
  * Path-1 settlement pulls USDT directly from the maker via `transferFrom`
  * inside `enterPosition`. Without this approval the first BUY reverts
  * with `ERC20: insufficient allowance`. Idempotent: reads current
  * allowance and only submits a tx when below threshold.
  *
+ * `amount` defaults to a BOUNDED amount (`DEFAULT_APPROVAL_AMOUNT`, 100k USDT),
+ * not MAX_UINT256 (S2): `settlement` is routinely sourced from a server-supplied
+ * `/config` or market list, so an unlimited approval would grant a server-named
+ * spender unbounded reach into a funded hot wallet. A hot bot key SHOULD still
+ * pass its own inventory-sized bound; `MAX_UINT256` is exported for the rare
+ * caller that explicitly opts into unlimited.
+ *
  * `viem` is a peer dependency — pass in the public + wallet clients you
  * already have so this helper doesn't bake in a transport choice.
  */
 import type { Address, PublicClient, WalletClient } from "viem";
 export declare const MAX_UINT256: bigint;
+/**
+ * S2: bounded default approval (100k USDT, atomic). Caps the blast radius of a
+ * settlement-contract bug (or a hostile server-supplied spender) to one
+ * inventory bound instead of the wallet's entire USDT balance, while sitting
+ * comfortably above `DEFAULT_THRESHOLD` so a continuously-quoting bot isn't
+ * re-approving on every call. Bots with larger inventory should pass their own
+ * `amount`. This is 6-decimal USDT, so 100k * 1e6.
+ */
+export declare const DEFAULT_APPROVAL_AMOUNT: bigint;
 export type EnsureAllowanceResult = {
     status: "already_ok";
     allowance: bigint;
@@ -30,12 +46,27 @@ export type EnsureAllowanceResult = {
  *                          `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.
+ *                         atomic-USDT amount. Default 10,000 USDT. This is
+ *                         WHEN to top up, not HOW MUCH — see `amount`.
+ * @param args.amount — How much to approve when a top-up is sent. Defaults
+ *                      to `DEFAULT_APPROVAL_AMOUNT` (100k USDT, BOUNDED — S2),
+ *                      not `MAX_UINT256`. `settlement` is routinely sourced
+ *                      from the matcher's own `/config` or market list, so an
+ *                      unlimited approval would grant a server-supplied spender
+ *                      unbounded reach into a funded hot wallet — size this to
+ *                      the inventory the bot actually needs between top-ups.
+ *                      It must exceed `threshold`, or every call re-approves.
+ *                      Pass `MAX_UINT256` to explicitly opt into unlimited.
  *
  * 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.
+ * tx hash and the amount approved if a new approval was sent. Caller can
+ * `await publicClient.waitForTransactionReceipt({ hash })` if it wants to
+ * confirm before placing orders.
+ *
+ * Operational note for bounded approvals: the allowance is consumed by
+ * fills, so a bot that quotes continuously WILL run it down. This helper
+ * only tops up when called — call it on your quoting loop, not just at
+ * startup, or fills start reverting with `insufficient allowance` mid-session.
  */
 export declare function ensureSettlementAllowance(args: {
     publicClient: PublicClient;
@@ -43,4 +74,5 @@ export declare function ensureSettlementAllowance(args: {
     usdt: Address;
     settlement: Address;
     threshold?: bigint;
+    amount?: bigint;
 }): Promise<EnsureAllowanceResult>;

package/dist/approve.js

@@ -21,10 +21,17 @@ const ERC20_ABI = [
     },
 ];
 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. */
+/** Default refresh threshold — re-approve if allowance falls below 10k USDT. */
 const DEFAULT_THRESHOLD = 10000n * 1000000n;
+/**
+ * S2: bounded default approval (100k USDT, atomic). Caps the blast radius of a
+ * settlement-contract bug (or a hostile server-supplied spender) to one
+ * inventory bound instead of the wallet's entire USDT balance, while sitting
+ * comfortably above `DEFAULT_THRESHOLD` so a continuously-quoting bot isn't
+ * re-approving on every call. Bots with larger inventory should pass their own
+ * `amount`. This is 6-decimal USDT, so 100k * 1e6.
+ */
+export const DEFAULT_APPROVAL_AMOUNT = 100000n * 1000000n;
 /**
  * Ensure the maker has enough USDT allowance on the settlement contract.
  *
@@ -36,12 +43,27 @@ const DEFAULT_THRESHOLD = 10000n * 1000000n;
  *                          `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.
+ *                         atomic-USDT amount. Default 10,000 USDT. This is
+ *                         WHEN to top up, not HOW MUCH — see `amount`.
+ * @param args.amount — How much to approve when a top-up is sent. Defaults
+ *                      to `DEFAULT_APPROVAL_AMOUNT` (100k USDT, BOUNDED — S2),
+ *                      not `MAX_UINT256`. `settlement` is routinely sourced
+ *                      from the matcher's own `/config` or market list, so an
+ *                      unlimited approval would grant a server-supplied spender
+ *                      unbounded reach into a funded hot wallet — size this to
+ *                      the inventory the bot actually needs between top-ups.
+ *                      It must exceed `threshold`, or every call re-approves.
+ *                      Pass `MAX_UINT256` to explicitly opt into unlimited.
  *
  * 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.
+ * tx hash and the amount approved if a new approval was sent. Caller can
+ * `await publicClient.waitForTransactionReceipt({ hash })` if it wants to
+ * confirm before placing orders.
+ *
+ * Operational note for bounded approvals: the allowance is consumed by
+ * fills, so a bot that quotes continuously WILL run it down. This helper
+ * only tops up when called — call it on your quoting loop, not just at
+ * startup, or fills start reverting with `insufficient allowance` mid-session.
  */
 export async function ensureSettlementAllowance(args) {
     const account = args.walletClient.account;
@@ -49,6 +71,11 @@ export async function ensureSettlementAllowance(args) {
         throw new Error("walletClient has no account");
     const owner = account.address;
     const threshold = args.threshold ?? DEFAULT_THRESHOLD;
+    const amount = args.amount ?? DEFAULT_APPROVAL_AMOUNT;
+    if (amount < threshold) {
+        throw new Error(`approve amount (${amount}) is below the re-approve threshold (${threshold}) — ` +
+            "every call would send a redundant approve tx; raise amount or lower threshold");
+    }
     const current = (await args.publicClient.readContract({
         address: args.usdt,
         abi: ERC20_ABI,
@@ -63,7 +90,7 @@ export async function ensureSettlementAllowance(args) {
         address: args.usdt,
         abi: ERC20_ABI,
         functionName: "approve",
-        args: [args.settlement, MAX_UINT256],
+        args: [args.settlement, amount],
     });
-    return { status: "approved", txHash, allowance: MAX_UINT256 };
+    return { status: "approved", txHash, allowance: amount };
 }

package/dist/eip712.d.ts

@@ -60,6 +60,29 @@ export declare function buildWsAuthTypedData(args: {
  * no sessionId).
  */
 export declare function freshSessionId(): `0x${string}`;
+/**
+ * Generate a fresh order/cancel `nonce` from a CSPRNG.
+ *
+ * The nonce is the only thing standing between an order and the backend's
+ * replay store: a PREDICTABLE nonce lets anyone pre-burn a maker's next
+ * nonce and grief their order flow (a liveness attack — the signature
+ * itself still can't be forged). `Math.random()` is not a CSPRNG and
+ * `Date.now()` is public knowledge; neither is acceptable here.
+ *
+ * Deliberately 48 bits, NOT the full uint256: `PostOrderBody.nonce` is a
+ * JSON `number`, so the value must survive `Number(nonce)` losslessly —
+ * anything above 2^53 would silently round and the posted nonce would stop
+ * matching the signed one, failing signature recovery. Across 2^48 values the
+ * CUMULATIVE (birthday-bound) chance that ANY two of one maker's ~750k orders
+ * collide is ~1e-3 (~k²/2·2^48) — about one in a thousand, not vanishing; the
+ * ~1-in-10^9 figure is only the MARGINAL odds that a single new draw hits an
+ * existing nonce at that point. Either way a collision is a rejected order
+ * (retry with a fresh nonce), not a loss.
+ *
+ * Single-writer bots may prefer a monotonic counter (no birthday bound at
+ * all) — seed it from this rather than from the clock.
+ */
+export declare function freshNonce(): bigint;
 /**
  * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
  * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being

package/dist/eip712.js

@@ -66,6 +66,40 @@ export function freshSessionId() {
     }
     return hex;
 }
+/**
+ * Generate a fresh order/cancel `nonce` from a CSPRNG.
+ *
+ * The nonce is the only thing standing between an order and the backend's
+ * replay store: a PREDICTABLE nonce lets anyone pre-burn a maker's next
+ * nonce and grief their order flow (a liveness attack — the signature
+ * itself still can't be forged). `Math.random()` is not a CSPRNG and
+ * `Date.now()` is public knowledge; neither is acceptable here.
+ *
+ * Deliberately 48 bits, NOT the full uint256: `PostOrderBody.nonce` is a
+ * JSON `number`, so the value must survive `Number(nonce)` losslessly —
+ * anything above 2^53 would silently round and the posted nonce would stop
+ * matching the signed one, failing signature recovery. Across 2^48 values the
+ * CUMULATIVE (birthday-bound) chance that ANY two of one maker's ~750k orders
+ * collide is ~1e-3 (~k²/2·2^48) — about one in a thousand, not vanishing; the
+ * ~1-in-10^9 figure is only the MARGINAL odds that a single new draw hits an
+ * existing nonce at that point. Either way a collision is a rejected order
+ * (retry with a fresh nonce), not a loss.
+ *
+ * Single-writer bots may prefer a monotonic counter (no birthday bound at
+ * all) — seed it from this rather than from the clock.
+ */
+export function freshNonce() {
+    const bytes = new Uint8Array(6);
+    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 n = 0n;
+    for (let i = 0; i < bytes.length; i++)
+        n = (n << 8n) | BigInt(bytes[i]);
+    return n;
+}
 /**
  * EIP-712 type schemas. Mirrors the backend's `EIP712_ORDER_TYPES` /
  * `EIP712_CANCEL_TYPES` exactly — if these drift, signatures stop being

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
 export { UpDownWsClient, type UpDownWsMessage, type SubscribePayload, type WsAuthCredentials, type ConnectAuthedOptions, } from "./ws.js";
-export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, type ClobAuthDomain, type ClobAuthMessage, } from "./auth.js";
-export { ensureSettlementAllowance, MAX_UINT256, type EnsureAllowanceResult, } from "./approve.js";
+export { ensureSettlementAllowance, MAX_UINT256, DEFAULT_APPROVAL_AMOUNT, type EnsureAllowanceResult, } from "./approve.js";
+export { readOnChainHolderShares, reconcileFills, reportedFromPositions, type OnChainHolderShares, type ShareReconciliation, type ReconcileStatus, type FillReconciliationReport, } from "./reconcile.js";
 export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, type UpDownAccountKitConfig, type Eip1193Provider, type GrantSessionResult, type RawTypedDataSigner, } from "./accountKit.js";
+export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, type RawTransaction, type OrderSessionRecord, } from "./accountKit.js";
 export { OrderType, OrderSide, Option, type ApiConfig, type Balance, type CancelOrderBody, type Eip712Domain, type MarketDetail, type MarketListItem, type OptionValue, type OrderBookFull, type OrderBookLevel, type OrderBookSide, type OrderRow, type OrderSideKey, type OrderSideValue, type OrderStatus, type OrderTypeKey, type OrderTypeValue, type OrdersResponse, type PairConfig, type PairSymbol, type PostOrderBody, type Position, type Stats, type Trade, type Version, } from "./types.js";

package/dist/index.js

@@ -2,14 +2,23 @@
 export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
 export { UpDownWsClient, } from "./ws.js";
 // EIP-712 helpers
-export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
 // Phase 3 / Gate 1 — L2 HMAC auth helpers
 export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, } from "./auth.js";
 // Approve helper
-export { ensureSettlementAllowance, MAX_UINT256, } from "./approve.js";
+export { ensureSettlementAllowance, MAX_UINT256, DEFAULT_APPROVAL_AMOUNT, } from "./approve.js";
+// S5 — on-chain fill reconciliation (independent detector for the B1/B6
+// off-chain ledger bugs: diffs authoritative on-chain `userShares` against
+// what the matcher reported).
+export { readOnChainHolderShares, reconcileFills, reportedFromPositions, } from "./reconcile.js";
 // Account Kit (Alchemy SCA) — owner-key ERC-1271 order signing + gasless custody.
 // Peer deps (@account-kit/*, @aa-sdk/core) are lazy-imported; importing this
 // module does NOT require them unless you construct/connect the signer.
 export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, } from "./accountKit.js";
+// Low-level "raw tx" tier (design doc §4) — transport-free primitives for hosts
+// that own their own Account-Abstraction send path (e.g. rain.trade's shared
+// session): on-chain setup builders → rain's exact `RawTransaction` shape, plus
+// a local order-session signer for the off-chain sigs their session can't make.
+export { buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession, } from "./accountKit.js";
 // Types
 export { OrderType, OrderSide, Option, } from "./types.js";

package/dist/reconcile.d.ts

@@ -0,0 +1,103 @@
+/**
+ * S5 — on-chain fill reconciliation.
+ *
+ * The matcher reports an MM's positions off-chain (`GET /positions/:wallet`,
+ * `GET /markets/:address/holders`). On-chain, `UpDownSettlement.userShares`
+ * (a public mapping) is the AUTHORITATIVE record of what each holder actually
+ * owns — it is the number `redeemFor`/`redeem` pays against. A bot that trusts
+ * only the matcher cannot see the off-chain ledger-integrity failures in the
+ * pre-prod review (B1 collateral double-commit, B6 phantom positions): both
+ * manifest as the matcher REPORTING shares (or a fill) that on-chain state does
+ * not back. This helper closes that gap — it reads `userShares` directly and
+ * diffs it against what the matcher reported, so an MM has an independent
+ * detector rather than taking the API's word for its own book.
+ *
+ * `viem` is a peer dependency — pass the `PublicClient` you already have.
+ */
+import type { Address, PublicClient } from "viem";
+import { type OptionValue } from "./types.js";
+/** Authoritative on-chain shares for one holder in one market. */
+export interface OnChainHolderShares {
+    marketId: bigint;
+    holder: Address;
+    /** `userShares[marketId][holder][UP]` (atomic). */
+    up: bigint;
+    /** `userShares[marketId][holder][DOWN]` (atomic). */
+    down: bigint;
+    resolved: boolean;
+    /** Winning option once resolved: `Option.UP`/`Option.DOWN`, or 0 if unresolved. */
+    winner: OptionValue | 0;
+}
+/**
+ * Read a holder's authoritative on-chain shares (both options) and the market's
+ * resolution state in one batch of `readContract` calls.
+ */
+export declare function readOnChainHolderShares(args: {
+    publicClient: PublicClient;
+    settlement: Address;
+    marketId: bigint;
+    holder: Address;
+}): Promise<OnChainHolderShares>;
+export type ReconcileStatus = "match" | "reported_over" | "reported_under";
+/** Per-option reconciliation of matcher-reported vs on-chain shares. */
+export interface ShareReconciliation {
+    option: OptionValue;
+    optionLabel: "UP" | "DOWN";
+    /** Authoritative on-chain `userShares`. */
+    onChain: bigint;
+    /** What the matcher reported off-chain. */
+    reported: bigint;
+    /** `reported - onChain`. Positive = matcher over-reports (phantom risk). */
+    drift: bigint;
+    status: ReconcileStatus;
+}
+export interface FillReconciliationReport {
+    marketId: bigint;
+    holder: Address;
+    resolved: boolean;
+    winner: OptionValue | 0;
+    lines: ShareReconciliation[];
+    /** True when every option reconciles exactly. */
+    ok: boolean;
+    /**
+     * True when the matcher reports MORE shares than the chain backs on some
+     * option (`reported_over`) — the dangerous direction: a phantom position the
+     * MM would price against but cannot redeem. Post-redemption a winner-side
+     * `reported_over` is benign (the holder was already paid and `userShares`
+     * zeroed); check `resolved`/`winner` before alerting.
+     */
+    hasPhantom: boolean;
+}
+/**
+ * Reconcile matcher-reported net shares against on-chain `userShares` for one
+ * holder in one market. `reported` is the net shares the matcher attributes to
+ * the holder per option (atomic units), e.g. folded from `GET /positions/:wallet`
+ * — see {@link reportedFromPositions}.
+ *
+ * Returns a per-option diff plus `ok` / `hasPhantom` flags an MM can gate on.
+ * A healthy market reconciles exactly; a divergence is the on-chain signature of
+ * the B1/B6 ledger bugs (or of a redemption the off-chain ledger hasn't caught
+ * up to yet — hence the `resolved`/`winner` context).
+ */
+export declare function reconcileFills(args: {
+    publicClient: PublicClient;
+    settlement: Address;
+    marketId: bigint;
+    holder: Address;
+    reported: {
+        up: bigint;
+        down: bigint;
+    };
+}): Promise<FillReconciliationReport>;
+/**
+ * Fold a matcher `Position[]` list (from `GET /positions/:wallet`, already
+ * filtered to one market) into the `{ up, down }` atomic-share shape
+ * {@link reconcileFills} expects. Unknown option labels are ignored.
+ */
+export declare function reportedFromPositions(positions: ReadonlyArray<{
+    optionLabel: "UP" | "DOWN";
+    shares: string;
+}>): {
+    up: bigint;
+    down: bigint;
+};

package/dist/reconcile.js

@@ -0,0 +1,129 @@
+import { Option } from "./types.js";
+/** Minimal read-only slice of the settlement ABI — no write surface. */
+const SETTLEMENT_RECON_ABI = [
+    {
+        type: "function",
+        name: "userShares",
+        stateMutability: "view",
+        inputs: [
+            { name: "marketId", type: "uint256" },
+            { name: "holder", type: "address" },
+            { name: "option", type: "uint8" },
+        ],
+        outputs: [{ name: "", type: "uint256" }],
+    },
+    {
+        type: "function",
+        name: "getMarket",
+        stateMutability: "view",
+        inputs: [{ name: "marketId", type: "uint256" }],
+        outputs: [
+            {
+                name: "",
+                type: "tuple",
+                components: [
+                    { name: "pairId", type: "bytes32" },
+                    { name: "cashUpFlow", type: "uint128" },
+                    { name: "cashDownFlow", type: "uint128" },
+                    { name: "startTime", type: "uint64" },
+                    { name: "endTime", type: "uint64" },
+                    { name: "duration", type: "uint32" },
+                    { name: "winner", type: "uint8" },
+                    { name: "resolved", type: "bool" },
+                    { name: "settled", type: "bool" },
+                    { name: "strikePrice", type: "int128" },
+                    { name: "settlementPrice", type: "int128" },
+                ],
+            },
+        ],
+    },
+];
+/**
+ * Read a holder's authoritative on-chain shares (both options) and the market's
+ * resolution state in one batch of `readContract` calls.
+ */
+export async function readOnChainHolderShares(args) {
+    const { publicClient, settlement, marketId, holder } = args;
+    const read = (option) => publicClient.readContract({
+        address: settlement,
+        abi: SETTLEMENT_RECON_ABI,
+        functionName: "userShares",
+        args: [marketId, holder, option],
+    });
+    const [up, down, market] = await Promise.all([
+        read(Option.UP),
+        read(Option.DOWN),
+        publicClient.readContract({
+            address: settlement,
+            abi: SETTLEMENT_RECON_ABI,
+            functionName: "getMarket",
+            args: [marketId],
+        }),
+    ]);
+    const winnerNum = Number(market.winner);
+    const winner = winnerNum === Option.UP ? Option.UP : winnerNum === Option.DOWN ? Option.DOWN : 0;
+    return { marketId, holder, up, down, resolved: market.resolved, winner };
+}
+function classify(onChain, reported) {
+    if (reported === onChain)
+        return "match";
+    return reported > onChain ? "reported_over" : "reported_under";
+}
+/**
+ * Reconcile matcher-reported net shares against on-chain `userShares` for one
+ * holder in one market. `reported` is the net shares the matcher attributes to
+ * the holder per option (atomic units), e.g. folded from `GET /positions/:wallet`
+ * — see {@link reportedFromPositions}.
+ *
+ * Returns a per-option diff plus `ok` / `hasPhantom` flags an MM can gate on.
+ * A healthy market reconciles exactly; a divergence is the on-chain signature of
+ * the B1/B6 ledger bugs (or of a redemption the off-chain ledger hasn't caught
+ * up to yet — hence the `resolved`/`winner` context).
+ */
+export async function reconcileFills(args) {
+    const chain = await readOnChainHolderShares(args);
+    const lines = [
+        {
+            option: Option.UP,
+            optionLabel: "UP",
+            onChain: chain.up,
+            reported: args.reported.up,
+            drift: args.reported.up - chain.up,
+            status: classify(chain.up, args.reported.up),
+        },
+        {
+            option: Option.DOWN,
+            optionLabel: "DOWN",
+            onChain: chain.down,
+            reported: args.reported.down,
+            drift: args.reported.down - chain.down,
+            status: classify(chain.down, args.reported.down),
+        },
+    ];
+    return {
+        marketId: args.marketId,
+        holder: args.holder,
+        resolved: chain.resolved,
+        winner: chain.winner,
+        lines,
+        ok: lines.every((l) => l.status === "match"),
+        hasPhantom: lines.some((l) => l.status === "reported_over"),
+    };
+}
+/**
+ * Fold a matcher `Position[]` list (from `GET /positions/:wallet`, already
+ * filtered to one market) into the `{ up, down }` atomic-share shape
+ * {@link reconcileFills} expects. Unknown option labels are ignored.
+ */
+export function reportedFromPositions(positions) {
+    let up = 0n;
+    let down = 0n;
+    for (const p of positions) {
+        const s = BigInt(p.shares);
+        if (p.optionLabel === "UP")
+            up += s;
+        else if (p.optionLabel === "DOWN")
+            down += s;
+    }
+    return { up, down };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.2.0",
-  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
+  "version": "0.4.0",
+  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets \u2014 matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
   "scripts": {
     "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc",
-    "test": "node scripts/eip712-golden.test.mjs",
+    "test": "node scripts/eip712-golden.test.mjs && node scripts/rawtx-tier.test.mjs && node scripts/hot-key-safety.test.mjs && node scripts/reconcile.test.mjs",
     "prepublishOnly": "npm run build && npm test",
     "example:taker": "npx tsx examples/simple-taker.ts",
     "example:maker": "npx tsx examples/simple-maker.ts",