@lamarge/sdk 0.0.0-stage → 0.1.1

package/dist/signer.js

@@ -0,0 +1,28 @@
+import { requireSigningDomains, ESCROW_DEPLOYMENTS } from "./protocol/deployments.js";
+import { convert, insist, same } from "./protocol/protocol.js";
+import { address, record } from "./protocol/validation.js";
+/** `typed` as the API sends it, in the form wallets sign: the domain's type implied, values converted. */
+export function typedDataRequest(typed) {
+    const { EIP712Domain: _, ...types } = typed.types;
+    return {
+        domain: { ...typed.domain, verifyingContract: address(typed.domain.verifyingContract) },
+        types,
+        primaryType: typed.primaryType,
+        message: record(convert(types, typed.primaryType, typed.message)),
+    };
+}
+export async function signTyped(signer, typed) {
+    insist(signer.signTypedData, "This signer cannot sign typed data");
+    return signer.signTypedData(typedDataRequest(typed));
+}
+export const signedItem = (item, signature) => ({ kind: item.kind, ...(item.fill_id === undefined ? {} : { fill_id: item.fill_id }), signature });
+/** A checked bundle, signed item by item once every domain is a pinned deployment. */
+export async function signItems(signer, items, manifest = ESCROW_DEPLOYMENTS) {
+    requireSigningDomains(items, manifest);
+    insist(items.every(item => same(item.signer, signer.address)), "This key cannot sign for a different linked account");
+    insist(signer.signTypedData, "Prepare unsigned and submit the collected contract signature");
+    const signed = [];
+    for (const item of items)
+        signed.push(signedItem(item, await signTyped(signer, item.typed_data)));
+    return signed;
+}

package/dist/store.d.ts

@@ -0,0 +1,21 @@
+import type { Typed } from "./protocol/protocol.ts";
+import type { SignedItem } from "./signer.ts";
+/**
+ * Where a flow keeps what it signed until the server has it: a restart then submits the same bytes
+ * instead of signing again. Persist it (a file, a database) wherever a process can stop mid-flow.
+ * One process writes a store: calls in that process are serialized per operation, another
+ * process sharing it would sign apart.
+ */
+export interface SignatureStore {
+    load(key: string): unknown | Promise<unknown>;
+    save(key: string, value: unknown): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+/** A stored bundle of signed items, read back as such or refused. */
+export declare function signedItems(value: unknown): SignedItem[] | undefined;
+/** Typed data read back from a store, in the shape the checks take; the checks still decide whether it may be submitted. */
+export declare function typedData(value: unknown): Typed;
+/** Lost with the process: enough for one run, not for recovery after a restart. */
+export declare function memoryStore(): SignatureStore;
+/** Runs `run` alone among this process's calls on `store` for `key`: a second call waits, then reads what the first stored. */
+export declare function exclusive<T>(store: SignatureStore, key: string, run: () => Promise<T>): Promise<T>;

package/dist/store.js

@@ -0,0 +1,46 @@
+import { array, hex, record } from "./protocol/validation.js";
+/** A stored bundle of signed items, read back as such or refused. */
+export function signedItems(value) {
+    if (value === undefined)
+        return undefined;
+    return array(value).map(entry => {
+        const item = record(entry);
+        return { kind: String(item.kind), ...(typeof item.fill_id === "string" ? { fill_id: item.fill_id } : {}), signature: hex(item.signature) };
+    });
+}
+/** Typed data read back from a store, in the shape the checks take; the checks still decide whether it may be submitted. */
+export function typedData(value) {
+    const typed = record(value);
+    const domain = record(typed.domain);
+    if (typeof typed.primaryType !== "string" || typeof domain.name !== "string" || typeof domain.chainId !== "number" || typeof domain.verifyingContract !== "string")
+        throw new Error("Unreadable typed data");
+    const types = Object.fromEntries(Object.entries(record(typed.types)).map(([name, fields]) => [name, array(fields).map(field => {
+            const { name: key, type } = record(field);
+            if (typeof key !== "string" || typeof type !== "string")
+                throw new Error("Unreadable typed data");
+            return { name: key, type };
+        })]));
+    return { types, primaryType: typed.primaryType, message: record(typed.message),
+        domain: { name: domain.name, chainId: domain.chainId, verifyingContract: domain.verifyingContract, ...(typeof domain.version === "string" ? { version: domain.version } : {}) } };
+}
+/** Lost with the process: enough for one run, not for recovery after a restart. */
+export function memoryStore() {
+    const values = new Map();
+    return { load: key => values.get(key), save: (key, value) => { values.set(key, value); }, delete: key => { values.delete(key); } };
+}
+const running = new WeakMap();
+/** Runs `run` alone among this process's calls on `store` for `key`: a second call waits, then reads what the first stored. */
+export async function exclusive(store, key, run) {
+    const queue = running.get(store) ?? new Map();
+    running.set(store, queue);
+    const previous = queue.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(run);
+    queue.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (queue.get(key) === current)
+            queue.delete(key);
+    }
+}

package/dist/take.d.ts

@@ -0,0 +1,27 @@
+import { type Answer, type Client } from "./client.ts";
+import type { components } from "./generated/api.ts";
+import { type Signer } from "./signer.ts";
+import { type SignatureStore } from "./store.ts";
+export type Fill = Answer<"getFills">[number];
+export type TakeInput = components["schemas"]["TakeInput"];
+export type Balance = Answer<"getBalances">[number];
+type Prepared = Answer<"postTake">;
+export interface TakeOptions {
+    store?: SignatureStore | undefined;
+    signal?: AbortSignal | undefined;
+    /** A fresh read of the taker's balances, when the caller already has one. */
+    balances?: Balance[] | undefined;
+    /** A take reserved earlier, to sign and submit. */
+    prepared?: Prepared | undefined;
+    /** The account that must receive on `input.to`; the linked one otherwise. */
+    recipient?: string | undefined;
+    /** Runs before a new payment signature, never before submitting a stored one: a check that refuses stops the take. */
+    beforeSigning?: (() => Promise<void>) | undefined;
+}
+/**
+ * Reserves `input`'s quotes, checks what the payment would sign against the request and the
+ * linked accounts, signs and submits it. The signature is stored before its first submission, so
+ * a restart submits it again rather than signing another. `signer` is the account paying on `input.from`.
+ */
+export declare function take(client: Client, signer: Signer, input: TakeInput, options?: TakeOptions): Promise<Fill[]>;
+export {};

package/dist/take.js

@@ -0,0 +1,81 @@
+import { LaMargeError } from "./client.js";
+import { checkAsterTakeIntent, checkLighterTakeIntent, checkTakeIntent, takePaymentKind } from "./protocol/intents.js";
+import { COLLATERAL_ROUTE, fromHex, lighterAccountOwner, TAKER_API_KEY, transferMessage, USDC_ASSET } from "./protocol/lighter.js";
+import { ASTER_TRANSFER_CHAIN_ID, checkAsterRequest, insist, same } from "./protocol/protocol.js";
+import { required } from "./protocol/validation.js";
+import { MAX_PARTS } from "./book.js";
+import { signedItem, signItems, signTyped } from "./signer.js";
+import { memoryStore, signedItems } from "./store.js";
+// Kinds are open strings, so the union narrows through these guards.
+const isLighter = (item) => item.kind === "lighter_transfer";
+const isAster = (item) => item.kind === "aster_transfer";
+/** Each venue pays its own way: the escrow payment, or the one transfer LaMarge sends inside Aster or Lighter once the maker is locked. */
+async function signPayment(prepared, input, signer, payer, recipient, signal) {
+    const { take, to_sign } = prepared;
+    insist(to_sign.every(entry => entry.kind === takePaymentKind(input.from)), "The signing request differs from the take's venue");
+    const item = required(to_sign[0]);
+    if (isLighter(item)) {
+        checkLighterTakeIntent(to_sign, take.fills, input, payer.address, recipient, Number(payer.venue_wallet));
+        const terms = item.typed_data;
+        insist(same(await lighterAccountOwner(terms.to_account_index, signal), required(take.fills[0]).maker_recipient), "The Lighter transfer pays another account than the maker's");
+        const message = transferMessage({
+            from: terms.from_account_index, apiKey: TAKER_API_KEY, to: terms.to_account_index, asset: USDC_ASSET, fromRoute: COLLATERAL_ROUTE, toRoute: COLLATERAL_ROUTE,
+            amount: BigInt(terms.amount), fee: BigInt(terms.usdc_fee), memo: fromHex(terms.memo), expiredAt: 0, nonce: terms.nonce,
+        });
+        return [signedItem(item, await signer.signMessage({ message }))];
+    }
+    if (isAster(item)) {
+        checkAsterTakeIntent(to_sign, take.fills, input, payer.address, recipient);
+        checkAsterRequest(item.typed_data, ASTER_TRANSFER_CHAIN_ID);
+        return [signedItem(item, await signTyped(signer, item.typed_data))];
+    }
+    const typed = to_sign.filter((entry) => !isLighter(entry) && !isAster(entry));
+    checkTakeIntent(typed, take.fills, input, payer.address, recipient);
+    return signItems(signer, typed);
+}
+/**
+ * Reserves `input`'s quotes, checks what the payment would sign against the request and the
+ * linked accounts, signs and submits it. The signature is stored before its first submission, so
+ * a restart submits it again rather than signing another. `signer` is the account paying on `input.from`.
+ */
+export async function take(client, signer, input, options = {}) {
+    const { store = memoryStore(), signal } = options;
+    input = { ...input, max_parts: input.max_parts ?? MAX_PARTS };
+    const balances = options.balances ?? await client.call("getBalances", { signal });
+    const payer = balances.find(balance => balance.venue === input.from);
+    const recipient = balances.find(balance => balance.venue === input.to)?.address;
+    insist(payer && recipient, "Link both venues first");
+    insist(options.recipient === undefined || same(recipient, options.recipient), "Linked account changed; review the transfer again");
+    insist(same(payer.address, signer.address), "The signer is not the account paying on this venue");
+    const prepared = options.prepared ?? await client.call("postTake", { body: input, signal });
+    const { take: reserved, to_sign } = prepared;
+    if (!to_sign.length || input.transfer_intent_id && reserved.fills.some(fill => fill.state !== "RESERVED"))
+        return reserved.fills;
+    const key = `take:${reserved.id}`;
+    let signatures = signedItems(await store.load(key));
+    if (!signatures) {
+        try {
+            await options.beforeSigning?.();
+            signatures = await signPayment(prepared, input, signer, payer, recipient, signal);
+            signal?.throwIfAborted();
+            await store.save(key, signatures);
+        }
+        catch (error) {
+            // A transfer's own recovery decides what happens to its reservation.
+            if (!input.transfer_intent_id)
+                await client.call("deleteTake", { path: { id: reserved.id } }).catch(() => null);
+            throw error;
+        }
+    }
+    try {
+        const { fills } = await client.call("postTakeSignatures", { path: { id: reserved.id }, body: { signatures }, signal, retry: true });
+        await store.delete(key);
+        return fills;
+    }
+    catch (error) {
+        // Expired: none of its signatures was accepted, so they can never be used.
+        if (error instanceof LaMargeError && error.code === "TAKE_EXPIRED")
+            await store.delete(key);
+        throw error;
+    }
+}

package/dist/transfer.d.ts

@@ -0,0 +1,63 @@
+import { type Answer, type Client } from "./client.ts";
+import type { Signer } from "./signer.ts";
+import { type SignatureStore } from "./store.ts";
+import { type Fill } from "./take.ts";
+export type TransferIntent = Answer<"getTransfer">;
+/**
+ * Where a transfer from an escrow venue pays from. `venue`: what the escrow chain does not hold
+ * is withdrawn from the venue account first. `wallet`: only the address and its available balance
+ * pay; a shortfall stops the transfer before anything is signed, and nothing is withdrawn.
+ */
+export type Funding = "venue" | "wallet";
+export interface TransferRequest {
+    /** Persist it before the first call: the same id finds the same transfer again after a restart. */
+    client_transfer_id: string;
+    from: string;
+    to: string;
+    amount_in: string;
+    min_out: string;
+    max_parts?: number | undefined;
+    /** The linked account receiving on `to`; the payer is the signer. */
+    recipient: string;
+    funding: Funding;
+    /** The transfer to resume, as `onIntent` last named it. */
+    transfer_id?: string | undefined;
+}
+export type TransferStage = "checking" | "funding" | "waiting" | "authorizing" | "taking";
+export interface TransferOptions {
+    store?: SignatureStore | undefined;
+    signal?: AbortSignal | undefined;
+    onStage?: ((stage: TransferStage) => void) | undefined;
+    /** Called with each transfer this one becomes: a stale one is replaced, never repeated. Persist its id; the flow waits for a returned promise. */
+    onIntent?: ((intent: TransferIntent) => void | Promise<void>) | undefined;
+    /** Between reads while funds or a permit arrive. */
+    pollMs?: number | undefined;
+    /** How long to wait for funds or a permit before `TransferPending`. */
+    arrivalWaitMs?: number | undefined;
+    now?: (() => number) | undefined;
+}
+/** Nothing failed, but the transfer cannot go on yet; run it again with the same request later. */
+export declare class TransferPending extends Error {
+    readonly intent: TransferIntent;
+    readonly reason: "arrival_unconfirmed" | "authorization_unconfirmed" | "unknown" | "refused";
+    readonly name = "TransferPending";
+    constructor(intent: TransferIntent, reason: "arrival_unconfirmed" | "authorization_unconfirmed" | "unknown" | "refused");
+}
+/** A reservation nothing was signed or paid for: replacing it repeats nothing. */
+export declare const unsignedReservation: (fill: {
+    state: string;
+    payment_leg: string;
+    maker_leg: string;
+    transactions: readonly unknown[];
+    delivery_hash: string | null;
+    signed_at?: string | null | undefined;
+    payment_locked_at?: string | null | undefined;
+    maker_claimed_at?: string | null | undefined;
+}) => boolean;
+/**
+ * Moves `amount_in` from the signer's account on `from` to `recipient` on `to`, for at least
+ * `min_out`: funding first (per `funding`), then the take, signed and submitted. Durable
+ * operations are resolved before anything new: running the same request again resumes it, and a
+ * withdrawal is never repeated because a balance looks short.
+ */
+export declare function transfer(client: Client, signer: Signer, request: TransferRequest, options?: TransferOptions): Promise<Fill[]>;

package/dist/transfer.js

@@ -0,0 +1,253 @@
+import { LaMargeError, wait } from "./client.js";
+import { permitDone, submitPermit } from "./account.js";
+import { prefunded, sweepable } from "./funds.js";
+import { checkFundingPlan } from "./protocol/consents.js";
+import { insist, same, shortfall, VENUE_SETTLED } from "./protocol/protocol.js";
+import { required } from "./protocol/validation.js";
+import { exclusive, memoryStore } from "./store.js";
+import { submitWithdrawal } from "./withdraw.js";
+import { checkQuote, MAX_PARTS } from "./book.js";
+import { take } from "./take.js";
+/** Nothing failed, but the transfer cannot go on yet; run it again with the same request later. */
+export class TransferPending extends Error {
+    intent;
+    reason;
+    name = "TransferPending";
+    constructor(intent, reason) {
+        super(reason === "refused" ? intent.withdrawal?.error ?? "Funding refused" : reason === "unknown" ? "Funding outcome unknown"
+            : reason === "authorization_unconfirmed" ? "Authorization not confirmed yet" : "Funds not received yet");
+        this.intent = intent;
+        this.reason = reason;
+    }
+}
+/** The book, the caller's own orders aside, pays all of the take for at least its minimum. */
+async function reviewQuote(client, input, signal) {
+    const [book, orders, venues] = await Promise.all([
+        client.call("getBook", { query: { from: input.from, to: input.to }, signal }), client.call("getOrders", { signal }), client.call("getVenues", { signal })
+    ]);
+    checkQuote(book, new Set(orders.map(order => order.id)), input, BigInt(venues.find(venue => venue.id === input.to)?.release_minimum ?? 0));
+}
+/** A reservation nothing was signed or paid for: replacing it repeats nothing. */
+export const unsignedReservation = (fill) => (fill.state === "RESERVED" || fill.state === "EXPIRED") && fill.signed_at === null
+    && fill.payment_leg === "NONE" && (fill.maker_leg === "NONE" || fill.maker_leg === "ABANDONED")
+    && fill.transactions.length === 0 && !fill.delivery_hash && !fill.payment_locked_at && !fill.maker_claimed_at;
+function replacement(intent, clientId) {
+    const { from, to, amount_in, min_out, max_parts, payer, recipient, then, previous_transfer_id: previous } = intent;
+    return { client_transfer_id: clientId, from, to, amount_in, min_out, max_parts, payer, recipient, ...(then ? { then } : {}), ...(previous ? { previous_transfer_id: previous } : {}) };
+}
+/** The transfer's withdrawal from the venue account, to the signer, for exactly `amount`. Once the server records it, the transfer names it: the stored signature can go. */
+async function withdrawFor(client, signer, intent, amount, store, signal) {
+    const key = `transfer-withdrawal:${intent.id}`;
+    return exclusive(store, key, async () => {
+        try {
+            const { result } = await submitWithdrawal({
+                key, venue: intent.from, signer, destination: signer.address, amount, store, signal,
+                prepare: async () => intent.withdrawal_preparation?.typed_data
+                    ?? (await client.call("prepareTransferWithdrawal", { path: { id: intent.id }, body: { amount: amount.toString() }, signal })).typed_data,
+                submit: (_typed, signature) => client.call("submitTransferWithdrawal", { path: { id: intent.id }, body: { signature }, signal, retry: true }),
+            });
+            if (result.state !== "unknown")
+                await store.delete(key);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof LaMargeError && error.code === "VENUE_REJECTED")
+                await store.delete(key);
+            throw error;
+        }
+    });
+}
+/**
+ * Moves `amount_in` from the signer's account on `from` to `recipient` on `to`, for at least
+ * `min_out`: funding first (per `funding`), then the take, signed and submitted. Durable
+ * operations are resolved before anything new: running the same request again resumes it, and a
+ * withdrawal is never repeated because a balance looks short.
+ */
+export async function transfer(client, signer, request, options = {}) {
+    const { store = memoryStore(), signal, onStage, onIntent, pollMs = 2_000, arrivalWaitMs = 10 * 60_000, now = Date.now } = options;
+    const payer = signer.address;
+    const maxParts = request.max_parts ?? MAX_PARTS;
+    const stage = (value) => { signal?.throwIfAborted(); onStage?.(value); };
+    // A venue settled inside itself pays from its account: there is no wallet to pay from.
+    insist(request.funding === "venue" || !VENUE_SETTLED.has(request.from), `Wallet funding does not apply to ${request.from}, whose account pays`);
+    stage("checking");
+    let intent = request.transfer_id
+        ? await client.call("getTransfer", { path: { id: request.transfer_id }, query: { funding_plan: true }, signal })
+        : await client.call("postTransfer", { body: { client_transfer_id: request.client_transfer_id, from: request.from, to: request.to, amount_in: request.amount_in,
+                min_out: request.min_out, max_parts: maxParts, payer, recipient: request.recipient }, signal, retry: true });
+    // A replacement decided before a lost cancellation answer is completed, never decided again.
+    const renewal = (id) => `renewal:${id}`;
+    let renewedFrom;
+    if (intent.cancelled_at && await store.load(renewal(intent.id)) !== undefined) {
+        renewedFrom = intent.id;
+        intent = await client.call("postTransfer", { body: replacement(intent, `renew:${renewedFrom}`), signal, retry: true });
+    }
+    const checkIntent = () => {
+        insist(!intent.cancelled_at, "Transfer cancelled");
+        insist(intent.max_parts === maxParts && intent.from === request.from && intent.to === request.to && intent.amount_in === request.amount_in
+            && intent.min_out === request.min_out && same(intent.payer, payer) && same(intent.recipient, request.recipient), "Transfer terms changed; review the original transfer");
+    };
+    checkIntent();
+    if (!intent.withdrawal && !intent.take_id && intent.withdrawal_preparation && now() - Date.parse(intent.withdrawal_preparation.created_at) > 45_000) {
+        // Cancellation serializes with acceptance; an uncertain withdrawal is never replaced.
+        renewedFrom = intent.id;
+        await store.save(renewal(renewedFrom), true);
+        try {
+            await client.call("cancelTransfer", { path: { id: intent.id }, signal });
+        }
+        catch (error) {
+            // An answered refusal means nothing was cancelled: no replacement is owed. Only a lost answer keeps the marker.
+            if (error instanceof LaMargeError)
+                await store.delete(renewal(renewedFrom));
+            throw error;
+        }
+        intent = await client.call("postTransfer", { body: replacement(intent, `renew:${intent.id}`), signal, retry: true });
+        checkIntent();
+    }
+    await onIntent?.(intent);
+    if (renewedFrom)
+        await store.delete(renewal(renewedFrom));
+    // A replacement of a take that expired unsigned after its funding: never funded again.
+    const funded = (id) => `funded:${id}`;
+    const alreadyFunded = await store.load(funded(intent.id)) !== undefined;
+    const amount = BigInt(intent.amount_in);
+    const readFunds = async () => {
+        const balances = await client.call("getBalances", { signal });
+        const from = balances.find(balance => balance.venue === intent.from);
+        const to = balances.find(balance => balance.venue === intent.to);
+        insist(same(from?.address, payer) && same(to?.address, request.recipient), "Linked account changed; review the transfer again");
+        // Ready pays the take; supplied adds what the deposit address holds until it is swept.
+        const ready = prefunded(from, now());
+        return ready === null ? null : { ready, supplied: ready + sweepable(from), balances };
+    };
+    const covers = (funds) => insist(funds !== null && funds.supplied >= amount, "Wallet funds do not cover the transfer");
+    // Every new payment signature from wallet funds is preceded by a fresh read that covers it.
+    const beforeSigning = request.funding === "wallet" ? async () => covers(await readFunds()) : undefined;
+    const takeInput = () => ({ from: intent.from, to: intent.to, amount_in: intent.amount_in, min_out: intent.min_out, max_parts: intent.max_parts,
+        client_take_id: intent.client_take_id, transfer_intent_id: intent.id });
+    const pay = (balances) => take(client, signer, takeInput(), { store, signal, balances, recipient: request.recipient, beforeSigning });
+    // A take reserved again is priced again first, as the app does: a book that no longer pays its minimum reserves nothing.
+    const repriced = async (balances) => {
+        const [, read] = await Promise.all([reviewQuote(client, takeInput(), signal), balances ?? client.call("getBalances", { signal })]);
+        return pay(read);
+    };
+    /** The take already reserved, signed or paid, settled first; a replaced one is priced and taken again. Null when there is none. */
+    const recoverTake = async () => {
+        let renewed = false;
+        while (intent.take_id) {
+            stage("taking");
+            let prepared = await client.call("getV1TakesId", { path: { id: intent.take_id }, signal });
+            const unsigned = () => prepared.take.fills.length > 0 && prepared.take.fills.every(unsignedReservation);
+            if (unsigned() && prepared.take.fills.some(fill => fill.state === "RESERVED" && Date.parse(fill.pay_by) <= now())) {
+                // Cancellation serializes with acceptance. A late or uncertain signature is never replaced.
+                await client.call("deleteTake", { path: { id: intent.take_id }, signal });
+                prepared = await client.call("getV1TakesId", { path: { id: intent.take_id }, signal });
+            }
+            if (!unsigned() || !prepared.take.fills.every(fill => fill.state === "EXPIRED")) {
+                if (!prepared.to_sign.length || prepared.take.fills.some(fill => fill.state !== "RESERVED"))
+                    return prepared.take.fills;
+                return take(client, signer, takeInput(), { store, signal, prepared, recipient: request.recipient, beforeSigning });
+            }
+            // A deterministic replacement survives a lost response or a restart, with the same terms.
+            intent = await client.call("postTransfer", { body: replacement(intent, `retry:${intent.id}`), signal, retry: true });
+            checkIntent();
+            await store.save(funded(intent.id), true);
+            await onIntent?.(intent);
+            renewed = true;
+        }
+        // The original take was already funded: repricing never triggers another withdrawal.
+        return renewed ? repriced() : null;
+    };
+    const recovered = await recoverTake();
+    if (recovered)
+        return recovered;
+    if (alreadyFunded)
+        return repriced();
+    // Paid inside the venue: nothing to fund, the take's transfer comes from the venue account.
+    if (VENUE_SETTLED.has(intent.from)) {
+        stage("taking");
+        return pay();
+    }
+    const checkWithdrawalState = () => {
+        if (intent.withdrawal?.state === "refused")
+            throw new TransferPending(intent, "refused");
+        if (intent.withdrawal?.state === "unknown")
+            throw new TransferPending(intent, "unknown");
+    };
+    // A wallet deposit without payment setup signs its permit first; the take waits until it is final.
+    let authorizing = false;
+    const fund = async () => {
+        const plan = checkFundingPlan(intent, now());
+        insist(request.funding === "venue" || BigInt(plan.withdrawal_amount) === 0n, "Wallet funds do not cover the transfer");
+        authorizing = ["required", "pending"].includes(plan.payment_setup);
+        if (plan.requests.some(item => item.kind === "permit")) {
+            stage("funding");
+            await submitPermit(client, intent.from, signer, signal);
+        }
+    };
+    checkWithdrawalState();
+    let funds = await readFunds();
+    // Wallet funds are read before the permit too: a transfer they cannot pay signs nothing.
+    if (request.funding === "wallet" && !intent.withdrawal)
+        covers(funds);
+    let planned = false;
+    if (!intent.withdrawal) {
+        await fund();
+        planned = true;
+    }
+    if (!intent.withdrawal && (intent.withdrawal_preparation || funds !== null && funds.supplied < amount)) {
+        insist(request.funding === "venue", "Wallet funds do not cover the transfer");
+        // Margin leaves the venue only for a take the book can execute now.
+        if (!intent.withdrawal_preparation)
+            await reviewQuote(client, takeInput(), signal);
+        stage("funding");
+        const preparation = intent.withdrawal_preparation;
+        const withdrawal = preparation ? BigInt(preparation.amount) : shortfall(amount, required(funds, "A fresh balance is required").supplied, intent.from);
+        if (intent.funding_plan)
+            insist(withdrawal === BigInt(intent.funding_plan.withdrawal_amount), "Funding amount changed; review the transfer again");
+        intent.withdrawal = await withdrawFor(client, signer, intent, withdrawal, store, signal);
+        checkWithdrawalState();
+        // Until it is relayed the wait below reads the balance anyway.
+        if (intent.withdrawal.state === "relayed")
+            funds = await readFunds();
+    }
+    insist(intent.withdrawal || funds !== null, "A fresh balance is required; try again shortly");
+    const waitingForFunds = () => funds === null || funds.ready < amount || (intent.withdrawal != null && intent.withdrawal.state !== "relayed");
+    const deadline = now() + arrivalWaitMs;
+    let reread = false;
+    if (waitingForFunds())
+        stage("waiting");
+    while (waitingForFunds()) {
+        if (now() >= deadline)
+            throw new TransferPending(intent, "arrival_unconfirmed");
+        await wait(pollMs, signal);
+        [intent, funds] = await Promise.all([client.call("getTransfer", { path: { id: intent.id }, signal }), readFunds()]);
+        checkIntent();
+        const accepted = await recoverTake();
+        if (accepted)
+            return accepted;
+        checkWithdrawalState();
+        reread = true;
+    }
+    stage("taking");
+    // The wait's last read stands unless the funding plan is still to be read.
+    if (!reread || !planned) {
+        intent = await client.call("getTransfer", { path: { id: intent.id }, query: { funding_plan: !planned }, signal });
+        checkIntent();
+        const accepted = await recoverTake();
+        if (accepted)
+            return accepted;
+    }
+    if (!planned && intent.funding_plan)
+        await fund();
+    // The permit gets its own wait, however long the funds took to arrive.
+    const confirmBy = now() + arrivalWaitMs;
+    while (authorizing && !await permitDone(client, intent.from, signer, signal)) {
+        stage("authorizing");
+        if (now() >= confirmBy)
+            throw new TransferPending(intent, "authorization_unconfirmed");
+        await wait(pollMs, signal);
+    }
+    stage("taking");
+    return repriced(required(funds, "A fresh balance is required").balances);
+}

package/dist/withdraw.d.ts

@@ -0,0 +1,67 @@
+import { type Client } from "./client.ts";
+import type { components } from "./generated/api.ts";
+import { type Typed } from "./protocol/protocol.ts";
+import { type Signer } from "./signer.ts";
+import { type SignatureStore } from "./store.ts";
+export type Withdrawal = components["schemas"]["Withdrawal"];
+/**
+ * One withdrawal's signature, stored under `key` (with `context`) before its first submission and
+ * submitted again after a restart; a stored one is checked at its own signing time. The caller
+ * decides when the record may go.
+ */
+export declare function submitWithdrawal(options: {
+    key: string;
+    context?: Record<string, unknown>;
+    venue: string;
+    signer: Signer;
+    destination: string;
+    amount: bigint;
+    store: SignatureStore;
+    signal?: AbortSignal | undefined;
+    prepare: () => Promise<Typed>;
+    submit: (typed: Typed, signature: `0x${string}`) => Promise<Withdrawal>;
+}): Promise<{
+    result: Withdrawal;
+    saved: Record<string, unknown>;
+}>;
+export interface WithdrawalRequest {
+    /** Persist it before the first call and keep it: the same id finds this withdrawal again, never a second one. */
+    id: string;
+    venue: string;
+    amount: bigint;
+    /** `signer`, the linked address; `wallet`, its venue wallet. */
+    to: "wallet" | "signer";
+}
+/**
+ * Withdraws exactly `amount` from the signer's Hyperliquid or Polymarket account. Its signature
+ * and outcome stay in `store` under `id`: running the same request again returns the outcome or
+ * submits the same signature, and a refused one asks for a new id. Aster relays a withdrawal in a
+ * second envelope this flow does not sign yet.
+ */
+export declare function withdraw(client: Client, signer: Signer, request: WithdrawalRequest, options?: {
+    store?: SignatureStore | undefined;
+    signal?: AbortSignal | undefined;
+}): Promise<Withdrawal>;
+/** Reads the pinned escrows, as a viem `PublicClient` per chain id does with `readContract`. */
+export type ChainReaders = Record<number, {
+    readContract(request: {
+        address: `0x${string}`;
+        abi: readonly unknown[];
+        functionName: string;
+        args: readonly unknown[];
+        blockTag?: "finalized" | "latest";
+    }): Promise<unknown>;
+}>;
+/** What a refund reads of the fill: a REST fill fits. */
+export type RefundFill = Pick<components["schemas"]["Fill"], "id" | "role" | "maker_leg" | "payment_leg" | "t2" | "from_venue" | "to_venue" | "maker_recipient" | "maker_owner" | "payer" | "swap_id" | "order_id" | "amount_in" | "hashlock" | "deliver_by" | "delivery_hash">;
+/**
+ * The pinned contracts, read directly: the payment lock at a finalized block, the maker's lock at
+ * the latest, where the destination has one, and the consent digest, which an old ABI cannot
+ * answer. A server's label cannot authorize giving up a payment for capital locked or delivered.
+ */
+export declare function checkEscrowLocks(fill: RefundFill, deadline: number, readers: ChainReaders): Promise<void>;
+/**
+ * As the maker of an abandoned fill, gives the taker's locked payment back before `t2`. Without a
+ * reader of each chain the fill touches, nothing is signed.
+ */
+export declare function refundPayment(client: Client, signer: Signer, fill: RefundFill, readers: ChainReaders, signal?: AbortSignal): Promise<void>;