@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/market/swapAction.js

@@ -0,0 +1,508 @@
+/**
+ * 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`).
+ *
+ *   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.
+ */
+import { 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";
+/** A P2PKH unlocking script's upper bound: push(DER ≤ 72 + sighash byte) + push(33-byte key). */
+export const P2PKH_UNLOCK_LENGTH = 108;
+/**
+ * How long the relay may take (the swap's `expires`): 15 s (0.34.0, D15, David Case 2026-11-04;
+ * was 120 s, a 10-05 builder number): the held submit returns inside it.
+ */
+export const SWAP_TTL_MS = 15_000;
+const toHex = (b) => Utils.toHex(b);
+export class LegShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LegShapeError";
+    }
+}
+/** The token's 32-byte wire id (internal byte order) for a token with a 32-byte id (`<txid>_0`; `<txid>` and `<txid>.0` read the same). */
+export function assetIdOf(tokenId) {
+    const r = parseTokenId(tokenId);
+    if (!r || r.vout !== 0)
+        throw new Error(`pools exist only for 32-byte ids (<txid>_0), not ${tokenId}`);
+    return toHex(Utils.toArray(r.txid, "hex").reverse());
+}
+/**
+ * The basket rows usable as token inputs for `tokenId`: 1Color value outputs
+ * with this 32-byte id (the pool template counts only those) whose
+ * customInstructions name the key (protocolID, keyID).
+ */
+export function tokenInputsOf(rows, tokenId) {
+    const assetId = assetIdOf(tokenId);
+    const out = [];
+    for (const r of rows) {
+        // A pool the wallet holds as LP carries the same 1Color prefix; it is not a token input.
+        if (!r.lockingScript || isPoolRow(r))
+            continue;
+        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 op = parseOutpoint(r.outpoint);
+        if (!op)
+            continue;
+        out.push({
+            outpoint: `${op.txid}.${op.vout}`,
+            txid: op.txid,
+            vout: op.vout,
+            satoshis: r.satoshis,
+            lockingScript: r.lockingScript,
+            amount: t.amount,
+            protocolID: ci.protocolID,
+            keyID: ci.keyID,
+            counterparty: typeof ci.counterparty === "string" ? ci.counterparty : "self",
+        });
+    }
+    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) {
+    const out = [];
+    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 op = parseOutpoint(r.outpoint);
+        if (!op)
+            continue;
+        out.push({
+            outpoint: `${op.txid}.${op.vout}`,
+            txid: op.txid,
+            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 } : {}),
+        });
+    }
+    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);
+    const out = tx.outputs[poolOutput.outputIndex];
+    if (!out)
+        throw new LegShapeError(`the lookup's BEEF has no output ${poolOutput.outputIndex}`);
+    return { txid: tx.id("hex"), vout: poolOutput.outputIndex, satoshis: out.satoshis, script: out.lockingScript, sourceTransaction: tx };
+}
+/**
+ * A P2PKH (or 1Color-on-P2PKH) input signed by the wallet: BIP-143 over
+ * the finished transaction under `scope` (ALL|FORKID), `createSignature` with `hashToDirectlySign`
+ * (1sat-sdk's `signP2PKHInputWallet`).
+ */
+export async function signP2pkhWithWallet(wallet, tx, inputIndex, src, scope = TransactionSignature.SIGHASH_ALL | TransactionSignature.SIGHASH_FORKID) {
+    const input = tx.inputs[inputIndex];
+    const preimage = TransactionSignature.format({
+        sourceTXID: input.sourceTXID,
+        sourceOutputIndex: input.sourceOutputIndex,
+        sourceSatoshis: src.satoshis,
+        transactionVersion: tx.version,
+        otherInputs: tx.inputs.filter((_, n) => n !== inputIndex),
+        inputIndex,
+        outputs: tx.outputs,
+        inputSequence: input.sequence ?? 0xffffffff,
+        subscript: LockingScript.fromHex(src.lockingScript),
+        lockTime: tx.lockTime,
+        scope,
+    });
+    const sighash = Hash.sha256(Hash.sha256(Array.from(preimage)));
+    const args = { protocolID: src.protocolID, keyID: src.keyID, counterparty: src.counterparty };
+    const { signature } = await wallet.createSignature({ ...args, hashToDirectlySign: Array.from(sighash) });
+    const { publicKey } = await wallet.getPublicKey({ ...args, forSelf: true });
+    return new UnlockingScript().writeBin([...signature, scope]).writeBin(Utils.toArray(publicKey, "hex"));
+}
+// ---------------------------------------------------------------------------
+// The leg's sats
+// ---------------------------------------------------------------------------
+function varIntSize(n) {
+    return n < 0xfd ? 1 : n <= 0xffff ? 3 : n <= 0xffffffff ? 5 : 9;
+}
+/**
+ * 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.
+ */
+export function swapTxSize(plan, takerInputs) {
+    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);
+    for (const o of plan.outputs) {
+        const len = o.script.length / 2;
+        size += 8 + varIntSize(len) + len;
+    }
+    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.
+ */
+export function swapFunding(plan, tokenInputs, 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 ZERO_PKH = "00".repeat(20);
+/** 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"));
+/**
+ * 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.
+ */
+export function legDerivation(keyInput, which) {
+    return {
+        derivationPrefix: which === "payout" ? LEG_PAYOUT_PREFIX : LEG_COMMISSION_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 plan with the given payout and commission addresses (`planSwap`, the leg's quote as the expectation). */
+function legPlan(i, poolUtxo, userPkh, commissionPkh) {
+    const { leg, pool } = i;
+    return PoolTemplate.planSwap({
+        pool: poolUtxo,
+        amountIn: leg.amountIn,
+        bsvIn: i.direction === "bsvToToken",
+        userPkh,
+        commissionPkh,
+        expect: {
+            bsvReserve: pool.bsvReserve,
+            tokenReserve: pool.tokenReserve,
+            lpFeeBps: pool.liquidityFeeBps,
+            validatorFeeBps: pool.validationFeeBps,
+            commissionBps: pool.commissionBps,
+            lpFee: leg.liquidityFee,
+            validatorFee: leg.validationFee,
+            commission: leg.commission,
+            amountOut: leg.amountOut,
+        },
+    });
+}
+/**
+ * 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`.
+ */
+export async function planSwapLeg(i) {
+    const { leg } = i;
+    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)}`);
+    }
+    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 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 };
+}
+/** Steps 1 (unless `planned` is given) and 3 (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 decoded = PoolTemplate.decode(poolUtxo.script);
+    const identity = !bsvIn || commissionTo === "own" ? 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;
+    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 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 commission = { amount: commissionAmount, pkh: commissionPkh, to: commissionTo };
+    if (ownCommission) {
+        const at = plan.outputs.length - 1;
+        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 };
+    }
+    // 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])
+        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.
+    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)
+        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);
+    for (let n = 1; n < swap.inputs.length; n++) {
+        if (!spendValid(swap, n))
+            throw new LegShapeError(`input ${n} of the swap does not validate`);
+    }
+    return {
+        pool: planned.pool,
+        validator: planned.validator,
+        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 },
+        swap,
+        tokenInputs,
+        payout,
+        commission,
+    };
+}
+/** @bsv/sdk's `Spend` over input `n` of `tx` (its source output from `sourceTransaction`). */
+export function spendValid(tx, n) {
+    const inp = tx.inputs[n];
+    const src = inp.sourceTransaction?.outputs[inp.sourceOutputIndex];
+    if (!src)
+        return false;
+    try {
+        return new Spend({
+            sourceTXID: inp.sourceTXID ?? inp.sourceTransaction.id("hex"),
+            sourceOutputIndex: inp.sourceOutputIndex,
+            sourceSatoshis: src.satoshis,
+            lockingScript: src.lockingScript,
+            transactionVersion: tx.version,
+            otherInputs: tx.inputs.filter((_, j) => j !== n),
+            outputs: tx.outputs,
+            inputIndex: n,
+            unlockingScript: inp.unlockingScript,
+            inputSequence: inp.sequence ?? 0xffffffff,
+            lockTime: tx.lockTime,
+        }).validate();
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// After the relay's answer
+// ---------------------------------------------------------------------------
+/**
+ * The validator's final transaction, checked against ours: same inputs (in
+ * order, the taker's unlocking scripts unchanged), same outputs; only input
+ * 0's unlocking script (the validator's slot) differs. Its inputs get our
+ * source transactions, so it serializes as AtomicBEEF.
+ */
+export function finalSwapOf(p, raw, txid) {
+    return finalCallOf(p.swap, raw, txid, "the swap we built");
+}
+/**
+ * A validator-signed pool call checked against the one we built (`ours`):
+ * same inputs in order with our unlocking scripts on every input but the
+ * pool's (input 0), same outputs. Shared by the swap and AddLiquidity.
+ */
+export function finalCallOf(ours, raw, txid, what) {
+    let tx;
+    try {
+        tx = Transaction.fromBinary(raw);
+    }
+    catch {
+        tx = Transaction.fromBEEF(raw);
+    }
+    if (txid && tx.id("hex") !== txid)
+        throw new LegShapeError(`the relay's transaction is ${tx.id("hex")}, not ${txid}`);
+    const same = tx.inputs.length === ours.inputs.length &&
+        tx.outputs.length === ours.outputs.length &&
+        tx.inputs.every((inp, n) => {
+            const o = ours.inputs[n];
+            const src = inp.sourceTXID ?? inp.sourceTransaction?.id("hex");
+            return src === o.sourceTXID && inp.sourceOutputIndex === o.sourceOutputIndex && (n === 0 || inp.unlockingScript?.toHex() === o.unlockingScript.toHex());
+        }) &&
+        tx.outputs.every((out, n) => out.satoshis === ours.outputs[n].satoshis && out.lockingScript.toHex() === ours.outputs[n].lockingScript.toHex());
+    if (!same)
+        throw new LegShapeError(`the relay's transaction is not ${what}`);
+    tx.inputs.forEach((inp, n) => {
+        inp.sourceTransaction = ours.inputs[n].sourceTransaction;
+        inp.sourceTXID = ours.inputs[n].sourceTXID;
+    });
+    return tx;
+}
+/**
+ * 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`).
+ */
+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,
+            description: p.payout.kind === "brc29" ? "AMM swap payout" : "AMM swap tokens",
+            labels: ["amm-swap"],
+        });
+        out.internalized = r.accepted;
+    }
+    catch (err) {
+        out.errors.push(`internalizeAction: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out;
+}
+function internalizeOutputOf(o) {
+    return o.kind === "brc29" ? { outputIndex: o.outputIndex, protocol: WALLET_PAYMENT, paymentRemittance: { ...o.remittance } } : receiptOutput(o.outputIndex, o.receipt);
+}

package/dist/market/swapFlow.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A prepared swap through the relay to its end (pure over the wallet and
+ * AuthFetch, tested with fakes). 0.34.0 (D15, David Case 2026-11-04): the submit's answer is
+ * the settled record — the host holds the `/call` request until the relay thread rests (the
+ * validator's answer; a dial failure settles `failed` at once) — so nothing polls:
+ *
+ *   submit (amm.swap.submit) →
+ *     accepted: completeSwap (internalizeAction; 0.29.0: no relinquishOutput)
+ *     refused / timeout / an error answer to submit (nothing recorded):
+ *       nothing to undo: the leg's `amm-swap` outputs stay there
+ *     no answer (a network failure, the host's 503 past its bound, a `pending` record, the
+ *       relay's transport `failed`): "no answer yet", left alone — the relay may still carry it;
+ *       "Check again" reads the record ONCE (`GET <base>/swaps?id=`, plain) and acts on it.
+ *
+ * The swap's id is the relay's (amm-p2p relay.zig `idOf`): sha256 of the swap as submitted (the
+ * validator's slot empty), hex — known to the page, so a lost answer can be checked again.
+ */
+import { type WalletInterface } from "@bsv/sdk";
+import type { PoolState } from "@dcasegr/amm-engine";
+import { type AuthFetchLike } from "./relay.js";
+import { type CompletedSwap, type PreparedSwap } from "./swapAction.js";
+export type SwapOutcome = {
+    status: "accepted";
+    id: string;
+    txid: string;
+    completed: CompletedSwap;
+} | {
+    status: "refused";
+    id: string;
+    reason: string;
+    pool?: PoolState;
+} | {
+    status: "timeout";
+    id: string;
+} | {
+    status: "failed";
+    reason: string;
+} | {
+    status: "unknown";
+    id: string;
+    reason: string;
+};
+export interface RelayContext {
+    wallet: WalletInterface;
+    authFetch: AuthFetchLike;
+    /** The token instance's AMM base. */
+    base: string;
+    /** The plain fetch "Check again" reads the record with (default: the browser's). */
+    fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+}
+/** The relay's id of a prepared swap: sha256 of the swap's bytes as submitted, hex. */
+export declare function swapIdOf(p: PreparedSwap): string;
+/** "no answer yet": what a held request that came back without the settled record means. */
+export declare const NO_ANSWER_YET = "no answer yet";
+/** `peerId`: the chosen validator's libp2p peer ID, from the pools route's row (the relay dials it). */
+export declare function relaySwap(c: RelayContext, p: PreparedSwap, peerId: string): Promise<SwapOutcome>;
+/** "Check again" for an unknown outcome: the record read ONCE, plain (`GET <base>/swaps?id=`, P10), and acted on. */
+export declare function checkAgain(c: RelayContext, p: PreparedSwap, id: string): Promise<SwapOutcome>;

package/dist/market/swapFlow.js

@@ -0,0 +1,86 @@
+/**
+ * A prepared swap through the relay to its end (pure over the wallet and
+ * AuthFetch, tested with fakes). 0.34.0 (D15, David Case 2026-11-04): the submit's answer is
+ * the settled record — the host holds the `/call` request until the relay thread rests (the
+ * validator's answer; a dial failure settles `failed` at once) — so nothing polls:
+ *
+ *   submit (amm.swap.submit) →
+ *     accepted: completeSwap (internalizeAction; 0.29.0: no relinquishOutput)
+ *     refused / timeout / an error answer to submit (nothing recorded):
+ *       nothing to undo: the leg's `amm-swap` outputs stay there
+ *     no answer (a network failure, the host's 503 past its bound, a `pending` record, the
+ *       relay's transport `failed`): "no answer yet", left alone — the relay may still carry it;
+ *       "Check again" reads the record ONCE (`GET <base>/swaps?id=`, plain) and acts on it.
+ *
+ * The swap's id is the relay's (amm-p2p relay.zig `idOf`): sha256 of the swap as submitted (the
+ * validator's slot empty), hex — known to the page, so a lost answer can be checked again.
+ */
+import { Hash, Utils } from "@bsv/sdk";
+import { RelayError, parseSwapRecord, submitSwap } from "./relay.js";
+import { completeSwap } from "./swapAction.js";
+import { readSwap } from "../lib/overlay.js";
+const errText = (e) => (e instanceof Error ? e.message : String(e));
+/** The relay's id of a prepared swap: sha256 of the swap's bytes as submitted, hex. */
+export function swapIdOf(p) {
+    return Utils.toHex(Hash.sha256(p.swap.toBinary()));
+}
+/** "no answer yet": what a held request that came back without the settled record means. */
+export const NO_ANSWER_YET = "no answer yet";
+/** `peerId`: the chosen validator's libp2p peer ID, from the pools route's row (the relay dials it). */
+export async function relaySwap(c, p, peerId) {
+    const id = swapIdOf(p);
+    let record;
+    try {
+        record = await submitSwap(c.authFetch, c.base, {
+            funding: p.funding.atomicBeef,
+            swap: p.swap.toBinary(),
+            pool: p.pool,
+            validator: p.validator,
+            peerId,
+            expires: p.expires,
+        });
+    }
+    catch (err) {
+        // The host's bound passed with the relay still out: no answer yet (the swap stands).
+        if (err instanceof RelayError && err.httpStatus === 503)
+            return { status: "unknown", id, reason: NO_ANSWER_YET };
+        // The relay answered with an error: it recorded nothing and sent nothing on.
+        if (err instanceof RelayError)
+            return { status: "failed", reason: `amm.swap.submit: ${err.message}` };
+        return { status: "unknown", id, reason: `${NO_ANSWER_YET}: amm.swap.submit: ${errText(err)}` };
+    }
+    return act(c, p, record);
+}
+/** A record's outcome, acted on (accepted: the wallet takes the payout in). */
+async function act(c, p, r) {
+    switch (r.status) {
+        case "pending":
+            return { status: "unknown", id: r.id, reason: NO_ANSWER_YET };
+        case "accepted":
+            return { status: "accepted", id: r.id, txid: r.txid, completed: await completeSwap(c.wallet, p, r.tx, r.txid) };
+        case "refused":
+            return r.pool ? { status: "refused", id: r.id, reason: r.reason, pool: r.pool } : { status: "refused", id: r.id, reason: r.reason };
+        case "timeout":
+            return { status: "timeout", id: r.id };
+        case "failed":
+            return { status: "unknown", id: r.id, reason: `the relay could not reach the validator (${r.reason})` };
+    }
+}
+/** "Check again" for an unknown outcome: the record read ONCE, plain (`GET <base>/swaps?id=`, P10), and acted on. */
+export async function checkAgain(c, p, id) {
+    let raw;
+    try {
+        raw = await readSwap(c.base, id, c.fetch);
+    }
+    catch (err) {
+        return { status: "unknown", id, reason: `${NO_ANSWER_YET}: ${errText(err)}` };
+    }
+    if (raw === null)
+        return { status: "unknown", id, reason: `${NO_ANSWER_YET}: the relay has no record of it` };
+    try {
+        return await act(c, p, parseSwapRecord(raw));
+    }
+    catch (err) {
+        return { status: "unknown", id, reason: errText(err) };
+    }
+}