@dcasegr/amm-client 0.39.0 → 0.42.2

package/dist/market/activeSwap.d.ts

@@ -1,49 +1,28 @@
 /**
- * The active swap basket (skein-amm 0.12.0, David Case 2026-10-21/22; 0.29.0,
- * 2026-11-02): everything the swap legs spend, held outside the BRC-207 module
- * in the exchange's own basket `amm-swap` (src/wallet/color.ts): the token
- * outputs and each leg's sats.
+ * The active swap basket (skein-amm 0.12.0, David Case 2026-10-21/22; 0.40.0, agent-env
+ * plans/swap-balance-build-2026-11-05.md §0 7, Builder 2 item 2): what a swap stages for its legs,
+ * held outside the BRC-207 module in the exchange's own basket `amm-swap` (src/wallet/color.ts).
+ * No deposit, no withdraw, no balance the user manages.
  *
- *   - **In** (`sendToSwapBasket`): before the legs of a tokens-in swap, ONE
- *     wallet-built send through the module: one 1Color value output per leg
- *     not covered by what `amm-swap` already holds, each exactly the leg's
- *     amount in (the pool takes no token change, so a leg needs inputs that
- *     sum to its amount exactly), locked to a key derived from the leg's pool outpoint (`swapKeyID`) under `[2, "amm
- *     swap"]` (counterparty self), the plan naming them a transfer out; and
- *     (0.29.0) one P2PKH sats output per leg not covered (the leg's exact
- *     sats, `swapFunding`), to that outpoint's `:sats` key, filed in
- *     `amm-swap` by the createAction itself (customInstructions `{sats: true,
- *     assetId, protocolID, keyID, counterparty}`). The module passes the sats outputs
- *     through, selects the token inputs, adds change, asks once, signs and
- *     submits to `tm_color_<assetId>`; the wallet funds the sats; the page
- *     submits it to this skein too (a repeat is harmless), then files each
- *     token output in `amm-swap` (basket insertion, customInstructions
- *     `{assetId, amount, protocolID, keyID, counterparty}`). A sats-in swap,
- *     or a tokens-in swap whose tokens are all staged already, sends only the
- *     sats (`sendSatsToSwapBasket`: a plain createAction, no `p color` labels).
- *   - **Spent** by the legs (src/market/swapAction.ts): app-built,
- *     `createSignature` under the key the customInstructions name; the
- *     wallet marks them spent when it takes the accepted swap in (0.29.0: no
- *     relinquishOutput). An output a failed leg did not spend stays for a
- *     later swap.
- *   - **Move back** (`moveBack`, the recovery path; 0.29.3: a module plan,
- *     David Case 2026-11-02): ONE createAction through the wallet's BRC-207
- *     module, a `p color plan` transfer: every `amm-swap` token output of the
- *     token and (0.29.1) the sats rows staged for its legs (their `assetId`)
- *     as explicit inputs (their source transactions in `inputBEEF`) — to the
- *     module FOREIGN inputs (not in a `p color` basket): the token rows
- *     checked admitted and unspent on the token's overlay, the sats rows
- *     adding nothing; one output, the whole amount to a NEW module receiving
- *     key of the user's own, the plan's owned output 0 (the module checks it
- *     pays the remittance's key and files it in `p color <assetTag>` with its
- *     custody in the same call). The page unlocks its inputs at signAction;
- *     the wallet funds the fee and takes the sats rows into its change; the
- *     module approves and submits, the wallet broadcasts. The page submits it
- *     to this skein's token topic too. Nothing is taken in afterwards and
- *     nothing is kept in the browser. *     (0.29.6) With no token row and only sats rows staged for the token
- *     (a sats-in leg that failed): one plain createAction (no `p color`
- *     labels), the sats rows as explicit inputs and no outputs — the wallet
- *     keeps them as its change and pays the fee (`moveBackSats`).
+ *   - **Staging** (`stage`): at Swap, ONE wallet action. Sats only (a buy, or a sell whose tokens
+ *     the basket holds): a plain createAction, ONE P2PKH output to a fresh key under `SWAP_PROTOCOL`
+ *     (self, keyID random, `amm-swap-<hex>`), filed in `amm-swap` by the action with its
+ *     customInstructions (`{sats: true, protocolID, keyID, counterparty}`: no token tag). With
+ *     tokens: the module transfer plan — ONE token output to a fresh key and the ONE sats output in
+ *     the same action, the token key's id ALSO in that output's description (`… · amm-swap <hex>`,
+ *     as the LP key's `amm-lp <hex>`), the action labelled `SWAP_STAGE_LABEL`; the module selects
+ *     the token inputs, adds change, signs and submits; the page submits it too, then files the
+ *     token output in `amm-swap` (basket insertion, `{assetId, amount, protocolID, keyID,
+ *     counterparty}`). A labelled staged token output the basket lacks (the page died before the
+ *     filing) is filed on load from the action's description (`unfiledStagedTokens`).
+ *   - **Spent** by the legs (src/market/swapAction.ts), their change kept here between legs.
+ *   - **Move back** (`moveBack`, as 0.29.3): ONE createAction through the wallet's BRC-207 module,
+ *     a `p color plan` transfer: every `amm-swap` token row of the token and every sats row as
+ *     explicit inputs (their source transactions in `inputBEEF`), one output — the whole amount to
+ *     a NEW module receiving key of the user's own, the plan's owned output 0. The page unlocks its
+ *     inputs at signAction; the wallet funds the fee and takes the sats into its change. With no
+ *     token row and sats rows staged: one plain createAction, the sats rows as explicit inputs and
+ *     no outputs (`moveBackSats`).
  */
 import { Beef, Transaction, type WalletInterface } from "@bsv/sdk";
 import { type Steak } from "../lp/close.js";
@@ -51,83 +30,76 @@ import { type Spends } from "../wallet/action.js";
 import { type SatsInput, type TokenInput } from "./swapAction.js";
 /** The keyID prefix of an `amm-swap` key (`SWAP_PROTOCOL`, counterparty self). */
 export declare const SWAP_KEY_PREFIX = "amm-swap-";
-/**
- * The keyID of a staged `amm-swap` output (0.29.2, David Case 2026-11-02: derived, not random):
- * `amm-swap-<txid>.<vout>` for a leg's token row and `amm-swap-<txid>.<vout>:sats` for its sats
- * row, `<txid>.<vout>` the leg's pool outpoint as quoted (`leg.outpoint`, `_` written `.`).
- * Protocol `[2, "amm swap"]`, counterparty self, as before. A leg refused and retried against the
- * same pool outpoint stages to the same key again, which is fine.
- */
-export declare function swapKeyID(poolOutpoint: string, kind: "token" | "sats"): string;
+/** The label of a staging action that carries tokens (0.40.0): the staged token output's key id is in its output description. */
+export declare const SWAP_STAGE_LABEL = "amm-swap-stage";
+/** The marker a staged token output's description ends with (` · amm-swap <hex>`, 0.40.0): it names the key id. */
+export declare const SWAP_KEY_MARK = " \u00B7 amm-swap ";
+/** A staged row's keyID (0.40.0): `amm-swap-<16 random bytes, hex>`. */
+export declare function newSwapKeyID(): string;
+/** A staged token output's description: the readable text (at most 50 characters), then `SWAP_KEY_MARK` and the keyID's hex. */
+export declare function swapKeyDescription(readable: string, keyID: string): string;
+/** The keyID a staged token output's description names (`swapKeyDescription`), or null. */
+export declare function swapKeyIdOfDescription(description: string | undefined): string | null;
 /** The `amm-swap` outputs of `tokenId` the legs can spend. */
 export declare function swapHoldings(wallet: WalletInterface, tokenId: string): Promise<TokenInput[]>;
 /** The `amm-swap` sats outputs the legs can spend (0.29.0). */
 export declare function swapSatsHoldings(wallet: WalletInterface): Promise<SatsInput[]>;
-/**
- * What `amm-swap` holds, per token id: the token amount and the number of token outputs, and
- * (0.29.6) the sats staged for the token's legs (the sats rows whose customInstructions name its
- * `assetId`). A token with only sats staged has amount 0n and outputs 0.
- */
+/** What `amm-swap` holds, per token id: the token amount and the number of token outputs (0.40.0: the sats rows are no token's, `swapSatsTotal`). */
 export declare function swapTotals(wallet: WalletInterface): Promise<Map<string, {
     amount: bigint;
     outputs: number;
-    sats: number;
 }>>;
+/** The sats `amm-swap` holds (0.40.0: shown once, not per token). */
+export declare function swapSatsTotal(wallet: WalletInterface): Promise<number>;
 /** The source transactions of `amm-swap`'s outputs (a leg's BEEF), with `extra` merged in. */
 export declare function swapHoldingBeef(wallet: WalletInterface, extra?: number[]): Promise<Beef>;
-export interface SentToSwapBasket {
+/** What a staging action made (0.40.0): the sats row and, with tokens, the token row. */
+export interface Staged {
     txid: string;
-    /** The send as the wallet's AtomicBEEF. */
+    /** The action as the wallet's AtomicBEEF. */
     tx: number[];
-    /** The new `amm-swap` token outputs, in the order of `stage.tokens`. */
-    holdings: TokenInput[];
-    /** The new `amm-swap` sats outputs, in the order of `stage.sats` (0.29.0). */
-    sats: SatsInput[];
+    /** The sats row (absent: tokens staged with no sats lacking). */
+    sats?: SatsInput;
+    tokens?: TokenInput;
+    /** The token row filed in `amm-swap` (with tokens). */
     filed: boolean;
     submitted: string;
     errors: string[];
 }
-/** A staged sats output: the leg's exact sats, keyed by the leg's pool outpoint (`swapKeyID`). */
-export interface StagedSats {
-    satoshis: number;
-    /** The leg's pool outpoint, `<txid>_<vout>` or `<txid>.<vout>`. */
-    pool: string;
-}
-/** What one send stages: a token output per leg (its amount in), then a sats output per leg. */
-export interface SwapStage {
-    tokens: {
+/** What one staging action puts into `amm-swap` (0.40.0): sats, and (a sell the basket does not cover) tokens of one token. */
+export interface StageRequest {
+    sats: number;
+    tokens?: {
+        tokenId: string;
         amount: bigint;
-        pool: string;
-    }[];
-    sats: StagedSats[];
+    };
 }
 /**
- * "In" (see the module comment): one module send of `stage.tokens` (each one
- * output) to `amm-swap` keys derived from each leg's pool (`swapKeyID`), filed in `amm-swap`, and of `stage.sats`
- * (each one output) after them. Throws when the wallet refuses or fails the
- * send; filing and the page's own submit are reported in `errors`.
+ * Staging (see the module comment): ONE wallet action. Throws when the wallet refuses or fails it;
+ * the token row's filing and the page's own submit are reported in `errors`.
  */
-export declare function sendToSwapBasket(wallet: WalletInterface, base: string, tokenId: string, stage: SwapStage, meta?: {
+export declare function stage(wallet: WalletInterface, req: StageRequest, o?: {
     sym?: string;
-}, submit?: (topic: string, beef: number[]) => Promise<{
-    steak?: Steak;
-}>): Promise<SentToSwapBasket>;
-export interface SentSats {
+    submit?: (topic: string, beef: number[]) => Promise<{
+        steak?: Steak;
+    }>;
+}): Promise<Staged>;
+/** A staged token output the basket lacks (0.40.0): its outpoint, token, amount and the key its description names. */
+export interface UnfiledStaged {
     txid: string;
-    /** The send as the wallet's AtomicBEEF. */
-    tx: number[];
-    /** The new `amm-swap` sats outputs, in the order of `sats`. */
-    sats: SatsInput[];
-    errors: string[];
+    vout: number;
+    tokenId: string;
+    amount: bigint;
+    keyID: string;
 }
 /**
- * The sats-only send (0.29.0): one plain createAction (no `p color` labels: the module is not in
- * the path) with one P2PKH output per amount to the leg's "amm swap" `:sats` key (`swapKeyID`), filed in `amm-swap`; the
- * wallet funds it, adds change and broadcasts. Throws when the wallet refuses or fails it.
+ * The labelled staging actions' token outputs not in `amm-swap` (0.40.0): every output of an action
+ * labelled `SWAP_STAGE_LABEL` whose description names a staged key and whose script is a 1Color
+ * value output, its basket not `amm-swap`. A wallet that refuses the read: none.
  */
-export declare function sendSatsToSwapBasket(wallet: WalletInterface, tokenId: string, sats: StagedSats[], meta?: {
-    sym?: string;
-}): Promise<SentSats>;
+export declare function unfiledStagedTokens(wallet: WalletInterface): Promise<UnfiledStaged[]>;
+/** One unfiled staged token output filed in `amm-swap` from its transaction's BEEF (basket insertion, as `stage` files it). */
+export declare function fileStagedToken(wallet: WalletInterface, u: UnfiledStaged, beef: number[]): Promise<boolean>;
 export interface MovedBack {
     txid: string;
     amount: bigint;
@@ -156,3 +128,12 @@ export declare function moveBack(i: {
         steak?: Steak;
     }>;
 }): Promise<MovedBack>;
+/**
+ * Move back with only sats in the swap basket (0.29.6, David Case 2026-11-03; 0.40.0: every sats
+ * row, `satsRows` default the basket's): ONE plain wallet createAction (no `p color` labels, the module
+ * is not in the path) with the token's `amm-swap` sats rows as explicit inputs (their sources in
+ * `inputBEEF`) and NO outputs: the wallet keeps everything as its change and pays the fee from it.
+ * The page unlocks the rows at signAction; the wallet broadcasts and marks the rows spent itself
+ * (no relinquish, no take-in, nothing kept). Nothing is submitted to an overlay (no token moves).
+ */
+export declare function moveBackSats(wallet: WalletInterface, sym?: string, satsRows?: SatsInput[]): Promise<MovedBack>;