@pulsepairs/sdk 0.8.1 → 0.9.0

package/README.md

@@ -389,6 +389,8 @@ in **bps** (10000 = full face), fees atomic. `Option` is `1 = UP`, `2 = DOWN`.
 
 ```
 Clients          UpDownHttpClient, UpDownWsClient, wsUrlFromHttpBase
+Maker writes     UpDownHttpClient.postOrder, cancelOrder, amendOrder,
+(v0.9.0)         amendOrdersBulk, postOrdersBulk, bulkFailures
 EIP-712          ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES,
                  buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData,
                  freshSessionId, freshNonce, domainForSettlement,
@@ -411,6 +413,76 @@ Enums/types      OrderType, OrderSide, Option, ApiConfig, PairConfig, PostOrderB
 
 ---
 
+## Cancel-and-replace, and bulk writes (v0.9.0)
+
+**`amendOrder` replaces a resting order in one request.** Doing it as
+cancel-then-place leaves the book without your quote for a round trip, and a
+fill can land on the original inside that window — so the two-step is not just
+slower, it is a different outcome. The server does both under one lock, and a
+rejected amend leaves the **original** resting, never nothing.
+
+```ts
+const res = await api.amendOrder({
+  cancelOrderId: resting.id,
+  order: { maker, market, option: Option.UP, side: 0, type: 0,
+           price: 5100, amount: "10000000", maxFee, nonce: freshNonce(),
+           expiry, signature },
+});
+res.replaced;      // the order id that was retired
+res.priorityKept;  // false when the amend forfeited queue position
+res.remaining;     // atomic USDT carried over to the replacement
+```
+
+`order` is a **freshly signed order**, exactly as `postOrder` takes — it carries
+its own nonce and expiry. An amend is a new order, not an edit.
+
+Pass `expectedRemaining` to make it conditional: the amend is refused with
+`REMAINING_MISMATCH` unless the resting order still has exactly that much
+unfilled. Omit it to amend regardless of intervening fills.
+
+### Bulk: read `results[]`, never the status code
+
+`amendOrdersBulk` and `postOrdersBulk` answer **HTTP 200 with each order's
+outcome in the body**. A rejection — bad signature, stale expiry, rate-limit
+shed — never reaches a status code, so a caller that treats 200 as "all placed"
+silently counts every shed order as a success. Use `bulkFailures`:
+
+```ts
+const res = await api.postOrdersBulk({ orders: ladder });
+for (const f of bulkFailures(res)) {
+  console.warn(`orders[${f.index}] rejected: ${f.error}`, f.scope ?? "");
+}
+```
+
+`index` is the position in the array you sent — results are positional.
+
+Two behavioural differences worth knowing, because they change how latency
+scales:
+
+| | fan-out | latency vs batch size |
+|---|---|---|
+| `postOrdersBulk` | concurrent | roughly flat |
+| `amendOrdersBulk` | **serial** | roughly linear |
+
+Amends run serially on purpose: two amends racing on neighbouring price levels
+would otherwise see each other's half-applied state. Both cap at 20 per request.
+
+### Verifying against a live matcher
+
+`npm test` is network-free. To round-trip all three against the dev stack:
+
+```bash
+UPND_INTEGRATION=1 PRIVATE_KEY=0x… npm run test:integration
+```
+
+It rests an order, amends it, bulk-places two, bulk-amends those, and cancels
+everything in a `finally` — including on failure. It defaults to dev and refuses
+to run against prod without `UPND_ALLOW_PROD=1`, because it places real orders
+and only dev's USDT is play money. Needs a live 5m market with >120s left, so
+the keeper has to be cycling.
+
+---
+
 ## Field-name gotchas (live with them)
 
 - `OrderRow.nonce` / `OrderRow.expiry` are JSON **strings** (uint256 precision).

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-import type { ApiConfig, Balance, CancelOrderBody, MarketDetail, MarketListItem, OrderBookFull, OrdersResponse, PairSymbol, PostOrderBody, Position, Stats, Trade, Version } from "./types.js";
+import type { AmendOrderBody, AmendOrderResult, ApiConfig, Balance, BulkAmendBody, BulkAmendResults, BulkFailure, BulkOrdersBody, BulkOrdersResults, CancelOrderBody, MarketDetail, MarketListItem, OrderBookFull, OrdersResponse, PairSymbol, PostOrderBody, Position, Stats, Trade, Version } from "./types.js";
 import { type PortfolioPnl } from "./pnl.js";
 export declare class UpDownHttpClient {
     private readonly baseUrl;
@@ -85,5 +85,71 @@ export declare class UpDownHttpClient {
         id: string;
         status: "CANCEL_PENDING" | string;
     }>;
+    /**
+     * Atomic cancel-and-replace: retire a resting order and rest its replacement
+     * in ONE request.
+     *
+     * This is the call a quoting bot makes most. Doing it as cancel-then-place
+     * leaves the book without your quote for a round trip, and a fill can land
+     * on the original in that window — so the two-step is not just slower, it is
+     * a different outcome. The server does both under one lock; a rejected amend
+     * leaves the ORIGINAL resting, never nothing.
+     *
+     * `order` must be a freshly signed order, exactly as `postOrder` takes. It
+     * carries its own nonce and expiry: the replacement is a new order, not an
+     * edit of the old one.
+     *
+     * Rejections arrive as thrown errors here, unlike the bulk form — this route
+     * answers a real status code (404 `ORDER_NOT_RESTING`, 409
+     * `REMAINING_MISMATCH` / `FILL_IN_FLIGHT`, 400 `SCOPE_MISMATCH` /
+     * `EMPTY_REPLACEMENT`).
+     */
+    amendOrder(body: AmendOrderBody): Promise<AmendOrderResult>;
+    /**
+     * Many amends in one request — a ladder refresh.
+     *
+     * READ `results[]`, NOT THE STATUS CODE. This route answers `200` with each
+     * amend's outcome in the body, so a rejection never reaches `parseJson`'s
+     * throw. `bulkFailures()` below exists to make that hard to forget.
+     *
+     * Results are positional: `results[i]` is the outcome of `amends[i]`.
+     *
+     * Server-side these run SERIALLY, not concurrently — two amends racing on
+     * neighbouring price levels would otherwise see each other's half-applied
+     * state. So latency scales with batch size roughly linearly, unlike
+     * `postOrdersBulk`. Capped at 20 per request.
+     */
+    amendOrdersBulk(body: BulkAmendBody): Promise<BulkAmendResults>;
+    /**
+     * Place many orders in one request.
+     *
+     * Same 200-with-per-order-results contract as `amendOrdersBulk` — read
+     * `results[]`. Unlike amends these fan out CONCURRENTLY server-side, so the
+     * whole request costs roughly one order's latency rather than N.
+     *
+     * Results are positional: `results[i]` is the outcome of `orders[i]`.
+     * Capped at 20 per request.
+     */
+    postOrdersBulk(body: BulkOrdersBody): Promise<BulkOrdersResults>;
 }
+/**
+ * The rejected entries of a bulk response, with their request index.
+ *
+ * Exists because the failure mode it prevents has already happened twice, on
+ * both sides of this integration: a bulk call answers `200`, the caller treats
+ * that as "all placed", and every per-order rejection — bad signature, stale
+ * expiry, rate-limit shed — is silently counted as a success. A reported "no
+ * 429s at 600/min" was a true statement about a blind metric for exactly this
+ * reason.
+ *
+ * `index` is the position in the request array, so a caller can correlate a
+ * failure back to the order it sent.
+ */
+export declare function bulkFailures(response: {
+    results: Array<{
+        ok: boolean;
+    } & Record<string, unknown>>;
+}): Array<BulkFailure & {
+    index: number;
+}>;
 export declare function wsUrlFromHttpBase(httpBase: string): string;

package/dist/http.js

@@ -181,6 +181,94 @@ export class UpDownHttpClient {
         });
         return parseJson(res);
     }
+    /**
+     * Atomic cancel-and-replace: retire a resting order and rest its replacement
+     * in ONE request.
+     *
+     * This is the call a quoting bot makes most. Doing it as cancel-then-place
+     * leaves the book without your quote for a round trip, and a fill can land
+     * on the original in that window — so the two-step is not just slower, it is
+     * a different outcome. The server does both under one lock; a rejected amend
+     * leaves the ORIGINAL resting, never nothing.
+     *
+     * `order` must be a freshly signed order, exactly as `postOrder` takes. It
+     * carries its own nonce and expiry: the replacement is a new order, not an
+     * edit of the old one.
+     *
+     * Rejections arrive as thrown errors here, unlike the bulk form — this route
+     * answers a real status code (404 `ORDER_NOT_RESTING`, 409
+     * `REMAINING_MISMATCH` / `FILL_IN_FLIGHT`, 400 `SCOPE_MISMATCH` /
+     * `EMPTY_REPLACEMENT`).
+     */
+    async amendOrder(body) {
+        const res = await fetch(buildUrl(this.baseUrl, "/orders/amend"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseJson(res);
+    }
+    /**
+     * Many amends in one request — a ladder refresh.
+     *
+     * READ `results[]`, NOT THE STATUS CODE. This route answers `200` with each
+     * amend's outcome in the body, so a rejection never reaches `parseJson`'s
+     * throw. `bulkFailures()` below exists to make that hard to forget.
+     *
+     * Results are positional: `results[i]` is the outcome of `amends[i]`.
+     *
+     * Server-side these run SERIALLY, not concurrently — two amends racing on
+     * neighbouring price levels would otherwise see each other's half-applied
+     * state. So latency scales with batch size roughly linearly, unlike
+     * `postOrdersBulk`. Capped at 20 per request.
+     */
+    async amendOrdersBulk(body) {
+        const res = await fetch(buildUrl(this.baseUrl, "/orders/amend/bulk"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseJson(res);
+    }
+    /**
+     * Place many orders in one request.
+     *
+     * Same 200-with-per-order-results contract as `amendOrdersBulk` — read
+     * `results[]`. Unlike amends these fan out CONCURRENTLY server-side, so the
+     * whole request costs roughly one order's latency rather than N.
+     *
+     * Results are positional: `results[i]` is the outcome of `orders[i]`.
+     * Capped at 20 per request.
+     */
+    async postOrdersBulk(body) {
+        const res = await fetch(buildUrl(this.baseUrl, "/orders/bulk"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseJson(res);
+    }
+}
+/**
+ * The rejected entries of a bulk response, with their request index.
+ *
+ * Exists because the failure mode it prevents has already happened twice, on
+ * both sides of this integration: a bulk call answers `200`, the caller treats
+ * that as "all placed", and every per-order rejection — bad signature, stale
+ * expiry, rate-limit shed — is silently counted as a success. A reported "no
+ * 429s at 600/min" was a true statement about a blind metric for exactly this
+ * reason.
+ *
+ * `index` is the position in the request array, so a caller can correlate a
+ * failure back to the order it sent.
+ */
+export function bulkFailures(response) {
+    const out = [];
+    response.results.forEach((r, index) => {
+        if (!r.ok)
+            out.push({ ...r, index });
+    });
+    return out;
 }
 export function wsUrlFromHttpBase(httpBase) {
     const u = new URL(httpBase);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
+export { UpDownHttpClient, wsUrlFromHttpBase, bulkFailures } 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, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_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";
@@ -7,4 +7,4 @@ export { readOnChainHolderShares, reconcileFills, reportedFromPositions, type On
 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 { PRICE_BPS_SCALE, WIN_MARK_BPS, LOSE_MARK_BPS, DEFAULT_USDT_DECIMALS, atomicToUsdt, markValueAtomic, midBps, markForOption, isResolvedWinner, positionPnl, feesPaidByWallet, portfolioPnl, computePortfolioPnl, type MarkSource, type PositionPnl, type PortfolioPnl, type PositionPnlOptions, } from "./pnl.js";
-export { OrderType, OrderSide, Option, takerPriceBps, 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";
+export { OrderType, OrderSide, Option, takerPriceBps, type AmendOrderBody, type AmendOrderResult, type ApiConfig, type Balance, type BulkAmendBody, type BulkAmendResults, type BulkFailure, type BulkOrdersBody, type BulkOrdersResults, 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 SubmittedOrder, type Stats, type Trade, type Version, } from "./types.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 // HTTP + WS clients
-export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
+export { UpDownHttpClient, wsUrlFromHttpBase, bulkFailures } from "./http.js";
 export { UpDownWsClient, } from "./ws.js";
 // EIP-712 helpers
 export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, 

package/dist/types.d.ts

@@ -244,6 +244,92 @@ export type Version = {
 };
 /** Atomic-USDT body for `POST /orders`. The backend re-verifies the
  *  signature against the per-pair domain on receipt. */
+/**
+ * An order as the API reports it back after a successful submission — the
+ * shape `POST /orders`, `POST /orders/bulk` and both amend routes return.
+ */
+export type SubmittedOrder = {
+    id: string;
+    status: string;
+    market: string;
+    option: number;
+    side: string;
+    type: string;
+    price: number;
+    amount: string;
+    /** Atomic. `"0"` on a MARKET/IOC order that found no liquidity — the field
+     *  that distinguishes "placed" from "placed and did nothing". */
+    filledAmount: string;
+    createdAt: number | string;
+};
+/**
+ * A per-order failure inside a `200`.
+ *
+ * `/orders/bulk` and `/orders/amend/bulk` answer 200 with each order's outcome
+ * in the body, so a rejection for a bad signature, a stale expiry or the
+ * per-maker rate limit NEVER surfaces as an HTTP status. Any success rate or
+ * latency figure derived from status codes silently excludes this entire
+ * class — a mistake both this venue and LedgerCore made independently in their
+ * own instrumentation. Read `results[]`.
+ */
+export type BulkFailure = {
+    ok: false;
+    error: string;
+    code?: string;
+    /** `"maker"` when the per-wallet per-second bucket shed this order. */
+    scope?: string;
+    /** Present on an amend rejected for a fill that landed first. */
+    filled?: string;
+    remaining?: string;
+};
+/** One amend: retire `cancelOrderId`, rest `order` in its place, atomically. */
+export type AmendOrderBody = {
+    /** The resting order to replace. */
+    cancelOrderId: string;
+    /**
+     * Optimistic-concurrency guard, atomic USDT. When set, the amend is refused
+     * with `REMAINING_MISMATCH` unless the resting order still has exactly this
+     * much unfilled. Omit to amend regardless of intervening fills.
+     */
+    expectedRemaining?: string;
+    /** The replacement — a fully signed order, same shape as `POST /orders`. */
+    order: PostOrderBody;
+};
+/** `POST /orders/amend` success. */
+export type AmendOrderResult = SubmittedOrder & {
+    /** Echo of the `cancelOrderId` that was retired. */
+    replaced: string;
+    /**
+     * Whether the replacement kept the original's queue position. False when the
+     * amend changed a term that forfeits priority (price, or an increase in
+     * size) — worth reading, because a maker that assumes priority survived will
+     * mis-model its own fill probability.
+     */
+    priorityKept: boolean;
+    /** Atomic USDT already filled on the ORIGINAL order before it was retired. */
+    filled: string;
+    /** Atomic USDT that was still resting and has moved to the replacement. */
+    remaining: string;
+};
+/** `POST /orders/amend/bulk` — amends run SERIALLY server-side. */
+export type BulkAmendBody = {
+    amends: AmendOrderBody[];
+};
+export type BulkAmendResults = {
+    results: Array<({
+        ok: true;
+    } & AmendOrderResult) | BulkFailure>;
+};
+/** `POST /orders/bulk` — orders fan out CONCURRENTLY server-side. */
+export type BulkOrdersBody = {
+    orders: PostOrderBody[];
+};
+export type BulkOrdersResults = {
+    results: Array<{
+        ok: true;
+        order: SubmittedOrder;
+    } | BulkFailure>;
+};
 export type PostOrderBody = {
     maker: string;
     /** Composite key `<settlement>-<marketId>` — used for routing only. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.8.1",
+  "version": "0.9.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",
@@ -34,7 +34,8 @@
   "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 && node scripts/hot-key-safety.test.mjs && node scripts/reconcile.test.mjs && node scripts/pnl.test.mjs && node scripts/ws-subscribe.test.mjs && node scripts/ws-onerror.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 && node scripts/pnl.test.mjs && node scripts/ws-subscribe.test.mjs && node scripts/ws-onerror.test.mjs && node scripts/amend-wrappers.test.mjs && node scripts/amend-integration.test.mjs",
+    "test:integration": "UPND_INTEGRATION=1 node scripts/amend-integration.test.mjs",
     "prepublishOnly": "npm run build && npm test",
     "example:taker": "npx tsx examples/simple-taker.ts",
     "example:maker": "npx tsx examples/simple-maker.ts",