@dcasegr/amm-client 0.39.0 → 0.42.2

package/dist/market/activeSwap.js

@@ -1,53 +1,32 @@
 /**
- * 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.
+ * The active swap basket (skein-amm 0.12.0, David Case 2026-10-21/22; 0.40.0, agent-env
+ * plans/swap-balance-build-2026-11-05.md §0 7, Builder 2 item 2): what a swap stages for its legs,
+ * held outside the BRC-207 module in the exchange's own basket `amm-swap` (src/wallet/color.ts).
+ * No deposit, no withdraw, no balance the user manages.
  *
- *   - **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`).
+ *   - **Staging** (`stage`): at Swap, ONE wallet action. Sats only (a buy, or a sell whose tokens
+ *     the basket holds): a plain createAction, ONE P2PKH output to a fresh key under `SWAP_PROTOCOL`
+ *     (self, keyID random, `amm-swap-<hex>`), filed in `amm-swap` by the action with its
+ *     customInstructions (`{sats: true, protocolID, keyID, counterparty}`: no token tag). With
+ *     tokens: the module transfer plan — ONE token output to a fresh key and the ONE sats output in
+ *     the same action, the token key's id ALSO in that output's description (`… · amm-swap <hex>`,
+ *     as the LP key's `amm-lp <hex>`), the action labelled `SWAP_STAGE_LABEL`; the module selects
+ *     the token inputs, adds change, signs and submits; the page submits it too, then files the
+ *     token output in `amm-swap` (basket insertion, `{assetId, amount, protocolID, keyID,
+ *     counterparty}`). A labelled staged token output the basket lacks (the page died before the
+ *     filing) is filed on load from the action's description (`unfiledStagedTokens`).
+ *   - **Spent** by the legs (src/market/swapAction.ts), their change kept here between legs.
+ *   - **Move back** (`moveBack`, as 0.29.3): ONE createAction through the wallet's BRC-207 module,
+ *     a `p color plan` transfer: every `amm-swap` token row of the token and every sats row as
+ *     explicit inputs (their source transactions in `inputBEEF`), one output — the whole amount to
+ *     a NEW module receiving key of the user's own, the plan's owned output 0. The page unlocks its
+ *     inputs at signAction; the wallet funds the fee and takes the sats into its change. With no
+ *     token row and sats rows staged: one plain createAction, the sats rows as explicit inputs and
+ *     no outputs (`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 { sdkTokenId, tokenIdOfWire } from "../lib/tokenId.js";
 import { basketBeef, basketRows } from "../lp/wallet.js";
 import { tokenP2pkhScript } from "../lp/poolDeploy.js";
 import { steakText, submitToOverlay } from "../lp/close.js";
@@ -57,21 +36,28 @@ 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-";
+/** The label of a staging action that carries tokens (0.40.0): the staged token output's key id is in its output description. */
+export const SWAP_STAGE_LABEL = "amm-swap-stage";
+/** The marker a staged token output's description ends with (` · amm-swap <hex>`, 0.40.0): it names the key id. */
+export const SWAP_KEY_MARK = " · 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" : ""}`;
+/** A staged row's keyID (0.40.0): `amm-swap-<16 random bytes, hex>`. */
+export function newSwapKeyID() {
+    return `${SWAP_KEY_PREFIX}${Utils.toHex(Array.from(crypto.getRandomValues(new Uint8Array(16))))}`;
+}
+/** A staged token output's description: the readable text (at most 50 characters), then `SWAP_KEY_MARK` and the keyID's hex. */
+export function swapKeyDescription(readable, keyID) {
+    const hex = keyID.startsWith(SWAP_KEY_PREFIX) ? keyID.slice(SWAP_KEY_PREFIX.length) : "";
+    if (!/^[0-9a-f]{2,128}$/.test(hex))
+        throw new Error(`not a staged key id: ${keyID}`);
+    return `${describe(readable)}${SWAP_KEY_MARK}${hex}`;
+}
+/** The keyID a staged token output's description names (`swapKeyDescription`), or null. */
+export function swapKeyIdOfDescription(description) {
+    const m = / · amm-swap ([0-9a-f]{2,128})$/.exec(description ?? "");
+    return m && m[1].length % 2 === 0 ? `${SWAP_KEY_PREFIX}${m[1]}` : null;
 }
 /** The `amm-swap` outputs of `tokenId` the legs can spend. */
 export async function swapHoldings(wallet, tokenId) {
@@ -81,37 +67,27 @@ export async function swapHoldings(wallet, tokenId) {
 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.
- */
+/** What `amm-swap` holds, per token id: the token amount and the number of token outputs (0.40.0: the sats rows are no token's, `swapSatsTotal`). */
 export async function swapTotals(wallet) {
     const totals = new Map();
-    const rows = await basketRows(wallet, SWAP_BASKET);
-    for (const r of rows) {
+    for (const r of await basketRows(wallet, SWAP_BASKET)) {
         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 };
+        const s = totals.get(id) ?? { amount: 0n, outputs: 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 sats `amm-swap` holds (0.40.0: shown once, not per token). */
+export async function swapSatsTotal(wallet) {
+    return (await swapSatsHoldings(wallet)).reduce((a, r) => a + r.satoshis, 0);
+}
 /** 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();
@@ -119,92 +95,78 @@ export async function swapHoldingBeef(wallet, 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`.
+ * Staging (see the module comment): ONE wallet action. Throws when the wallet refuses or fails it;
+ * the token row's 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");
+export async function stage(wallet, req, o = {}) {
+    // The sats output: what the basket lacks of the fee sats (with tokens it may lack none).
+    if (!Number.isSafeInteger(req.sats) || req.sats < 0 || (req.sats === 0 && !req.tokens))
+        throw new Error("nothing to stage in the swap basket");
+    const sym = o.sym ?? "token";
+    const satsKeyID = newSwapKeyID();
+    const satsPub = (await wallet.getPublicKey({ protocolID: SWAP_PROTOCOL, keyID: satsKeyID, counterparty: "self", forSelf: true })).publicKey;
+    const satsScript = new P2PKH().lock(PublicKey.fromString(satsPub).toAddress()).toHex();
+    const satsOutput = {
+        lockingScript: satsScript,
+        satoshis: req.sats,
+        outputDescription: describe(`Sats for a ${sym} swap`),
+        basket: SWAP_BASKET,
+        customInstructions: swapSatsInstructions({ protocolID: SWAP_PROTOCOL, keyID: satsKeyID, counterparty: "self" }),
+    };
+    const satsRow = (txid, vout) => ({ outpoint: `${txid}.${vout}`, txid, vout, satoshis: req.sats, lockingScript: satsScript, protocolID: SWAP_PROTOCOL, keyID: satsKeyID, counterparty: "self" });
+    if (!req.tokens) {
+        const { txid, tx } = await runTokenAction(wallet, {
+            description: describe("AMM swap: sats into the swap basket"),
+            labels: ["amm-swap"],
+            outputs: [satsOutput],
+            options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+        });
+        const final = Transaction.fromAtomicBEEF(tx);
+        if (final.outputs[0]?.lockingScript.toHex() !== satsScript)
+            throw new Error("the wallet's action has no output 0 to the swap key");
+        return { txid, tx, sats: satsRow(txid, 0), filed: false, submitted: "not submitted (no token moved)", errors: [] };
+    }
+    const { tokenId, amount } = req.tokens;
+    if (amount <= 0n)
+        throw new Error("nothing to stage in 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 keyID = newSwapKeyID();
+    const pub = (await wallet.getPublicKey({ protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", forSelf: true })).publicKey;
+    const tokenScript = tokenP2pkhScript(assetId, amount, pub);
     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)],
+        labels: [...transferPlanLabels(assetId), "amm-swap", SWAP_STAGE_LABEL],
+        outputs: [{ lockingScript: tokenScript, satoshis: 1, outputDescription: swapKeyDescription(`${sym} for a swap`, keyID) }, ...(req.sats > 0 ? [satsOutput] : [])],
         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);
+    if (final.outputs[0]?.lockingScript.toHex() !== tokenScript || (req.sats > 0 && final.outputs[1]?.lockingScript.toHex() !== satsScript))
+        throw new Error("the wallet's action does not have the staged outputs at 0 and 1");
+    const out = {
+        txid,
+        tx,
+        ...(req.sats > 0 ? { sats: satsRow(txid, 1) } : {}),
+        tokens: { outpoint: `${txid}.0`, txid, vout: 0, satoshis: 1, lockingScript: tokenScript, amount, protocolID: SWAP_PROTOCOL, keyID, counterparty: "self" },
+        filed: false,
+        submitted: "not submitted",
+        errors: [],
+    };
     try {
-        out.submitted = steakText(await submit(`tm_color_${assetId}`, tx));
+        if (o.submit)
+            out.submitted = steakText(await o.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"] });
+        const r = await wallet.internalizeAction({
+            tx,
+            outputs: [{ outputIndex: 0, protocol: "basket insertion", insertionRemittance: { basket: SWAP_BASKET, customInstructions: swapInstructions({ assetId, amount, protocolID: SWAP_PROTOCOL, keyID, counterparty: "self" }) } }],
+            description: describe(`AMM swap: ${sym} into the swap basket`),
+            labels: ["amm-swap"],
+        });
         out.filed = r.accepted;
     }
     catch (err) {
@@ -213,23 +175,38 @@ export async function sendToSwapBasket(wallet, base, tokenId, stage, meta = {},
     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.
+ * The labelled staging actions' token outputs not in `amm-swap` (0.40.0): every output of an action
+ * labelled `SWAP_STAGE_LABEL` whose description names a staged key and whose script is a 1Color
+ * value output, its basket not `amm-swap`. A wallet that refuses the read: none.
  */
-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`),
+export async function unfiledStagedTokens(wallet) {
+    const out = [];
+    try {
+        const r = await wallet.listActions({ labels: [SWAP_STAGE_LABEL], includeOutputs: true, includeOutputLockingScripts: true, limit: 1000 });
+        for (const a of r.actions ?? []) {
+            for (const o of a.outputs ?? []) {
+                const keyID = swapKeyIdOfDescription(o.outputDescription);
+                const t = keyID && o.lockingScript ? decodeOneColor(Utils.toArray(o.lockingScript, "hex")) : null;
+                if (!keyID || !t || t.role !== "value" || !t.idBytes || o.basket === SWAP_BASKET)
+                    continue;
+                out.push({ txid: a.txid, vout: o.outputIndex, tokenId: tokenIdOfWire(t.idBytes), amount: t.amount, keyID });
+            }
+        }
+    }
+    catch {
+        /* no history read: none */
+    }
+    return out;
+}
+/** One unfiled staged token output filed in `amm-swap` from its transaction's BEEF (basket insertion, as `stage` files it). */
+export async function fileStagedToken(wallet, u, beef) {
+    const r = await wallet.internalizeAction({
+        tx: beef,
+        outputs: [{ outputIndex: u.vout, protocol: "basket insertion", insertionRemittance: { basket: SWAP_BASKET, customInstructions: swapInstructions({ assetId: sdkTokenId(u.tokenId), amount: u.amount, protocolID: SWAP_PROTOCOL, keyID: u.keyID, counterparty: "self" }) } }],
+        description: "AMM swap: a staged token filed",
         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 };
+    return r.accepted;
 }
 /** 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) {
@@ -259,8 +236,8 @@ export async function moveBack(i) {
     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);
+    // 0.40.0: every sats row goes in too (they are no token's); the wallet's change takes their sats.
+    const satsRows = satsInputsOf(rows);
     if (holdings.length === 0 && satsRows.length > 0)
         return await moveBackSats(wallet, sym, satsRows);
     if (holdings.length === 0)
@@ -279,7 +256,7 @@ export async function moveBack(i) {
         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`) })),
+            ...satsRows.map((h) => ({ outpoint: h.outpoint, unlockingScriptLength: P2PKH_UNLOCK_LENGTH, inputDescription: describe("Sats in the swap basket") })),
         ],
         outputs: [{ lockingScript, satoshis: 1, outputDescription: describe(`${sym} back to your wallet`) }],
         labels: [...transferPlanLabels(assetId, { ownedOutputs: [{ outputIndex: 0, ...key.receipt }] }), "amm-swap"],
@@ -296,14 +273,17 @@ export async function moveBack(i) {
     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
+ * Move back with only sats in the swap basket (0.29.6, David Case 2026-11-03; 0.40.0: every sats
+ * row, `satsRows` default the basket's): 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) {
+export async function moveBackSats(wallet, sym = "the swap", satsRows) {
+    satsRows ??= await swapSatsHoldings(wallet);
+    if (satsRows.length === 0)
+        throw new Error("the swap basket holds no sats");
     const sources = await swapHoldingBeef(wallet);
     for (const h of satsRows)
         if (!sources.findTxid(h.txid))
@@ -311,7 +291,7 @@ async function moveBackSats(wallet, sym, satsRows) {
     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`) })),
+        inputs: satsRows.map((h) => ({ outpoint: h.outpoint, unlockingScriptLength: P2PKH_UNLOCK_LENGTH, inputDescription: describe("Sats in the swap basket") })),
         outputs: [],
         labels: ["amm-swap"],
         options: { randomizeOutputs: false, acceptDelayedBroadcast: false },

package/dist/market/plan.d.ts

@@ -15,7 +15,8 @@ export interface SwapForm {
     /** Sats (bsvToToken) or tokens in display units (tokenToBsv). */
     amount: string;
     slippageBps: string;
-    allowPartial: boolean;
+    /** 0.40.2: the most pools the order may draw on, a positive integer the caller gives. */
+    maxSources: number;
 }
 export type PlanInput = {
     ok: true;

package/dist/market/plan.js

@@ -78,7 +78,7 @@ satsPerKb = DEFAULT_FEE_RATE_SATS_PER_KB) {
             direction: form.direction,
             amountIn,
             slippage: { toleranceBps },
-            allowPartial: form.allowPartial,
+            maxSources: form.maxSources,
             fixedCost,
             inventory: withLastSeen(usable, live),
         },