@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/market/activeSwap.js

@@ -0,0 +1,320 @@
+/**
+ * The active swap basket (skein-amm 0.12.0, David Case 2026-10-21/22; 0.29.0,
+ * 2026-11-02): everything the swap legs spend, held outside the BRC-207 module
+ * in the exchange's own basket `amm-swap` (src/wallet/color.ts): the token
+ * outputs and each leg's sats.
+ *
+ *   - **In** (`sendToSwapBasket`): before the legs of a tokens-in swap, ONE
+ *     wallet-built send through the module: one 1Color value output per leg
+ *     not covered by what `amm-swap` already holds, each exactly the leg's
+ *     amount in (the pool takes no token change, so a leg needs inputs that
+ *     sum to its amount exactly), locked to a key derived from the leg's pool outpoint (`swapKeyID`) under `[2, "amm
+ *     swap"]` (counterparty self), the plan naming them a transfer out; and
+ *     (0.29.0) one P2PKH sats output per leg not covered (the leg's exact
+ *     sats, `swapFunding`), to that outpoint's `:sats` key, filed in
+ *     `amm-swap` by the createAction itself (customInstructions `{sats: true,
+ *     assetId, protocolID, keyID, counterparty}`). The module passes the sats outputs
+ *     through, selects the token inputs, adds change, asks once, signs and
+ *     submits to `tm_color_<assetId>`; the wallet funds the sats; the page
+ *     submits it to this skein too (a repeat is harmless), then files each
+ *     token output in `amm-swap` (basket insertion, customInstructions
+ *     `{assetId, amount, protocolID, keyID, counterparty}`). A sats-in swap,
+ *     or a tokens-in swap whose tokens are all staged already, sends only the
+ *     sats (`sendSatsToSwapBasket`: a plain createAction, no `p color` labels).
+ *   - **Spent** by the legs (src/market/swapAction.ts): app-built,
+ *     `createSignature` under the key the customInstructions name; the
+ *     wallet marks them spent when it takes the accepted swap in (0.29.0: no
+ *     relinquishOutput). An output a failed leg did not spend stays for a
+ *     later swap.
+ *   - **Move back** (`moveBack`, the recovery path; 0.29.3: a module plan,
+ *     David Case 2026-11-02): ONE createAction through the wallet's BRC-207
+ *     module, a `p color plan` transfer: every `amm-swap` token output of the
+ *     token and (0.29.1) the sats rows staged for its legs (their `assetId`)
+ *     as explicit inputs (their source transactions in `inputBEEF`) — to the
+ *     module FOREIGN inputs (not in a `p color` basket): the token rows
+ *     checked admitted and unspent on the token's overlay, the sats rows
+ *     adding nothing; one output, the whole amount to a NEW module receiving
+ *     key of the user's own, the plan's owned output 0 (the module checks it
+ *     pays the remittance's key and files it in `p color <assetTag>` with its
+ *     custody in the same call). The page unlocks its inputs at signAction;
+ *     the wallet funds the fee and takes the sats rows into its change; the
+ *     module approves and submits, the wallet broadcasts. The page submits it
+ *     to this skein's token topic too. Nothing is taken in afterwards and
+ *     nothing is kept in the browser. *     (0.29.6) With no token row and only sats rows staged for the token
+ *     (a sats-in leg that failed): one plain createAction (no `p color`
+ *     labels), the sats rows as explicit inputs and no outputs — the wallet
+ *     keeps them as its change and pays the fee (`moveBackSats`).
+ */
+import { Beef, P2PKH, PublicKey, Transaction, Utils } from "@bsv/sdk";
+import { decodeOneColor } from "../pool/index.js";
+import { parseOutpoint, parseTokenId, sdkTokenId, tokenIdOfWire, tokenIdText } from "../lib/tokenId.js";
+import { basketBeef, basketRows } from "../lp/wallet.js";
+import { tokenP2pkhScript } from "../lp/poolDeploy.js";
+import { steakText, submitToOverlay } from "../lp/close.js";
+import { SWAP_BASKET, SWAP_PROTOCOL, newReceivingKey, swapInstructions, swapSatsInstructions, runTokenAction, transferPlanLabels } from "../wallet/color.js";
+import { identityKeyOf } from "../wallet/brc29.js";
+import { inputIndexOf, runAppSignedAction } from "../wallet/action.js";
+import { P2PKH_UNLOCK_LENGTH, satsInputsOf, signP2pkhWithWallet, spendValid, tokenInputsOf } from "./swapAction.js";
+/** The keyID prefix of an `amm-swap` key (`SWAP_PROTOCOL`, counterparty self). */
+export const SWAP_KEY_PREFIX = "amm-swap-";
+function describe(text) {
+    return text.length <= 50 ? text : `${text.slice(0, 49)}…`;
+}
+/**
+ * The keyID of a staged `amm-swap` output (0.29.2, David Case 2026-11-02: derived, not random):
+ * `amm-swap-<txid>.<vout>` for a leg's token row and `amm-swap-<txid>.<vout>:sats` for its sats
+ * row, `<txid>.<vout>` the leg's pool outpoint as quoted (`leg.outpoint`, `_` written `.`).
+ * Protocol `[2, "amm swap"]`, counterparty self, as before. A leg refused and retried against the
+ * same pool outpoint stages to the same key again, which is fine.
+ */
+export function swapKeyID(poolOutpoint, kind) {
+    const op = parseOutpoint(poolOutpoint);
+    if (!op)
+        throw new Error(`not a pool outpoint: ${poolOutpoint}`);
+    return `${SWAP_KEY_PREFIX}${op.txid}.${op.vout}${kind === "sats" ? ":sats" : ""}`;
+}
+/** The `amm-swap` outputs of `tokenId` the legs can spend. */
+export async function swapHoldings(wallet, tokenId) {
+    return tokenInputsOf(await basketRows(wallet, SWAP_BASKET), tokenId);
+}
+/** The `amm-swap` sats outputs the legs can spend (0.29.0). */
+export async function swapSatsHoldings(wallet) {
+    return satsInputsOf(await basketRows(wallet, SWAP_BASKET));
+}
+/**
+ * What `amm-swap` holds, per token id: the token amount and the number of token outputs, and
+ * (0.29.6) the sats staged for the token's legs (the sats rows whose customInstructions name its
+ * `assetId`). A token with only sats staged has amount 0n and outputs 0.
+ */
+export async function swapTotals(wallet) {
+    const totals = new Map();
+    const rows = await basketRows(wallet, SWAP_BASKET);
+    for (const r of rows) {
+        if (!r.lockingScript)
+            continue;
+        const t = decodeOneColor(Utils.toArray(r.lockingScript, "hex"));
+        if (!t || t.role !== "value" || !t.idBytes)
+            continue;
+        const id = tokenIdOfWire(t.idBytes);
+        const s = totals.get(id) ?? { amount: 0n, outputs: 0, sats: 0 };
+        s.amount += t.amount;
+        s.outputs++;
+        totals.set(id, s);
+    }
+    for (const r of satsInputsOf(rows)) {
+        const ref = r.assetId ? parseTokenId(r.assetId) : null;
+        if (!ref)
+            continue;
+        const id = tokenIdText(ref);
+        const s = totals.get(id) ?? { amount: 0n, outputs: 0, sats: 0 };
+        s.sats += r.satoshis;
+        totals.set(id, s);
+    }
+    return totals;
+}
+/** The source transactions of `amm-swap`'s outputs (a leg's BEEF), with `extra` merged in. */
+export async function swapHoldingBeef(wallet, extra) {
+    const beef = (await basketBeef(wallet, SWAP_BASKET)) ?? new Beef();
+    if (extra)
+        beef.mergeBeef(Beef.fromBinary(extra));
+    return beef;
+}
+/** The "amm swap" keys (`swapKeyID`) for `sats` and their outputs, filed in `amm-swap` by the createAction itself. */
+async function satsOutputs(wallet, sats, sym, assetId) {
+    return await Promise.all(sats.map(async ({ satoshis, pool }) => {
+        if (!Number.isSafeInteger(satoshis) || satoshis <= 0)
+            throw new Error("nothing to send to the swap basket");
+        const keyID = swapKeyID(pool, "sats");
+        const { publicKey } = await wallet.getPublicKey({ protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", forSelf: true });
+        const lockingScript = new P2PKH().lock(PublicKey.fromString(publicKey).toAddress()).toHex();
+        return {
+            keyID,
+            assetId,
+            satoshis,
+            lockingScript,
+            output: {
+                lockingScript,
+                satoshis,
+                outputDescription: describe(`Sats for a ${sym} swap leg`),
+                basket: SWAP_BASKET,
+                customInstructions: swapSatsInstructions({ assetId, protocolID: SWAP_PROTOCOL, keyID, counterparty: "self" }),
+            },
+        };
+    }));
+}
+/** The send's sats outputs from `first` on, as `SatsInput`s (an output the wallet moved is an error). */
+function satsHeld(final, txid, keys, first, errors) {
+    const out = [];
+    keys.forEach((k, n) => {
+        const vout = first + n;
+        const o = final.outputs[vout];
+        if (!o || o.lockingScript.toHex() !== k.lockingScript || o.satoshis !== k.satoshis) {
+            errors.push(`the wallet's send has no output ${vout} to the swap key`);
+            return;
+        }
+        out.push({ outpoint: `${txid}.${vout}`, txid, vout, satoshis: k.satoshis, lockingScript: k.lockingScript, protocolID: SWAP_PROTOCOL, keyID: k.keyID, counterparty: "self", assetId: k.assetId });
+    });
+    return out;
+}
+/**
+ * "In" (see the module comment): one module send of `stage.tokens` (each one
+ * output) to `amm-swap` keys derived from each leg's pool (`swapKeyID`), filed in `amm-swap`, and of `stage.sats`
+ * (each one output) after them. Throws when the wallet refuses or fails the
+ * send; filing and the page's own submit are reported in `errors`.
+ */
+export async function sendToSwapBasket(wallet, base, tokenId, stage, meta = {}, submit = (topic, beef) => submitToOverlay(base, topic, beef)) {
+    const amounts = stage.tokens;
+    if (amounts.length === 0 || amounts.some((a) => a.amount <= 0n))
+        throw new Error("nothing to send to the swap basket");
+    const assetId = sdkTokenId(tokenId);
+    const sym = meta.sym ?? "token";
+    const keys = await Promise.all(amounts.map(async ({ amount, pool }) => {
+        const keyID = swapKeyID(pool, "token");
+        const { publicKey } = await wallet.getPublicKey({ protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", forSelf: true });
+        return { amount, keyID, publicKey, lockingScript: tokenP2pkhScript(assetId, amount, publicKey) };
+    }));
+    const satsKeys = await satsOutputs(wallet, stage.sats, sym, assetId);
+    const { txid, tx } = await runTokenAction(wallet, {
+        description: describe(`AMM swap: ${sym} into the swap basket`),
+        labels: [...transferPlanLabels(assetId), "amm-swap"],
+        outputs: [...keys.map((k) => ({ lockingScript: k.lockingScript, satoshis: 1, outputDescription: describe(`${sym} for a swap leg`) })), ...satsKeys.map((k) => k.output)],
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+    });
+    const out = { txid, tx, holdings: [], sats: [], filed: false, submitted: "not submitted", errors: [] };
+    const final = Transaction.fromAtomicBEEF(tx);
+    keys.forEach((k, vout) => {
+        const o = final.outputs[vout];
+        if (!o || o.lockingScript.toHex() !== k.lockingScript) {
+            out.errors.push(`the wallet's send has no output ${vout} to the swap key`);
+            return;
+        }
+        out.holdings.push({ outpoint: `${txid}.${vout}`, txid, vout, satoshis: o.satoshis, lockingScript: k.lockingScript, amount: k.amount, protocolID: SWAP_PROTOCOL, keyID: k.keyID, counterparty: "self" });
+    });
+    out.sats = satsHeld(final, txid, satsKeys, keys.length, out.errors);
+    try {
+        out.submitted = steakText(await submit(`tm_color_${assetId}`, tx));
+    }
+    catch (err) {
+        out.submitted = "the submit failed";
+        out.errors.push(`submit: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const rows = out.holdings.map((h) => ({
+        outputIndex: h.vout,
+        protocol: "basket insertion",
+        insertionRemittance: { basket: SWAP_BASKET, customInstructions: swapInstructions({ assetId, amount: h.amount, protocolID: SWAP_PROTOCOL, keyID: h.keyID, counterparty: "self" }) },
+    }));
+    try {
+        const r = await wallet.internalizeAction({ tx, outputs: rows, description: describe(`AMM swap: ${sym} into the swap basket`), labels: ["amm-swap"] });
+        out.filed = r.accepted;
+    }
+    catch (err) {
+        out.errors.push(`internalizeAction: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out;
+}
+/**
+ * The sats-only send (0.29.0): one plain createAction (no `p color` labels: the module is not in
+ * the path) with one P2PKH output per amount to the leg's "amm swap" `:sats` key (`swapKeyID`), filed in `amm-swap`; the
+ * wallet funds it, adds change and broadcasts. Throws when the wallet refuses or fails it.
+ */
+export async function sendSatsToSwapBasket(wallet, tokenId, sats, meta = {}) {
+    if (sats.length === 0)
+        throw new Error("nothing to send to the swap basket");
+    const sym = meta.sym ?? "token";
+    const keys = await satsOutputs(wallet, sats, sym, sdkTokenId(tokenId));
+    const { txid, tx } = await runTokenAction(wallet, {
+        description: describe(`AMM swap: sats into the swap basket`),
+        labels: ["amm-swap"],
+        outputs: keys.map((k) => k.output),
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+    });
+    const errors = [];
+    return { txid, tx, sats: satsHeld(Transaction.fromAtomicBEEF(tx), txid, keys, 0, errors), errors };
+}
+/** The page's unlocking scripts for the `amm-swap` outputs `holdings` in the wallet's transaction `tx`, each checked with `Spend`. */
+export async function swapBasketSpends(wallet, tx, holdings, what) {
+    const spends = {};
+    for (const h of holdings) {
+        const n = inputIndexOf(tx, h.txid, h.vout);
+        if (n < 0)
+            throw new Error(`the wallet's ${what} does not spend the swap basket output ${h.outpoint}`);
+        tx.inputs[n].unlockingScript = await signP2pkhWithWallet(wallet, tx, n, h);
+        if (!spendValid(tx, n))
+            throw new Error(`input ${n} of the ${what} does not validate`);
+        spends[n] = { unlockingScript: tx.inputs[n].unlockingScript.toHex() };
+    }
+    return spends;
+}
+/**
+ * "Move back" (see the module comment; 0.29.3: a module plan). Throws before anything is
+ * broadcast (no outputs, a wallet or module refusal, an input that does not validate: the action
+ * is aborted). The module files the output in `p color <assetTag>` with its custody in the same
+ * createAction: no take-in afterwards, nothing kept in the browser. The page's own submit to this
+ * skein's token topic (the module submitted at the wallet's overlay too) is reported in `errors`.
+ */
+export async function moveBack(i) {
+    const { wallet } = i;
+    const assetId = sdkTokenId(i.tokenId);
+    const sym = i.meta?.sym ?? "token";
+    const topic = `tm_color_${assetId}`;
+    const rows = await basketRows(wallet, SWAP_BASKET);
+    const holdings = tokenInputsOf(rows, assetId);
+    // 0.29.1 (David): the token's sats rows (staged for its legs) go in too; the wallet's change takes their sats.
+    const satsRows = satsInputsOf(rows).filter((r) => r.assetId === assetId);
+    if (holdings.length === 0 && satsRows.length > 0)
+        return await moveBackSats(wallet, sym, satsRows);
+    if (holdings.length === 0)
+        throw new Error(`the swap basket holds no ${sym}`);
+    const amount = holdings.reduce((a, h) => a + h.amount, 0n);
+    const sources = await swapHoldingBeef(wallet);
+    for (const h of [...holdings, ...satsRows])
+        if (!sources.findTxid(h.txid))
+            throw new Error(`the wallet's BEEF lacks the swap basket output ${h.outpoint}`);
+    // The output: the whole amount to a module receiving key of the user's own, the plan's owned output 0.
+    const me = await identityKeyOf(wallet);
+    const key = await newReceivingKey(wallet, assetId, me);
+    const lockingScript = tokenP2pkhScript(assetId, amount, key.publicKey);
+    const { txid, tx: beef } = await runAppSignedAction(wallet, {
+        description: describe(`AMM move back: ${sym}`),
+        inputBEEF: sources.toBinary(),
+        inputs: [
+            ...holdings.map((h) => ({ outpoint: h.outpoint, unlockingScriptLength: P2PKH_UNLOCK_LENGTH, inputDescription: describe(`${sym} in the swap basket`) })),
+            ...satsRows.map((h) => ({ outpoint: h.outpoint, unlockingScriptLength: P2PKH_UNLOCK_LENGTH, inputDescription: describe(`Sats staged for a ${sym} swap`) })),
+        ],
+        outputs: [{ lockingScript, satoshis: 1, outputDescription: describe(`${sym} back to your wallet`) }],
+        labels: [...transferPlanLabels(assetId, { ownedOutputs: [{ outputIndex: 0, ...key.receipt }] }), "amm-swap"],
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+    }, (tx) => swapBasketSpends(wallet, tx, [...holdings, ...satsRows], "move back"));
+    const out = { txid, amount, beef, submitted: "not submitted", errors: [] };
+    try {
+        out.submitted = steakText(await (i.submit ?? ((t, b) => submitToOverlay(i.base, t, b)))(topic, beef));
+    }
+    catch (err) {
+        out.submitted = "the submit failed";
+        out.errors.push(`submit: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out;
+}
+/**
+ * Move back with only sats staged for the token (0.29.6, David Case 2026-11-03: a sats-in leg that
+ * failed leaves sats and no token): ONE plain wallet createAction (no `p color` labels, the module
+ * is not in the path) with the token's `amm-swap` sats rows as explicit inputs (their sources in
+ * `inputBEEF`) and NO outputs: the wallet keeps everything as its change and pays the fee from it.
+ * The page unlocks the rows at signAction; the wallet broadcasts and marks the rows spent itself
+ * (no relinquish, no take-in, nothing kept). Nothing is submitted to an overlay (no token moves).
+ */
+async function moveBackSats(wallet, sym, satsRows) {
+    const sources = await swapHoldingBeef(wallet);
+    for (const h of satsRows)
+        if (!sources.findTxid(h.txid))
+            throw new Error(`the wallet's BEEF lacks the swap basket output ${h.outpoint}`);
+    const { txid, tx: beef } = await runAppSignedAction(wallet, {
+        description: describe(`AMM move back: ${sym} sats`),
+        inputBEEF: sources.toBinary(),
+        inputs: satsRows.map((h) => ({ outpoint: h.outpoint, unlockingScriptLength: P2PKH_UNLOCK_LENGTH, inputDescription: describe(`Sats staged for a ${sym} swap`) })),
+        outputs: [],
+        labels: ["amm-swap"],
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+    }, (tx) => swapBasketSpends(wallet, tx, satsRows, "move back"));
+    return { txid, amount: 0n, beef, submitted: "not submitted (no token moved)", errors: [] };
+}

package/dist/market/plan.d.ts

@@ -0,0 +1,85 @@
+import type { Direction, Plan, PlanRequest, PoolState } from "@dcasegr/amm-engine";
+import type { LiveAnswer } from "../lib/overlay.js";
+import { type ValidatorStatus } from "./view.js";
+/**
+ * Estimated miner fee per leg, in sats, for the engine's per-leg cost
+ * heuristic: a swap is ~13 KB (docs/notes.md, "Publishing is part of
+ * submit") at the client's fee rate (`createClient`'s `feeRateSatsPerKb`; the pages':
+ * `VITE_FEE_RATE`). The exact fee of a built swap is `swapFunding` (src/market/swapAction.ts).
+ */
+export declare function legMinerFeeSats(satsPerKb: number): bigint;
+/** `legMinerFeeSats` at the default rate (100 sats/kB). */
+export declare const LEG_MINER_FEE_SATS: bigint;
+export interface SwapForm {
+    direction: Direction;
+    /** Sats (bsvToToken) or tokens in display units (tokenToBsv). */
+    amount: string;
+    slippageBps: string;
+    allowPartial: boolean;
+}
+export type PlanInput = {
+    ok: true;
+    request: PlanRequest;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The pools the planner may use (0.4.0, shruggr/skein#120): those whose validator is in the token's
+ * liveness (0.34.0: the pools route's rows, src/lib/overlay.ts `liveOfPools`: the host listed only the pools whose validator beats; before, the `.live` read), which holds only the beats within the
+ * instance's own window. No read, none.
+ */
+export declare function livePools(pools: PoolState[], live: LiveAnswer | null): PoolState[];
+/**
+ * Parses the form against one token's pools; only the pools whose validator is live (`livePools`)
+ * are planned. `dec` scales a token amount (base units when unknown).
+ */
+export declare function buildPlanRequest(tokenId: string, form: SwapForm, pools: PoolState[], live: LiveAnswer | null, dec: number | undefined, 
+/** The miner fee rate the per-leg cost is estimated at, sats per 1000 bytes (default 100). */
+satsPerKb?: number): PlanInput;
+export interface LegView {
+    outpoint: string;
+    pool: PoolState;
+    amountIn: bigint;
+    amountOut: bigint;
+    lpFee: bigint;
+    validatorFee: bigint;
+    /** The pool's commission (CommissionBps of amountIn), in the input asset; 0 for a pool with none. */
+    commission: bigint;
+    validator: ValidatorStatus;
+}
+export interface PlanView {
+    direction: Direction;
+    legs: LegView[];
+    totalIn: bigint;
+    totalOut: bigint;
+    /** In the input asset (LP and validator fees and the commission are taken from amountIn). */
+    lpFees: bigint;
+    validatorFees: bigint;
+    commissions: bigint;
+    /** Sats per display token paid (bsvToToken) or received (tokenToBsv). */
+    effectivePrice: string;
+    /** The best pool's marginal price, same unit. */
+    midPrice: string;
+    /** What the order would get at the mid price, minus what the plan gets, in bps of the former (fees included). */
+    slippageVsMidBps: bigint;
+    /** The engine's absolute bound (from toleranceBps against its quoted mid). */
+    minAmountOut: bigint;
+    meetsSlippageBound: boolean;
+    filledCompletely: boolean;
+    /** amountIn the plan leaves unfilled. */
+    unfilled: bigint;
+}
+export declare function planView(p: Plan, inventory: PoolState[], live: LiveAnswer | null, dec: number | undefined): PlanView;
+/** Plans with the engine and shapes the result. */
+export declare function quote(request: PlanRequest, live: LiveAnswer | null, dec: number | undefined): {
+    plan: Plan;
+    view: PlanView;
+};
+/**
+ * Races (docs/notes.md "Market UI and matching engine"): the plan's pools
+ * that are no longer in a fresh lookup answer (spent by someone else's swap
+ * since the plan was made). A pool's outpoint changes on every spend, so
+ * "gone" is exactly "not listed".
+ */
+export declare function goneFromLookup(planned: Pick<Plan, "legs">, fresh: PoolState[]): string[];

package/dist/market/plan.js

@@ -0,0 +1,149 @@
+/**
+ * The swap form → the engine's `PlanRequest`, and the engine's `Plan` → what
+ * the page shows (pure). The planning itself is the engine's (`plan`, partial
+ * fills across several pools when allowed); nothing is re-derived here except
+ * display numbers: per-leg fees (LP, validator, commission), effective price
+ * and slippage against the mid price.
+ */
+import { plan as enginePlan } from "@dcasegr/amm-engine";
+import { DEFAULT_FEE_RATE_SATS_PER_KB } from "../lib/config.js";
+import { parseAmount } from "../lp/amounts.js";
+import { priceOf, validatorStatus, withLastSeen } from "./view.js";
+/**
+ * Estimated miner fee per leg, in sats, for the engine's per-leg cost
+ * heuristic: a swap is ~13 KB (docs/notes.md, "Publishing is part of
+ * submit") at the client's fee rate (`createClient`'s `feeRateSatsPerKb`; the pages':
+ * `VITE_FEE_RATE`). The exact fee of a built swap is `swapFunding` (src/market/swapAction.ts).
+ */
+export function legMinerFeeSats(satsPerKb) {
+    return BigInt(Math.ceil(13 * satsPerKb));
+}
+/** `legMinerFeeSats` at the default rate (100 sats/kB). */
+export const LEG_MINER_FEE_SATS = legMinerFeeSats(DEFAULT_FEE_RATE_SATS_PER_KB);
+/**
+ * The pools the planner may use (0.4.0, shruggr/skein#120): those whose validator is in the token's
+ * liveness (0.34.0: the pools route's rows, src/lib/overlay.ts `liveOfPools`: the host listed only the pools whose validator beats; before, the `.live` read), which holds only the beats within the
+ * instance's own window. No read, none.
+ */
+export function livePools(pools, live) {
+    if (!live)
+        return [];
+    return pools.filter((p) => validatorStatus(p.validatorIdentityKey, live).live);
+}
+/**
+ * Parses the form against one token's pools; only the pools whose validator is live (`livePools`)
+ * are planned. `dec` scales a token amount (base units when unknown).
+ */
+export function buildPlanRequest(tokenId, form, pools, live, dec, 
+/** The miner fee rate the per-leg cost is estimated at, sats per 1000 bytes (default 100). */
+satsPerKb = DEFAULT_FEE_RATE_SATS_PER_KB) {
+    if (!form.amount.trim())
+        return { ok: false, error: "enter an amount" };
+    let amountIn;
+    try {
+        amountIn = parseAmount(form.amount, form.direction === "bsvToToken" ? 0 : (dec ?? 0));
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    if (amountIn <= 0n)
+        return { ok: false, error: "the amount must be positive" };
+    let toleranceBps;
+    try {
+        toleranceBps = BigInt(form.slippageBps.trim() || "0");
+    }
+    catch {
+        return { ok: false, error: "slippage: whole basis points" };
+    }
+    if (toleranceBps < 0n || toleranceBps > 10000n)
+        return { ok: false, error: "slippage: 0-10000 bps" };
+    if (pools.length === 0)
+        return { ok: false, error: "no pools for this token" };
+    const usable = livePools(pools, live);
+    if (usable.length === 0) {
+        return {
+            ok: false,
+            error: !live
+                ? "no liveness read for this token: no pool can be planned"
+                : !live.kept
+                    ? "this instance keeps no liveness for this token (its market role is off for it): no validator is known live"
+                    : "no pool's validator is live on this token",
+        };
+    }
+    const fixedCost = { minerFeeSats: legMinerFeeSats(satsPerKb) };
+    return {
+        ok: true,
+        request: {
+            tokenId,
+            direction: form.direction,
+            amountIn,
+            slippage: { toleranceBps },
+            allowPartial: form.allowPartial,
+            fixedCost,
+            inventory: withLastSeen(usable, live),
+        },
+    };
+}
+export function planView(p, inventory, live, dec) {
+    const byOutpoint = new Map(inventory.map((x) => [x.outpoint, x]));
+    const legs = p.legs.map((l) => {
+        const pool = byOutpoint.get(l.outpoint);
+        return {
+            outpoint: l.outpoint,
+            pool,
+            amountIn: l.amountIn,
+            amountOut: l.amountOut,
+            lpFee: l.liquidityFee,
+            validatorFee: l.validationFee,
+            commission: l.commission,
+            validator: validatorStatus(pool.validatorIdentityKey, live),
+        };
+    });
+    const sum = (f) => legs.reduce((a, l) => a + f(l), 0n);
+    const totalIn = sum((l) => l.amountIn);
+    const totalOut = sum((l) => l.amountOut);
+    const bsvToToken = p.direction === "bsvToToken";
+    // Mid: the best pool's marginal price (most output per unit in), pre-fee.
+    let best;
+    for (const x of inventory) {
+        if (!best)
+            best = x;
+        else if (bsvToToken ? x.tokenReserve * best.bsvReserve > best.tokenReserve * x.bsvReserve : x.bsvReserve * best.tokenReserve > best.bsvReserve * x.tokenReserve)
+            best = x;
+    }
+    let midOut = 0n;
+    if (best && totalIn > 0n)
+        midOut = bsvToToken ? (totalIn * best.tokenReserve) / best.bsvReserve : (totalIn * best.bsvReserve) / best.tokenReserve;
+    const slippageVsMidBps = midOut > 0n ? ((midOut - totalOut) * 10000n) / midOut : 0n;
+    return {
+        direction: p.direction,
+        legs,
+        totalIn,
+        totalOut,
+        lpFees: sum((l) => l.lpFee),
+        validatorFees: sum((l) => l.validatorFee),
+        commissions: sum((l) => l.commission),
+        effectivePrice: bsvToToken ? priceOf(totalIn, totalOut, dec) : priceOf(totalOut, totalIn, dec),
+        midPrice: best ? priceOf(best.bsvReserve, best.tokenReserve, dec) : "—",
+        slippageVsMidBps,
+        minAmountOut: p.resolvedMinAmountOut,
+        meetsSlippageBound: p.meetsSlippageBound,
+        filledCompletely: p.filledCompletely,
+        unfilled: p.originalAmountIn - totalIn,
+    };
+}
+/** Plans with the engine and shapes the result. */
+export function quote(request, live, dec) {
+    const p = enginePlan(request);
+    return { plan: p, view: planView(p, request.inventory, live, dec) };
+}
+/**
+ * Races (docs/notes.md "Market UI and matching engine"): the plan's pools
+ * that are no longer in a fresh lookup answer (spent by someone else's swap
+ * since the plan was made). A pool's outpoint changes on every spend, so
+ * "gone" is exactly "not listed".
+ */
+export function goneFromLookup(planned, fresh) {
+    const live = new Set(fresh.map((p) => p.outpoint));
+    return planned.legs.map((l) => l.outpoint).filter((op) => !live.has(op));
+}

package/dist/market/prices.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices): a token's price comes from
+ * its pool list — the pools route the host answers (`GET <origin>/amm/pools`, held as an event
+ * stream on every page) — Σsats / Σtokens over the pools listed there (the host lists only pools
+ * whose validator is beating). No price is derived from beats (the 0.9.0 beat prices are gone);
+ * the depth is the sats a buy needs to move the price up by 2%, x·(√1.02 − 1), over the summed
+ * sats.
+ */
+/** The sats a buy needs to move the marginal price up by `bps`, over `sats` summed reserves; null with none. */
+export declare function depthOf(sats: bigint, bps?: number): {
+    bps: number;
+    sats: bigint;
+} | null;

package/dist/market/prices.js

@@ -0,0 +1,14 @@
+/**
+ * Prices (0.34.0, D6, David Case 2026-11-04: one source for prices): a token's price comes from
+ * its pool list — the pools route the host answers (`GET <origin>/amm/pools`, held as an event
+ * stream on every page) — Σsats / Σtokens over the pools listed there (the host lists only pools
+ * whose validator is beating). No price is derived from beats (the 0.9.0 beat prices are gone);
+ * the depth is the sats a buy needs to move the price up by 2%, x·(√1.02 − 1), over the summed
+ * sats.
+ */
+/** The sats a buy needs to move the marginal price up by `bps`, over `sats` summed reserves; null with none. */
+export function depthOf(sats, bps = 200) {
+    if (sats === 0n)
+        return null;
+    return { bps, sats: BigInt(Math.round(Number(sats) * (Math.sqrt(1 + bps / 10_000) - 1))) };
+}

package/dist/market/relay.d.ts

@@ -0,0 +1,84 @@
+import type { PoolState } from "@dcasegr/amm-engine";
+export declare const SWAP_SUBMIT_FN = "amm.swap.submit";
+export declare const SWAP_STATUS_FN = "amm.swap.status";
+export declare const SWAP_TERMS_FN = "amm.swap.terms";
+/** The relay's terms: where it takes the commission (hash160 hex), or null when it names none; this market's minimum commission (bps, 0 when unset). */
+export interface SwapTerms {
+    commissionPkh: string | null;
+    minCommissionBps: number;
+}
+/** What the relay needs of `AuthFetch` (and what the tests fake). */
+export interface AuthFetchLike {
+    fetch(url: string, config?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }): Promise<Pick<Response, "status" | "text">>;
+}
+export interface SwapSubmit {
+    /** The funding transaction as AtomicBEEF (the swap's unproven parent, with its ancestry). */
+    funding: number[];
+    /** Raw swap transaction, the validator's slot empty. */
+    swap: number[];
+    /** The pool outpoint the swap spends, `<txid>_<vout>`. */
+    pool: string;
+    /** The pool's validator identity key (hex; sent as 33 bytes). */
+    validator: string;
+    /** The validator's libp2p peer ID (text), as the liveness read gave it: what the relay dials. */
+    peerId: string;
+    /** Unix ms after which the relay gives up. */
+    expires: number;
+}
+export type SwapRecord = {
+    id: string;
+    status: "pending";
+} | {
+    id: string;
+    status: "accepted";
+    tx: number[];
+    txid: string;
+} | {
+    id: string;
+    status: "refused";
+    reason: string;
+    pool?: PoolState;
+} | {
+    id: string;
+    status: "timeout";
+} | {
+    id: string;
+    status: "failed";
+    reason: string;
+};
+export declare class RelayError extends Error {
+    readonly code: string;
+    readonly httpStatus: number;
+    constructor(code: string, message: string, httpStatus: number);
+}
+export declare function dagBytes(bytes: number[]): {
+    "/": {
+        bytes: string;
+    };
+};
+/** DAG-JSON bytes, hex, or a byte array → bytes; null otherwise. */
+export declare function readBytes(x: unknown): number[] | null;
+export declare function callUrl(base: string): string;
+export declare function submitBody(s: SwapSubmit): {
+    fn: string;
+    args: Record<string, unknown>;
+};
+/** One `{fn, args}` call on the app's `/call` route. Throws `RelayError` on an error answer. */
+export declare function callApp(af: AuthFetchLike, base: string, fn: string, args: unknown): Promise<unknown>;
+/**
+ * A refusal's pool, as the validator writes it (messages.zig poolValue:
+ * `lpFeeBps`, `validatorFeeBps`, `validatorIdentity`) or as the lookup does
+ * (the engine's names), into the engine's PoolState. A closed pool, or one
+ * missing a field, is undefined: nothing left to re-price.
+ */
+export declare function toPoolState(raw: unknown): PoolState | undefined;
+export declare function parseSwapRecord(x: unknown): SwapRecord;
+/** `amm.swap.terms`'s answer: `commissionPkh` as DAG-JSON bytes (or hex, or a byte array) of 20 bytes, or null / absent; `minCommissionBps` an integer 0 to 10 000, absent 0 (0.16.0). */
+export declare function parseSwapTerms(x: unknown): SwapTerms;
+export declare function swapTerms(af: AuthFetchLike, base: string): Promise<SwapTerms>;
+export declare function submitSwap(af: AuthFetchLike, base: string, s: SwapSubmit): Promise<SwapRecord>;
+export declare function swapStatus(af: AuthFetchLike, base: string, id: string): Promise<SwapRecord>;