@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/market/relay.js

@@ -0,0 +1,201 @@
+/**
+ * The marketplace relay (docs/notes.md, "Marketplace relay"): the user's own
+ * skein instance takes the funding and swap transactions and carries them to
+ * the pool's validator, so the browser needs no libp2p. Two functions on the
+ * AMM app's box, hosted by programs/amm-p2p:
+ *
+ *   amm.swap.terms   (reads)   {} → {commissionPkh: bytes(20) | null, minCommissionBps}
+ *   amm.swap.submit  (writes)  {funding, swap, pool, validator, peerId, expires} → the record
+ *                              (0.34.0, D15: the host holds the request until the relay thread
+ *                              rests, so the answer is the settled record; past the host's bound,
+ *                              503: no answer yet)
+ *   amm.swap.status  (reads)   {id} → the record (0.34.0: the pages read it plain, `GET
+ *                              <base>/swaps?id=`, src/lib/overlay.ts `readSwap`, behind "Check again")
+ *
+ *   commissionPkh  the address the relay takes the pool's commission at
+ *              (Swap's `commissionPkh`; 0.16.0: hash160 of the instance's
+ *              own derived key, no config); null when the instance names
+ *              none, in which case a pool with a nonzero CommissionBps pays
+ *              the commission to the taker's own key
+ *              (src/market/swapAction.ts, "the commission")
+ *   minCommissionBps  this market's minimum commission (0.16.0: the record
+ *              root sets, `amm/market`; absent or unset, 0): a listing
+ *              preference, the pools the Swap page lists, not a rule
+ *
+ *   funding    bytes: the funding transaction as the wallet's AtomicBEEF (its
+ *              ancestry with it: the validator's overlay verifies the unproven
+ *              funding against parents in the BEEF); 0.29.0: the transaction
+ *              of the leg's `amm-swap` sats output, the swap's input 1
+ *   swap       bytes: the raw swap, the validator's slot `OP_0`
+ *   pool       text `<txid>_<vout>`; validator bytes(33); expires unix ms
+ *   peerId     text: the validator's libp2p peer ID, from the pools route's row
+ *              (`validatorPeerId`, 0.34.0: the host joined it from the beat): the
+ *              relay dials it (or, when it is the relay's own node, hands the
+ *              swap to its own validator program); it looks at no liveness
+ *
+ * record (programs/amm-p2p relay.zig `Record.answer`; id = sha256 of the swap, hex):
+ *   {id, status: "pending" | "accepted" | "refused" | "timeout" | "failed", pool, expires, …,
+ *    tx?, txid?            accepted: the validator's signed swap
+ *    reason?, detail?,     refused / timeout / failed
+ *    poolState?}           refused: the pool's current state (the validator's)
+ * "failed" is the relay's transport failure (retryable by submitting again):
+ * the validator may or may not have the swap, so the page treats it as no
+ * answer, not as a refusal.
+ *
+ * Transport: the app's `/call` route (skein docs/APPS.md §4): `POST
+ * <VITE_AMM_OVERLAY>/call`, JSON body `{fn, args}`, answer `{fn, result}`
+ * (200) or `{fn, error: {code, message}}` (400 bad-request / bad-args, 403
+ * not-admitted, 404 unknown-fn, 409 read-only, 500 failed). The route is
+ * BRC-104 authenticated: the caller must be admitted to the app's box, so
+ * both calls go through the wallet-backed AuthFetch (src/wallet/authFetch.ts).
+ *
+ * Bytes in `args` are DAG-JSON bytes (`{"/": {"bytes": "<base64, unpadded>"}}`),
+ * how skein reads JSON bodies (docs/MESSAGES.md "The messagebox"); answers are
+ * read as DAG-JSON bytes, hex or a byte array.
+ */
+import { Utils } from "@bsv/sdk";
+export const SWAP_SUBMIT_FN = "amm.swap.submit";
+export const SWAP_STATUS_FN = "amm.swap.status";
+export const SWAP_TERMS_FN = "amm.swap.terms";
+export class RelayError extends Error {
+    code;
+    httpStatus;
+    constructor(code, message, httpStatus) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.httpStatus = httpStatus;
+        this.name = "RelayError";
+    }
+}
+export function dagBytes(bytes) {
+    return { "/": { bytes: Utils.toBase64(bytes).replace(/=+$/, "") } };
+}
+/** DAG-JSON bytes, hex, or a byte array → bytes; null otherwise. */
+export function readBytes(x) {
+    if (Array.isArray(x) && x.every((b) => Number.isInteger(b) && b >= 0 && b < 256))
+        return x;
+    if (typeof x === "string" && /^([0-9a-f]{2})+$/i.test(x))
+        return Utils.toArray(x, "hex");
+    const b = x?.["/"]?.bytes;
+    if (typeof b === "string") {
+        const padded = b + "=".repeat((4 - (b.length % 4)) % 4);
+        return Utils.toArray(padded, "base64");
+    }
+    return null;
+}
+export function callUrl(base) {
+    return `${base.replace(/\/+$/, "")}/call`;
+}
+export function submitBody(s) {
+    return {
+        fn: SWAP_SUBMIT_FN,
+        args: { funding: dagBytes(s.funding), swap: dagBytes(s.swap), pool: s.pool, validator: dagBytes(Utils.toArray(s.validator, "hex")), peerId: s.peerId, expires: s.expires },
+    };
+}
+/** One `{fn, args}` call on the app's `/call` route. Throws `RelayError` on an error answer. */
+export async function callApp(af, base, fn, args) {
+    const res = await af.fetch(callUrl(base), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ fn, args }),
+    });
+    const text = await res.text();
+    let answer = null;
+    try {
+        answer = JSON.parse(text);
+    }
+    catch {
+        /* not JSON */
+    }
+    if (res.status === 200 && answer && "result" in answer)
+        return answer.result;
+    const e = answer?.error;
+    throw new RelayError(typeof e?.code === "string" ? e.code : `HTTP ${res.status}`, typeof e?.message === "string" ? e.message : text.slice(0, 200), res.status);
+}
+/**
+ * A refusal's pool, as the validator writes it (messages.zig poolValue:
+ * `lpFeeBps`, `validatorFeeBps`, `validatorIdentity`) or as the lookup does
+ * (the engine's names), into the engine's PoolState. A closed pool, or one
+ * missing a field, is undefined: nothing left to re-price.
+ */
+export function toPoolState(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const p = raw;
+    if (p.closed)
+        return undefined;
+    const num = (...ks) => ks.map((k) => p[k]).find((v) => typeof v === "number" || typeof v === "string");
+    const outpoint = p.outpoint;
+    const bsv = num("bsvReserve");
+    const tokens = num("tokenReserve");
+    const lp = num("liquidityFeeBps", "lpFeeBps");
+    const val = num("validationFeeBps", "validatorFeeBps");
+    const comm = num("commissionBps");
+    const rawId = p.validatorIdentityKey ?? p.validatorIdentity;
+    const idBytes = typeof rawId === "string" ? null : readBytes(rawId);
+    const identity = typeof rawId === "string" ? rawId : idBytes?.length === 33 ? Utils.toHex(idBytes) : undefined;
+    if (typeof outpoint !== "string" || bsv === undefined || tokens === undefined || lp === undefined || val === undefined || typeof identity !== "string") {
+        return undefined;
+    }
+    return {
+        outpoint,
+        bsvReserve: BigInt(bsv),
+        tokenReserve: BigInt(tokens),
+        liquidityFeeBps: BigInt(lp),
+        validationFeeBps: BigInt(val),
+        commissionBps: BigInt((comm ?? 0)),
+        validatorIdentityKey: identity,
+    };
+}
+export function parseSwapRecord(x) {
+    const r = x;
+    const id = r?.id ?? r?.swapId;
+    const status = r?.status ?? r?.state;
+    if (!r || typeof id !== "string")
+        throw new Error(`relay: not a swap record: ${JSON.stringify(x)?.slice(0, 200)}`);
+    switch (status) {
+        case "pending":
+        case "timeout":
+            return { id, status };
+        case "failed":
+            return { id, status, reason: (typeof r.reason === "string" ? r.reason : "failed") + (typeof r.detail === "string" && r.detail ? `: ${r.detail}` : "") };
+        case "accepted": {
+            const tx = readBytes(r.tx);
+            if (!tx || typeof r.txid !== "string")
+                throw new Error("relay: accepted without tx / txid");
+            return { id, status, tx, txid: r.txid };
+        }
+        case "refused": {
+            const pool = toPoolState(r.poolState ?? (typeof r.pool === "object" ? r.pool : undefined));
+            const reason = (typeof r.reason === "string" ? r.reason : "refused") + (typeof r.detail === "string" && r.detail ? `: ${r.detail}` : "");
+            return pool ? { id, status, reason, pool } : { id, status, reason };
+        }
+        default:
+            throw new Error(`relay: unknown swap status ${JSON.stringify(status)}`);
+    }
+}
+/** `amm.swap.terms`'s answer: `commissionPkh` as DAG-JSON bytes (or hex, or a byte array) of 20 bytes, or null / absent; `minCommissionBps` an integer 0 to 10 000, absent 0 (0.16.0). */
+export function parseSwapTerms(x) {
+    const r = x;
+    if (!r || typeof r !== "object")
+        throw new Error(`relay: not swap terms: ${JSON.stringify(x)?.slice(0, 200)}`);
+    const m = r.minCommissionBps ?? 0;
+    if (typeof m !== "number" || !Number.isInteger(m) || m < 0 || m > 10_000)
+        throw new Error("relay: minCommissionBps is not an integer, 0 to 10000");
+    if (r.commissionPkh === null || r.commissionPkh === undefined)
+        return { commissionPkh: null, minCommissionBps: m };
+    const b = readBytes(r.commissionPkh);
+    if (!b || b.length !== 20)
+        throw new Error("relay: commissionPkh is not 20 bytes");
+    return { commissionPkh: Utils.toHex(b), minCommissionBps: m };
+}
+export async function swapTerms(af, base) {
+    return parseSwapTerms(await callApp(af, base, SWAP_TERMS_FN, {}));
+}
+export async function submitSwap(af, base, s) {
+    const { fn, args } = submitBody(s);
+    return parseSwapRecord(await callApp(af, base, fn, args));
+}
+export async function swapStatus(af, base, id) {
+    return parseSwapRecord(await callApp(af, base, SWAP_STATUS_FN, { id }));
+}

package/dist/market/swapAction.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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 { Beef, Transaction, UnlockingScript, type WalletInterface, type WalletProtocol } from "@bsv/sdk";
+import type { Direction, Leg, PoolState } from "@dcasegr/amm-engine";
+import { type CallPlan, type PoolUtxo } from "../pool/index.js";
+import type { LookupOutput } from "../lib/overlay.js";
+import { type Brc29Payout } from "../wallet/brc29.js";
+import { type ColorReceipt } from "../wallet/color.js";
+/** A P2PKH unlocking script's upper bound: push(DER ≤ 72 + sighash byte) + push(33-byte key). */
+export declare 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 declare const SWAP_TTL_MS = 15000;
+export declare class LegShapeError extends Error {
+    constructor(message: string);
+}
+/** An `amm-swap` basket output the wallet can sign: a 1Color value output of the token, with its key. */
+export interface TokenInput {
+    /** `txid.vout` (BRC-100 outpoint form). */
+    outpoint: string;
+    txid: string;
+    vout: number;
+    satoshis: number;
+    lockingScript: string;
+    amount: bigint;
+    protocolID: WalletProtocol;
+    keyID: string;
+    counterparty: string;
+}
+/** 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 declare function assetIdOf(tokenId: string): string;
+/**
+ * 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 declare function tokenInputsOf(rows: {
+    outpoint: string;
+    satoshis: number;
+    lockingScript?: string;
+    tags?: string[];
+    customInstructions?: string;
+}[], tokenId: string): TokenInput[];
+/**
+ * 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 declare function selectExactTokenInputs(candidates: TokenInput[], amount: bigint): TokenInput[] | null;
+/** An `amm-swap` sats output (customInstructions `{sats: true, assetId, protocolID, keyID, counterparty}`): a plain P2PKH to an "amm swap" key. */
+export interface SatsInput {
+    /** `txid.vout` */
+    outpoint: string;
+    txid: string;
+    vout: number;
+    satoshis: number;
+    lockingScript: string;
+    protocolID: WalletProtocol;
+    keyID: string;
+    counterparty: string;
+    /** The token whose swap staged it (`<txid>_<vout>`, 0.29.1), when its row names one. */
+    assetId?: string;
+}
+/** The basket rows usable as a leg's sats: plain P2PKH outputs whose customInstructions say `sats: true` and name the key. */
+export declare function satsInputsOf(rows: {
+    outpoint: string;
+    satoshis: number;
+    lockingScript?: string;
+    customInstructions?: string;
+}[]): SatsInput[];
+/** The sats twin of `selectExactTokenInputs`: one output of exactly `satoshis` (the leg has no change), or null. */
+export declare function selectExactSatsInput(candidates: SatsInput[], satoshis: number): SatsInput | null;
+/** The pool output from the lookup's BEEF, as the template's PoolUtxo. */
+export declare function poolUtxoFrom(poolOutput: LookupOutput): PoolUtxo;
+/**
+ * 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 declare function signP2pkhWithWallet(wallet: WalletInterface, tx: Transaction, inputIndex: number, src: {
+    satoshis: number;
+    lockingScript: string;
+    protocolID: WalletProtocol;
+    keyID: string;
+    counterparty: string;
+}, scope?: number): Promise<UnlockingScript>;
+/**
+ * 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 declare function swapTxSize(plan: CallPlan, takerInputs: number): number;
+export interface SwapFunding {
+    /** The leg's sats output's exact amount (0.29.0: an `amm-swap` output). */
+    satoshis: number;
+    /** What the contract's outputs take beyond the pool's and the token inputs' sats. */
+    outputs: number;
+    fee: number;
+    size: number;
+    satsPerKb: number;
+}
+/**
+ * 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 declare function swapFunding(plan: CallPlan, tokenInputs: {
+    satoshis: number;
+}[], satsPerKb: number): SwapFunding;
+export interface PlanLegInput {
+    wallet: WalletInterface;
+    /** `<txid>_0` (src/lib/tokenId.ts). */
+    tokenId: string;
+    meta?: {
+        sym?: string;
+        dec?: number;
+    };
+    direction: Direction;
+    leg: Leg;
+    pool: PoolState;
+    /** The lookup's `{outpoint, beef: true}` answer for `leg.outpoint`. */
+    poolOutput: LookupOutput;
+    /**
+     * The relay's commission address (`amm.swap.terms`, hash160 hex), or null
+     * when the relay names none: a pool with a nonzero CommissionBps then pays
+     * the commission to a fresh key of the taker's own.
+     */
+    commissionPkh: string | null;
+    /**
+     * token → sats: the token inputs carrying exactly `leg.amountIn`, or (0.29.0) what they will be
+     * once staged: one output of 1 sat per leg (`sendToSwapBasket`). Their count and sats size the
+     * leg's sats.
+     */
+    tokenInputs?: Pick<TokenInput, "satoshis" | "amount">[];
+    /** sats per 1000 bytes (`VITE_FEE_RATE`). */
+    satsPerKb: number;
+}
+/** Step 1: the leg's plan (placeholder addresses) and exact sats (`funding.satoshis`: the `amm-swap` sats output the leg spends). */
+export interface PlannedLeg {
+    /** The pool outpoint `<txid>_<vout>`. */
+    pool: string;
+    validator: string;
+    bsvIn: boolean;
+    poolUtxo: PoolUtxo;
+    /** Sized with placeholder payout and commission addresses (prepareSwap re-plans with the derived keys). */
+    plan: CallPlan;
+    funding: SwapFunding;
+    commissionAmount: bigint;
+    commissionTo: SwapCommission["to"];
+}
+export interface PrepareSwapInput extends PlanLegInput {
+    /** token → sats: `amm-swap` outputs carrying exactly `leg.amountIn`. */
+    tokenInputs?: TokenInput[];
+    /** The leg's `amm-swap` sats output: exactly the planned `funding.satoshis` (0.29.0). */
+    satsInput: SatsInput;
+    /** The swap basket's source transactions: the sats and token inputs' (default: `amm-swap`'s, from the wallet). */
+    holdingBeef?: Beef;
+    /** Step 1 already done (`planSwapLeg` over the same input); planned here when absent. */
+    planned?: PlannedLeg;
+    now?: number;
+    ttlMs?: number;
+}
+export type SwapPayout = {
+    kind: "color";
+    outputIndex: number;
+    satoshis: number;
+    lockingScript: string;
+    receipt: ColorReceipt;
+} | ({
+    kind: "brc29";
+} & Brc29Payout);
+export interface PreparedSwap {
+    /** The pool outpoint `<txid>_<vout>`. */
+    pool: string;
+    validator: string;
+    expires: number;
+    plan: CallPlan;
+    funding: SwapFunding & {
+        /** The leg's `amm-swap` sats output (input 1). */
+        input: SatsInput;
+        /** Its transaction as the wallet's AtomicBEEF: the swap's funding transaction, what the relay is sent. */
+        atomicBeef: number[];
+        txid: string;
+        /** `txid.vout` */
+        outpoint: string;
+    };
+    /** Every input signed except the pool's validator slot. */
+    swap: Transaction;
+    tokenInputs: TokenInput[];
+    payout: SwapPayout;
+    commission: SwapCommission;
+}
+/** The leg's commission (the pool's CommissionBps of amount in, in the input asset). */
+export interface SwapCommission {
+    /** 0 when the pool's CommissionBps is 0: no output. */
+    amount: bigint;
+    /** Swap's `commissionPkh` (pushed even when there is no output). */
+    pkh: string;
+    /** "relay": the relay's address; "own": the taker's key, internalized with the payout; "none": no output. */
+    to: "relay" | "own" | "none";
+    /** "own" only: the wallet's record of the commission output. */
+    payout?: SwapPayout;
+}
+/** BRC-29 / BRC-207 derivationPrefix of a leg's payout (0.29.1): base64 of the UTF-8 text "amm swap". */
+export declare const LEG_PAYOUT_PREFIX: string;
+/** derivationPrefix of the taker's own commission output (0.29.1): base64 of "amm swap commission". */
+export declare const LEG_COMMISSION_PREFIX: string;
+/**
+ * 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 declare function legDerivation(keyInput: string, which: "payout" | "commission"): {
+    derivationPrefix: string;
+    derivationSuffix: string;
+};
+/** The leg's key input in a swap transaction (see `legDerivation`): input 2 when it spends tokens, else input 1. */
+export declare function legKeyInputOf(swap: Transaction, bsvIn: boolean): string;
+/**
+ * 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 declare function planSwapLeg(i: PlanLegInput): Promise<PlannedLeg>;
+/** Steps 1 (unless `planned` is given) and 3 (see the module comment). Throws `PoolBuildError` / `LegShapeError`; the wallet is left as it was. */
+export declare function prepareSwap(i: PrepareSwapInput): Promise<PreparedSwap>;
+/** @bsv/sdk's `Spend` over input `n` of `tx` (its source output from `sourceTransaction`). */
+export declare function spendValid(tx: Transaction, n: number): boolean;
+/**
+ * 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 declare function finalSwapOf(p: PreparedSwap, raw: number[], txid?: string): Transaction;
+/**
+ * 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 declare function finalCallOf(ours: Transaction, raw: number[], txid: string | undefined, what: string): Transaction;
+export interface CompletedSwap {
+    txid: string;
+    internalized: boolean;
+    /** Internalize errors (the swap itself is final). */
+    errors: string[];
+}
+/**
+ * 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 declare function completeSwap(wallet: WalletInterface, p: PreparedSwap, raw: number[], txid?: string): Promise<CompletedSwap>;