@dcasegr/amm-client 0.38.2 → 0.41.1

package/dist/market/swapAction.js

@@ -1,52 +1,39 @@
 /**
- * One swap leg through the user's BRC-100 wallet (docs/notes.md, "Swap
- * funding and signing"). The page holds no keys: every key and signature
- * comes from the wallet (`getPublicKey`, `createAction`, `createSignature`).
+ * One swap leg through the user's BRC-100 wallet (docs/notes.md, "Swap funding and signing";
+ * 0.40.0, agent-env plans/swap-balance-build-2026-11-05.md §0 7, Builder 2 item 3). The page holds
+ * no keys: every key and signature comes from the wallet (`getPublicKey`, `createSignature`).
  *
- *   1. `planSwapLeg` (`PoolTemplate.planSwap`): the outputs the contract
- *      requires (pool, payout, LP fee, validator fee, commission) and the
- *      method arguments. The commission goes to the relay's `amm.swap.terms`
- *      address; when the relay names none and the pool's CommissionBps is
- *      nonzero, to a key of the taker's own (see "the commission" below). The
- *      leg's sats are exact: what the contract's outputs take beyond the
- *      pool's and the token inputs' sats (amount in + 1 sat per 1Color output
- *      the taker pays for), plus the miner fee of the final swap
- *      (`swapFunding`). Sized with placeholder addresses: the payout keys
- *      (and the taker's own commission key) are derived at step 3 from the
- *      leg's first staged input (`legDerivation`, 0.29.1), not random.
- *   2. **The leg's inputs** (0.29.0, David Case 2026-11-02): every one an
- *      output of the active swap basket `amm-swap` (src/market/activeSwap.ts):
- *      ONE sats output of exactly that amount (`SatsInput`) and, token → sats,
- *      the token outputs carrying exactly the amount in (`TokenInput`), staged
- *      there by one wallet send before the legs (no funding transaction, no
- *      `1sat-deposit`).
- *   3. **Swap transaction**, built here (`prepareSwap`): inputs pool
- *      (`callUnlock`, the validator's slot `OP_0`, `_changeAmount = 0`), the
- *      sats output, the token outputs; outputs exactly the contract's, no
- *      change. The sats and token inputs are signed with `createSignature`
- *      (SIGHASH_ALL|FORKID over the BIP-143 sighash computed here, under the
- *      key each input's customInstructions name) and every input but the
- *      pool's is checked with `Spend`.
- *   4. The relay (src/market/relay.ts) carries it to the validator, with the
- *      sats output's transaction as the swap's funding transaction (its
- *      AtomicBEEF, from the wallet).
- *   5. Accepted: `completeSwap` internalizes the payout (sats: BRC-29 wallet
- *      payment; tokens, 0.12.0: the output is locked to a BRC-207 module
- *      receiving key whose sender is the pool's validator, taken in with a
- *      basket insertion into `p color <assetTag>` and the receipt,
- *      src/wallet/color.ts), and the commission when it is the taker's own
- *      (same two forms). No relinquishOutput (0.29.0): the wallet marks the
- *      `amm-swap` outputs the swap spends spent when it takes the swap in.
- *      Refused / timed out: nothing to undo; the leg's outputs stay in
- *      `amm-swap` for a later swap.
+ *   1. **The leg's inputs** (`selectLegInputs`): every one an `amm-swap` row (src/market/activeSwap.ts)
+ *      — the pool, then as many sats rows as cover the leg's sats (largest first), then (a sell) as
+ *      many token rows as cover `amountIn` (largest first). The leg's sats (`legNeed`): what the
+ *      contract's outputs take beyond the pool's and the token inputs' sats, plus the miner fee of
+ *      the final transaction at the rate (`swapTxSize`, the sats change output counted).
+ *   2. **The outputs**: the contract's (pool, payout, LP fee, validator fee, commission, then the
+ *      token change = token inputs − `amountIn` when > 0), then Rúnar's sats change = sats inputs −
+ *      the need when ≥ 1 (`_changePKH`, `_changeAmount`); under 1, no change output.
+ *   3. **The keys** (`prepareSwap`): the payout (and the taker's own commission) under ONE
+ *      derivation per ORDER (`legDerivation` of the order's key input: the first leg's first token
+ *      input on a sell, its first sats input on a buy), every leg of the order the same; a token
+ *      payout to a module receiving key for SELF (sender the user's identity). The change: a leg
+ *      that is not the order's last → keys under `SWAP_PROTOCOL` (self), keyID
+ *      `amm-swap-<txid>.<vout>:change` of the leg's first input of that kind (`changeKeyID`), taken
+ *      into `amm-swap` with the order's key input in its customInstructions; the LAST leg (it takes
+ *      all that remains) → the WALLET: sats to a BRC-29 key of the user's, tokens to a module
+ *      receiving key for self, both `legDerivation(order, "change")`.
+ *   4. The relay (src/market/relay.ts) carries it to the validator with the first sats input's
+ *      transaction as the swap's funding transaction: ONE BEEF of every staged input's source,
+ *      its subject that transaction (0.40.1, `fundingBeef`).
+ *   5. Accepted: `completeSwap` takes in, in ONE `internalizeAction`, the payout, the commission
+ *      when it is the taker's own, and the change. No relinquishOutput: taking the swap in marks the
+ *      `amm-swap` rows it spends spent.
  */
-import { Hash, LockingScript, PublicKey, Spend, Transaction, TransactionSignature, UnlockingScript, Utils, } from "@bsv/sdk";
+import { Beef, Hash, LockingScript, PublicKey, Spend, Transaction, TransactionSignature, UnlockingScript, Utils, } from "@bsv/sdk";
 import { PoolTemplate, decodeOneColor } from "../pool/index.js";
 import { isPoolRow } from "../lp/poolRows.js";
 import { basketBeef } from "../lp/wallet.js";
 import { outpointText, parseOutpoint, parseTokenId, sdkTokenId } from "../lib/tokenId.js";
-import { WALLET_PAYMENT, identityKeyOf, newBrc29Payout } from "../wallet/brc29.js";
-import { SWAP_BASKET, newReceivingKey, receiptOutput } from "../wallet/color.js";
+import { WALLET_PAYMENT, identityKeyOf, newBrc29Payout, p2pkhHexOf } from "../wallet/brc29.js";
+import { SWAP_BASKET, SWAP_PROTOCOL, newReceivingKey, receiptOutput, swapInstructions, swapSatsInstructions } from "../wallet/color.js";
 /** A P2PKH unlocking script's upper bound: push(DER ≤ 72 + sighash byte) + push(33-byte key). */
 export const P2PKH_UNLOCK_LENGTH = 108;
 /**
@@ -68,6 +55,24 @@ export function assetIdOf(tokenId) {
         throw new Error(`pools exist only for 32-byte ids (<txid>_0), not ${tokenId}`);
     return toHex(Utils.toArray(r.txid, "hex").reverse());
 }
+function keyOf(r) {
+    let ci = {};
+    try {
+        ci = JSON.parse(r.customInstructions ?? "{}");
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(ci.protocolID) || typeof ci.keyID !== "string")
+        return null;
+    return {
+        protocolID: ci.protocolID,
+        keyID: ci.keyID,
+        counterparty: typeof ci.counterparty === "string" ? ci.counterparty : "self",
+        ...(typeof ci.order === "string" ? { order: ci.order } : {}),
+        ...(ci.sats === true ? { sats: true } : {}),
+    };
+}
 /**
  * The basket rows usable as token inputs for `tokenId`: 1Color value outputs
  * with this 32-byte id (the pool template counts only those) whose
@@ -83,17 +88,9 @@ export function tokenInputsOf(rows, tokenId) {
         const t = decodeOneColor(Utils.toArray(r.lockingScript, "hex"));
         if (!t || t.role !== "value" || !t.idBytes || toHex(Array.from(t.idBytes)) !== assetId)
             continue;
-        let ci = {};
-        try {
-            ci = JSON.parse(r.customInstructions ?? "{}");
-        }
-        catch {
-            continue;
-        }
-        if (!Array.isArray(ci.protocolID) || typeof ci.keyID !== "string")
-            continue;
+        const k = keyOf(r);
         const op = parseOutpoint(r.outpoint);
-        if (!op)
+        if (!k || !op)
             continue;
         out.push({
             outpoint: `${op.txid}.${op.vout}`,
@@ -102,41 +99,14 @@ export function tokenInputsOf(rows, tokenId) {
             satoshis: r.satoshis,
             lockingScript: r.lockingScript,
             amount: t.amount,
-            protocolID: ci.protocolID,
-            keyID: ci.keyID,
-            counterparty: typeof ci.counterparty === "string" ? ci.counterparty : "self",
+            protocolID: k.protocolID,
+            keyID: k.keyID,
+            counterparty: k.counterparty,
+            ...(k.order ? { order: k.order } : {}),
         });
     }
     return out;
 }
-/**
- * Token outputs summing to exactly `amount`, or null. The pool contract has
- * no token change output (Pool.runar.go Swap: the token inputs are the
- * amountIn), so an inexact selection cannot be spent into a swap. Fewest
- * outputs first; a bounded search.
- */
-export function selectExactTokenInputs(candidates, amount) {
-    const sorted = [...candidates].sort((a, b) => (a.amount > b.amount ? -1 : a.amount < b.amount ? 1 : 0)).slice(0, 24);
-    for (let size = 1; size <= Math.min(sorted.length, 6); size++) {
-        const pick = [];
-        const walk = (from, left) => {
-            if (pick.length === size)
-                return left === 0n;
-            for (let i = from; i < sorted.length; i++) {
-                if (sorted[i].amount > left)
-                    continue;
-                pick.push(sorted[i]);
-                if (walk(i + 1, left - sorted[i].amount))
-                    return true;
-                pick.pop();
-            }
-            return false;
-        };
-        if (walk(0, amount))
-            return pick;
-    }
-    return null;
-}
 const P2PKH_RE = /^76a914[0-9a-f]{40}88ac$/i;
 /** The basket rows usable as a leg's sats: plain P2PKH outputs whose customInstructions say `sats: true` and name the key. */
 export function satsInputsOf(rows) {
@@ -144,17 +114,9 @@ export function satsInputsOf(rows) {
     for (const r of rows) {
         if (!r.lockingScript || !P2PKH_RE.test(r.lockingScript))
             continue;
-        let ci = {};
-        try {
-            ci = JSON.parse(r.customInstructions ?? "{}");
-        }
-        catch {
-            continue;
-        }
-        if (ci.sats !== true || !Array.isArray(ci.protocolID) || typeof ci.keyID !== "string")
-            continue;
+        const k = keyOf(r);
         const op = parseOutpoint(r.outpoint);
-        if (!op)
+        if (!k || !k.sats || !op)
             continue;
         out.push({
             outpoint: `${op.txid}.${op.vout}`,
@@ -162,18 +124,14 @@ export function satsInputsOf(rows) {
             vout: op.vout,
             satoshis: r.satoshis,
             lockingScript: r.lockingScript,
-            protocolID: ci.protocolID,
-            keyID: ci.keyID,
-            counterparty: typeof ci.counterparty === "string" ? ci.counterparty : "self",
-            ...(typeof ci.assetId === "string" ? { assetId: ci.assetId } : {}),
+            protocolID: k.protocolID,
+            keyID: k.keyID,
+            counterparty: k.counterparty,
+            ...(k.order ? { order: k.order } : {}),
         });
     }
     return out;
 }
-/** The sats twin of `selectExactTokenInputs`: one output of exactly `satoshis` (the leg has no change), or null. */
-export function selectExactSatsInput(candidates, satoshis) {
-    return candidates.find((c) => c.satoshis === satoshis) ?? null;
-}
 /** The pool output from the lookup's BEEF, as the template's PoolUtxo. */
 export function poolUtxoFrom(poolOutput) {
     const tx = Transaction.fromAtomicBEEF(poolOutput.beef);
@@ -214,68 +172,89 @@ export async function signP2pkhWithWallet(wallet, tx, inputIndex, src, scope = T
 function varIntSize(n) {
     return n < 0xfd ? 1 : n <= 0xffff ? 3 : n <= 0xffffffff ? 5 : 9;
 }
+/** A P2PKH output's size: 8 (sats) + 1 (length) + 25. */
+const P2PKH_OUTPUT_SIZE = 34;
 /**
  * The final swap's size in bytes: the pool input at `maxCallUnlockLength`
  * (validator's signature in), `takerInputs` P2PKH inputs (the sats, tokens)
- * at 108 bytes of unlocking script, the contract's outputs, no change.
+ * at 108 bytes of unlocking script, the contract's outputs, and (0.40.0) the
+ * sats change output when `withChange`.
  */
-export function swapTxSize(plan, takerInputs) {
+export function swapTxSize(plan, takerInputs, withChange = false) {
     const poolUnlock = PoolTemplate.maxCallUnlockLength(plan);
     let size = 4 + varIntSize(1 + takerInputs);
     size += 36 + varIntSize(poolUnlock) + poolUnlock + 4;
     size += takerInputs * (36 + varIntSize(P2PKH_UNLOCK_LENGTH) + P2PKH_UNLOCK_LENGTH + 4);
-    size += varIntSize(plan.outputs.length);
+    const outs = plan.outputs.length + (withChange ? 1 : 0);
+    size += varIntSize(outs);
     for (const o of plan.outputs) {
         const len = o.script.length / 2;
         size += 8 + varIntSize(len) + len;
     }
+    if (withChange)
+        size += P2PKH_OUTPUT_SIZE;
     return size + 4;
 }
 /**
- * The leg's exact sats: Σ contract outputs − pool sats − token inputs' sats
- * (sats in: amount in + 1 for the token payout, the fees and the commission
- * being part of amount in; tokens in: 1 per 1Color fee or commission output
- * − the token inputs' sats), plus
- * ceil(size × rate / 1000) for the final swap.
+ * A leg's sats need: Σ contract outputs − pool sats − token inputs' sats, plus ceil(size × rate /
+ * 1000) for the final swap with `inputs` taker inputs (sats and tokens), without and with the sats
+ * change output.
  */
-export function swapFunding(plan, tokenInputs, satsPerKb) {
+export function legNeed(plan, tokenInputs, inputs, satsPerKb) {
     const outSum = plan.outputs.reduce((a, o) => a + o.satoshis, 0n);
     const tokenSats = tokenInputs.reduce((a, t) => a + BigInt(t.satoshis), 0n);
     const outputs = Number(outSum - BigInt(plan.poolUtxo.satoshis) - tokenSats);
-    const size = swapTxSize(plan, 1 + tokenInputs.length);
-    const fee = Math.ceil((size * satsPerKb) / 1000);
-    return { satoshis: Math.max(1, outputs + fee), outputs, fee, size, satsPerKb };
+    const fee = Math.ceil((swapTxSize(plan, inputs) * satsPerKb) / 1000);
+    const feeWithChange = Math.ceil((swapTxSize(plan, inputs, true) * satsPerKb) / 1000);
+    return { outputs, fee, need: outputs + fee, feeWithChange, needWithChange: outputs + feeWithChange, satsPerKb };
 }
-const ZERO_PKH = "00".repeat(20);
+// ---------------------------------------------------------------------------
+// The keys
+// ---------------------------------------------------------------------------
 /** BRC-29 / BRC-207 derivationPrefix of a leg's payout (0.29.1): base64 of the UTF-8 text "amm swap". */
 export const LEG_PAYOUT_PREFIX = Utils.toBase64(Utils.toArray("amm swap", "utf8"));
 /** derivationPrefix of the taker's own commission output (0.29.1): base64 of "amm swap commission". */
 export const LEG_COMMISSION_PREFIX = Utils.toBase64(Utils.toArray("amm swap commission", "utf8"));
+/** derivationPrefix of an order's last leg's change to the wallet (0.40.0): base64 of "amm swap change". */
+export const LEG_CHANGE_PREFIX = Utils.toBase64(Utils.toArray("amm swap change", "utf8"));
 /**
- * The derivation of a leg's payout keys (0.29.1, David Case 2026-11-02: deterministic from what
- * the leg spends). `keyInput` is the leg's first staged `amm-swap` input, `<txid>.<vout>` (txid in
- * display hex, lowercase): tokens in, its first token input (the swap's input 2); sats in, its sats
- * input (input 1). derivationSuffix = base64(sha256(UTF-8 of that text)); derivationPrefix
- * `LEG_PAYOUT_PREFIX` for the payout, `LEG_COMMISSION_PREFIX` for the taker's own commission. The
- * same pair keys the BRC-29 payment (keyID "<prefix> <suffix>", sender the user) and the BRC-207
- * receipt (`p color <assetTag> <prefixHex> <suffixHex>`, sender the pool's validator). A staged
- * output is spent by one transaction only, so the keys are the leg's alone.
+ * The derivation of an order's payout keys (0.29.1; 0.40.0: ONE per ORDER). `keyInput` is the
+ * order's key input, `<txid>.<vout>` (txid in display hex, lowercase): the first leg's first token
+ * input on a sell, its first sats input on a buy. derivationSuffix = base64(sha256(UTF-8 of that
+ * text)); derivationPrefix `LEG_PAYOUT_PREFIX` for the payout, `LEG_COMMISSION_PREFIX` for the
+ * taker's own commission, `LEG_CHANGE_PREFIX` for the last leg's change to the wallet. The same
+ * pair keys the BRC-29 payment (keyID "<prefix> <suffix>", sender the user) and the BRC-207 receipt
+ * (`p color <assetTag> <prefixHex> <suffixHex>`, sender the user: a receipt for self).
  */
 export function legDerivation(keyInput, which) {
     return {
-        derivationPrefix: which === "payout" ? LEG_PAYOUT_PREFIX : LEG_COMMISSION_PREFIX,
+        derivationPrefix: which === "payout" ? LEG_PAYOUT_PREFIX : which === "commission" ? LEG_COMMISSION_PREFIX : LEG_CHANGE_PREFIX,
         derivationSuffix: Utils.toBase64(Hash.sha256(Utils.toArray(keyInput, "utf8"))),
     };
 }
-/** The leg's key input in a swap transaction (see `legDerivation`): input 2 when it spends tokens, else input 1. */
-export function legKeyInputOf(swap, bsvIn) {
-    const inp = swap.inputs[bsvIn ? 1 : 2];
-    if (!inp)
-        throw new LegShapeError("the swap has no staged input to key its payout by");
-    return `${inp.sourceTXID ?? inp.sourceTransaction.id("hex")}.${inp.sourceOutputIndex}`;
+/** The keyID of a leg's change kept in `amm-swap` (0.40.0): `amm-swap-<txid>.<vout>:change`, the leg's first input of that kind. */
+export function changeKeyID(firstInput) {
+    const op = parseOutpoint(firstInput);
+    if (!op)
+        throw new LegShapeError(`not an outpoint: ${firstInput}`);
+    return `amm-swap-${op.txid}.${op.vout}:change`;
+}
+/** A swap transaction's taker inputs (every input after the pool's), each told sats or tokens by its source output (0.40.0). */
+export function legInputsOf(tx) {
+    const sats = [];
+    const tokens = [];
+    for (const inp of tx.inputs.slice(1)) {
+        const txid = inp.sourceTXID ?? inp.sourceTransaction?.id("hex");
+        const src = inp.sourceTransaction?.outputs[inp.sourceOutputIndex];
+        if (!txid || !src)
+            continue;
+        (decodeOneColor(src.lockingScript.toBinary()) ? tokens : sats).push(`${txid}.${inp.sourceOutputIndex}`);
+    }
+    return { sats, tokens };
 }
-/** The plan with the given payout and commission addresses (`planSwap`, the leg's quote as the expectation). */
-function legPlan(i, poolUtxo, userPkh, commissionPkh) {
+const ZERO_PKH = "00".repeat(20);
+/** The plan with the given payout, commission and token change addresses (`planSwap`, the leg's quote as the expectation). */
+function legPlan(i, poolUtxo, userPkh, commissionPkh, tokenChange, tokenChangePkh) {
     const { leg, pool } = i;
     return PoolTemplate.planSwap({
         pool: poolUtxo,
@@ -283,6 +262,8 @@ function legPlan(i, poolUtxo, userPkh, commissionPkh) {
         bsvIn: i.direction === "bsvToToken",
         userPkh,
         commissionPkh,
+        tokenChange,
+        tokenChangePkh,
         expect: {
             bsvReserve: pool.bsvReserve,
             tokenReserve: pool.tokenReserve,
@@ -296,116 +277,203 @@ function legPlan(i, poolUtxo, userPkh, commissionPkh) {
         },
     });
 }
+const largestFirst = (xs, size) => [...xs].sort((a, b) => {
+    const d = size(b) - size(a);
+    return d > 0n ? 1 : d < 0n ? -1 : a.outpoint.localeCompare(b.outpoint);
+});
 /**
- * Step 1 (see the module comment): the leg's plan and exact sats, sized with placeholder payout
- * and commission addresses (20 bytes each: the sizes are the same). No wallet call: the payout
- * keys are derived at step 3 from the leg's staged input (`legDerivation`). Throws
- * `PoolBuildError` / `LegShapeError`.
+ * Item 3's inputs: (a sell) as many token rows as cover `leg.amountIn`, largest first; then as many
+ * sats rows as cover the leg's sats need, largest first (each sats row added grows the size). Null
+ * when the rows cannot cover the leg (the staged sats or tokens ran out). The need is planned with
+ * placeholder addresses (20 bytes each: the sizes are the same).
  */
-export async function planSwapLeg(i) {
-    const { leg } = i;
+export function selectLegInputs(i, sats, tokens) {
     const bsvIn = i.direction === "bsvToToken";
     const poolUtxo = poolUtxoFrom(i.poolOutput);
-    if (`${poolUtxo.txid}_${poolUtxo.vout}` !== leg.outpoint) {
-        throw new LegShapeError(`the pool moved: the lookup's tip is ${poolUtxo.txid}.${poolUtxo.vout}, the plan priced ${outpointText(leg.outpoint)}`);
+    if (`${poolUtxo.txid}_${poolUtxo.vout}` !== i.leg.outpoint) {
+        throw new LegShapeError(`the pool moved: the read's tip is ${poolUtxo.txid}.${poolUtxo.vout}, the plan priced ${outpointText(i.leg.outpoint)}`);
     }
-    const tokenInputs = i.tokenInputs ?? [];
-    const tokensIn = tokenInputs.reduce((a, t) => a + t.amount, 0n);
-    if (bsvIn ? tokenInputs.length > 0 : tokensIn !== leg.amountIn) {
-        throw new LegShapeError(`token inputs carry ${tokensIn}, the leg needs exactly ${bsvIn ? 0n : leg.amountIn}`);
+    const pickedTokens = [];
+    if (!bsvIn) {
+        let held = 0n;
+        for (const t of largestFirst(tokens, (x) => x.amount)) {
+            if (held >= i.leg.amountIn)
+                break;
+            pickedTokens.push(t);
+            held += t.amount;
+        }
+        if (held < i.leg.amountIn)
+            return null;
     }
-    const decoded = PoolTemplate.decode(poolUtxo.script);
-    if (!decoded)
-        throw new LegShapeError(`${outpointText(leg.outpoint)} is not a pool output`);
-    const commissionAmount = (leg.amountIn * decoded.args.commissionBps + 9999n) / 10000n;
-    const commissionTo = commissionAmount === 0n ? "none" : i.commissionPkh ? "relay" : "own";
-    const plan = legPlan(i, poolUtxo, ZERO_PKH, i.commissionPkh ?? ZERO_PKH);
-    return { pool: leg.outpoint, validator: i.pool.validatorIdentityKey, bsvIn, poolUtxo, plan, funding: swapFunding(plan, tokenInputs, i.satsPerKb), commissionAmount, commissionTo };
+    const tokenChange = pickedTokens.reduce((a, t) => a + t.amount, 0n) - (bsvIn ? 0n : i.leg.amountIn);
+    const plan = legPlan(i, poolUtxo, ZERO_PKH, i.commissionPkh ?? ZERO_PKH, tokenChange, ZERO_PKH);
+    const pickedSats = [];
+    let held = 0;
+    for (const s of largestFirst(sats, (x) => BigInt(x.satoshis))) {
+        pickedSats.push(s);
+        held += s.satoshis;
+        const need = legNeed(plan, pickedTokens, pickedSats.length + pickedTokens.length, i.satsPerKb);
+        if (held >= need.need)
+            return { sats: pickedSats, tokens: pickedTokens, need };
+    }
+    return null;
+}
+const pkhOfKey = (publicKey) => toHex(PublicKey.fromString(publicKey).toHash());
+/** The leg's own key input: its first token input on a sell, its first sats input on a buy. */
+export function keyInputOf(inputs, bsvIn) {
+    const k = bsvIn ? inputs.sats[0] : inputs.tokens[0];
+    if (!k)
+        throw new LegShapeError("the leg has no staged input to key its payout by");
+    return k.outpoint;
+}
+/** BRC-95's Atomic BEEF prefix (the sdk's `ATOMIC_BEEF`), little-endian. */
+const ATOMIC_BEEF_PREFIX = [0x01, 0x01, 0x01, 0x01];
+/**
+ * The relay's `funding` (0.40.1): ONE BEEF holding the source transaction of every staged input
+ * the leg spends (sats and token rows alike, each with its ancestry as the wallet gives it), its
+ * subject the funding transaction (the first sats input's). The form: an Atomic BEEF envelope
+ * (the prefix and the subject's txid, as the sdk writes one) around the sdk's V2 BEEF of them all
+ * — the relay's `given()` reads the envelope's subject and keeps every transaction in it; the
+ * sdk's own `toBinaryAtomic` would drop the sources the subject does not descend from. The
+ * relay's request BEEF to the validator is its own V2 (relay.zig `requestBeef`).
+ */
+export function fundingBeef(beef, fundingTxid, sources) {
+    const all = new Beef();
+    for (const txid of new Set([fundingTxid, ...sources]))
+        all.mergeBeef(beef.toBinaryAtomic(txid));
+    return [...ATOMIC_BEEF_PREFIX, ...Utils.toArray(fundingTxid, "hex").reverse(), ...all.toBinary()];
 }
-/** Steps 1 (unless `planned` is given) and 3 (see the module comment). Throws `PoolBuildError` / `LegShapeError`; the wallet is left as it was. */
+/** Builds and signs the leg (see the module comment). Throws `PoolBuildError` / `LegShapeError`; the wallet is left as it was. */
 export async function prepareSwap(i) {
-    const { wallet } = i;
-    const planned = i.planned ?? (await planSwapLeg(i));
-    const { poolUtxo, bsvIn, commissionTo, commissionAmount } = planned;
-    const tokenInputs = i.tokenInputs ?? [];
-    const tokensIn = tokenInputs.reduce((a, t) => a + t.amount, 0n);
-    if (bsvIn ? tokenInputs.length > 0 : tokensIn !== i.leg.amountIn) {
-        throw new LegShapeError(`token inputs carry ${tokensIn}, the leg needs exactly ${bsvIn ? 0n : i.leg.amountIn}`);
-    }
-    const sats = i.satsInput;
-    // The payout keys (0.29.1): derived from the leg's first staged input.
-    const keyInput = bsvIn ? sats.outpoint : tokenInputs[0].outpoint;
+    const { wallet, inputs } = i;
+    const bsvIn = i.direction === "bsvToToken";
+    const poolUtxo = poolUtxoFrom(i.poolOutput);
+    if (`${poolUtxo.txid}_${poolUtxo.vout}` !== i.leg.outpoint)
+        throw new LegShapeError(`the pool moved: the read's tip is ${poolUtxo.txid}.${poolUtxo.vout}`);
+    const tokensIn = inputs.tokens.reduce((a, t) => a + t.amount, 0n);
+    if (bsvIn ? inputs.tokens.length > 0 : tokensIn < i.leg.amountIn)
+        throw new LegShapeError(`token inputs carry ${tokensIn}, the leg needs ${bsvIn ? 0n : i.leg.amountIn}`);
+    if (inputs.sats.length === 0)
+        throw new LegShapeError("the leg has no sats row");
+    const tokenChange = tokensIn - (bsvIn ? 0n : i.leg.amountIn);
+    const order = i.order ?? keyInputOf(inputs, bsvIn);
     const decoded = PoolTemplate.decode(poolUtxo.script);
-    const identity = !bsvIn || commissionTo === "own" ? await identityKeyOf(wallet) : "";
+    if (!decoded)
+        throw new LegShapeError(`${outpointText(i.leg.outpoint)} is not a pool output`);
+    const commissionAmount = (i.leg.amountIn * decoded.args.commissionBps + 9999n) / 10000n;
+    const commissionTo = commissionAmount === 0n ? "none" : i.commissionPkh ? "relay" : "own";
+    const identity = await identityKeyOf(wallet);
     const sdkId = sdkTokenId(i.tokenId);
-    const validatorIdentity = decoded.state.validatorIdentity;
-    const pay = legDerivation(keyInput, "payout");
-    const brc29 = bsvIn ? null : await newBrc29Payout(wallet, identity, pay);
-    const tokenKey = bsvIn ? await newReceivingKey(wallet, sdkId, validatorIdentity, pay) : null;
-    const userPkh = toHex(PublicKey.fromString(brc29 ? brc29.publicKey : tokenKey.publicKey).toHash());
-    let ownCommission = null;
+    // The payout (one derivation per order; a token payout is a receipt for self).
+    const pay = legDerivation(order, "payout");
+    const payBrc29 = bsvIn ? null : await newBrc29Payout(wallet, identity, pay);
+    const payToken = bsvIn ? await newReceivingKey(wallet, sdkId, identity, pay) : null;
+    const userPkh = pkhOfKey(payBrc29 ? payBrc29.publicKey : payToken.publicKey);
+    let own = null;
     if (commissionTo === "own") {
-        const com = legDerivation(keyInput, "commission");
-        const own = bsvIn ? await newBrc29Payout(wallet, identity, com) : null;
-        const token = bsvIn ? null : await newReceivingKey(wallet, sdkId, validatorIdentity, com);
-        ownCommission = { brc29: own, token, pkh: toHex(PublicKey.fromString(own ? own.publicKey : token.publicKey).toHash()) };
+        const com = legDerivation(order, "commission");
+        const b = bsvIn ? await newBrc29Payout(wallet, identity, com) : null;
+        const t = bsvIn ? null : await newReceivingKey(wallet, sdkId, identity, com);
+        own = { brc29: b, token: t, pkh: pkhOfKey(b ? b.publicKey : t.publicKey) };
+    }
+    const commissionPkh = own?.pkh ?? i.commissionPkh ?? ZERO_PKH;
+    // The change keys: kept in amm-swap (not the last leg) or the wallet's (the last).
+    const change = legDerivation(order, "change");
+    const swapKey = async (keyID) => (await wallet.getPublicKey({ protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", forSelf: true })).publicKey;
+    let tokenChangeKey = null;
+    if (tokenChange > 0n) {
+        if (i.last) {
+            const k = await newReceivingKey(wallet, sdkId, identity, change);
+            tokenChangeKey = { pkh: k.pkh, out: (outputIndex, lockingScript) => ({ kind: "color", outputIndex, satoshis: 1, lockingScript, receipt: k.receipt }) };
+        }
+        else {
+            const keyID = changeKeyID(inputs.tokens[0].outpoint);
+            const pub = await swapKey(keyID);
+            const ci = swapInstructions({ assetId: sdkId, amount: tokenChange, protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", order });
+            tokenChangeKey = { pkh: pkhOfKey(pub), out: (outputIndex, lockingScript) => ({ kind: "basket", outputIndex, satoshis: 1, lockingScript, customInstructions: ci }) };
+        }
     }
-    const commissionPkh = ownCommission?.pkh ?? i.commissionPkh ?? ZERO_PKH;
-    const plan = legPlan(i, poolUtxo, userPkh, commissionPkh);
-    // The leg's sats were sized for these token inputs: the same count and sats, or the fee is off.
-    const amounts = swapFunding(plan, tokenInputs, i.satsPerKb);
-    if (amounts.satoshis !== planned.funding.satoshis)
-        throw new LegShapeError(`the token inputs need ${amounts.satoshis} sats with the leg, it was planned with ${planned.funding.satoshis}`);
-    if (sats.satoshis !== amounts.satoshis)
-        throw new LegShapeError(`the swap basket's sats output ${sats.outpoint} holds ${sats.satoshis} sats, the leg needs exactly ${amounts.satoshis}`);
-    const payout = brc29
-        ? { kind: "brc29", outputIndex: 1, satoshis: Number(plan.outputs[1].satoshis), lockingScript: plan.outputs[1].script, remittance: brc29.remittance }
-        : { kind: "color", outputIndex: 1, satoshis: Number(plan.outputs[1].satoshis), lockingScript: plan.outputs[1].script, receipt: tokenKey.receipt };
-    // The commission is the last output when there is one (Pool.runar.go Swap).
+    const plan = legPlan(i, poolUtxo, userPkh, commissionPkh, tokenChange, tokenChangeKey?.pkh ?? ZERO_PKH);
+    // The sats change: sats inputs − the need with the change output counted, when ≥ 1.
+    const held = inputs.sats.reduce((a, s) => a + s.satoshis, 0);
+    const need = legNeed(plan, inputs.tokens, inputs.sats.length + inputs.tokens.length, i.satsPerKb);
+    if (held < need.need)
+        throw new LegShapeError(`the swap basket's sats rows hold ${held} sats, the leg needs ${need.need}`);
+    const changeSats = held - need.needWithChange;
+    let satsChange = null;
+    if (changeSats >= 1) {
+        const at = plan.outputs.length;
+        if (i.last) {
+            const b = await newBrc29Payout(wallet, identity, change);
+            satsChange = { pkh: pkhOfKey(b.publicKey), satoshis: changeSats, payout: { kind: "brc29", outputIndex: at, satoshis: changeSats, lockingScript: b.lockingScript, remittance: b.remittance } };
+        }
+        else {
+            const keyID = changeKeyID(inputs.sats[0].outpoint);
+            const pub = await swapKey(keyID);
+            satsChange = {
+                pkh: pkhOfKey(pub),
+                satoshis: changeSats,
+                payout: { kind: "basket", outputIndex: at, satoshis: changeSats, lockingScript: p2pkhHexOf(pub), customInstructions: swapSatsInstructions({ protocolID: SWAP_PROTOCOL, keyID, counterparty: "self", order }) },
+            };
+        }
+    }
+    const payout = payBrc29
+        ? { kind: "brc29", outputIndex: 1, satoshis: Number(plan.outputs[1].satoshis), lockingScript: plan.outputs[1].script, remittance: payBrc29.remittance }
+        : { kind: "color", outputIndex: 1, satoshis: Number(plan.outputs[1].satoshis), lockingScript: plan.outputs[1].script, receipt: payToken.receipt };
     const commission = { amount: commissionAmount, pkh: commissionPkh, to: commissionTo };
-    if (ownCommission) {
-        const at = plan.outputs.length - 1;
+    // The commission is the last fee output when there is one (Pool.runar.go Swap), before the token change.
+    if (own) {
+        const at = plan.outputs.length - 1 - (tokenChange > 0n ? 1 : 0);
         const out = plan.outputs[at];
-        commission.payout = ownCommission.brc29
-            ? { kind: "brc29", outputIndex: at, satoshis: Number(out.satoshis), lockingScript: out.script, remittance: ownCommission.brc29.remittance }
-            : { kind: "color", outputIndex: at, satoshis: Number(out.satoshis), lockingScript: out.script, receipt: ownCommission.token.receipt };
+        commission.payout = own.brc29
+            ? { kind: "brc29", outputIndex: at, satoshis: Number(out.satoshis), lockingScript: out.script, remittance: own.brc29.remittance }
+            : { kind: "color", outputIndex: at, satoshis: Number(out.satoshis), lockingScript: out.script, receipt: own.token.receipt };
     }
+    const tokenChangeOut = tokenChangeKey ? tokenChangeKey.out(plan.outputs.length - 1, plan.outputs[plan.outputs.length - 1].script) : undefined;
     // The inputs' source transactions: the active swap basket's.
     const beef = i.holdingBeef ?? (await basketBeef(wallet, SWAP_BASKET));
     if (!beef)
         throw new LegShapeError("the wallet returned no BEEF for the swap basket");
-    for (const t of [sats, ...tokenInputs])
+    for (const t of [...inputs.sats, ...inputs.tokens])
         if (!beef.findTxid(t.txid))
             throw new LegShapeError(`the wallet's BEEF lacks the swap basket output ${t.outpoint}`);
     const sourceOf = (txid) => beef.findAtomicTransaction(txid) ?? beef.findTxid(txid).tx;
-    // Step 3: the swap transaction.
+    // The swap transaction.
     const swap = new Transaction();
     swap.version = 1;
     swap.lockTime = 0;
     swap.addInput({ sourceTXID: poolUtxo.txid, sourceOutputIndex: poolUtxo.vout, sourceTransaction: poolUtxo.sourceTransaction, unlockingScript: new UnlockingScript(), sequence: 0xffffffff });
-    swap.addInput({ sourceTXID: sats.txid, sourceOutputIndex: sats.vout, sourceTransaction: sourceOf(sats.txid), unlockingScript: new UnlockingScript(), sequence: 0xffffffff });
-    for (const t of tokenInputs)
+    for (const t of [...inputs.sats, ...inputs.tokens])
         swap.addInput({ sourceTXID: t.txid, sourceOutputIndex: t.vout, sourceTransaction: sourceOf(t.txid), unlockingScript: new UnlockingScript(), sequence: 0xffffffff });
     for (const o of plan.outputs)
         swap.addOutput({ satoshis: Number(o.satoshis), lockingScript: LockingScript.fromHex(o.script) });
-    swap.inputs[0].unlockingScript = PoolTemplate.callUnlock(plan, swap, null).unlockingScript;
-    swap.inputs[1].unlockingScript = await signP2pkhWithWallet(wallet, swap, 1, sats);
-    for (const [n, t] of tokenInputs.entries())
-        swap.inputs[n + 2].unlockingScript = await signP2pkhWithWallet(wallet, swap, n + 2, t);
+    if (satsChange)
+        swap.addOutput({ satoshis: satsChange.satoshis, lockingScript: LockingScript.fromHex(`76a914${satsChange.pkh}88ac`) });
+    swap.inputs[0].unlockingScript = PoolTemplate.callUnlock(plan, swap, satsChange ? { pkh: satsChange.pkh, satoshis: satsChange.satoshis } : null).unlockingScript;
+    const rows = [...inputs.sats, ...inputs.tokens];
+    for (const [n, t] of rows.entries())
+        swap.inputs[n + 1].unlockingScript = await signP2pkhWithWallet(wallet, swap, n + 1, t);
     for (let n = 1; n < swap.inputs.length; n++) {
         if (!spendValid(swap, n))
             throw new LegShapeError(`input ${n} of the swap does not validate`);
     }
+    const funding = inputs.sats[0];
     return {
-        pool: planned.pool,
-        validator: planned.validator,
+        pool: i.leg.outpoint,
+        validator: i.pool.validatorIdentityKey,
+        bsvIn,
         expires: (i.now ?? Date.now()) + (i.ttlMs ?? SWAP_TTL_MS),
         plan,
-        funding: { ...amounts, input: sats, atomicBeef: beef.toBinaryAtomic(sats.txid), txid: sats.txid, outpoint: sats.outpoint },
+        order,
+        last: i.last,
+        funding: { atomicBeef: fundingBeef(beef, funding.txid, [...inputs.sats, ...inputs.tokens].map((r) => r.txid)), txid: funding.txid, fee: satsChange ? need.feeWithChange : need.fee, need: need.need },
         swap,
-        tokenInputs,
+        satsInputs: inputs.sats,
+        tokenInputs: inputs.tokens,
         payout,
         commission,
+        ...(tokenChangeOut ? { tokenChange: tokenChangeOut } : {}),
+        ...(satsChange ? { satsChange: satsChange.payout } : {}),
     };
 }
 /** @bsv/sdk's `Spend` over input `n` of `tx` (its source output from `sourceTransaction`). */
@@ -476,23 +544,30 @@ export function finalCallOf(ours, raw, txid, what) {
     });
     return tx;
 }
+/** The leg's outputs the wallet takes in (0.40.0): the payout, the taker's own commission, the token change, the sats change. */
+export function takeInOutputs(p) {
+    const outs = [internalizeOutputOf(p.payout)];
+    if (p.commission.payout)
+        outs.push(internalizeOutputOf(p.commission.payout));
+    if (p.tokenChange)
+        outs.push(internalizeOutputOf(p.tokenChange));
+    if (p.satsChange)
+        outs.push(internalizeOutputOf(p.satsChange));
+    return outs;
+}
 /**
- * Accepted: the wallet takes the payout in (`internalizeAction`). No
- * relinquishOutput (0.29.0, David Case 2026-11-02: "Anything we internalize
- * should relinquish outputs itself"): taking the swap in marks the wallet's
- * outputs it spends — the `amm-swap` sats and token inputs — spent
- * (wallet-toolbox `markUserInputsSpent`).
+ * Accepted: the wallet takes the leg in, ONE `internalizeAction` (0.40.0: the payout, the taker's
+ * own commission, the change). No relinquishOutput (0.29.0, David Case 2026-11-02: "Anything we
+ * internalize should relinquish outputs itself"): taking the swap in marks the wallet's outputs
+ * it spends — the `amm-swap` sats and token rows — spent (wallet-toolbox `markUserInputsSpent`).
  */
 export async function completeSwap(wallet, p, raw, txid) {
     const final = finalSwapOf(p, raw, txid);
     const out = { txid: final.id("hex"), internalized: false, errors: [] };
-    const outputs = [internalizeOutputOf(p.payout)];
-    if (p.commission.payout)
-        outputs.push(internalizeOutputOf(p.commission.payout));
     try {
         const r = await wallet.internalizeAction({
             tx: final.toAtomicBEEF(true),
-            outputs,
+            outputs: takeInOutputs(p),
             description: p.payout.kind === "brc29" ? "AMM swap payout" : "AMM swap tokens",
             labels: ["amm-swap"],
         });
@@ -503,6 +578,10 @@ export async function completeSwap(wallet, p, raw, txid) {
     }
     return out;
 }
-function internalizeOutputOf(o) {
-    return o.kind === "brc29" ? { outputIndex: o.outputIndex, protocol: WALLET_PAYMENT, paymentRemittance: { ...o.remittance } } : receiptOutput(o.outputIndex, o.receipt);
+export function internalizeOutputOf(o) {
+    if (o.kind === "brc29")
+        return { outputIndex: o.outputIndex, protocol: WALLET_PAYMENT, paymentRemittance: { ...o.remittance } };
+    if (o.kind === "basket")
+        return { outputIndex: o.outputIndex, protocol: "basket insertion", insertionRemittance: { basket: SWAP_BASKET, customInstructions: o.customInstructions } };
+    return receiptOutput(o.outputIndex, o.receipt);
 }