@dcasegr/amm-client 0.39.0 → 0.41.1

package/dist/market/swapAction.d.ts

@@ -1,50 +1,37 @@
 /**
- * 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 { Beef, Transaction, UnlockingScript, type WalletInterface, type WalletProtocol } from "@bsv/sdk";
+import { Beef, Transaction, UnlockingScript, type InternalizeOutput, 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 PaymentRemittance } 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;
@@ -68,29 +55,25 @@ export interface TokenInput {
     protocolID: WalletProtocol;
     keyID: string;
     counterparty: string;
+    /** 0.40.0: the order whose change it is (its key input, `<txid>.<vout>`); a staged row has none. */
+    order?: 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: {
+type Row = {
     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.
+ * 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 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 declare function tokenInputsOf(rows: Row[], tokenId: string): TokenInput[];
+/** An `amm-swap` sats output (customInstructions `{sats: true, protocolID, keyID, counterparty, order?}`): a plain P2PKH to an "amm swap" key. */
 export interface SatsInput {
     /** `txid.vout` */
     outpoint: string;
@@ -101,18 +84,11 @@ export interface SatsInput {
     protocolID: WalletProtocol;
     keyID: string;
     counterparty: string;
-    /** The token whose swap staged it (`<txid>_<vout>`, 0.29.1), when its row names one. */
-    assetId?: string;
+    /** 0.40.0: the order whose change it is (its key input); a staged row has none. */
+    order?: 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;
+export declare function satsInputsOf(rows: Row[]): SatsInput[];
 /** The pool output from the lookup's BEEF, as the template's PoolUtxo. */
 export declare function poolUtxoFrom(poolOutput: LookupOutput): PoolUtxo;
 /**
@@ -130,28 +106,56 @@ export declare function signP2pkhWithWallet(wallet: WalletInterface, tx: Transac
 /**
  * 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 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;
+export declare function swapTxSize(plan: CallPlan, takerInputs: number, withChange?: boolean): number;
+/** What a leg's sats inputs must cover (0.40.0). */
+export interface LegNeed {
     /** What the contract's outputs take beyond the pool's and the token inputs' sats. */
     outputs: number;
+    /** The miner fee with no change output, and its need (outputs + fee): what the sats inputs must cover. */
     fee: number;
-    size: number;
+    need: number;
+    /** The miner fee and need with the sats change output counted. */
+    feeWithChange: number;
+    needWithChange: 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.
+ * 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 declare function swapFunding(plan: CallPlan, tokenInputs: {
+export declare function legNeed(plan: CallPlan, tokenInputs: {
     satoshis: number;
-}[], satsPerKb: number): SwapFunding;
+}[], inputs: number, satsPerKb: number): LegNeed;
+/** 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;
+/** derivationPrefix of an order's last leg's change to the wallet (0.40.0): base64 of "amm swap change". */
+export declare const LEG_CHANGE_PREFIX: string;
+/**
+ * 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 declare function legDerivation(keyInput: string, which: "payout" | "commission" | "change"): {
+    derivationPrefix: string;
+    derivationSuffix: string;
+};
+/** 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 declare function changeKeyID(firstInput: string): string;
+/** 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 declare function legInputsOf(tx: Transaction): {
+    sats: string[];
+    tokens: string[];
+};
 export interface PlanLegInput {
     wallet: WalletInterface;
     /** `<txid>_0` (src/lib/tokenId.ts). */
@@ -163,45 +167,38 @@ export interface PlanLegInput {
     direction: Direction;
     leg: Leg;
     pool: PoolState;
-    /** The lookup's `{outpoint, beef: true}` answer for `leg.outpoint`. */
+    /** The pools read's `{beef, outputIndex}` 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.
+     * The relay's commission address (hash160 hex), or null when the relay names none: a pool with
+     * a nonzero CommissionBps then pays the commission to a 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"];
+/** The leg's inputs (`selectLegInputs`): its sats rows and token rows, and what the sats cover. */
+export interface LegInputs {
+    sats: SatsInput[];
+    tokens: TokenInput[];
+    need: LegNeed;
 }
+/**
+ * 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 declare function selectLegInputs(i: PlanLegInput, sats: SatsInput[], tokens: TokenInput[]): LegInputs | null;
 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). */
+    /** The leg's `amm-swap` rows (`selectLegInputs`). */
+    inputs: LegInputs;
+    /** The order's key input (`<txid>.<vout>`); absent: this is the order's first leg, its own key input. */
+    order?: string;
+    /** This leg takes all that remains of the order: its change goes to the wallet. */
+    last: boolean;
+    /** The swap basket's source transactions: the rows' (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;
 }
@@ -211,29 +208,49 @@ export type SwapPayout = {
     satoshis: number;
     lockingScript: string;
     receipt: ColorReceipt;
-} | ({
+} | {
     kind: "brc29";
-} & Brc29Payout);
+    outputIndex: number;
+    satoshis: number;
+    lockingScript: string;
+    remittance: PaymentRemittance;
+}
+/** 0.40.0: a change output kept in `amm-swap` (basket insertion with its customInstructions). */
+ | {
+    kind: "basket";
+    outputIndex: number;
+    satoshis: number;
+    lockingScript: string;
+    customInstructions: string;
+};
 export interface PreparedSwap {
     /** The pool outpoint `<txid>_<vout>`. */
     pool: string;
     validator: string;
+    bsvIn: boolean;
     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. */
+    /** The order's key input (`<txid>.<vout>`): what the payout keys are derived from. */
+    order: string;
+    /** Whether this leg's change went to the wallet. */
+    last: boolean;
+    funding: {
+        /** What the relay is sent as `funding` (0.40.1, `fundingBeef`): every staged input's source with its ancestry, the subject the first sats input's transaction. */
         atomicBeef: number[];
         txid: string;
-        /** `txid.vout` */
-        outpoint: string;
+        fee: number;
+        need: number;
     };
     /** Every input signed except the pool's validator slot. */
     swap: Transaction;
+    satsInputs: SatsInput[];
     tokenInputs: TokenInput[];
     payout: SwapPayout;
     commission: SwapCommission;
+    /** The token change output (a sell whose token rows exceed amountIn). */
+    tokenChange?: SwapPayout;
+    /** The sats change output (≥ 1 sat). */
+    satsChange?: SwapPayout;
 }
 /** The leg's commission (the pool's CommissionBps of amount in, in the input asset). */
 export interface SwapCommission {
@@ -246,34 +263,19 @@ export interface SwapCommission {
     /** "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;
+/** The leg's own key input: its first token input on a sell, its first sats input on a buy. */
+export declare function keyInputOf(inputs: Pick<LegInputs, "sats" | "tokens">, 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`.
+ * 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 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 fundingBeef(beef: Beef, fundingTxid: string, sources: string[]): number[];
+/** Builds and signs the leg (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;
@@ -296,11 +298,14 @@ export interface CompletedSwap {
     /** Internalize errors (the swap itself is final). */
     errors: string[];
 }
+/** 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 declare function takeInOutputs(p: Pick<PreparedSwap, "payout" | "commission" | "tokenChange" | "satsChange">): InternalizeOutput[];
 /**
- * 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 declare function completeSwap(wallet: WalletInterface, p: PreparedSwap, raw: number[], txid?: string): Promise<CompletedSwap>;
+export declare function internalizeOutputOf(o: SwapPayout): InternalizeOutput;
+export {};