@totalis/hip4-client 0.0.0-stage → 0.65.2

package/dist/maker.js

@@ -0,0 +1,608 @@
+import { audienceClient, headerRecord } from "./base.js";
+import { ApiError, randomBytes32, resendable, sendOnce, singleFetch, sleep, unwrap, uuidv7 } from "./request.js";
+import { toTotalisSigner } from "./signer.js";
+import { items } from "./pagination.js";
+import { TotalisStream } from "./stream.js";
+import { follow } from "./totalis.js";
+import { address, cashoutTransferTypedData, hashTypedData, quoteTypedData, sellBackTypedData } from "./typed-data.js";
+import { calldata, controllerTransactions } from "./controller.js";
+export { controllerTransactions, encodeCall, openMakerVaultTransaction } from "./controller.js";
+export function createMakerClient(environment, options) {
+    return audienceClient(environment, options);
+}
+/**
+ * `quote` or `bid` on an RFQ where a taker's acceptance of this maker's quote
+ * awaits its answer. Publishing would replace that quote, which the venue
+ * refuses with 409 `STATE_CONFLICT`. Nothing was published: answer the
+ * acceptance (`confirm`, or `onAcceptance`) first, or let its deadline pass.
+ */
+export class AcceptancePendingError extends Error {
+    rfqId;
+    quoteId;
+    deadline;
+    name = "AcceptancePendingError";
+    code = "ACCEPTANCE_PENDING";
+    constructor(rfqId, quoteId, deadline) {
+        super(`an acceptance of quote ${quoteId} on RFQ ${rfqId} awaits this maker's answer until ${deadline}`);
+        this.rfqId = rfqId;
+        this.quoteId = quoteId;
+        this.deadline = deadline;
+    }
+}
+// An opening event older than this arrived by replay, not live fanout.
+const REPLAYED_AFTER_MS = 2_000;
+/** An in-memory store that drops entries a minute after they expire. */
+export function memoryPublished() {
+    const entries = new Map();
+    return {
+        record(digest, expiry) {
+            const stale = Date.now() / 1000 - 60;
+            for (const [known, until] of entries)
+                if (until < stale)
+                    entries.delete(known);
+            entries.set(digest, expiry);
+        },
+        forget: (digest) => void entries.delete(digest),
+        expiry: (digest) => entries.get(digest),
+    };
+}
+const randomSalt = () => BigInt(randomBytes32()).toString();
+const expiryIn = (seconds) => String(Math.floor(Date.now() / 1000) + seconds);
+/**
+ * The maker SDK over the public maker surface (the one Totalis MM uses):
+ * publish unsigned entry and cash-out quotes on one route, then confirm the
+ * exact terms a taker accepted when QUOTE_ACCEPTED arrives.
+ */
+export function createMaker(options) {
+    const { environment, apiKey, makerId, signer: signerInput, stream: streamOptions, streamBaseUrl, ...clientOptions } = options;
+    const client = createMakerClient(environment, { ...clientOptions, accessToken: apiKey });
+    const recoveryFetch = singleFetch(clientOptions.fetch);
+    const signer = toTotalisSigner(signerInput);
+    const stream = new TotalisStream({
+        environment, accessToken: apiKey, headers: headerRecord(clientOptions.headers), ...streamOptions,
+        subscription: { ...streamOptions?.subscription, type: "maker", maker_id: makerId },
+        ...(clientOptions.baseUrl === undefined ? {} : { baseUrl: clientOptions.baseUrl }),
+        ...(streamBaseUrl === undefined ? {} : { streamBaseUrl }),
+    });
+    let deploymentRead;
+    // Acceptances still before their deadline and not yet answered, from the
+    // snapshot, the acceptances GET and QUOTE_ACCEPTED, so a handler attached
+    // after the stream is live still answers what it already delivered.
+    const pending = new Map();
+    /** This maker's unanswered acceptance on the RFQ, if any. Replacing or cancelling its quote would withdraw it. */
+    const awaiting = (rfqId) => {
+        for (const [id, acceptance] of pending) {
+            // Deadlines are venue time: a fast local clock must not drop a live acceptance.
+            if (Date.parse(acceptance.deadline) <= stream.serverNow())
+                pending.delete(id);
+            else if (acceptance.rfq_id === rfqId)
+                return acceptance;
+        }
+        return undefined;
+    };
+    const refuseWhileAwaiting = (rfqId) => {
+        const acceptance = awaiting(rfqId);
+        if (acceptance !== undefined)
+            throw new AcceptancePendingError(rfqId, acceptance.quote_id, acceptance.deadline);
+    };
+    // Resolves once the acceptances a truncated snapshot left out have been paged
+    // in, and rejects while that read has failed: until then they are not known.
+    let acceptancesPaged = Promise.resolve();
+    let pagingFailed = false;
+    const pageAcceptances = () => {
+        pagingFailed = false;
+        const paging = continueAcceptances();
+        acceptancesPaged = paging;
+        paging.catch((error) => {
+            if (acceptancesPaged === paging)
+                pagingFailed = true;
+            handlers.forEach(({ failed }) => failed(error));
+        });
+        return paging;
+    };
+    /**
+     * Pending acceptances are known: the stream is live and any truncated
+     * acceptances are paged in. A failed page read is read again here, and
+     * rejects again if it fails, so nothing is quoted while acceptances are unknown.
+     */
+    const acceptancesKnown = async () => {
+        await stream.live();
+        if (pagingFailed)
+            pageAcceptances();
+        await acceptancesPaged;
+    };
+    // Called with an RFQ whose acceptance was answered, so a held RFQ is offered again at once.
+    const released = new Set();
+    // Answered acceptances until their deadline, so a copy still being replayed or paged does not hold the RFQ again.
+    const answeredUntil = new Map();
+    /** `filled`: the answer filled the RFQ, so it is no longer open to quote. */
+    const answered = (acceptance, filled = false) => {
+        answeredUntil.set(acceptance.quote_id, Date.parse(acceptance.deadline));
+        if (pending.delete(acceptance.quote_id))
+            released.forEach((release) => release(acceptance.rfq_id, filled));
+    };
+    /**
+     * Record a digest as signable before publishing it (a lost response may
+     * still have published it), and forget it when the venue definitely rejects it.
+     */
+    async function publish(rfqId, digest, expiry, post) {
+        // An acceptance may have arrived while the terms were prepared.
+        refuseWhileAwaiting(rfqId);
+        await published.record(digest, expiry);
+        try {
+            await post();
+        }
+        catch (error) {
+            if (!resendable(error))
+                await published.forget(digest);
+            throw error;
+        }
+    }
+    const published = options.published ?? memoryPublished();
+    const deployment = () => (deploymentRead ??= client.GET("/v1/deployment").then(unwrap).catch((error) => {
+        deploymentRead = undefined;
+        throw error;
+    }));
+    // Fees can change by governance and accepts require the current ones, so
+    // every quote reads them; only the deployment identity is cached.
+    async function vaultFees() {
+        const { fee_bps, taker_fee_bps } = unwrap(await client.GET("/v1/deployment"));
+        if (fee_bps === null || taker_fee_bps === null)
+            throw new Error("the venue has not published the vault's fees yet");
+        return { fee_bps, taker_fee_bps };
+    }
+    /**
+     * Publish an unsigned quote on an entry RFQ; it replaces this maker's
+     * previous quote there. Nothing is signed until a taker accepts it. The
+     * fees are the vault's current ones, read from GET /v1/deployment for this quote.
+     * Throws `AcceptancePendingError`, publishing nothing, while a taker's
+     * acceptance of this maker's quote on the RFQ awaits an answer: replacing
+     * the quote would withdraw that acceptance. It starts the maker stream if
+     * needed and waits until it is live, so the pending acceptances are known.
+     */
+    async function quote(rfq, terms) {
+        await acceptancesKnown();
+        refuseWhileAwaiting(rfq.rfq_id);
+        const [chain, fees] = await Promise.all([deployment(), vaultFees()]);
+        const entry = {
+            maker_id: makerId, legs: [...rfq.legs].sort((a, b) => Number(a.outcome_id) - Number(b.outcome_id)), stake: rfq.stake, payout: String(terms.payout),
+            fee_bps: fees.fee_bps, taker_fee_bps: fees.taker_fee_bps, taker: rfq.taker.toLowerCase(),
+            expiry: expiryIn(terms.lifetimeSeconds ?? 20), salt: terms.salt ?? randomSalt(),
+        };
+        const quote_id = hashTypedData(quoteTypedData(chain, entry));
+        await publish(rfq.rfq_id, quote_id, Number(entry.expiry), async () => unwrap(await client.POST("/v1/rfqs/{rfq_id}/quotes", {
+            params: { path: { rfq_id: rfq.rfq_id }, header: { "Idempotency-Key": uuidv7() } }, body: { quote_id, entry },
+        })));
+        return { quoteId: quote_id, entry };
+    }
+    /**
+     * Publish an unsigned cash-out quote on the same route as entry quotes: a
+     * sell-back when this maker wrote the position (`rfq.maker_id` is this
+     * maker), paid from the maker vault; otherwise a transfer to this maker's
+     * signer, paid from that wallet's own account balance in the vault, not the
+     * maker vault. The venue refuses a transfer that balance cannot pay with
+     * `INVALID_REQUEST` naming `transfer.price`, so bid only on your own
+     * positions unless it is funded. The owner signs it before accepting, so
+     * confirming it executes it. Throws `AcceptancePendingError` like `quote`.
+     */
+    async function bid(rfq, terms) {
+        await acceptancesKnown();
+        refuseWhileAwaiting(rfq.rfq_id);
+        const chain = await deployment();
+        const common = { position_id: rfq.position_id, price: String(terms.price), expiry: expiryIn(terms.lifetimeSeconds ?? 45), salt: terms.salt ?? randomSalt(), leg_state: rfq.leg_state };
+        let command;
+        if (rfq.maker_id === makerId) {
+            const sell_back = { ...common, owner: rfq.owner };
+            command = { quote_id: hashTypedData(sellBackTypedData(chain, sell_back)), sell_back };
+        }
+        else {
+            const transfer = { ...common, seller: rfq.owner, buyer: await signer.address() };
+            command = { quote_id: hashTypedData(cashoutTransferTypedData(chain, transfer)), transfer };
+        }
+        await publish(rfq.rfq_id, command.quote_id, Number(common.expiry), async () => unwrap(await client.POST("/v1/rfqs/{rfq_id}/quotes", {
+            params: { path: { rfq_id: rfq.rfq_id }, header: { "Idempotency-Key": uuidv7() } }, body: command,
+        })));
+        return { quoteId: command.quote_id, ...command };
+    }
+    /**
+     * Cancel a published quote. `ACCEPTED` means this maker already confirmed it:
+     * it is filled, and there is nothing left to answer. While a taker's
+     * acceptance of it awaits an answer the venue refuses the cancel with 409
+     * `STATE_CONFLICT`: turn the acceptance down with
+     * `confirm(acceptance, "DECLINE")` instead.
+     */
+    async function cancelQuote(quoteId) {
+        const response = await client.DELETE("/v1/quotes/{quote_id}", { params: { path: { quote_id: quoteId } } });
+        // A quote this maker already confirmed answers 409 with {status: "ACCEPTED"}: a result, not a failure.
+        const body = response.error;
+        if (response.response.status === 409 && typeof body === "object" && body !== null && "status" in body && body.status === "ACCEPTED")
+            return { status: "ACCEPTED" };
+        const result = unwrap(response);
+        // Cancelled or replaced can no longer be accepted, so it must no longer be signable.
+        if (result.status !== "ACCEPTED") {
+            await published.forget(quoteId);
+            const acceptance = pending.get(quoteId);
+            if (acceptance !== undefined)
+                answered(acceptance);
+        }
+        return result;
+    }
+    /**
+     * Arm or renew this maker's quote lease: its open quotes stand only while the
+     * lease is live. If `leaseMs` passes without another renewal, the venue
+     * cancels every open quote of this maker that no taker is accepting, and each
+     * one it publishes after, until the lease is renewed or released. Takers see
+     * QUOTE_REMOVED with status CANCELLED. Without a lease nothing changes.
+     */
+    async function renewQuoteLease(leaseMs) {
+        return unwrap(await client.PUT("/v1/makers/{maker_id}/quote-lease", { params: { path: { maker_id: makerId } }, body: { lease_ms: leaseMs } }));
+    }
+    /** Disarm the quote lease: open quotes then stand until their own expiry. `released` is false if none was armed. */
+    async function releaseQuoteLease() {
+        return unwrap(await client.DELETE("/v1/makers/{maker_id}/quote-lease", { params: { path: { maker_id: makerId } } }));
+    }
+    let stopLease;
+    /**
+     * Renew the quote lease now and every third of `leaseMs` until the returned
+     * stop, `close()` or another `keepQuoteLease` call. If this process dies or
+     * loses the venue, the lease lapses and its quotes are withdrawn. Stopping
+     * leaves the lease to lapse; `releaseQuoteLease()` keeps quotes standing
+     * without one. `onError` gets each failed renewal; renewals continue.
+     */
+    function keepQuoteLease(leaseMs, onError = () => undefined) {
+        stopLease?.();
+        let timer;
+        let stopped = false;
+        const renew = () => void renewQuoteLease(leaseMs).catch(onError).finally(() => {
+            if (!stopped)
+                timer = setTimeout(renew, leaseMs / 3);
+        });
+        const stop = () => {
+            stopped = true;
+            clearTimeout(timer);
+            if (stopLease === stop)
+                stopLease = undefined;
+        };
+        stopLease = stop;
+        renew();
+        return stop;
+    }
+    /** The exact terms an acceptance asks this maker to sign, checked against the quote ID. */
+    async function termsFor(acceptance) {
+        const chain = await deployment();
+        const typedData = acceptance.kind === "ENTRY" ? quoteTypedData(chain, acceptance.entry)
+            : acceptance.kind === "SELL_BACK" ? sellBackTypedData(chain, acceptance.sell_back)
+                : cashoutTransferTypedData(chain, acceptance.transfer);
+        if (hashTypedData(typedData) !== acceptance.quote_id)
+            throw new Error("acceptance terms do not match their quote ID");
+        // The quote signer signs only terms this maker published and that are still live.
+        const expiry = await published.expiry(acceptance.quote_id);
+        if (expiry === undefined || expiry * 1000 <= Date.now())
+            throw new Error("acceptance is not for a live quote this maker published");
+        return typedData;
+    }
+    // Each delivery also goes to every handler.
+    const handlers = new Set();
+    const deliver = (acceptance) => {
+        for (const [id, { deadline }] of pending)
+            if (Date.parse(deadline) <= stream.serverNow())
+                pending.delete(id);
+        for (const [id, deadline] of answeredUntil)
+            if (deadline <= stream.serverNow())
+                answeredUntil.delete(id);
+        if (Date.parse(acceptance.deadline) > stream.serverNow() && !answeredUntil.has(acceptance.quote_id))
+            pending.set(acceptance.quote_id, acceptance);
+        handlers.forEach(({ dispatch }) => dispatch(acceptance));
+    };
+    const continueAcceptances = async () => {
+        const read = (query) => client.GET("/v1/makers/{maker_id}/acceptances", { params: { path: { maker_id: makerId }, query: { ...query, limit: 200 } } }).then(unwrap);
+        for await (const acceptance of items(read, (page) => page.acceptances))
+            deliver(acceptance);
+    };
+    stream.on("reset", () => pending.clear());
+    // A resumed stream replays events with nothing marking their end (a maker
+    // stream has no publication freshness), so it is live before any replayed
+    // QUOTE_ACCEPTED is applied. Without a snapshot on this connection, the
+    // pending acceptances are read in full before anything is quoted.
+    let snapshotted = false;
+    stream.on("status", (status) => {
+        if (status !== "live")
+            snapshotted = false;
+        else if (!snapshotted)
+            void pageAcceptances().catch(() => undefined);
+    });
+    stream.on("snapshot", (snapshot) => {
+        snapshotted = true;
+        (snapshot.resources.acceptances ?? []).forEach(deliver);
+        if (!(snapshot.truncated ?? []).some((truncation) => truncation.resource === "acceptances"))
+            return;
+        void pageAcceptances().catch(() => undefined);
+    });
+    stream.on("event", (event) => void (event.event_type === "QUOTE_ACCEPTED" && deliver(event.payload)));
+    // Each acceptance's answer is decided, signed and built once, registered before any await so
+    // concurrent callers share it; asking again resends those exact bytes.
+    const answers = new Map();
+    function answer(acceptance, decide) {
+        let entry = answers.get(acceptance.quote_id);
+        if (entry === undefined) {
+            const built = (async () => {
+                const decision = await decide();
+                const command = decision === "DECLINE"
+                    ? { decision }
+                    : { decision, maker_signature: await signer.signTypedData(await termsFor(acceptance)) };
+                // A quote has at most one acceptance, so the quote ID alone keys the answer.
+                const params = { path: { quote_id: acceptance.quote_id } };
+                return async () => {
+                    const result = await sendOnce(() => client.POST("/v1/quotes/{quote_id}/confirm", { params, body: command }));
+                    // Answered: unless it filled the RFQ, its quotes may change again.
+                    answered(acceptance, result.status === "ACCEPTED" || result.status === "FILLED");
+                    return result;
+                };
+            })();
+            entry = { until: Date.parse(acceptance.deadline), built };
+            answers.set(acceptance.quote_id, entry);
+            // Nothing was sent if deciding or signing failed; a later delivery may decide again.
+            built.catch(() => answers.delete(acceptance.quote_id));
+            for (const [id, { until }] of answers)
+                if (until < Date.now() - 60_000)
+                    answers.delete(id);
+        }
+        return entry.built.then((send) => send());
+    }
+    /**
+     * Answer an acceptance before its deadline. CONFIRM signs the exact accepted
+     * terms with the quote signer. The first answer for a quote is final:
+     * calling again, or `NetworkError.resend()`, resends the identical request,
+     * which the venue answers with the stored result.
+     */
+    function confirm(acceptance, decision = "CONFIRM") {
+        return answer(acceptance, () => decision);
+    }
+    /**
+     * Handle every pending acceptance: from QUOTE_ACCEPTED, live or replayed by
+     * the stream after a reconnect with a cursor, and the snapshot's
+     * `acceptances` (paging GET /v1/makers/{maker_id}/acceptances when the
+     * snapshot truncated them), including acceptances the stream delivered
+     * before it was attached. The handler decides once per quote; if every send
+     * of the answer is lost, a redelivery before the deadline resends that same
+     * answer. `onError` receives the acceptance, or none when paging the
+     * truncated acceptances failed.
+     */
+    function onAcceptance(handler, onError = () => undefined) {
+        const busy = new Set();
+        const answered = new Set();
+        const dispatch = (request) => {
+            const id = request.quote_id;
+            if (busy.has(id) || answered.has(id) || Date.parse(request.deadline) <= Date.now())
+                return;
+            busy.add(id);
+            void answer(request, () => handler(request)).then(() => answered.add(id), (error) => {
+                // A lost or backed-off answer is resent unchanged by the next delivery.
+                if (!resendable(error))
+                    answered.add(id);
+                onError(error, request);
+            }).finally(() => busy.delete(id));
+        };
+        const entry = { dispatch, failed: (error) => onError(error) };
+        handlers.add(entry);
+        stream.start();
+        [...pending.values()].forEach(dispatch);
+        return () => void handlers.delete(entry);
+    }
+    /**
+     * Every open RFQ once per subscription: from RFQ_CREATED, the snapshot's
+     * open RFQs, and a paged `GET /v1/rfqs` after a reconnect that replayed
+     * instead of snapshotting (or whose snapshot was truncated). Each call keeps
+     * its own in-memory handled set, so another subscription or a restart
+     * delivers the still-open RFQs again; quoting one again replaces this
+     * maker's previous quote on it, so a repeat cannot fill twice. An RFQ where
+     * a taker's acceptance of this maker's quote awaits an answer is held back
+     * until that acceptance is answered or its deadline passes, so quoting it
+     * again does not withdraw an acceptance this maker already knows of.
+     */
+    function onRfq(handler, onError = () => undefined) {
+        const seen = new Set();
+        // RFQs that ended since a snapshot or held delivery captured them open.
+        const ended = new Set();
+        const held = new Map();
+        const release = (rfqId, filled = false) => {
+            if (filled)
+                ended.add(rfqId);
+            const entry = held.get(rfqId);
+            if (entry === undefined)
+                return;
+            clearTimeout(entry.timer);
+            held.delete(rfqId);
+            call(entry.rfq);
+        };
+        const call = (rfq) => {
+            if (stream.status === "closed" || ended.has(rfq.rfq_id) || seen.has(rfq.rfq_id) || held.has(rfq.rfq_id) || !(Date.parse(rfq.expires_at) > stream.serverNow()))
+                return;
+            const acceptance = awaiting(rfq.rfq_id);
+            if (acceptance !== undefined) {
+                // Offered again once the acceptance is answered, or when its deadline passes.
+                held.set(rfq.rfq_id, { rfq, timer: setTimeout(() => release(rfq.rfq_id), Math.max(Date.parse(acceptance.deadline) - stream.serverNow(), 0) + 50) });
+                return;
+            }
+            seen.add(rfq.rfq_id);
+            if (seen.size > 10_000)
+                seen.delete(seen.values().next().value);
+            // A failed handler leaves the RFQ deliverable again by a later snapshot or recovery read.
+            const failed = (error) => {
+                seen.delete(rfq.rfq_id);
+                onError(error);
+            };
+            try {
+                void Promise.resolve(handler(rfq)).catch(failed);
+            }
+            catch (error) {
+                failed(error);
+            }
+        };
+        // A live RFQ_CREATED carries the whole open RFQ; its event type is the
+        // status. A replayed one may have been accepted or cancelled since, so it is
+        // read once more and delivered only if still open.
+        const opened = async (event) => {
+            if (event.event_type !== "RFQ_CREATED")
+                return;
+            const now = stream.serverNow();
+            if (!(Date.parse(event.payload.expires_at) > now) || seen.has(event.payload.rfq_id))
+                return;
+            if (now - Date.parse(event.occurred_at) <= REPLAYED_AFTER_MS)
+                return call({ ...event.payload, status: "OPEN" });
+            const current = unwrap(await client.GET("/v1/rfqs/{rfq_id}", { params: { path: { rfq_id: event.payload.rfq_id } } }));
+            if (current.status === "OPEN")
+                call(current);
+        };
+        let covered = false;
+        let stopped = false;
+        const afterAcceptances = (deliver) => {
+            if (stopped)
+                return;
+            void acceptancesKnown().then(() => {
+                if (!stopped)
+                    deliver();
+            }, (error) => {
+                if (stopped)
+                    return;
+                onError(error);
+                if (stream.status !== "closed")
+                    setTimeout(() => afterAcceptances(deliver), 1_000);
+            });
+        };
+        const recover = async () => {
+            for await (const rfq of items((query) => client.GET("/v1/rfqs", { params: { query: { ...query, limit: 100 } } }).then(unwrap), (page) => page.rfqs)) {
+                if (rfq.status === "OPEN")
+                    call(rfq);
+            }
+        };
+        const offs = [
+            stream.on("event", (event) => {
+                if (event.event_type === "RFQ_ACCEPTED" || event.event_type === "RFQ_CANCELLED" || event.event_type === "RFQ_FAILED") {
+                    ended.add(event.payload.rfq_id);
+                    if (ended.size > 10_000)
+                        ended.delete(ended.values().next().value);
+                    return;
+                }
+                afterAcceptances(() => void opened(event).catch(onError));
+            }),
+            stream.on("snapshot", (snapshot) => {
+                const resources = snapshot.resources;
+                // The acceptance listener ran first; a truncated snapshot's other acceptances are paged in before any RFQ is offered.
+                afterAcceptances(() => (resources.open_rfqs ?? []).forEach(call));
+                covered = !(snapshot.truncated ?? []).some((truncation) => truncation.resource === "open_rfqs");
+            }),
+            stream.on("status", (status) => {
+                if (status === "live" && !covered)
+                    afterAcceptances(() => void recover().catch(onError));
+                if (status !== "live")
+                    covered = false;
+            }),
+        ];
+        stream.start();
+        if (stream.status === "live")
+            afterAcceptances(() => void recover().catch(onError));
+        released.add(release);
+        return () => {
+            stopped = true;
+            offs.forEach((off) => off());
+            released.delete(release);
+            held.forEach(({ timer }) => clearTimeout(timer));
+            held.clear();
+        };
+    }
+    /** Vault transactions for this maker, for its controller wallet to sign and send. */
+    const controller = async () => {
+        const { owner } = unwrap(await client.GET("/v1/makers/{maker_id}/capital", { params: { path: { maker_id: makerId } } }));
+        return controllerTransactions(await deployment(), makerId, owner);
+    };
+    /**
+     * The pending vault withdrawal, if any, and what would block executing it
+     * now. Send `controller()`'s `executeWithdraw` once `pending.executable`.
+     */
+    const withdrawal = async () => unwrap(await client.GET("/v1/makers/{maker_id}/withdrawal", { params: { path: { maker_id: makerId } } }));
+    const settled = new Set(["NO_IMPROVEMENT", "FAILED"]);
+    const operationDone = new Set(["COMMITTED", "REVERTED", "EXPIRED_UNEXECUTED"]);
+    /**
+     * Ask for a collateral reduction and follow the job on the maker stream until
+     * it needs nothing more from the maker: NO_IMPROVEMENT, FAILED, or DURABLE
+     * with the attestation transaction ready (or already executed). A job stays
+     * QUEUED until `next_eligible_at`. With `signTransaction`, a wallet that
+     * holds HYPE for the gas (the maker wallet, or any other) signs the returned
+     * call as a raw EIP-1559 transaction, and it is submitted through the
+     * self-funded route. Without it, the job is returned with its `transaction`
+     * and `idempotencyKey`: sign the transaction yourself and submit it to
+     * `POST /v1/makers/{maker_id}/operations/{operation_id}/self-funded-transaction`
+     * under that same `Idempotency-Key`, the only one the route admits for this job.
+     */
+    async function reduceCollateral(request = {}) {
+        const path = { maker_id: makerId };
+        // The self-funded route admits the attestation only under the key that created the job.
+        const header = { "Idempotency-Key": uuidv7() };
+        const { job_id } = await sendOnce(() => client.POST("/v1/makers/{maker_id}/collateral-reductions", { params: { path, header } }));
+        const read = async (signal) => unwrap(await client.GET("/v1/makers/{maker_id}/collateral-reductions/{job_id}", { params: { path: { maker_id: makerId, job_id } }, signal, fetch: recoveryFetch }));
+        const ready = (job) => settled.has(job.status) ||
+            (job.status === "DURABLE" && (job.transaction !== null || (job.operation_status !== null && operationDone.has(job.operation_status))));
+        const job = await follow(stream, read, ready, (event) => (event.event_type === "COLLATERAL_REDUCTION_UPDATED" && event.payload.job_id === job_id) ||
+            event.event_type === "OPERATION_UPDATED", request.signal, clientOptions.retry || undefined);
+        const idempotencyKey = header["Idempotency-Key"];
+        if (job.transaction === null || job.operation_id === null || request.signTransaction === undefined)
+            return { job, idempotencyKey };
+        const { chain_id, to, data } = job.transaction;
+        const signed_transaction = (await request.signTransaction({ chain_id, to: address(to), data: calldata(data), value: "0" })).toLowerCase();
+        const submitted = await sendOnce(() => client.POST("/v1/makers/{maker_id}/operations/{operation_id}/self-funded-transaction", {
+            params: { path: { maker_id: makerId, operation_id: job.operation_id }, header }, body: { signed_transaction },
+        }));
+        return { job, idempotencyKey, submitted };
+    }
+    return {
+        client, stream, deployment, quote, bid, cancelQuote, renewQuoteLease, releaseQuoteLease, keepQuoteLease, confirm, onAcceptance, onRfq, controller, withdrawal, reduceCollateral,
+        close: () => {
+            stopLease?.();
+            stream.close();
+        },
+    };
+}
+/**
+ * Read the account's maker (`GET /v1/me/maker`) and, once indexed or
+ * `PENDING`, admit it (`POST /v1/me/maker`, unless `admit: false`). Admission needs no signature
+ * and repeats safely. The POST's 404 (no maker indexed yet) is `NOT_INDEXED`,
+ * not an error.
+ */
+export async function makerReadiness(client, options = {}) {
+    const init = options.signal === undefined ? {} : { signal: options.signal };
+    let { ownership } = unwrap(await client.GET("/v1/me/maker", init));
+    // A self-service PENDING profile is activated by the same POST; an operator decision keeps it as it is.
+    if ((ownership.state === "SETUP_REQUIRED" || ownership.state === "PENDING") && options.admit !== false) {
+        try {
+            ({ ownership } = unwrap(await client.POST("/v1/me/maker", init)));
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404)
+                return { state: "NOT_INDEXED", ownership };
+            throw error;
+        }
+        if (ownership.state === "SETUP_REQUIRED")
+            return { state: "NOT_INDEXED", ownership };
+    }
+    switch (ownership.state) {
+        case "READY":
+        case "PENDING":
+        case "RESTRICTED":
+            return { state: ownership.state, makerId: ownership.maker.maker_id, ownership };
+        case "NOT_CREATED":
+            return { state: "NOT_INDEXED", ownership };
+        default:
+            return { state: ownership.state, ownership };
+    }
+}
+/** `makerReadiness` again every `intervalMs` (default 3000) while `NOT_INDEXED`; resolves with the first other state. */
+export async function waitForMaker(client, options = {}) {
+    const { intervalMs = 3_000, ...read } = options;
+    for (;;) {
+        const readiness = await makerReadiness(client, read);
+        if (readiness.state !== "NOT_INDEXED")
+            return readiness;
+        await sleep(intervalMs, options.signal);
+    }
+}

package/dist/money.d.ts

@@ -0,0 +1,59 @@
+import type { components } from "./generated/openapi.js";
+type Schemas = components["schemas"];
+type Balance = Schemas["Balance"];
+type EntryTerms = Pick<Schemas["schemas-QuoteTerms"], "stake" | "payout" | "fee_bps" | "taker_fee_bps">;
+type CashoutTerms = {
+    readonly kind: "SELL_BACK";
+    readonly sell_back: Pick<Schemas["schemas-SellBackTerms"], "price">;
+} | {
+    readonly kind: "TRANSFER";
+    readonly transfer: Pick<Schemas["schemas-TransferTerms"], "price">;
+};
+/**
+ * Spendable Totalis cash from `GET /v1/me/balances`, in USDC base units, as
+ * the SDK plans entries and withdrawals with it. `null` means unknown (the
+ * component is not `CURRENT`), never 0: show it as unknown and read again.
+ * - `vault`: free vault cash (`VAULT_FREE`).
+ * - `wallet`: wallet USDC (`WALLET_USDC`) less `pending.wallet_reserved`
+ *   (open withdrawals, stake fundings and wallet deposits not yet committed),
+ *   floored at 0.
+ * - `total`: the venue's spendable `amount`; it subtracts withdrawals and
+ *   stake fundings but not a pending wallet deposit, which moves into the
+ *   vault, so it can exceed `vault + wallet` while a deposit is pending.
+ */
+export declare function spendableCash(balance: Pick<Balance, "amount" | "state" | "components" | "pending">): {
+    readonly vault: bigint | null;
+    readonly wallet: bigint | null;
+    readonly total: bigint | null;
+};
+/**
+ * What the owner receives from a gross close amount (a settlement payout or a
+ * sell-back price), as the vault pays it: the profit fee is
+ * `floor((amount - netStake) * feeBps / 10000)` on the part above the
+ * position's net stake, and nothing at or below it. `feeBps` and `netStake`
+ * are the position's own (`fee_bps`, `net_stake`), fixed when it opened.
+ */
+export declare function netOfProfitFee(amount: bigint | string, netStake: bigint | string, feeBps: number): bigint;
+/** A quote's net stake: the stake less the entry fee, `floor(stake * taker_fee_bps / 10000)`. */
+export declare function netStake(terms: Pick<EntryTerms, "stake" | "taker_fee_bps">): bigint;
+/**
+ * What the taker receives if every leg wins, net of the profit fee: the
+ * figure to show next to an entry quote, whose `payout` is gross. A fractional
+ * or partial result pays less; `netOfProfitFee` applies to whatever the
+ * position settles at. Example: stake 3 USDC at 20 bps entry fee and payout
+ * 9.18 USDC at 100 bps profit fee nets 9.118140 USDC.
+ */
+export declare function netPayout(quote: {
+    readonly entry: EntryTerms;
+} | EntryTerms): bigint;
+/**
+ * What the owner receives from a cash-out quote. A `TRANSFER` pays its price
+ * in full; a `SELL_BACK` withholds the position's profit fee on the price
+ * above its net stake. `position` is the position read (`GET
+ * /v1/me/positions/{position_id}`); `null` when its `net_stake` is unknown.
+ */
+export declare function netCashout(bid: CashoutTerms, position: {
+    readonly net_stake: string | null;
+    readonly fee_bps: number;
+}): bigint | null;
+export {};