@pulsepairs/sdk 0.3.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.
 
 ---
 
@@ -261,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

package/dist/accountKit.d.ts

@@ -253,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: {

package/dist/accountKit.js

@@ -483,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))) {
@@ -504,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) {
@@ -617,7 +625,10 @@ async function buildOrderSessionInstall(sca, moduleChain) {
     // 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);
+    // 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",
@@ -708,6 +719,18 @@ export async function signWithOrderSession(args) {
 }
 /* ───────────────────────── calldata encoders ───────────────────────── */
 const MAX_UINT256 = (1n << 256n) - 1n;
+/** 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(amount));

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,8 +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,11 +2,15 @@
 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.

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.3.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 && node scripts/rawtx-tier.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",