@lamarge/sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snowbl Capital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @lamarge/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript client of the [LaMarge API](https://docs.lamarge.trade), for apps, takers and makers. It runs in browsers, Bun and Node 22.12+, ships ESM only and has no runtime dependency.
+
+| Entry | Contents |
+| --- | --- |
+| `@lamarge/sdk` | `createClient`, every public operation by its `operationId` (`client.call`), `LaMargeError`, sign-in, signing of checked items, taker flows, `Maker`, `Quoter`, the event feed, `VenueDeliverer` |
+| `@lamarge/sdk/protocol` | The reviewed deployments and every check run before a signature: EIP-712 schemas and domains, intents, withdrawals, Aster and Lighter messages, units |
+| `@lamarge/sdk/aster` | `AsterDeliverer`: an active maker's transfers inside Aster. Needs `viem`, an optional peer dependency |
+| `@lamarge/sdk/lighter` | `LighterDeliverer`: an active maker's transfers inside Lighter, signed by a `LighterSigner` the application holds (lighter-ts-sdk or Lighter's Go signer) |
+
+```ts
+import { createClient, signIn, signItems } from "@lamarge/sdk";
+import { privateKeyToAccount } from "viem/accounts";
+
+const client = createClient({ apiUrl: "https://api.lamarge.trade" });
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+await signIn(client, account, "https://app.lamarge.trade");
+const balances = await client.call("getBalances");
+```
+
+A transfer, as a server-side taker runs it. Persist `client_transfer_id`, the transfer id `onIntent` names and the store's contents: running the same request again resumes it and submits what was signed rather than signing again.
+
+```ts
+import { transfer } from "@lamarge/sdk";
+
+const fills = await transfer(client, account, {
+  client_transfer_id: "rebalance-2026-10-17-1", from: "hyperliquid", to: "polymarket",
+  amount_in: "250000000", min_out: "249500000", recipient: account.address,
+  funding: "wallet", // never withdraws from the venue; "venue" withdraws the shortfall first
+}, { store, onIntent: intent => save(intent.id) });
+```
+
+| Flow | Does |
+| --- | --- |
+| `signIn`, `checkDeployment` | SIWE for the app's origin, after checking every chain the API names against the pinned deployment |
+| `linkAccount`, `setUpVenue` | Links an account, by the link message when it is not the master's; runs its setup steps (permit, Aster agent, Lighter key) |
+| `transfer` | Funding, the take, its payment; recovery by client id; `TransferPending` when funds or a permit have not arrived yet |
+| `take` | Reserves quotes, checks and signs the payment (escrow, Aster or Lighter), submits it |
+| `changes` | Snapshot, then every page of events over the WebSocket, HTTP replay between connections, `{ resync }` when the journal moved on |
+
+Making a market takes two keys on two hosts. `Maker` holds the financial key and only provisions and releases capital; `Quoter` holds a scoped credential (`mk_`) and the quote key, and only quotes, cancels and reports deliveries.
+
+```ts
+import { createClient, Maker, Quoter } from "@lamarge/sdk";
+
+const master = new Maker(createClient({ apiUrl }), financialAccount, operatorAddress, "https://app.lamarge.trade");
+await master.login();
+const credential = await master.createCredential("quoter", quoteAccount.address);
+const order = await master.waitForFunding(await master.addCapital({ venue: "hyperliquid", amount: "5000000", client_request_id, funding_source: "venue" }, credential, store));
+
+const quoter = new Quoter(createClient({ apiUrl, token: credential.token }), credential.id, quoteAccount);
+await quoter.lease(30);
+await quoter.batch([await quoter.prepare(await quoter.order(order.id), quotes, 5_000_000n, Math.floor(Date.now() / 1000) + 25)]);
+```
+
+A passive maker's pools sit in the escrow (Hyperliquid, Polymarket): the operator settles every fill. An active maker's pools sit inside a venue (Lighter, Aster): its agent also runs a deliverer, which sends each paid fill's transfer, persists it in a `DeliveryJournal` before sending, never signs a fill twice and reports the transfer. The agent itself (its loop, configuration, journal storage, single-writer lock and shutdown) is the application's; LaMarge's maker example is one, available on request.
+
+A `Signer` is an address with `signMessage` and `signTypedData`: a viem `LocalAccount`, a KMS key through viem's `toAccount`, or a browser wallet's client wrapped in those two methods. The SDK hands it only what its checks accepted; never sign a `to_sign` item that a check of `@lamarge/sdk/protocol` has not compared with your own request.
+
+Answers are typed from the public API reference, not validated: enums stay open to values a newer server adds. A refusal is a `LaMargeError` whose `code` and `reason` are stable. Only reads and calls marked `retry` are repeated, with the identical request; never retry a write by building a new one.
+
+## Development
+
+```sh
+bun install --frozen-lockfile
+bun run check      # generated types are current, typecheck, tests, build
+bun run api:generate
+```
+
+`src/generated/api.ts` comes from `docs/api/api-reference/openapi.yaml`, the API's public contract. The SDK is developed in LaMarge's repository, next to the server, the app and that contract; [snowbl-capital/lamarge-sdk](https://github.com/snowbl-capital/lamarge-sdk) mirrors each release, with the public contract and the Lighter test vectors its checks need. Changes are made upstream; issues are welcome there.
+
+Each release `sdk-vX.Y.Z` is cut from the commit production runs, so the server keeps every operation and field it uses. Before 1.0 a minor release may break.

package/dist/account.d.ts

@@ -0,0 +1,32 @@
+import { type Client } from "./client.ts";
+import { type Signer } from "./signer.ts";
+/**
+ * Links `owner`'s account on `venue` under the signed-in `master`: the master's own address needs
+ * no proof, any other signs the link message once it is checked. Its setup steps follow (`setUpVenue`).
+ */
+export declare function linkAccount(client: Client, master: Pick<Signer, "address">, venue: string, owner?: Pick<Signer, "address" | "signMessage">, signal?: AbortSignal): Promise<{
+    setup: import("./index.ts").components["schemas"]["SetupSteps"];
+    venue: import("./index.ts").components["schemas"]["VenueId"];
+    address: import("./index.ts").components["schemas"]["Address"];
+    venue_wallet: string | null;
+    linked_at: import("./index.ts").components["schemas"]["Timestamp"];
+}>;
+/**
+ * Does each step of the linked account that the venue does not show yet (a permit, Aster's agent
+ * approval, Lighter's key) and waits until the venue shows it. A step submitted before is awaited,
+ * never signed twice. `owner` is the account linked on `venue`; `steps` limits the run to those
+ * steps, as a maker pool needs only Aster's agent and none of a taker's payment setup.
+ */
+export declare function setUpVenue(client: Client, venue: string, owner: Signer, options?: {
+    steps?: readonly string[] | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<{
+    venue: import("./index.ts").components["schemas"]["VenueId"];
+    address: import("./index.ts").components["schemas"]["Address"];
+    ready: boolean;
+    steps: import("./index.ts").components["schemas"]["SetupStep"][];
+}>;
+/** The permit a transfer from wallet funds asks for; one already submitted or final needs nothing. */
+export declare function submitPermit(client: Client, venue: string, owner: Signer, signal?: AbortSignal): Promise<void>;
+/** Whether the account's submitted permit is final; a failed one stops the transfer. */
+export declare function permitDone(client: Client, venue: string, owner: Pick<Signer, "address">, signal?: AbortSignal): Promise<boolean>;

package/dist/account.js

@@ -0,0 +1,113 @@
+import { LaMargeError, wait } from "./client.js";
+import { checkLinkChallenge } from "./protocol/consents.js";
+import { requireV5Deployment } from "./protocol/deployments.js";
+import { fromHex, registrationMessage, TAKER_API_KEY } from "./protocol/lighter.js";
+import { CHAINS, checkAsterApproval, checkPermit, insist, same } from "./protocol/protocol.js";
+import { required } from "./protocol/validation.js";
+import { signTyped } from "./signer.js";
+/**
+ * Links `owner`'s account on `venue` under the signed-in `master`: the master's own address needs
+ * no proof, any other signs the link message once it is checked. Its setup steps follow (`setUpVenue`).
+ */
+export async function linkAccount(client, master, venue, owner = { ...master, signMessage: () => Promise.reject(new Error("Unreachable")) }, signal) {
+    let proof;
+    if (!same(owner.address, master.address)) {
+        const challenge = await client.call("postLinkChallenge", { body: { venue, address: owner.address }, signal });
+        checkLinkChallenge(challenge, owner.address, master.address);
+        proof = { nonce: challenge.nonce, signature: await owner.signMessage({ message: challenge.message }) };
+    }
+    const linked = await client.call("postLink", { body: { venue, address: owner.address, ...proof }, signal, retry: true });
+    insist(linked.venue === venue && same(linked.address, owner.address), "Linked another account");
+    return linked;
+}
+/** A prepared step's request, checked against what LaMarge may ask of the account, then signed. */
+async function signStep(step, venue, owner, wallet) {
+    const request = required(step.to_sign, "Prepare the setup again");
+    insist(same(request.signer, owner.address), "Setup asks another account to sign");
+    if (request.kind === "permit") {
+        const chain = required(CHAINS[venue]);
+        requireV5Deployment(chain.id, chain.escrow);
+        const item = { kind: request.kind, signer: request.signer, typed_data: required(request.typed_data) };
+        checkPermit(item, venue, owner.address);
+        return signTyped(owner, item.typed_data);
+    }
+    if (request.kind === "aster_approval") {
+        const typed = required(request.typed_data);
+        const approval = { message: String(typed.message.msg), nonce: request.ref, expires_at: required(request.expires_at), typed_data: typed };
+        checkAsterApproval(approval, owner.address);
+        return signTyped(owner, approval.typed_data);
+    }
+    // Lighter's own owner message: LaMarge's key at its index, for the linked account, at the key's nonce.
+    const message = required(request.message);
+    const key = /^Register Lighter Account\n\npubkey: 0x([0-9a-f]{80})\n/.exec(message)?.[1];
+    insist(key && message === registrationMessage({ account: Number(required(wallet, "Link the Lighter account again")), apiKey: TAKER_API_KEY, publicKey: fromHex(key), nonce: Number(request.ref) }), "Unexpected Lighter key registration");
+    return owner.signMessage({ message });
+}
+/** Prepares and, when it is still required, signs and submits one step; an unanswered submission is sent again unchanged. */
+async function runStep(client, venue, step, owner, wallet, signal) {
+    // Signed once: a stale Aster approval is the only one prepared and signed again.
+    for (let retried = false;; retried = true) {
+        const prepared = await client.call("postVenueSetupStep", { path: { venue, step }, body: {}, signal });
+        if (prepared.status !== "required")
+            return prepared;
+        const body = { ref: required(prepared.to_sign).ref, signature: await signStep(prepared, venue, owner, wallet) };
+        try {
+            for (let attempt = 1;; attempt++) {
+                try {
+                    return await client.call("postVenueSetupStep", { path: { venue, step }, body, signal });
+                }
+                catch (error) {
+                    if (!(error instanceof LaMargeError && error.code === "VENUE_UNAVAILABLE") || attempt === 3)
+                        throw error;
+                    await wait(2_000 * attempt, signal);
+                }
+            }
+        }
+        catch (error) {
+            // Aster names a stale approval only in its message; the API has no reason for it yet.
+            if (retried || !(error instanceof LaMargeError && error.code === "VENUE_REJECTED" && /nonce|expired/i.test(error.message)))
+                throw error;
+        }
+    }
+}
+/**
+ * Does each step of the linked account that the venue does not show yet (a permit, Aster's agent
+ * approval, Lighter's key) and waits until the venue shows it. A step submitted before is awaited,
+ * never signed twice. `owner` is the account linked on `venue`; `steps` limits the run to those
+ * steps, as a maker pool needs only Aster's agent and none of a taker's payment setup.
+ */
+export async function setUpVenue(client, venue, owner, options = {}) {
+    const { steps, signal } = options;
+    // Lighter's key registration names the linked account's index.
+    let [setup, wallet] = await Promise.all([client.call("getVenueSetup", { path: { venue }, signal }),
+        venue === "lighter" ? client.call("getBalances", { signal }).then(rows => rows.find(row => row.venue === venue)?.venue_wallet ?? null) : null]);
+    insist(same(setup.address, owner.address), "Setup returned another account");
+    const todo = setup.steps.filter(row => row.status !== "done" && (!steps || steps.includes(row.step)));
+    for (const { step } of todo) {
+        let current = await runStep(client, venue, step, owner, wallet, signal);
+        for (let read = 0; current.status === "pending"; read++) {
+            insist(read < 60, "Setup is awaiting the venue's confirmation. Check again.");
+            await wait(2_000, signal);
+            setup = await client.call("getVenueSetup", { path: { venue }, signal });
+            current = required(setup.steps.find(row => row.step === step));
+        }
+        insist(current.status === "done", `${venue} setup failed`);
+    }
+    if (todo.length)
+        setup = await client.call("getVenueSetup", { path: { venue }, signal });
+    insist(same(setup.address, owner.address) && (steps ? setup.steps.every(row => row.status === "done" || !steps.includes(row.step)) : setup.ready), "Setup is incomplete");
+    return setup;
+}
+/** The permit a transfer from wallet funds asks for; one already submitted or final needs nothing. */
+export async function submitPermit(client, venue, owner, signal) {
+    await runStep(client, venue, "permit", owner, null, signal);
+}
+/** Whether the account's submitted permit is final; a failed one stops the transfer. */
+export async function permitDone(client, venue, owner, signal) {
+    const setup = await client.call("getVenueSetup", { path: { venue }, signal });
+    insist(same(setup.address, owner.address), "Setup returned another account");
+    const permit = required(setup.steps.find(step => step.step === "permit"));
+    if (permit.status === "required")
+        throw new Error("Payment authorization failed");
+    return permit.status === "done";
+}

package/dist/aster.d.ts

@@ -0,0 +1,74 @@
+import { VenueDeliverer, type DeliveryJournal, type FillSource, type Log } from "./delivery.ts";
+import type { DeliveryFill } from "./maker.ts";
+import { type Signer } from "./signer.ts";
+export declare const ASTER_MAINNET: {
+    chain: string;
+    futures: string;
+    spot: string;
+};
+/** The pool's own address, whose key signs its transfers: a dedicated address, never the master. */
+export type AsterConfig = {
+    account: string;
+};
+/**
+ * A delivery's signed request, persisted before its first send. `attempted` is set before any
+ * send, `transfer_id` once Aster answered. `outcome` once settled: `reported` to LaMarge;
+ * `failed`, LaMarge will not take it; `refused` by Aster on the first send; `dropped`, never sent
+ * before the deadline; `unknown`, never answered within the nonce window, never signed again.
+ */
+export type AsterDelivery = {
+    fill_id: string;
+    query: string;
+    nonce: number;
+    amount: string;
+    to: string;
+    attempted: boolean;
+    transfer_id?: string;
+    outcome?: "reported" | "failed" | "dropped" | "refused" | "unknown";
+    created_at: string;
+};
+/** `Message{msg}` in Aster's signing domain: its transfers' chain for requests, BSC's for an agent approval. */
+export declare const signAster: (account: Pick<Signer, "signTypedData">, msg: string, chainId?: number) => Promise<`0x${string}`>;
+export declare class AsterDeliverer extends VenueDeliverer<AsterDelivery> {
+    private owner;
+    private agent;
+    private api;
+    private lastNonce;
+    /** When each fill's next send may be tried. */
+    private sendAt;
+    /**
+     * `owner` signs transfers; `agent`, an agent of the same account allowed only to trade,
+     * moves its margin to Spot first.
+     */
+    constructor(owner: Signer, agent: Signer, store: DeliveryJournal<AsterDelivery>, api?: {
+        chain: string;
+        futures: string;
+        spot: string;
+    }, now?: () => number);
+    /** Microseconds, distinct for each request. */
+    private nonce;
+    /** Aster's JSON answer; a `{code<0}` answer to a request it read is a refusal, anything else unanswered is an error. */
+    private request;
+    /** A request of the agent for the account: the parameters, then nonce, user and signer. */
+    private byAgent;
+    /** The USDT the account's Spot wallet holds, in base units. */
+    private spot;
+    /**
+     * Moves what the Spot wallet lacks for the fill from the margin; the move's id makes a retry a
+     * no-op. `held` is Spot's balance when known, otherwise it is read. Returns what Spot keeps
+     * after the fill's transfer, or undefined after a margin move.
+     */
+    fundSpot(fill: DeliveryFill, held?: bigint): Promise<bigint | undefined>;
+    /** The fill's transfer at `nonce`, signed by the account's key over the request. */
+    sign(fill: DeliveryFill, nonce: number): Promise<AsterDelivery>;
+    /** Sends persisted bytes; returns the transfer id, executed or pending. */
+    send(delivery: AsterDelivery): Promise<string>;
+    /**
+     * Signs and sends due fills whose payment is locked, one at a time, while each transfer gets
+     * an answer from Aster. Spot is read once and each amount deducted locally; it is read again
+     * after a margin move.
+     */
+    protected deliver(quoter: FillSource, due: DeliveryFill[], deliveries: Record<string, AsterDelivery>, log: Log): Promise<boolean>;
+    /** Moves one persisted delivery forward; false while Aster has not answered its request. */
+    protected settle(quoter: FillSource, delivery: AsterDelivery, fill: DeliveryFill | undefined, deliveries: Record<string, AsterDelivery>, log: Log): Promise<boolean>;
+}

package/dist/aster.js

@@ -0,0 +1,169 @@
+// Delivery inside Aster: one transfer per fill from the pool's Spot wallet to the taker's,
+// signed by the account's own key, persisted before it is sent and never signed twice.
+import { getAddress, parseUnits } from "viem";
+import { errorText, Refused, VenueDeliverer } from "./delivery.js";
+import { asterAmount, asterClientId, asterRequest, ASTER_TRANSFER_CHAIN_ID, insist, venueUnits } from "./protocol/protocol.js";
+import { isRecord } from "./protocol/validation.js";
+import { signTyped } from "./signer.js";
+export const ASTER_MAINNET = { chain: "https://chainapi.asterdex.com", futures: "https://fapi.asterdex.com", spot: "https://sapi.asterdex.com" };
+/** Aster takes a signed request while its nonce is within about a minute of its clock: the same bytes are resent for 50 seconds at most. */
+const WINDOW_MS = 50_000;
+/** No request is sent closer than this to `deliver_by`: each one reaches Aster within its 10-second timeout, and Aster transfers synchronously. */
+const SEND_MARGIN_MS = 15_000;
+/** `Message{msg}` in Aster's signing domain: its transfers' chain for requests, BSC's for an agent approval. */
+export const signAster = (account, msg, chainId = ASTER_TRANSFER_CHAIN_ID) => signTyped(account, asterRequest(msg, chainId));
+const query = (fields) => fields.map(([name, value]) => `${name}=${value}`).join("&");
+export class AsterDeliverer extends VenueDeliverer {
+    owner;
+    agent;
+    api;
+    lastNonce = 0;
+    /** When each fill's next send may be tried. */
+    sendAt = new Map();
+    /**
+     * `owner` signs transfers; `agent`, an agent of the same account allowed only to trade,
+     * moves its margin to Spot first.
+     */
+    constructor(owner, agent, store, api = ASTER_MAINNET, now = () => Date.now()) {
+        super("aster", SEND_MARGIN_MS, store, now);
+        this.owner = owner;
+        this.agent = agent;
+        this.api = api;
+    }
+    /** Microseconds, distinct for each request. */
+    nonce() { this.lastNonce = Math.max(this.now() * 1000, this.lastNonce + 1); return this.lastNonce; }
+    /** Aster's JSON answer; a `{code<0}` answer to a request it read is a refusal, anything else unanswered is an error. */
+    async request(method, url) {
+        const response = await fetch(url, { method, headers: { accept: "application/json", ...(method === "POST" ? { "content-type": "application/x-www-form-urlencoded" } : {}) }, signal: AbortSignal.timeout(10_000) });
+        const answer = await response.json().catch(() => null);
+        const body = isRecord(answer) ? answer : null;
+        if (body && typeof body.code === "number" && body.code < 0 && response.status < 500 && response.status !== 429)
+            throw new Refused(`Aster refused: ${body.code} ${String(body.msg ?? "")}`);
+        if (!response.ok || !body)
+            throw new Error(`Aster ${new URL(url).pathname}: HTTP ${response.status}`);
+        return body;
+    }
+    /** A request of the agent for the account: the parameters, then nonce, user and signer. */
+    async byAgent(method, url, params) {
+        const message = query([...params, ["nonce", String(this.nonce())], ["user", this.owner.address], ["signer", this.agent.address]]);
+        return this.request(method, `${url}?${message}&signature=${await signAster(this.agent, message)}`);
+    }
+    /** The USDT the account's Spot wallet holds, in base units. */
+    async spot() {
+        const account = await this.byAgent("GET", `${this.api.spot}/api/v3/account`, []);
+        insist(Array.isArray(account.balances), "Aster answered no Spot balances");
+        const balances = account.balances;
+        const free = balances.filter(isRecord).find(balance => balance.asset === "USDT")?.free ?? "0";
+        insist(typeof free === "string" && /^\d+(\.\d+)?$/.test(free), "Unexpected Aster Spot balance");
+        return parseUnits(free, 18);
+    }
+    /**
+     * Moves what the Spot wallet lacks for the fill from the margin; the move's id makes a retry a
+     * no-op. `held` is Spot's balance when known, otherwise it is read. Returns what Spot keeps
+     * after the fill's transfer, or undefined after a margin move.
+     */
+    async fundSpot(fill, held) {
+        const needed = venueUnits(BigInt(fill.amount_out), "aster");
+        held ??= await this.spot();
+        if (held >= needed)
+            return held - needed;
+        await this.byAgent("POST", `${this.api.futures}/fapi/v3/asset/wallet/transfer`, [["amount", asterAmount(needed - held)], ["asset", "USDT"], ["clientTranId", `m${asterClientId(fill.id)}`], ["kindType", "FUTURE_SPOT"]]);
+        return undefined;
+    }
+    /** The fill's transfer at `nonce`, signed by the account's key over the request. */
+    async sign(fill, nonce) {
+        insist(fill.to_venue === "aster" && fill.delivery_to !== null && /^0x[0-9a-fA-F]{40}$/.test(fill.delivery_to), "Not an Aster delivery");
+        const message = query([["asset", "USDT"], ["amount", asterAmount(BigInt(fill.amount_out))], ["toAddress", getAddress(fill.delivery_to)], ["clientTranId", asterClientId(fill.id)], ["nonce", String(nonce)], ["user", this.owner.address]]);
+        return { fill_id: fill.id, query: `${message}&signature=${await signAster(this.owner, message)}`, nonce, amount: fill.amount_out, to: fill.delivery_to, attempted: false, created_at: new Date(this.now()).toISOString() };
+    }
+    /** Sends persisted bytes; returns the transfer id, executed or pending. */
+    async send(delivery) {
+        const reply = await this.request("POST", `${this.api.chain}/aster-chain/v3/transfer?${delivery.query}`);
+        const id = typeof reply.transferId === "number" ? String(reply.transferId) : reply.transferId;
+        insist(typeof id === "string" && /^\d+$/.test(id) && ["SUCCESS", "PENDING"].includes(String(reply.status)), "Unexpected Aster transfer answer");
+        return id;
+    }
+    /**
+     * Signs and sends due fills whose payment is locked, one at a time, while each transfer gets
+     * an answer from Aster. Spot is read once and each amount deducted locally; it is read again
+     * after a margin move.
+     */
+    async deliver(quoter, due, deliveries, log) {
+        let spot;
+        for (const fill of due.filter(fill => fill.payment_leg === "LOCKED")) {
+            try {
+                if (!this.turn(this.sendAt, fill.id))
+                    return false;
+                // Sign only once Spot holds the amount, so the whole nonce window is left for sending.
+                spot = await this.fundSpot(fill, spot);
+                const delivery = await this.sign(fill, this.nonce());
+                deliveries[fill.id] = delivery;
+                await this.store.save(deliveries);
+                this.sendAt.delete(fill.id);
+                if (!(await this.settle(quoter, delivery, fill, deliveries, log)))
+                    return false;
+            }
+            catch (error) {
+                log(`${fill.id}: ${errorText(error)}`);
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Moves one persisted delivery forward; false while Aster has not answered its request. */
+    async settle(quoter, delivery, fill, deliveries, log) {
+        const id = delivery.fill_id;
+        const save = async () => { await this.store.save(deliveries); };
+        const reported = delivery.transfer_id !== undefined && fill?.delivery_hash === delivery.transfer_id;
+        if (!this.awaits(fill) || reported) {
+            delivery.outcome = reported ? "reported" : "failed";
+            await save();
+            log(`${id}: fill no longer awaits this delivery`);
+            return true;
+        }
+        if (delivery.transfer_id === undefined) {
+            if (this.now() >= delivery.nonce / 1000 + WINDOW_MS || Date.parse(fill.deliver_by ?? "") - this.now() <= SEND_MARGIN_MS) {
+                // Past its window Aster refuses these bytes; an attempted one may have executed, and
+                // another request for the fill could pay twice.
+                delivery.outcome = delivery.attempted ? "unknown" : "dropped";
+                await save();
+                log(delivery.attempted
+                    ? `${id}: Aster never answered transfer ${asterClientId(id)}; not signed again: report its transferId if the account's history shows it`
+                    : `${id}: too close to the delivery deadline, transfer not sent`);
+                return true;
+            }
+            if (!this.turn(this.sendAt, id))
+                return false;
+            // Recorded before the request: a lost answer is never taken for a refusal.
+            const first = !delivery.attempted;
+            delivery.attempted = true;
+            await save();
+            try {
+                delivery.transfer_id = await this.send(delivery);
+            }
+            catch (error) {
+                // Only a first send's refusal is final: after a lost answer, the earlier send may have
+                // executed, and the resend's refusal says nothing of it.
+                if (!(error instanceof Refused) || !first)
+                    throw error;
+                // Private account (-5124) or Spot short (032209): left to its refund, never signed again.
+                delivery.outcome = "refused";
+                await save();
+                log(`${id}: ${error.message}`);
+                return true;
+            }
+            this.sendAt.delete(id);
+            await save();
+            log(`${id}: transfer ${delivery.transfer_id} sent`);
+        }
+        if (!this.reportDue(id))
+            return true;
+        // Executed or pending on Aster: reported until the server takes it or never will.
+        const outcome = await this.report(quoter, id, delivery.transfer_id, log);
+        if (outcome) {
+            delivery.outcome = outcome;
+            await save();
+        }
+        return true;
+    }
+}

package/dist/book.d.ts

@@ -0,0 +1,39 @@
+type Level = {
+    order_id: string;
+    supply: string;
+    receive: string;
+    available: string;
+    min_fill: string;
+    valid_until: string;
+};
+/** The most fills one take reserves. */
+export declare const MAX_PARTS = 8;
+/** `out` received on the destination, `pay` paid on the source. */
+export interface Sweep {
+    out: bigint;
+    pay: bigint;
+    parts: number;
+}
+/**
+ * As the server matches: best price first, at most `maxParts`; each part takes the least of what
+ * is left, `available` and `maxFill`, is skipped below `min_fill` and pays rounded up. Nothing
+ * executes when the parts together stay below `floor`, the receiving venue's minimum deposit.
+ */
+export declare function sweep(levels: Level[], maxFill: bigint, own: Set<string>, amount: bigint, maxParts?: number, floor?: bigint): Sweep;
+/** Smallest payment the book executes, in payment units: each part meets its maker's minimum and
+ * the parts together `floor`. A larger payment never receives less, so a bisection finds it. */
+export declare function minimumTake(levels: Level[], maxFill: bigint, own: Set<string>, floor?: bigint): bigint | null;
+/** The book cannot take this request now: nothing was reserved or signed. */
+export declare class QuoteUnavailable extends Error {
+    readonly name = "QuoteUnavailable";
+}
+/** That the book pays all of `amount_in` for at least `min_out`, the caller's own orders aside; `floor` is the receiving venue's minimum deposit. */
+export declare function checkQuote(book: {
+    max_fill: string;
+    levels: Level[];
+}, own: Set<string>, input: {
+    amount_in: string;
+    min_out: string;
+    max_parts?: number | undefined;
+}, floor?: bigint): void;
+export {};

package/dist/book.js

@@ -0,0 +1,64 @@
+/** The most fills one take reserves. */
+export const MAX_PARTS = 8;
+const divCeil = (n, d) => (n + d - 1n) / d;
+const live = (levels) => levels.filter(level => Date.parse(level.valid_until) > Date.now());
+/**
+ * As the server matches: best price first, at most `maxParts`; each part takes the least of what
+ * is left, `available` and `maxFill`, is skipped below `min_fill` and pays rounded up. Nothing
+ * executes when the parts together stay below `floor`, the receiving venue's minimum deposit.
+ */
+export function sweep(levels, maxFill, own, amount, maxParts = MAX_PARTS, floor = 0n) {
+    let left = amount;
+    let out = 0n;
+    let parts = 0;
+    for (const level of live(levels)) {
+        if (parts === maxParts || left === 0n)
+            break;
+        if (own.has(level.order_id))
+            continue;
+        const supply = BigInt(level.supply);
+        const receive = BigInt(level.receive);
+        const got = [(left * supply) / receive, BigInt(level.available), maxFill].reduce((a, b) => (a < b ? a : b));
+        if (got === 0n || got < BigInt(level.min_fill))
+            continue;
+        out += got;
+        left -= divCeil(got * receive, supply);
+        parts += 1;
+    }
+    return out < floor ? { out: 0n, pay: 0n, parts: 0 } : { out, pay: amount - left, parts };
+}
+/** Smallest payment the book executes, in payment units: each part meets its maker's minimum and
+ * the parts together `floor`. A larger payment never receives less, so a bisection finds it. */
+export function minimumTake(levels, maxFill, own, floor = 0n) {
+    let high = 0n;
+    for (const level of live(levels)) {
+        if (own.has(level.order_id))
+            continue;
+        const most = BigInt(level.available) < maxFill ? BigInt(level.available) : maxFill;
+        high += divCeil(most * BigInt(level.receive), BigInt(level.supply));
+    }
+    if (!sweep(levels, maxFill, own, high, MAX_PARTS, floor).parts)
+        return null;
+    let low = 0n;
+    while (high - low > 1n) {
+        const middle = (low + high) / 2n;
+        if (sweep(levels, maxFill, own, middle, MAX_PARTS, floor).parts)
+            high = middle;
+        else
+            low = middle;
+    }
+    return high;
+}
+/** The book cannot take this request now: nothing was reserved or signed. */
+export class QuoteUnavailable extends Error {
+    name = "QuoteUnavailable";
+}
+/** That the book pays all of `amount_in` for at least `min_out`, the caller's own orders aside; `floor` is the receiving venue's minimum deposit. */
+export function checkQuote(book, own, input, floor = 0n) {
+    const amount = BigInt(input.amount_in);
+    const next = sweep(book.levels, BigInt(book.max_fill), own, amount, input.max_parts, floor);
+    if (!next.parts)
+        throw new QuoteUnavailable("No executable price available");
+    if (next.pay !== amount || next.out < BigInt(input.min_out))
+        throw new QuoteUnavailable("No price meets this transfer's minimum");
+}