@totalis/hip4-client 0.0.0-stage → 0.65.2

package/dist/totalis.js

@@ -0,0 +1,1160 @@
+import { keccak_256 } from "@noble/hashes/sha3";
+import { createApiKeyClient, issueApiKey, rotateApiKey } from "./api-keys.js";
+import { audienceClient, headerRecord } from "./base.js";
+import { bridgeAction, bridgeGasBuffer, hyperliquidExchange, hyperliquidNetwork, settleHypercore, signSendAsset, usdcUnits, } from "./hypercore.js";
+import { BalanceUnknownError, EntryError, ExitUnavailableError, normalizeError } from "./flow-errors.js";
+import { spendableCash } from "./money.js";
+import { ApiError, backoffDelay, envelope, NetworkError, randomBytes32, resendable, sendOnce, singleFetch, sleep, unwrap, uuidv7 } from "./request.js";
+import { toTotalisSigner } from "./signer.js";
+import { StreamClosedError, TotalisStream } from "./stream.js";
+import { address, cashoutTransferTypedData, exitTypedData, receiveWithAuthorizationTypedData, sellBackTypedData, takerAcceptTypedData, payoutNonce, transferWithAuthorizationTypedData, } from "./typed-data.js";
+/**
+ * What an entry's bridge may have moved to its wallet, by its state: nothing
+ * before it is sent, once discarded or refused. Only `LANDED` proves it
+ * landed. A legacy record sent its bridge before the accept.
+ */
+function bridgedCash(signed) {
+    if (signed.bridge === undefined)
+        return undefined;
+    const state = "version" in signed ? signed.bridgeState : "SENT";
+    const landed = state === "LANDED" ? "yes" : state === "SENT" || state === "PROCESSED" ? "unknown" : undefined;
+    return landed === undefined ? undefined : { amount: usdcUnits(signed.bridge.action.amount).toString(), landed };
+}
+/**
+ * An entry's `EntryFailure`; undefined unless its operation ended with
+ * `failure_reason` `INSUFFICIENT_CASH`. Pass the record as `onRecord` last
+ * handed it back (or `openPosition`'s `record`): only `LANDED` shows the Core
+ * cash moved before `fund_by`. `PROCESSED` only says the nonce is spent, which
+ * a refused or expired send also does, so it does not show the move.
+ */
+export function entryFailure(record, operation) {
+    if (operation.failure_reason !== "INSUFFICIENT_CASH")
+        return undefined;
+    if (record.bridge === undefined || "version" in record && record.bridgeState === "LANDED")
+        return "INSUFFICIENT_CASH";
+    return "CORE_MOVE_MISSED";
+}
+const answered = { ok: "LANDED", processed: "PROCESSED", refused: "REFUSED" };
+const defaultTransport = hyperliquidExchange();
+/** The acceptance's `fund_by` in ms: until then a WALLET-funded entry may move its Core cash. */
+function fundBy(outcome) {
+    if (outcome.status === "NOT_ADMITTED" || outcome.fund_by === undefined)
+        return undefined;
+    const ms = Date.parse(outcome.fund_by);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+/**
+ * The latest the venue clock can read, from responses' `server_time`. The
+ * venue stamps a response after its request left, so now on the venue is at
+ * most that stamp plus the time since sending. A stamp alone, judged at
+ * receipt, reads early by the response's delay. Elapsed time is the larger of
+ * the monotonic clock's (which may pause while the device sleeps) and the
+ * wall clock's (which may step back). `Infinity` before any response.
+ */
+function venueClock() {
+    const samples = [];
+    return {
+        /** Call as a request leaves; call the result with its response's `server_time`. */
+        sending() {
+            const mono = performance.now();
+            const wall = Date.now();
+            return (serverTime) => {
+                const server = Date.parse(serverTime);
+                if (!Number.isNaN(server))
+                    samples.push({ server, mono, wall });
+            };
+        },
+        latest() {
+            const mono = performance.now();
+            const wall = Date.now();
+            return Math.min(...samples.map((sample) => sample.server + Math.max(mono - sample.mono, wall - sample.wall)));
+        },
+    };
+}
+/** When an entry quote stops being acceptable, in ms on the venue clock: its `accept_before`. A quote without a readable one never is. */
+export function acceptBefore(quote) {
+    const ms = Date.parse(quote.accept_before);
+    return Number.isNaN(ms) ? -Infinity : ms;
+}
+/** How often a pending acceptance with an unsent bridge is read, and how long past the maker's deadline. */
+const watchMs = 250;
+const watchGraceMs = 2000;
+/** The venue refuses a sponsored deposit under 1 USDC. */
+const minimumDeposit = 1000000n;
+/**
+ * Makers answer an RFQ within about a second; collecting that long lets the
+ * best of them win instead of the fastest.
+ */
+const defaultCollectMs = 1_000;
+const timerSlackMs = 250;
+function termsOf(quote) {
+    return quote.kind === "ENTRY" ? quote.entry : quote.kind === "SELL_BACK" ? quote.sell_back : quote.transfer;
+}
+/** The highest payout among quotes still before their `accept_before` (ties go to the earliest). */
+export function bestQuote() {
+    return (quotes, now) => quotes
+        .filter((quote) => acceptBefore(quote) > now)
+        .reduce((best, quote) => best === undefined || BigInt(quote.entry.payout) > BigInt(best.entry.payout) ? quote : best, undefined);
+}
+/** The highest price with at least `minLifeSeconds` left: execution needs 20 s after confirmation. */
+export function bestBid(minLifeSeconds = 25) {
+    return (bids, now) => bids
+        .filter((bid) => Number(termsOf(bid).expiry) * 1000 - now >= minLifeSeconds * 1000)
+        .reduce((best, bid) => best === undefined || BigInt(termsOf(bid).price) > BigInt(termsOf(best).price) ? bid : best, undefined);
+}
+const now = () => Math.floor(Date.now() / 1000);
+/** ABI calldata for a call whose arguments are all static words (addresses and integers). */
+function callData(signature, ...words) {
+    const selector = Array.from(keccak_256(new TextEncoder().encode(signature)).slice(0, 4), (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `0x${selector}${words.map((word) => (typeof word === "bigint" ? word.toString(16) : word.slice(2)).padStart(64, "0")).join("")}`;
+}
+const idempotency = (key = uuidv7()) => ({ "Idempotency-Key": key });
+function withTimeout(signal, ms) {
+    return signal === undefined ? AbortSignal.timeout(ms) : AbortSignal.any([signal, AbortSignal.timeout(ms)]);
+}
+const unavailable = new Set([500, 502, 503, 504]);
+/** A failed recovery read worth retrying: a lost response, a BACKOFF error, or a 500/502/503/504 without the venue's error envelope. */
+const transientRead = (error) => resendable(error) || (error instanceof ApiError && unavailable.has(error.status) && error.code.startsWith("HTTP_"));
+/**
+ * Single-flight recovery reads for a follower. A transient failure is read
+ * again after a backoff, or after its Retry-After capped at `maxDelayMs` if
+ * that is longer, while the stream stays live; any other failure goes to
+ * `fail`. A call while a read is in flight asks for one more read after it. A
+ * call during a backoff, or during a read that then fails, reads at once, but
+ * during a Retry-After wait it reads when the wait ends. `stop` ends it, aborting the read.
+ */
+function recoveryReads(stream, read, onValue, fail, stop, retry = {}) {
+    const { baseDelayMs = 250, maxDelayMs = 10_000, sleep: wait = sleep } = retry;
+    let reading = false;
+    let again = false;
+    let interrupt;
+    const pause = async (ms, wakeable) => {
+        const cut = new AbortController();
+        if (wakeable)
+            interrupt = () => cut.abort();
+        const ended = new Promise((resolve) => {
+            cut.signal.addEventListener("abort", () => resolve(), { once: true });
+            stop.addEventListener("abort", () => resolve(), { once: true, signal: cut.signal });
+        });
+        await Promise.race([wait(ms, AbortSignal.any([stop, cut.signal])).catch(() => undefined), ended]);
+        interrupt = undefined;
+        cut.abort();
+        return !stop.aborted;
+    };
+    return async () => {
+        if (reading) {
+            again = true;
+            interrupt?.();
+            return;
+        }
+        reading = true;
+        let failures = 0;
+        try {
+            while (!stop.aborted && stream.status === "live") {
+                again = false;
+                try {
+                    const value = await read(stop);
+                    if (stop.aborted)
+                        return;
+                    failures = 0;
+                    onValue(value, again);
+                    if (!again)
+                        return;
+                }
+                catch (error) {
+                    if (stop.aborted)
+                        return;
+                    if (!transientRead(error))
+                        return fail(error);
+                    const retryAfterMs = error instanceof ApiError ? error.retryAfterMs : undefined;
+                    const backoff = backoffDelay(failures++, baseDelayMs, maxDelayMs);
+                    if (retryAfterMs === undefined && again)
+                        continue;
+                    const delay = retryAfterMs === undefined ? backoff : Math.max(Math.min(retryAfterMs, maxDelayMs), backoff);
+                    if (!(await pause(delay, retryAfterMs === undefined)))
+                        return;
+                }
+            }
+        }
+        finally {
+            reading = false;
+        }
+    };
+}
+/**
+ * Follow a resource: read it, then read again only when the stream says it
+ * changed (`wake`) or after a reconnect, until `done`. Reads made while the
+ * stream is not live never settle it, so quotes read while disconnected are stale.
+ * A read that fails transiently is retried with `retry`'s backoff, not
+ * rejected; a wake during the backoff reads at once.
+ */
+export function follow(stream, read, done, wake, signal, retry) {
+    return followUntil(stream, read, done, wake, () => undefined, signal, retry);
+}
+function followUntil(stream, read, done, wake, recheckMs, signal, retry) {
+    stream.start();
+    return new Promise((resolve, reject) => {
+        const stop = new AbortController();
+        const offs = [];
+        let recheck;
+        const finish = (settle) => {
+            if (stop.signal.aborted)
+                return;
+            stop.abort();
+            clearTimeout(recheck);
+            for (const off of offs)
+                off();
+            signal?.removeEventListener("abort", abort);
+            settle();
+        };
+        const check = recoveryReads(stream, read, (value, superseded) => {
+            if (superseded || stream.status !== "live")
+                return;
+            if (done(value))
+                return finish(() => resolve(value));
+            const delay = recheckMs(value);
+            clearTimeout(recheck);
+            if (delay !== undefined)
+                recheck = setTimeout(() => void check(), Math.max(delay, 0));
+        }, (error) => finish(() => reject(error)), stop.signal, retry);
+        const abort = () => finish(() => reject(signal?.reason));
+        if (signal?.aborted)
+            return abort();
+        signal?.addEventListener("abort", abort, { once: true });
+        offs.push(stream.on("event", (event) => void (wake(event) && check())), stream.on("status", (status) => {
+            if (status === "live")
+                void check();
+            else if (status === "closed")
+                finish(() => reject(new StreamClosedError("closed", 1000)));
+        }));
+        void check();
+    });
+}
+// An RFQ that ends drops its quotes too, so rendered quotes empty with it.
+const rfqEnded = (event) => event.event_type === "RFQ_CANCELLED" || event.event_type === "RFQ_FAILED" || event.event_type === "RFQ_ACCEPTED";
+const quotesChanged = (rfqId) => (event) => (event.event_type === "QUOTE_CREATED" || event.event_type === "QUOTE_REMOVED" || rfqEnded(event)) && event.payload.rfq_id === rfqId;
+/** The venue refuses to accept a cash-out quote with this much signed life left or less. */
+const cashoutAcceptLifeMs = 22_000;
+/** When the quote stops being acceptable, in ms on the venue clock. */
+const acceptableUntil = (offer) => offer.kind === "ENTRY" ? acceptBefore(offer) : Number(termsOf(offer).expiry) * 1000 - cashoutAcceptLifeMs;
+/**
+ * The account's live quotes, kept from the stream: the snapshot's `quotes`,
+ * then QUOTE_CREATED and QUOTE_REMOVED. The quotes GET is read only for an RFQ
+ * someone follows after a snapshot that truncated `quotes`.
+ */
+function streamQuotes(stream, read) {
+    const books = new Map();
+    const removed = new Set();
+    const recovered = new Set();
+    let truncated = false;
+    const put = (offer) => {
+        if (removed.has(offer.quote_id))
+            return;
+        let book = books.get(offer.rfq_id);
+        if (book === undefined)
+            books.set(offer.rfq_id, (book = new Map()));
+        book.set(offer.quote_id, offer);
+    };
+    const clear = () => {
+        books.clear();
+        removed.clear();
+        recovered.clear();
+    };
+    stream.on("reset", clear);
+    stream.on("snapshot", (snapshot) => {
+        clear();
+        for (const offer of snapshot.resources.quotes ?? [])
+            put(offer);
+        truncated = (snapshot.truncated ?? []).some((truncation) => truncation.resource === "quotes");
+    });
+    stream.on("event", (event) => {
+        if (event.event_type === "QUOTE_CREATED")
+            put(event.payload);
+        else if (event.event_type === "QUOTE_REMOVED") {
+            removed.add(event.payload.quote_id);
+            books.get(event.payload.rfq_id)?.delete(event.payload.quote_id);
+        }
+        else if (rfqEnded(event)) {
+            books.delete(event.payload.rfq_id);
+        }
+    });
+    return {
+        /**
+         * The acceptable quotes on an RFQ, oldest first. Expiry sends no event, so
+         * quotes past their accept life are dropped here. After a truncated
+         * snapshot the RFQ's quotes are read once from the quotes GET.
+         */
+        async offers(rfqId, signal) {
+            if (truncated && !recovered.has(rfqId)) {
+                for (const offer of await read(rfqId, signal))
+                    put(offer);
+                recovered.add(rfqId);
+            }
+            const book = books.get(rfqId);
+            const now = stream.serverNow();
+            for (const [quoteId, offer] of book ?? [])
+                if (acceptableUntil(offer) <= now)
+                    book.delete(quoteId);
+            return [...(book?.values() ?? [])].sort((a, b) => a.sequence - b.sequence);
+        },
+    };
+}
+/**
+ * The taker SDK: the same public client surface the Totalis app and third-party
+ * clients use. Quotes, operations and acceptances are followed on the account
+ * stream; HTTP reads recover after a reconnect or answer a doorbell.
+ */
+export function createTotalis(options) {
+    const { environment, signer: signerInput, stream: streamOptions, streamBaseUrl, accessToken, ...clientOptions } = options;
+    const client = audienceClient(environment, { ...clientOptions, accessToken });
+    const keys = createApiKeyClient(environment, { ...clientOptions, accessToken });
+    const stream = new TotalisStream({
+        environment, accessToken, headers: headerRecord(clientOptions.headers), ...streamOptions,
+        subscription: { ...streamOptions?.subscription, type: "account" },
+        ...(clientOptions.baseUrl === undefined ? {} : { baseUrl: clientOptions.baseUrl }),
+        ...(streamBaseUrl === undefined ? {} : { streamBaseUrl }),
+    });
+    const retry = clientOptions.retry || undefined;
+    const recoveryFetch = singleFetch(clientOptions.fetch);
+    const signer = signerInput === undefined ? undefined : toTotalisSigner(signerInput);
+    const requireSigner = () => signer ?? Promise.reject(new Error("this flow needs a signer"));
+    let deploymentRead;
+    const deployment = () => (deploymentRead ??= client.GET("/v1/deployment").then(unwrap).catch((error) => {
+        deploymentRead = undefined;
+        throw error;
+    }));
+    async function cancelRfq(rfqId) {
+        await client.POST("/v1/rfqs/{rfq_id}/cancel", { params: { path: { rfq_id: rfqId }, header: idempotency() } }).catch(() => undefined);
+    }
+    const book = streamQuotes(stream, async (rfqId, signal) => unwrap(await client.GET("/v1/rfqs/{rfq_id}/quotes", { params: { path: { rfq_id: rfqId } }, ...(signal === undefined ? {} : { signal, fetch: recoveryFetch }) })).quotes);
+    async function createRfq(command) {
+        const header = idempotency();
+        return (await sendOnce(() => client.POST("/v1/rfqs", { params: { header }, body: command }))).rfq_id;
+    }
+    async function createCashout(positionId) {
+        const header = idempotency();
+        return (await sendOnce(() => client.POST("/v1/me/positions/{position_id}/cashout", { params: { path: { position_id: positionId }, header }, body: {} }))).rfq_id;
+    }
+    /** The live quotes rendered for a UI: `[]` while the stream is not live (stale). */
+    function watchQuotes(rfqId, listener) {
+        let stopped = false;
+        let expiry;
+        const refresh = async () => {
+            const offers = stream.status === "live" ? await book.offers(rfqId) : [];
+            if (stopped)
+                return;
+            const now = stream.serverNow();
+            listener(stream.status === "live" ? offers : [], now);
+            // Re-render when the soonest quote stops being acceptable; that sends no event.
+            clearTimeout(expiry);
+            const next = Math.min(...offers.map(acceptableUntil));
+            if (Number.isFinite(next))
+                expiry = setTimeout(() => void refresh().catch(() => undefined), Math.max(0, next - now) + 1);
+        };
+        const offs = [
+            stream.on("event", (event) => void (quotesChanged(rfqId)(event) && refresh().catch(() => undefined))),
+            stream.on("status", () => void refresh().catch(() => undefined)),
+        ];
+        stream.start();
+        void refresh().catch(() => undefined);
+        return () => {
+            stopped = true;
+            clearTimeout(expiry);
+            for (const off of offs)
+                off();
+        };
+    }
+    /**
+     * The quote `choose` picks once quotes have had `collectMs` to arrive after
+     * the first one it would take, re-chosen on every change to the RFQ's quotes
+     * and when the window ends. The window ends sooner when waiting would lose
+     * the quote `choose` picks now (it ages past `choose`'s rules or the venue's
+     * accept floor) or run past `timeoutMs`, so collecting never ends worse.
+     */
+    function awaitOffer(rfqId, eligible, choose, collectMs, timeoutMs, signal) {
+        const giveUpAt = performance.now() + timeoutMs - timerSlackMs;
+        let firstAt;
+        const pick = async (stop) => {
+            const offers = (await book.offers(rfqId, stop)).filter(eligible);
+            const now = stream.serverNow();
+            const offer = choose(offers, now);
+            if (offer === undefined)
+                return { offer, waitMs: undefined };
+            firstAt ??= performance.now();
+            const waitMs = Math.max(Math.min(firstAt + collectMs, giveUpAt) - performance.now(), 0);
+            const later = offers.filter((candidate) => acceptableUntil(candidate) > now + waitMs);
+            return { offer, waitMs: waitMs === 0 || choose(later, now + waitMs)?.quote_id !== offer.quote_id ? 0 : waitMs };
+        };
+        return followUntil(stream, pick, (picked) => picked.offer !== undefined && picked.waitMs === 0, quotesChanged(rfqId), (picked) => picked.waitMs, withTimeout(signal, timeoutMs), retry)
+            .then(({ offer }) => offer);
+    }
+    /** `spendableCash` of a fresh `GET /v1/me/balances`: free vault cash, wallet USDC not reserved by pending work, and the venue's total; `null` where unknown, never 0. */
+    async function readSpendableCash(signal) {
+        return spendableCash(unwrap(await client.GET("/v1/me/balances", signal === undefined ? {} : { signal })));
+    }
+    /** The wallet's USDC authorization of `value` into the vault; the venue fills `account` and `from` with the same wallet. */
+    async function depositAuthorization(chain, account, value) {
+        const authorization = { value: value.toString(), valid_after: String(now() - 60), valid_before: String(now() + 600), salt: randomBytes32() };
+        const authorization_signature = await (await requireSigner()).signTypedData(receiveWithAuthorizationTypedData(chain, { account, from: account, ...authorization }));
+        return { kind: "WALLET", ...authorization, authorization_signature };
+    }
+    /**
+     * Settle an acceptance whose accept response was lost, or a stored record
+     * after a restart: read it, and while the held request is still waiting for
+     * the maker, read once more after its deadline (the read retires an
+     * unanswered acceptance), unless `wait` is false. While `watching` the
+     * deadline, it reads every `watchMs` instead, so an early answer is seen
+     * before its `fund_by` passes. `absent` handles an accept the venue never
+     * received.
+     */
+    async function settleAcceptance(lost, read, absent, wait = true, watching) {
+        for (;;) {
+            // If the recovery read is lost too, surface the original command's error and its resend().
+            const acceptance = await read().catch((error) => Promise.reject(error instanceof NetworkError ? lost ?? error : error));
+            if (acceptance === "absent")
+                return absent();
+            if (!wait || acceptance.status !== "PENDING_CONFIRM" || acceptance.deadline === undefined)
+                return acceptance;
+            const deadline = Date.parse(acceptance.deadline);
+            await sleep(watching?.(deadline) ? watchMs : Math.max(0, deadline - Date.now()) + 1000);
+        }
+    }
+    /** A read whose 404 means the resource does not exist (yet). */
+    const orAbsent = (result) => (result.response.status === 404 ? "absent" : unwrap(result));
+    /**
+     * Read where an accept ended, for either kind of RFQ. An absent acceptance
+     * may still arrive, so cancel the RFQ first, then read once more: absent
+     * now is final. The cancel fences on 204, on `RFQ_NOT_CANCELLABLE` (the RFQ
+     * is no longer open or has expired) and on `NOT_FOUND` (no such RFQ for this
+     * account): the venue admits an accept only on an open, unexpired RFQ of the
+     * taker's. `STATE_CONFLICT` leaves the RFQ open: the acceptance is read
+     * once more, and still absent throws that error rather than `NOT_ADMITTED`.
+     * With `watch`, a pending acceptance is read every `watchMs` until its
+     * deadline plus `watchGraceMs` on the venue clock.
+     */
+    function fenceAcceptance(signed, clock, lost, wait = true, watch = false) {
+        const { rfqId, quoteId } = signed;
+        const watching = watch ? (deadline) => clock.latest() < deadline + watchGraceMs : undefined;
+        const read = async () => {
+            const stamped = clock.sending();
+            const acceptance = orAbsent(await client.GET("/v1/quotes/{quote_id}/acceptance", { params: { path: { quote_id: quoteId } } }));
+            if (acceptance === "absent")
+                return acceptance;
+            checkEcho(signed, acceptance, false);
+            stamped(acceptance.server_time);
+            return acceptance;
+        };
+        return settleAcceptance(lost, read, async () => {
+            const header = idempotency();
+            let open;
+            try {
+                await sendOnce(() => client.POST("/v1/rfqs/{rfq_id}/cancel", { params: { path: { rfq_id: rfqId }, header } }));
+            }
+            catch (error) {
+                if (error instanceof NetworkError)
+                    throw lost ?? error;
+                if (!(error instanceof ApiError) || error.status !== 409 && error.status !== 404)
+                    throw error;
+                if (error.code !== "RFQ_NOT_CANCELLABLE" && error.code !== "NOT_FOUND")
+                    open = error;
+            }
+            // An unfenced RFQ may still show the acceptance; absent there proves nothing.
+            return settleAcceptance(lost, read, async () => {
+                if (open !== undefined)
+                    throw open;
+                return { status: "NOT_ADMITTED", quote_id: quoteId, rfq_id: rfqId };
+            }, wait, watching);
+        }, wait, watching);
+    }
+    /**
+     * An acceptance must answer for this record's RFQ and quote; a direct accept
+     * answer must also echo its acceptance ID. A read answers for the quote
+     * whichever acceptance took it, as a quote has at most one.
+     */
+    function checkEcho(signed, acceptance, direct) {
+        if (acceptance.rfq_id !== signed.rfqId || acceptance.quote_id.toLowerCase() !== signed.quoteId.toLowerCase() || (direct && acceptance.acceptance_id !== signed.acceptanceId)) {
+            throw new Error(`the venue answered for acceptance ${acceptance.acceptance_id} on quote ${acceptance.quote_id}, not this record's`);
+        }
+    }
+    const resultOf = (signed, outcome, bridge) => ({
+        acceptanceId: signed.acceptanceId, rfqId: signed.rfqId, quoteId: signed.quoteId,
+        positionId: signed.kind === "ENTRY" ? signed.quoteId : signed.positionId,
+        status: outcome.status, operationId: outcome.status === "NOT_ADMITTED" ? undefined : outcome.operation_id, outcome,
+        ...(bridge.bridged === undefined ? {} : { bridged: bridge.bridged }),
+        ...(bridge.bridging === undefined ? {} : { bridging: bridge.bridging }),
+    });
+    /** A bridge this SDK signed and never sent, which may go only before `fund_by`. */
+    const bridgeUnsent = (signed) => signed.kind === "ENTRY" && "version" in signed && signed.bridge !== undefined && signed.bridgeState === undefined;
+    /** Record a never-sent bridge as discarded. Recovery derives the discard from the acceptance again, so a failed save loses nothing. */
+    async function discardBridge(signed, onRecord) {
+        if (signed.kind !== "ENTRY" || signed.bridge === undefined || signed.bridgeState !== undefined)
+            return;
+        await saveDiscard(signed, onRecord);
+    }
+    async function saveDiscard(signed, onRecord) {
+        try {
+            await onRecord?.({ ...signed, bridgeState: "DISCARDED" });
+        }
+        catch {
+            return;
+        }
+    }
+    /**
+     * Move an entry's bridge on from where its acceptance stands. Only this
+     * record's own `ACCEPTED` acceptance, while `clock` proves its `fund_by`
+     * is still ahead, sends it: first the record says `SENT`, then the same
+     * bytes go out, resent while unanswered until `fund_by`. A bridge never sent is discarded
+     * once the acceptance is answered any other way, another record's
+     * acceptance took the quote, or `fund_by` passed before the first send; one
+     * sent without an answer stays `SENT`. A legacy record is only read.
+     */
+    async function moveBridge(signed, outcome, clock, options) {
+        if (signed.kind !== "ENTRY" || signed.bridge === undefined)
+            return {};
+        if (!("version" in signed))
+            return { bridged: bridgedCash(signed) };
+        const { bridge, bridgeState } = signed;
+        if (bridgeState !== undefined && bridgeState !== "SENT")
+            return { bridged: bridgedCash(signed) };
+        const ours = outcome.status === "NOT_ADMITTED" || outcome.acceptance_id === signed.acceptanceId;
+        if (!ours && bridgeState === "SENT")
+            return { bridged: bridgedCash(signed) };
+        const until = ours && outcome.status === "ACCEPTED" ? fundBy(outcome) : undefined;
+        if (until === undefined || clock.latest() >= until) {
+            if (ours && outcome.status === "PENDING_CONFIRM")
+                return {};
+            await discardBridge(signed, options.onRecord);
+            return { bridged: bridgedCash(signed) };
+        }
+        const sent = { ...signed, bridgeState: "SENT" };
+        if (bridgeState === undefined) {
+            try {
+                await options.onRecord?.(sent);
+            }
+            catch (error) {
+                const unsent = Promise.reject(error);
+                unsent.catch(() => undefined);
+                return { bridging: unsent };
+            }
+            if (clock.latest() >= until) {
+                await saveDiscard(signed, options.onRecord);
+                return {};
+            }
+        }
+        const transport = options.transport ?? defaultTransport;
+        let attempted = false;
+        const bridging = settleHypercore(bridge, { transport: (action, signal) => { attempted = true; return transport(action, signal); }, deadline: until, now: clock.latest })
+            .then(async (answer) => {
+            if (answer.kind !== "unknown")
+                await options.onRecord?.({ ...sent, bridgeState: answered[answer.kind] });
+            else if (!attempted && bridgeState === undefined)
+                await saveDiscard(signed, options.onRecord);
+            return answer;
+        });
+        bridging.catch(() => undefined);
+        return { bridged: bridgedCash(sent), bridging };
+    }
+    /** The signer, account and deployment a new record is signed under. */
+    async function recordScope() {
+        const signer = await requireSigner();
+        const account = await signer.address();
+        const chain = await deployment();
+        return { signer, account, chain, scope: { account, chainId: chain.chain_id, vault: address(chain.vault_address.toLowerCase()) } };
+    }
+    async function checkScope(signed) {
+        const { scope } = await recordScope();
+        if (scope.account !== signed.account || scope.chainId !== signed.chainId || scope.vault !== signed.vault) {
+            throw new Error("this acceptance was signed by another wallet or on another deployment");
+        }
+    }
+    /**
+     * Plan an entry's funding from venue balances: free vault cash
+     * first, then the wallet, then a bridge from Core for what the wallet lacks.
+     * A wallet without a current read is authorized for the whole shortfall
+     * (the venue checks the exact amount) and never bridges; a vault without
+     * one, or unread Core (`null`) the plan needs, is never taken as a balance.
+     * No `core` plans from the wallet alone, so a wallet known to fall short
+     * throws INSUFFICIENT_FUNDS.
+     */
+    function planEntry(stake, core, cash) {
+        const vault = cash.vault === null ? null : BigInt(cash.vault);
+        const wallet = cash.wallet === null ? null : BigInt(cash.wallet);
+        if (vault === null)
+            throw new EntryError("BALANCE_UNKNOWN", "the free vault balance is unknown; read it again");
+        const shortfall = stake - vault;
+        if (shortfall <= 0n)
+            return { wallet: 0n, bridge: 0n };
+        if (wallet === null || wallet >= shortfall)
+            return { wallet: shortfall, bridge: 0n };
+        const bridge = shortfall - wallet;
+        if (core === undefined)
+            throw new EntryError("INSUFFICIENT_FUNDS", `${bridge} USDC base units short for this stake; pass core to bridge it from HyperCore`);
+        if (core === null)
+            throw new EntryError("BALANCE_UNKNOWN", "the wallet falls short and the Core balance is unknown; read it again");
+        const routable = core - bridgeGasBuffer;
+        if (routable < bridge)
+            throw new EntryError("INSUFFICIENT_FUNDS", `${bridge - (routable > 0n ? routable : 0n)} USDC base units short for this stake`);
+        return { wallet: shortfall, bridge };
+    }
+    async function signEntryWith(request, funding) {
+        const { quote, cash } = request;
+        const { signer, account, chain, scope } = await recordScope();
+        if (quote.entry.taker.toLowerCase() !== account)
+            throw new Error("the quote is for another taker");
+        const stake = BigInt(quote.entry.stake);
+        const core = request.core === undefined || request.core === null ? request.core : BigInt(request.core);
+        // Known cash is planned before any prompt, so a plan that fails asks the wallet for nothing.
+        let plan = funding === "plan" && cash !== undefined ? planEntry(stake, core, cash) : undefined;
+        const signing = signer.signTypedData(takerAcceptTypedData(chain, quote.entry));
+        if (funding === "plan" && cash === undefined) {
+            // The quote signature names no amount, so the wallet signs it while the balances are read; a refusal stops the read and is the call's error.
+            const reading = new AbortController();
+            signing.catch((error) => reading.abort(error));
+            plan = await readSpendableCash(reading.signal).then((read) => planEntry(stake, core, read)).catch(async (error) => {
+                await signing;
+                throw error;
+            });
+        }
+        const bridgeAmount = plan?.bridge ?? 0n;
+        const walletAmount = plan?.wallet ?? 0n;
+        const [taker_signature, bridge, walletFunding] = await Promise.all([
+            signing,
+            bridgeAmount > 0n ? signSendAsset(signer, bridgeAction(hyperliquidNetwork(chain.chain_id), bridgeAmount, {
+                ...(request.hypercoreNonce === undefined ? {} : { nonce: request.hypercoreNonce }),
+                ...(request.sourceDex === undefined ? {} : { sourceDex: request.sourceDex }),
+            })) : undefined,
+            walletAmount > 0n ? depositAuthorization(chain, account, walletAmount) : undefined,
+        ]);
+        const fundingCommand = plan === undefined ? (funding === "none" || funding === "plan" ? undefined : funding) : walletFunding;
+        return {
+            kind: "ENTRY", version: 2, acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope, expiry: quote.entry.expiry,
+            command: { taker_signature, ...(fundingCommand === undefined ? {} : { funding: fundingCommand }) },
+            ...(bridge === undefined ? {} : { bridge }),
+        };
+    }
+    /**
+     * Sign a Combo entry for a quote without sending it. Funding is planned
+     * from `cash`, the free vault cash and available wallet USDC you already
+     * read (`spendableCash`), or from a fresh balances read when it is left out:
+     * free vault cash, then a USDC authorization from the wallet, then a bridge
+     * of `core` (the Core USDC you offer, in USDC base units; `bridgeGasBuffer`
+     * stays behind) to the wallet for the rest. Pass `core: null` when your Core
+     * read failed: an entry that needs the bridge then throws `EntryError`
+     * `BALANCE_UNKNOWN` instead of asking the wallet for it all. Leave `core`
+     * out to fund from the wallet alone. The quote, the bridge and the wallet
+     * authorization are asked of the signer at once; a wallet that prompts
+     * shows them in turn. `sourceDex: ""` bridges from perps instead of spot.
+     * Persist the record, then `sendAcceptance` it; after a restart,
+     * `recoverAcceptance` it. Pass `hypercoreNonce` if your app reserves
+     * Hyperliquid nonces itself.
+     */
+    function signEntry(request) {
+        return signEntryWith(request, "plan");
+    }
+    /** Sign a cash-out quote as the position's owner without sending it: the same SellBack or CashoutTransfer digest the maker signs. */
+    async function signCashout(request) {
+        const { quote } = request;
+        const { signer, account, chain, scope } = await recordScope();
+        const seller = quote.kind === "SELL_BACK" ? quote.sell_back.owner : quote.transfer.seller;
+        if (seller.toLowerCase() !== account)
+            throw new Error("the quote sells another owner's position");
+        const typedData = quote.kind === "SELL_BACK" ? sellBackTypedData(chain, quote.sell_back) : cashoutTransferTypedData(chain, quote.transfer);
+        const taker_signature = await signer.signTypedData(typedData);
+        return {
+            kind: "CASHOUT", acceptanceId: request.acceptanceId ?? uuidv7(), rfqId: quote.rfq_id, quoteId: quote.quote_id, ...scope,
+            positionId: termsOf(quote).position_id, command: { taker_signature },
+        };
+    }
+    /**
+     * Send a signed entry or cash-out: one synchronous accept under the
+     * record's acceptance ID, whose answer must echo the record's acceptance,
+     * RFQ and quote IDs; a lost answer is read and fenced, never resent blind.
+     * An entry's bridge goes only after the accept answers `ACCEPTED` with a
+     * `fund_by` still ahead, and never holds up the result (see `bridging`);
+     * an accept answered any other way discards it, so nothing moved.
+     * `onRecord` is awaited with the record before the bridge is first sent,
+     * and gets it again with Hyperliquid's answer or the discard. An entry
+     * record from SDK 0.63 or older is refused: `recoverAcceptance` it.
+     */
+    async function sendAcceptance(signed, options = {}) {
+        if (signed.kind === "ENTRY" && signed.version !== 2)
+            throw new Error("this entry was signed by an older SDK, which sent its bridge before the accept; recoverAcceptance it instead");
+        await checkScope(signed);
+        options.signal?.throwIfAborted();
+        const clock = venueClock();
+        if (signed.kind === "ENTRY" && signed.bridge !== undefined) {
+            // The held accept's own stamp runs late by the maker's wait; a read sent alongside bounds the venue clock tightly.
+            const probed = clock.sending();
+            void client.GET("/v1/rfqs/{rfq_id}/quotes", { params: { path: { rfq_id: signed.rfqId } }, fetch: recoveryFetch }).then((read) => {
+                if (read.data !== undefined)
+                    probed(read.data.server_time);
+            }, () => undefined);
+        }
+        let outcome;
+        try {
+            const stamped = clock.sending();
+            const answer = await sendOnce(() => client.POST("/v1/quotes/{quote_id}/accept", { params: { path: { quote_id: signed.quoteId }, header: idempotency(signed.acceptanceId) }, body: signed.command }));
+            checkEcho(signed, answer, true);
+            stamped(answer.server_time);
+            outcome = answer;
+        }
+        catch (error) {
+            if (!(error instanceof NetworkError)) {
+                if (!normalizeError(error).mayStillRun)
+                    await discardBridge(signed, options.onRecord);
+                throw error;
+            }
+            outcome = await fenceAcceptance(signed, clock, error, true, bridgeUnsent(signed));
+        }
+        return resultOf(signed, outcome, await moveBridge(signed, outcome, clock, options));
+    }
+    /**
+     * Finish a stored record after a lost answer or a restart, signing nothing:
+     * read the acceptance, fencing an absent one so it ends `NOT_ADMITTED`. An
+     * entry's bridge never sent goes now only if the acceptance is `ACCEPTED`
+     * and its `fund_by` is still ahead, and is discarded otherwise; one sent
+     * without an answer is resent, the same bytes, within the same window. A
+     * record from SDK 0.63 or older is only read. One still `PENDING_CONFIRM`
+     * is read again after the maker's deadline, or every 250 ms until 2 s past
+     * it while a bridge is unsent; `wait: false` returns it as it stands instead.
+     */
+    async function recoverAcceptance(signed, options = {}) {
+        await checkScope(signed);
+        const clock = venueClock();
+        const outcome = await fenceAcceptance(signed, clock, undefined, options.wait ?? true, bridgeUnsent(signed));
+        return resultOf(signed, outcome, await moveBridge(signed, outcome, clock, options));
+    }
+    /** Cancel a fresh RFQ when its record fails before the accept is posted. */
+    async function signedOrCancel(rfqId, sign) {
+        try {
+            return await sign();
+        }
+        catch (error) {
+            await cancelRfq(rfqId);
+            throw error;
+        }
+    }
+    /**
+     * Open a combo position: create the RFQ, take a quote from those the stream
+     * pushes, sign it (`signEntry`), hand the record to `onSigned` to persist,
+     * then `sendAcceptance`. Returns the acceptance's status (`ACCEPTED` with
+     * `operationId`, `DECLINED` / `TIMED_OUT` / `CANCELLED`, or `NOT_ADMITTED`
+     * when a lost accept never arrived). The position opens under `positionId`,
+     * the quote's ID, once `waitForOperation(operationId)` resolves `COMMITTED`;
+     * pass its operation and the result's `record` to `entryFailure` to name a
+     * failure. Any vault shortfall is funded from the wallet, and from `core`
+     * by bridge, unless `funding` says otherwise.
+     */
+    async function openPosition(request) {
+        const { legs, stake, choose = bestQuote(), collectMs = defaultCollectMs, funding = "wallet", intent, quoteTimeoutMs = 20_000, signal } = request;
+        const reading = funding === "wallet" && request.cash === undefined ? readSpendableCash(signal) : undefined;
+        reading?.catch(() => undefined);
+        const account = await (await requireSigner()).address();
+        await deployment();
+        await stream.live(signal);
+        const wanted = { taker: account, stake: String(stake), legs: [...legs].sort((a, b) => Number(a.outcome_id) - Number(b.outcome_id)).map(({ outcome_id, side }) => ({ outcome_id, side })) };
+        const entry = { stake: wanted.stake, legs: wanted.legs };
+        const rfqId = await createRfq(intent === undefined ? entry : { ...entry, ...intent });
+        // Only quotes for exactly this position are offered to the chooser, and the chosen one is checked again before signing.
+        const matches = (quote) => quote.kind === "ENTRY" && quote.rfq_id === rfqId &&
+            quote.entry.taker.toLowerCase() === wanted.taker && quote.entry.stake === wanted.stake &&
+            JSON.stringify(quote.entry.legs.map(({ outcome_id, side }) => ({ outcome_id, side }))) === JSON.stringify(wanted.legs);
+        const { selected, signed } = await signedOrCancel(rfqId, async () => {
+            const selected = await awaitOffer(rfqId, matches, choose, collectMs, quoteTimeoutMs, signal);
+            if (!matches(selected))
+                throw new Error("the chosen quote is not for the requested position");
+            const signed = await signEntryWith({ quote: selected, core: request.core, cash: request.cash ?? await reading, sourceDex: request.sourceDex }, funding === "wallet" ? "plan" : funding);
+            await request.onSigned?.(signed);
+            return { selected, signed };
+        });
+        let record = signed;
+        const result = await sendAcceptance(signed, {
+            ...(request.transport === undefined ? {} : { transport: request.transport }),
+            ...(signal === undefined ? {} : { signal }),
+            onRecord: async (next) => {
+                record = next;
+                await request.onSigned?.(next);
+            },
+        });
+        return {
+            ...result,
+            entry: selected.entry,
+            /** The entry record as it stands now, with each bridge update `onSigned` gets: pass it to `entryFailure`. */
+            get record() {
+                return record;
+            },
+        };
+    }
+    /**
+     * Cash out a position: create its cash-out RFQ
+     * (`POST /v1/me/positions/{position_id}/cashout`), take a quote from those
+     * the stream pushes, sign it as its owner (`signCashout`), hand the record to
+     * `onSigned`, then `sendAcceptance`. `ACCEPTED` means the sell-back or
+     * transfer is queued as `operationId` (follow it with `waitForOperation`);
+     * otherwise the status says why not (`DECLINED`, `TIMED_OUT`, `CANCELLED`, `NOT_ADMITTED`).
+     */
+    async function cashOut(request) {
+        const { positionId, choose = bestBid(), collectMs = defaultCollectMs, quoteTimeoutMs = 20_000, signal } = request;
+        const owner = await (await requireSigner()).address();
+        await deployment();
+        await stream.live(signal);
+        const rfqId = await createCashout(positionId);
+        // Only quotes for this position, sold by this owner, are offered to the chooser and signed.
+        const matches = (quote) => {
+            if (quote.kind === "ENTRY" || quote.rfq_id !== rfqId)
+                return false;
+            const seller = quote.kind === "SELL_BACK" ? quote.sell_back.owner : quote.transfer.seller;
+            return termsOf(quote).position_id.toLowerCase() === positionId.toLowerCase() && seller === owner;
+        };
+        const signed = await signedOrCancel(rfqId, async () => {
+            const bid = await awaitOffer(rfqId, matches, choose, collectMs, quoteTimeoutMs, signal);
+            if (!matches(bid))
+                throw new Error("the chosen quote is not for this position and owner");
+            const signed = await signCashout({ quote: bid });
+            await request.onSigned?.(signed);
+            return signed;
+        });
+        return { ...(await sendAcceptance(signed, signal === undefined ? {} : { signal })), positionId };
+    }
+    /**
+     * Follow an operation to a terminal status (COMMITTED, REVERTED or
+     * EXPIRED_UNEXECUTED) from OPERATION_UPDATED, rereading it with
+     * `GET /v1/me/operations/{operation_id}` on VAULT_BALANCE_CHANGED too.
+     * Resolves at every terminal status: only COMMITTED executed, and a failed
+     * one's `failure_reason` says why when the venue knows (`entryFailure`
+     * words it for an entry).
+     */
+    function waitForOperation(operationId, signal) {
+        const terminal = new Set(["COMMITTED", "REVERTED", "EXPIRED_UNEXECUTED"]);
+        return follow(stream, async (stop) => unwrap(await client.GET("/v1/me/operations/{operation_id}", { params: { path: { operation_id: operationId } }, signal: stop, fetch: recoveryFetch })).operation, (operation) => terminal.has(operation.status), (event) => event.event_type === "VAULT_BALANCE_CHANGED" ||
+            (event.event_type === "OPERATION_UPDATED" && event.payload.operation_id === operationId && terminal.has(event.payload.status)), signal, retry);
+    }
+    /**
+     * Sign a withdrawal to an external address without sending it: the Exit for
+     * any wallet shortfall and the USDC payout, whose nonce derives from
+     * `idempotencyKey`. Keep `{ idempotencyKey, account, body }` before sending it with
+     * `sendWithdrawal`, so a lost answer or a restart resends the same bytes
+     * under the same key instead of signing a second withdrawal.
+     */
+    async function signWithdrawal(request) {
+        const signer = await requireSigner();
+        const account = await signer.address();
+        const chain = await deployment();
+        const idempotencyKey = request.idempotencyKey ?? uuidv7();
+        const amount = BigInt(request.amount);
+        const destination = address(request.destination.toLowerCase());
+        const { wallet } = await readSpendableCash();
+        if (wallet === null)
+            throw new BalanceUnknownError("WALLET_USDC", "the Totalis wallet balance is unknown; read it again");
+        const shortfall = amount - wallet;
+        const issued = now();
+        let deadline = issued;
+        let vault_withdrawal;
+        if (shortfall > 0n) {
+            const exit = { amount: shortfall.toString(), expiry: String(issued + 600), salt: BigInt(randomBytes32()).toString() };
+            vault_withdrawal = { ...exit, signature: await signer.signTypedData(exitTypedData(chain, { account, to: account, ...exit })) };
+            deadline = issued + 600;
+        }
+        // The venue requires the payout to outlive the vault leg by 300 s; a minute more absorbs clock skew.
+        const window = { valid_after: String(issued - 60), valid_before: String(deadline + 360) };
+        const nonce = payoutNonce(chain, account, idempotencyKey);
+        const authorization_signature = await signer.signTypedData(transferWithAuthorizationTypedData(chain, { from: account, to: destination, value: amount.toString(), ...window, nonce }));
+        const body = {
+            destination, amount: amount.toString(), ...(vault_withdrawal === undefined ? {} : { vault_withdrawal }),
+            payout_authorization: { ...window, authorization_signature },
+        };
+        return { idempotencyKey, account, body };
+    }
+    /** POST a signed withdrawal to `/v1/me/withdrawals`, resending the same bytes on a lost answer. 202 is admission, not payment; a replay returns it as it stands. */
+    async function startWithdrawal(signed) {
+        const { account, body: { destination, amount } } = signed;
+        const started = await sendOnce(() => client.POST("/v1/me/withdrawals", { params: { header: { "Idempotency-Key": signed.idempotencyKey } }, body: signed.body }));
+        if (started.account !== account || started.destination !== destination || started.amount !== amount) {
+            throw new Error("the venue returned a withdrawal with different terms");
+        }
+        return started;
+    }
+    const withdrawalUpdate = (event) => event.event_type === "WITHDRAWAL_UPDATED" ? event.payload : undefined;
+    /**
+     * Resolve at PAYOUT_COMMITTED (reject at FAILED) from the account stream,
+     * whose WITHDRAWAL_UPDATED carries the whole withdrawal. The recovery read,
+     * `GET /v1/me/withdrawals/{withdrawal_id}`, runs only when the stream
+     * (re)connects, or at once when `known` is not given; nothing polls. A
+     * recovery read that fails transiently is retried with backoff until it
+     * answers, the stream settles the withdrawal, or the follow ends.
+     */
+    function followWithdrawal(withdrawalId, known, signal) {
+        stream.start();
+        return new Promise((resolve, reject) => {
+            const stop = new AbortController();
+            const offs = [];
+            const finish = (settle) => {
+                if (stop.signal.aborted)
+                    return;
+                stop.abort();
+                for (const off of offs)
+                    off();
+                signal?.removeEventListener("abort", abort);
+                settle();
+            };
+            const settle = (withdrawal) => {
+                if (withdrawal.withdrawal_id !== withdrawalId)
+                    return;
+                if (withdrawal.status === "PAYOUT_COMMITTED")
+                    finish(() => resolve(withdrawal));
+                else if (withdrawal.status === "FAILED")
+                    finish(() => reject(new Error(`withdrawal ${withdrawalId} failed`)));
+            };
+            const recover = recoveryReads(stream, async (stop) => unwrap(await client.GET("/v1/me/withdrawals/{withdrawal_id}", { params: { path: { withdrawal_id: withdrawalId } }, signal: stop, fetch: recoveryFetch })), settle, (error) => finish(() => reject(error)), stop.signal, retry);
+            const abort = () => finish(() => reject(signal?.reason));
+            if (signal?.aborted)
+                return abort();
+            signal?.addEventListener("abort", abort, { once: true });
+            let live = stream.status === "live";
+            offs.push(stream.on("event", (event) => {
+                const withdrawal = withdrawalUpdate(event);
+                if (withdrawal !== undefined)
+                    settle(withdrawal);
+            }), stream.on("status", (status) => {
+                if (status === "live" && !live)
+                    void recover();
+                else if (status === "closed")
+                    finish(() => reject(new StreamClosedError("closed", 1000)));
+                live = status === "live";
+            }));
+            for (const withdrawal of known)
+                settle(withdrawal);
+            if (known.length === 0 && live)
+                void recover();
+        });
+    }
+    /**
+     * Send a signed withdrawal and follow it to PAYOUT_COMMITTED on the stream.
+     * A resend of the same `{ idempotencyKey, account, body }` (after a lost answer or a
+     * restart) returns the same withdrawal, never a second one.
+     */
+    async function sendWithdrawal(signed, options = {}) {
+        await stream.live(options.signal);
+        // Updates can arrive before the answer; keep them for the follow below.
+        const early = [];
+        const off = stream.on("event", (event) => {
+            const withdrawal = withdrawalUpdate(event);
+            if (withdrawal !== undefined)
+                early.push(withdrawal);
+        });
+        let started;
+        let followed;
+        try {
+            started = await startWithdrawal(signed);
+            followed = followWithdrawal(started.withdrawal_id, [...early, started], options.signal);
+        }
+        finally {
+            off();
+        }
+        // Settled or not, the follow is returned below; do not report it unhandled meanwhile.
+        followed.catch(() => undefined);
+        await options.onStarted?.(started.withdrawal_id);
+        return followed;
+    }
+    /**
+     * Withdraw to an external address in one request: any wallet shortfall
+     * leaves the vault through a signed Exit and the signed payout follows it,
+     * both relayed by Totalis. Resolves at PAYOUT_COMMITTED from the stream.
+     */
+    async function withdraw(request) {
+        await stream.live(request.signal);
+        return sendWithdrawal(await signWithdrawal(request), request);
+    }
+    /** Follow a withdrawal after a restart: one recovery read (retried while it fails transiently), then the stream. */
+    async function waitForWithdrawal(withdrawalId, signal) {
+        await stream.live(signal);
+        return followWithdrawal(withdrawalId, [], signal);
+    }
+    /**
+     * Sign an exit of free vault cash to the account's own HyperCore spot
+     * account without sending it, for example before a native HyperCore order.
+     * A Privy account's cash is swept to Core in the background; an external
+     * wallet has no sweep (TT-1790), so its app does this when Core needs the
+     * cash. The wallet signs an Exit to the CoreExit router (valid up to 10
+     * minutes) and Totalis relays it, paying the gas. Persist
+     * `{ exitId, body }`, then `sendCoreExit` it; a resend sends the same bytes.
+     * One exit at a time per account (CORE_MOVE_IN_FLIGHT); an account that
+     * isn't an embedded wallet moves at least 1 USDC, at most 10 times an hour
+     * with its withdrawals. An account with no HyperCore account yet gets
+     * CORE_ACCOUNT_ACTIVATION_REQUIRED until the user accepts Hyperliquid's
+     * one-time 1 USDC activation fee, sent as `activationFeeAccepted` on an
+     * exit of at least 2 USDC. A deployment without exits to HyperCore (staging)
+     * throws `ExitUnavailableError` before anything is signed.
+     */
+    async function signCoreExit(request) {
+        return signExit(request, await coreExitRoute());
+    }
+    async function coreExitRoute() {
+        const route = unwrap(await client.GET("/v1/me/core-exits")).deployment;
+        if (route === null)
+            throw new ExitUnavailableError();
+        return route;
+    }
+    async function signExit(request, route) {
+        const signer = await requireSigner();
+        const account = address((await signer.address()).toLowerCase());
+        const chain = await deployment();
+        const exitId = request.exitId ?? uuidv7();
+        const to = address(route.router_address.toLowerCase());
+        // A minute inside the venue's maximum life absorbs clock skew.
+        const exit = { amount: BigInt(request.amount).toString(), expiry: String(now() + Math.min(route.maximum_life_seconds - 60, 600)), salt: BigInt(randomBytes32()).toString() };
+        const signature = await signer.signTypedData(exitTypedData(chain, { account, to, ...exit }));
+        const body = envelope({ account, to, ...exit, signature, purpose: request.purpose ?? "ORDER", ...(request.activationFeeAccepted ? { activation_fee_accepted: true } : {}) });
+        return { exitId, account, body };
+    }
+    /**
+     * POST a signed exit under its exit ID, resending the same bytes on a lost
+     * answer. The 202 is admission: follow it with `waitForCoreExit`.
+     * The venue's `CORE_EXIT_UNAVAILABLE`, answered only on a deployment that
+     * runs no exits (staging), throws `ExitUnavailableError`.
+     */
+    async function sendCoreExit(signed) {
+        try {
+            return await sendOnce(() => client.POST("/v1/core-exits", { params: { header: { "Idempotency-Key": signed.exitId } }, body: signed.body }));
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === "CORE_EXIT_UNAVAILABLE") {
+                throw new ExitUnavailableError({ cause: error });
+            }
+            throw error;
+        }
+    }
+    /** Sign and send an exit to HyperCore in one call (`signCoreExit`, then `sendCoreExit`). */
+    async function exitToCore(request) {
+        return sendCoreExit(await signCoreExit(request));
+    }
+    /**
+     * Sign a sponsored deposit of wallet USDC into the vault without sending it:
+     * a USDC ReceiveWithAuthorization to the vault, valid for 10 minutes, that
+     * Totalis relays and pays gas for. At least 1 USDC. Persist
+     * `{ depositId, body }`, then `sendDeposit` it.
+     */
+    async function signDeposit(request) {
+        const account = address((await (await requireSigner()).address()).toLowerCase());
+        const { kind: _kind, ...authorization } = await depositAuthorization(await deployment(), account, BigInt(request.amount));
+        const body = envelope({ account, from: account, ...authorization });
+        return { depositId: request.depositId ?? uuidv7(), account, body };
+    }
+    /** POST a signed deposit under its ID, resending the same bytes on a lost answer. The 202 names the operation: follow it with `waitForOperation`. */
+    function sendDeposit(signed) {
+        return sendOnce(() => client.POST("/v1/me/deposits", { params: { header: { "Idempotency-Key": signed.depositId } }, body: signed.body }));
+    }
+    /**
+     * Sign the return of the account's Totalis cash to HyperCore without
+     * sending it: a deposit of the available wallet USDC (when at least 1 USDC)
+     * and one exit of that plus the free vault cash. Persist the record, then
+     * `sendReturnToCore` it, again after a restart. Both legs expire after
+     * about 10 minutes; past that, sign a new return. Only for an external
+     * wallet: Totalis already moves an embedded wallet's vault cash to Core in
+     * the background, so that account just `signDeposit`s its wallet USDC.
+     * Throws `ExitUnavailableError` without exits to HyperCore and
+     * `BalanceUnknownError` while a balance is unknown, before signing anything.
+     */
+    async function signReturnToCore(request = {}) {
+        const { wallet_kind } = unwrap(await client.GET("/v1/me"));
+        if (wallet_kind !== "EXTERNAL")
+            throw new Error("Totalis moves an embedded wallet's cash to HyperCore itself; deposit its wallet USDC with signDeposit instead");
+        const route = await coreExitRoute();
+        const { vault, wallet } = await readSpendableCash();
+        if (vault === null)
+            throw new BalanceUnknownError("VAULT_FREE", "the free vault balance is unknown; read it again");
+        if (wallet === null)
+            throw new BalanceUnknownError("WALLET_USDC", "the Totalis wallet balance is unknown; read it again");
+        const moved = wallet >= minimumDeposit ? wallet : 0n;
+        const amount = vault + moved;
+        if (amount <= 0n)
+            throw new Error("there is no Totalis cash to return to HyperCore");
+        const deposit = moved > 0n ? await signDeposit({ amount: moved, ...(request.depositId === undefined ? {} : { depositId: request.depositId }) }) : undefined;
+        const { depositId: _depositId, ...exit } = request;
+        return { ...(deposit === undefined ? {} : { deposit }), exit: await signExit({ ...exit, amount }, route) };
+    }
+    /**
+     * Send a signed return: the deposit, then, once its operation COMMITTED, the
+     * exit (an exit admitted before the deposit lands is refused for too little
+     * free cash). Resolves with the admitted exit; follow it with `waitForCoreExit`.
+     */
+    async function sendReturnToCore(signed, options = {}) {
+        if (signed.deposit !== undefined) {
+            await stream.live(options.signal);
+            const { operation_id } = await sendDeposit(signed.deposit);
+            const operation = await waitForOperation(operation_id, options.signal);
+            if (operation.status !== "COMMITTED")
+                throw new Error(`deposit ${operation_id} ended ${operation.status}; nothing left the vault`);
+        }
+        return sendCoreExit(signed.exit);
+    }
+    /** Return wallet USDC and free vault cash to HyperCore in one call (`signReturnToCore`, then `sendReturnToCore`). */
+    async function returnToCore(request = {}) {
+        const { signal, ...terms } = request;
+        return sendReturnToCore(await signReturnToCore(terms), signal === undefined ? {} : { signal });
+    }
+    /** Follow an exit on the stream until its cash is credited on HyperCore; it rejects if the exit ends any other way. */
+    async function waitForCoreExit(exitId, signal) {
+        const terminal = new Set(["CREDITED", "RECOVERED", "FAILED", "ABANDONED"]);
+        const exit = await follow(stream, async (stop) => unwrap(await client.GET("/v1/core-exits/{exit_id}", { params: { path: { exit_id: exitId } }, signal: stop, fetch: recoveryFetch })), (value) => terminal.has(value.status), (event) => event.event_type === "CORE_EXIT_UPDATED" && event.payload.exit_id === exitId, signal, retry);
+        if (exit.status !== "CREDITED")
+            throw new Error(`core exit ${exitId} ended ${exit.status}, not credited on HyperCore`);
+        return exit;
+    }
+    /**
+     * The transactions a wallet sends itself to deposit USDC from HyperEVM into
+     * its vault balance, paying its own gas: approve the vault for `amount`, then
+     * `depositUser(account, amount)`. Totalis indexes the deposit from its event;
+     * no API call follows. Send them with the wallet's own provider, in order.
+     */
+    async function directDepositCalls(amount) {
+        const account = address((await (await requireSigner()).address()).toLowerCase());
+        const chain = await deployment();
+        const value = BigInt(amount);
+        if (value <= 0n || value >= 1n << 128n)
+            throw new RangeError("deposit amount must be a positive uint128");
+        const vault = address(chain.vault_address.toLowerCase());
+        return [
+            { to: address(chain.usdc.address), data: callData("approve(address,uint256)", vault, value) },
+            { to: vault, data: callData("depositUser(address,uint128)", account, value) },
+        ];
+    }
+    return {
+        /** The typed HTTP client over the same credential, for reads the flows do not cover. */
+        client,
+        /** The account stream. Flows start it on first use; `close()` it when done. */
+        stream,
+        deployment,
+        /** Spendable Totalis cash from a fresh balances read (`spendableCash`): `{ vault, wallet, total }`, each `null` while unknown, never 0. */
+        spendableCash: readSpendableCash,
+        openPosition,
+        cashOut,
+        signEntry,
+        signCashout,
+        sendAcceptance,
+        recoverAcceptance,
+        signWithdrawal,
+        sendWithdrawal,
+        withdraw,
+        waitForWithdrawal,
+        waitForOperation,
+        signCoreExit,
+        sendCoreExit,
+        exitToCore,
+        waitForCoreExit,
+        signDeposit,
+        sendDeposit,
+        signReturnToCore,
+        sendReturnToCore,
+        returnToCore,
+        directDepositCalls,
+        /** Render an RFQ's live quotes (entry or cash-out) from the stream; `[]` while the stream is down. */
+        watchQuotes,
+        /** Issue a personal `ttk_` key; the signer must be the account wallet (embedded, or a wallet-only account's own). */
+        issueApiKey: async (request) => issueApiKey(keys, await requireSigner(), request),
+        rotateApiKey: async (keyId, request) => rotateApiKey(keys, await requireSigner(), keyId, request),
+        close: () => stream.close(),
+    };
+}
+export { BalanceUnknownError, EntryError, ExitUnavailableError };
+export { ApiError, NetworkError };