@dcasegr/amm-client 0.39.0 → 0.41.1

package/README.md

@@ -40,28 +40,41 @@ exchange with another wallet, keeping what was read and quoted.
 The client (each an async function unless noted):
 
 - the exchange: `enabledList`, `registeredTokens`, `tokenBaseOf`, `hostedTokens` (the token list
-  and ONE `GET /amm/stats`), `watchTokenPools` (the token's pools route as an event stream: the
-  whole answer, then each `change` — `swap`, `deploy`, `close`, `rescind` — applied to it, one it
-  cannot apply read again once; sync, returns the unsubscribe; 0.39.0: no host-wide stream),
+  and ONE `GET /amm/stats`), `tokenPools(tokenId)` (0.41.0: the token's pools route, a plain
+  read past the browser's cache), `watchPoolEvents(tokenId | "all", onEvent)` (0.41.0: the host's
+  pool event feed, `/@<token>/amm/events` or `<origin>/amm/events`; each message `{tokenId, …row}`,
+  a `/pools/history` row or a `revert`; signals for display, the pools route the truth; sync,
+  returns the unsubscribe; reconnect is the browser EventSource's),
   `claimStatus`, `isRoot`, `claimExchange`, `discoveryBase` (sync), `onDataChange` (sync);
-- history (0.39.0, plain GETs): `trades(tokenId, {from?, to?, limit?, before?, lp?})` →
-  `{trades, next}`, `trade(tokenId, txid)` → a `Trade` or null, `candles(tokenId, {tf, from, to})`,
-  `stats(tokenId)`, `statsAll({ids?})`, `holders(tokenId, {limit?, skip?})` → `{count, rows}`,
-  `positionsAll(lpKeys)` (every enabled token's positions); amounts bigints, prices `{sats,
-  tokens}` pairs of bigints (base units both);
+- history (plain GETs; 0.40.0: by pool id, `poolId` = the pool's deploy outpoint `<txid>_<vout>`):
+  `trades(tokenId, {from?, to?, limit?, before?, pool?})` → `{trades, next}` (each row its
+  `poolId` and `payoutPkh`), `trade(tokenId, txid)` → a `Trade` or null, `candles(tokenId, {tf,
+  from, to, series?})` (`series` `fill`, the default, or `market`), `stats(tokenId)` /
+  `statsAll({ids?, fresh?})` (`price` = the midpoint of what a buy and a sell of 1% of the pooled sats
+  would pay now, `buyPrice`, `sellPrice`, `lastTradePrice`), `holders(tokenId, {limit?, skip?})` →
+  `{count, rows}`, `positionsAll(poolIds)`, `poolsAt(tokenId, t)` (every pool listed at `t`),
+  `poolHistory(tokenId, {from?, to?, pool?, limit?, after?})` → `{events, next}` (oldest first;
+  forward paging: `next` as `after`), `spendsAll(outpoints)` (the host's `/amm/spends`); amounts
+  bigints, prices `{sats, tokens}` pairs of bigints (base units both);
 - swap: `quoteSwap(request, poolsAnswer, {sym, dec})` (sync: the engine's plan over the pools the
-  token's pools stream gave), `executeSwap(quote, {onProgress})`, `checkSwapAgain(leg)`,
-  `walletSats`;
+  token's pools route gave, each pool with its validator's `minLegSats`; the quote's price and
+  impact from the engine's `priceOf`, each leg's own `fees`, `stage` = what Swap sets aside
+  (`amount`, `feeSats`: 0.40.2, exactly `maxSources` legs), `legMinerFeeSats`); the request's
+  `maxSources` (required, 0.40.2; replaces `allowPartial`) is the most pools the swap may draw on —
+  1 is exactly one leg; the Open Exchange pages send 1 or 5,
+  `executeSwap(quote, {onProgress, signal})` (below), `walletSats`;
 - liquidity: `myPositions`, `validatorTerms`, `deployPosition({tokenId, tokens, sats})`,
   `closePosition({outpoint})`, `rebalancePosition({outpoint, tokens, sats})` (the old pool closed
   and a new one deployed in ONE wallet createAction);
-- your tokens: `myTokens`, `settleSwaps` (the silent pass over staged swap legs: the txids taken
-  in), `moveBackTokens(tokenId)` (what it did: txid, amount, BEEF, submit), `sendTokens`;
+- your tokens: `myTokens`, `settleSwaps` (the pass over the swap basket: a staged token output the
+  basket lacks filed from its action's description; then every row's spender, this wallet's legs
+  taken in: the txids), `swapBasketSats`, `moveBackTokens(tokenId)` (every row of the token and
+  every sats row: txid, amount, BEEF, submit), `moveBackStagedSats` (the sats alone), `sendTokens`;
 - settings (root): `deployBeef`, `enableToken`, `tokensToEnable`, `disableToken`, `defaults`,
   `setDefaultTerms`, `clearDefaultTerms`, `setDefaultMarket`, `clearDefaultMarket`, `tokenTerms`,
-  `setTokenTerms`, `discoveryState`, `setDiscovery`.
+  `setTokenTerms` (0.40.0: the terms `{lpBps, validatorBps, commissionBps, minLegSats?}`), `discoveryState`, `setDiscovery`.
 
-Pure helpers beside it: `hostedFrom`, `applyPoolChange`, `parseChange`, `poolViews`, `poolFees`, `withLeg`, `hasTerms`,
+Pure helpers beside it: `hostedFrom`, `parsePoolEventMessage`, `poolViews`, `poolFees`, `poolsWithMinimums`, `pairPrice`, `legCarrySats`, `hasTerms`,
 `enableCandidates`, `topicOf`, `lookupOf`, `ammLookupOf`, `walletDeployBeef`, `exchangeBase`,
 `tokenBase`; the types (`Quote`, `SwapResult`, `LegResult`, `Position`, `WalletToken`, …).
 
@@ -69,15 +82,19 @@ Pure helpers beside it: `hostedFrom`, `applyPoolChange`, `parseChange`, `poolVie
 
 An error of one of `CLIENT_ERROR_KINDS` is a `ClientError` with `kind` and the message the pages
 show: `stale_pool`, `fee_mismatch`, `quote_mismatch`, `slippage`, `pool_spent`, `user_rejected`,
-`no_answer`, `refused`, `network`. A swap leg that did not fill carries its `kind` beside its
-`error` text. `errorKind(e)` classifies any error; other errors stay plain `Error`s.
+`no_answer`, `below_minimum` (0.40.0: under a validator's minimum leg; a quote no pool takes),
+`refused`, `network`. `errorKind(e)` classifies any error; other errors stay plain `Error`s.
 
 ## The shared names
 
 What two sites must use to file identical wallet rows: `POOLS_BASKET` (`amm-pools`, the LP's
 position rows), `SWAP_BASKET` (`amm-swap`, what swap legs spend), `SWAP_PROTOCOL` (`[2, "amm
-swap"]`), `SWAP_KEY_PREFIX` + `swapKeyID` (the staged rows' keyIDs), `swapInstructions` /
-`swapSatsInstructions` (their customInstructions), `LP_KEY_PROTOCOL` (BRC-29) + `LP_KEY_MARK` +
+swap"]`), `SWAP_KEY_PREFIX` + `newSwapKeyID` (a staged row's random keyID), `changeKeyID` (a leg's
+change row: `amm-swap-<txid>.<vout>:change` of its first input of that kind), `SWAP_STAGE_LABEL`
+(`amm-swap-stage`) + `SWAP_KEY_MARK` + `swapKeyDescription` / `swapKeyIdOfDescription` (a staged
+token output's description naming its key), `legDerivation` (an order's payout, own commission and
+last-leg change keys), `swapInstructions` / `swapSatsInstructions` (their customInstructions, a
+change row's with `order`), `LP_KEY_PROTOCOL` (BRC-29) + `LP_KEY_MARK` +
 `lpKeyDescription` / `lpKeyIdOfDescription` (the deploy's pool output description naming the LP
 keyID), `POOL_TAG` / `POOL_OP` / `isPoolRow` / `poolCustomInstructions` (an `amm-pools` row),
 `POOL_DEPLOY_LABEL` (`amm-pool-deploy`), `SWAP_TTL_MS` (15 s), `transferPlanLabels` (the `p color
@@ -92,20 +109,36 @@ import { createClient, ClientError } from "@dcasegr/amm-client";
 const client = createClient({ origin: "https://swap.skein.nexus", wallet });
 const tokenId = "<txid>_0";
 
-// The token's pools route as an event stream: the pools a swap may use, the market.
-const stop = client.watchTokenPools(tokenId, async (pools) => {
-  stop();
-  const quote = client.quoteSwap({ tokenId, side: "buy", amountIn: 50_000n, maxSlippageBps: 50, allowPartial: false }, pools, { sym: "TOK", dec: 0 });
-  try {
-    const result = await client.executeSwap(quote, { onProgress: (p) => console.log(p.phase) });
-    console.log(result.status, result.legs);
-  } catch (e) {
-    if (e instanceof ClientError && e.kind === "pool_spent") console.log("quote again");
-    else throw e;
-  }
-});
+// The token's pools route: the pools a swap may use, the market (read again on a pool event).
+const pools = await client.tokenPools(tokenId);
+const quote = client.quoteSwap({ tokenId, side: "buy", amountIn: 50_000n, maxSlippageBps: 50, maxSources: 1 }, pools, { sym: "TOK", dec: 0 });
+try {
+  const cancel = new AbortController();
+  const result = await client.executeSwap(quote, { signal: cancel.signal, onProgress: (p) => console.log(p.phase) });
+  console.log(result.status, result.stop, result.legs, result.returned);
+} catch (e) {
+  if (e instanceof ClientError) console.log(e.kind, e.message);
+  else throw e;
+}
 ```
 
+`executeSwap` (0.40.0; 0.40.2: at most `maxSources` legs, the budget down by one per FILLED leg —
+a refused or unanswered leg does not count, the last leg takes all that remains): ONE swap at a time. First the pass over the swap basket, then ONE wallet
+action stages what `amm-swap` lacks of `quote.stage` (sats only: a plain createAction; a sell's
+tokens: the module transfer). Then legs one at a time: the SERVER's pool list read fresh (0.41.0:
+`GET /@<token>/amm/pools` before EACH leg; the client keeps no list of its own), the engine's
+`nextLeg` over it (`minOut` = the quote's floor less what has filled), the pool's current output by
+its id (`/pools/beef?pool=`), the staged rows that cover the leg (largest first), built, signed,
+relayed; accepted → taken in (payout, own commission, change) before the next leg; refused
+`pool_spent` → the list read again (the relaying host took the validator's state in before it
+answered, 0.41.0); refused otherwise → that pool output excluded; no answer → the overlay
+(a staged input spent: the leg landed), else sent once more, else raced on another pool. It stops
+`filled | cancelled | floor | min | no_pool | fees`. Filled: the last leg's change went to the
+wallet. Stopped early with rows left: `moveBack` runs itself (`result.returned`). Progress phases:
+`staging`, `relaying` / `repricing` (the leg's pool, amounts and the legs filled so far),
+`returning`, `done` / `failed`. The result: `{status, stop, legs: [{poolOutpoint, poolId,
+amountIn, amountOut, txid}], totalIn, totalOut, unfilled, returned?}`.
+
 ## Build
 
 From skein-amm's `web/`: `npm ci` in `ui` and in `engine`, then `npm pack` here (the build

package/dist/client.d.ts

@@ -15,22 +15,23 @@
  *   (`hostedTokens`): each token's price, liquidity (TVL) and pool count; no host-wide stream.
  * - **History** (0.39.0, D1–D6): `trades`, `trade`, `candles`, `stats`, `statsAll`, `holders`,
  *   `positionsAll` — plain GETs of the history routes (H1–H6, src/lib/overlay.ts).
- * - **Swap** (D11–D16): the token's pools route `GET /@<token>/amm/pools` held as an event stream
- *   (`watchTokenPools`; 0.39.0, D7: the whole answer once, then one `change` per pool change,
- *   applied to the held answer): the pools whose validator is beating and whose commission meets the
- *   market's minimum (the host's filter), the market's commission key hash; a quote is the
- *   matching engine's plan over that list (no request); a swap reads ONE `GET
- *   /@<token>/amm/pools/beef?lp=` for its legs (freshness, the pools' BEEF), then each leg's relay
- *   request (`amm.swap.submit`, held by the host until the relay rests; 15 s expiry); a lost answer
- *   is "no answer yet" with "Check again" (`GET /@<token>/amm/swaps?id=`, once).
- * - **Liquidity** (D9, D23): the wallet's pool rows and deploy history, then ONE `GET
- *   /@<token>/amm/positions?lp=` per token; a deploy the history has but the basket lacks is
- *   filed then; Close and Rebalance read their pool's BEEF by LP key (`/pools/beef?lp=`); the
- *   deploy's terms `GET /@<token>/amm/terms`.
+ * - **Swap** (D11–D16; 0.40.0; 0.41.0): the token's pools route `GET /@<token>/amm/pools`, a plain
+ *   read (`tokenPools`): the pools whose validator is beating and whose commission meets the
+ *   market's minimum (the host's filter), each validator's minimum leg, the market's commission key
+ *   hash; a quote is the matching engine's plan over that list (no request); a swap (`executeSwap`)
+ *   stages what the swap basket lacks by ONE wallet action, then per leg the pools route read fresh,
+ *   ONE `GET /@<token>/amm/pools/beef?pool=` and the leg's relay request (`amm.swap.submit`, held by
+ *   the host until the relay rests; 15 s expiry); no answer → the host's `GET /amm/spends`, once
+ *   more, a race. The pool events (`watchPoolEvents`, 0.41.0: the host's feeds) are signals for
+ *   display: a page reads the route again on one.
+ * - **Liquidity** (D9, D23; 0.40.0: by pool id): the wallet's pool rows and deploy history, then
+ *   ONE `GET /@<token>/amm/positions?pool=` per token; a deploy the history has but the basket
+ *   lacks is filed then; Close and Rebalance read their pool's BEEF by its id (`/pools/beef?pool=`);
+ *   the deploy's terms `GET /@<token>/amm/terms`.
  * - **Your tokens** (D17, D18, D19, D24): the wallet's module and the swap basket; the token list
- *   once and ONE discovery `GET /@discovery/1color/tokens?ids=` for held tokens the list lacks; a
- *   silent pass over the swap basket's staged legs (src/wallet/swapPayouts.ts); Move back submits
- *   at the host root.
+ *   once and ONE discovery `GET /@discovery/1color/tokens?ids=` for held tokens the list lacks; the
+ *   pass over the swap basket (0.40.0: ONE `GET /amm/spends` over every row,
+ *   src/wallet/swapPayouts.ts); Move back submits at the host root.
  * - **Settings** (D20, D21): the claim card (`claimStatus`: swap's identity, the recipient of
  *   root's messages), the token list once, discovery's list and ONE `?ids=` read; Enable's deploy
  *   BEEF from the wallet's basket else `GET /@discovery/1color/<token>/deploy`.
@@ -42,14 +43,13 @@
  */
 import { type WalletInterface } from "@bsv/sdk";
 import { type Send1ColorResult } from "@1sat/actions";
-import { type PoolState, type Plan } from "@dcasegr/amm-engine";
-import { type Candle, type CandleTf, type Holders, type TokenPosition, type TokenStats, type Trade, type TradesPage, type LiveAnswer, type PoolRow, type PoolsAnswer, type SignedFetch } from "./lib/overlay.js";
+import { type Leg, type PoolState, type Plan, type PricePair } from "@dcasegr/amm-engine";
+import { type Candle, type CandleSeries, type CandleTf, type PoolAt, type PoolHistoryPage, type SpendAll, type Holders, type TokenPosition, type TokenStats, type Trade, type TradesPage, type PoolRow, type PoolsAnswer, type PoolEventMessage, type SignedFetch } from "./lib/overlay.js";
 import { type Defaults, type Discovery, type EnabledToken, type ListedToken } from "./lib/skein.js";
 import type { AuthFetchLike } from "./market/relay.js";
-import { type PreparedSwap } from "./market/swapAction.js";
 import { type MovedBack } from "./market/activeSwap.js";
 import { type PositionRow } from "./lp/positions.js";
-import { ClientError, type ClientErrorKind } from "./errors.js";
+import { ClientError } from "./errors.js";
 /** A token id: the BRC-207 assetId `<txid>_<vout>`, `_0` included (src/lib/tokenId.ts). */
 export type TokenId = string;
 /** What a swap of 2% of the price costs: the sats a buy needs to move the marginal price up by `bps`. */
@@ -64,7 +64,10 @@ export interface HostedToken {
     dec: number;
     /** An image URL (a data: URL of the deploy's embedded icon, or an ORDFS URL). */
     icon?: string;
-    /** Sats per whole token across the token's pools: what the next small swap pays. Null with no open pool. */
+    /**
+     * Sats per whole token (0.40.0: the stats' `price`, the midpoint of what a buy and a sell of 1% of
+     * the pooled sats would pay now). Null with no open pool.
+     */
     marginalPrice: number | null;
     depth: Depth | null;
     /** Number of open pools. */
@@ -81,6 +84,8 @@ export interface HostedToken {
 export interface PoolView {
     /** `<txid>.<vout>` */
     outpoint: string;
+    /** The pool's id (0.40.0): its deploy outpoint, `<txid>_<vout>`. */
+    poolId: string;
     tokenId: TokenId;
     sats: bigint;
     tokens: bigint;
@@ -99,11 +104,18 @@ export interface QuoteRequest {
     amountIn: bigint;
     /** Max slippage against the quoted amount out, basis points. */
     maxSlippageBps: number;
-    allowPartial: boolean;
+    /**
+     * 0.40.2: the most pools the order may draw on, filled legs counted — a positive integer the
+     * caller always gives; the fee sats staged are for exactly that many legs. 1: exactly one leg
+     * for the whole amount. Replaces `allowPartial` (`false` was 1).
+     */
+    maxSources: number;
 }
 export interface QuoteLeg {
     /** The pool, `<txid>.<vout>`. */
     poolOutpoint: string;
+    /** The pool's id (0.40.0). */
+    poolId: string;
     amountIn: bigint;
     amountOut: bigint;
     /** Share of the amount in, basis points (the legs sum to 10000). */
@@ -114,37 +126,64 @@ export interface QuoteLeg {
         tokens: bigint;
     };
     validator: ValidatorRef;
+    /** The leg's own pool's fees (0.40.0: the fee line per leg). */
+    fees: Fees;
+}
+/** What Swap stages into the swap basket before its first leg (0.40.0): the swap amount exact, and the fee sats. */
+export interface QuoteStage {
+    /** The swap amount: sats on a buy, token base units on a sell. */
+    amount: bigint;
+    /** The sats for the carriers and miner fees of `maxSources` legs (0.40.2). */
+    feeSats: bigint;
 }
 export interface Quote {
     request: QuoteRequest;
     legs: QuoteLeg[];
     amountOut: bigint;
-    /** The least amount out the swap accepts: amountOut less max slippage. */
+    /** The least amount out the swap accepts (the floor): the route's amount out less max slippage. */
     minAmountOut: bigint;
     /** Sats per whole token this swap pays (fees included). */
     effectivePrice: number;
-    /** Sats per whole token before the swap. */
+    /**
+     * Sats per whole token now (0.40.0: the engine's `priceOf` over the pools the page holds — what a
+     * buy of 1% of the pooled sats would pay on a buy, a sell of 1% of the pooled tokens on a sell).
+     */
     marginalPrice: number;
     /** |effective − marginal| / marginal, basis points. */
     impactBps: number;
-    /** The validator's fees applied to every leg. */
-    fees: Fees;
+    /** What Swap stages (0.40.0). */
+    stage: QuoteStage;
+    /** The miner fee estimate of one leg, sats. */
+    legMinerFeeSats: bigint;
 }
+/** One leg of a swap that filled (0.40.0). */
 export interface LegResult {
+    /** The pool output it spent, `<txid>.<vout>`. */
     poolOutpoint: string;
-    status: "filled" | "failed";
-    txid?: string;
-    error?: string;
-    /** 0.31.1: the leg was refused `pool_spent`, repriced against the pool's newest state and sent again. */
-    repriced?: true;
-    /** 0.34.0 (D15): no answer yet — the swap's id, for "Check again" (`checkSwapAgain`). */
-    checkId?: string;
-    /** 0.38.0 (D13): the failure's kind, when it has one (`error` stays the text). */
-    kind?: ClientErrorKind;
+    poolId: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    txid: string;
 }
+/** Why a swap stopped (0.40.0). */
+export type SwapStop = "filled" | "cancelled" | "floor" | "min" | "no_pool" | "fees";
 export interface SwapResult {
+    /** "filled": every unit filled; "partial": some; "failed": none. */
     status: "filled" | "partial" | "failed";
+    stop: SwapStop;
+    /** The legs that filled, in order. */
     legs: LegResult[];
+    totalIn: bigint;
+    totalOut: bigint;
+    /** The swap amount not filled. */
+    unfilled: bigint;
+    /** What went back to the wallet when the swap stopped early (the Move back's), or why it did not. */
+    returned?: {
+        txid: string;
+        tokens: bigint;
+    } | {
+        error: string;
+    };
 }
 /** The validator's fees, basis points of the amount in. The LP accepts them; there is no fee input. */
 export interface Fees {
@@ -172,11 +211,17 @@ export interface ValidatorTerms {
     /** "this exchange's" when the validator is this skein. */
     isThisExchange: boolean;
     fees: Fees;
+    /** The validator's minimum leg, sats on the leg's sats side (0.40.0; 0: none). */
+    minLegSats: number;
 }
 /** One of the user's pools. A position is only deployed or closed (no add, no partial remove). */
 export interface Position {
     /** The pool, `<txid>.<vout>`. */
     outpoint: string;
+    /** The pool's id (0.40.0): its deploy outpoint, `<txid>_<vout>`. */
+    poolId: string;
+    /** The pool's swaps so far. */
+    swaps: number;
     tokenId: TokenId;
     sym: string;
     dec: number;
@@ -244,8 +289,6 @@ export interface WalletToken {
     outputs: number;
     /** Held in the exchange's active swap basket (`amm-swap`): spent by swap legs, or moved back. */
     inSwaps: bigint;
-    /** Sats staged in `amm-swap` for the token's swap legs (0.29.6): spent by swap legs, or moved back. */
-    swapSats: number;
     /** Registered on this exchange. */
     onExchange: boolean;
 }
@@ -265,9 +308,10 @@ export interface RegisteredToken {
     icon?: string;
     status: EnabledToken["status"];
 }
-export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer, Candle, CandleTf, Holders, TokenPosition, TokenStats, Trade, TradesPage };
-export type { PoolChange, Price } from "./lib/overlay.js";
-export { applyPoolChange, parseChange } from "./lib/overlay.js";
+export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer, Candle, CandleSeries, CandleTf, Holders, PoolAt, PoolHistoryPage, SpendAll, TokenPosition, TokenStats, Trade, TradesPage };
+export type { PoolEvent, PoolEventMessage, PoolRevert } from "./lib/overlay.js";
+export type { Price } from "./lib/overlay.js";
+export { parsePoolEventMessage } from "./lib/overlay.js";
 /** A token's symbol, decimals and icon, read off its deploy output. */
 export interface DeployMeta {
     sym?: string;
@@ -302,8 +346,19 @@ export declare function hostedFrom(list: EnabledToken[], stats: TokenStats[] | n
 export declare function poolViews(answer: PoolsAnswer | null, tokenId: TokenId): PoolView[];
 /** The fees a pool's own record names (D13: the Swap page's fee line), basis points. */
 export declare function poolFees(p: Pick<PoolState, "liquidityFeeBps" | "validationFeeBps" | "commissionBps">): Fees;
-/** A swap's result with one leg replaced (after "Check again"). */
-export declare function withLeg(r: SwapResult, leg: LegResult): SwapResult;
+/**
+ * A pools answer's rows as the planner takes them (0.40.0): each pool with its validator's
+ * minimum leg (`validators[].minLegSats`, the validator's announced terms).
+ */
+export declare function poolsWithMinimums(answer: PoolsAnswer): PoolRow[];
+/** Sats per whole token of an exact pair (`sats` per `tokens` base units), 0 when `tokens` is 0. */
+export declare function pairPrice(p: PricePair, dec: number): number;
+/**
+ * A leg's sats beyond its amount in (0.40.0, the stage's fee sats): the miner fee estimate plus its
+ * 1-sat carriers — on a buy the token payout; on a sell the token fee and commission outputs that
+ * are not zero, and the token change.
+ */
+export declare function legCarrySats(leg: Pick<Leg, "liquidityFee" | "validationFee" | "commission">, buy: boolean, minerFeeSats: bigint): bigint;
 /**
  * wallet-toolbox's `specOpWalletBalance` (`sdk.specOpWalletBalance`, @bsv/wallet-toolbox-client): the listOutputs "basket" of its
  * balance special operation. Written out, not imported: the client package exports it only inside its `sdk` namespace, which
@@ -342,18 +397,17 @@ export interface EnableCandidate {
  * instance's list (enabled or disabled) left out. Pure: the reads are `tokensToEnable`'s.
  */
 export declare function enableCandidates(listed: ListedToken[], walletIds: string[], onList: string[]): EnableCandidate[];
-/** The three fees root sets (basis points, integers 0 to 10 000). */
+/** The three fees root sets (basis points, integers 0 to 10 000), and (0.40.0) the minimum leg in sats (absent or 0: none). */
 export interface TermsInput {
     lpBps: number;
     validatorBps: number;
     commissionBps: number;
+    minLegSats?: number;
 }
 /** What a quote was planned from: kept for its execution. */
 interface Planned {
     plan: Plan;
-    pools: PoolRow[];
-    live: LiveAnswer;
-    market: PoolsAnswer["market"];
+    answer: PoolsAnswer;
     dec: number;
     sym: string;
 }
@@ -378,15 +432,31 @@ export interface ClientOptions {
     /** The wallet's identity key, when the caller has it (the claim's check). Default: read from the wallet when needed. */
     identityKey?: string | null;
 }
-/** Where a swap is (`executeSwap`'s `onProgress`, D12), in this order; `leg` the pool outpoint (`<txid>.<vout>`) of a leg event. */
+/**
+ * Where a swap is (`executeSwap`'s `onProgress`, D12; 0.40.0): `staging` (what the swap basket
+ * lacks is staged), `relaying` (a leg sent: its pool outpoint `<txid>.<vout>` and amounts, and the
+ * legs filled so far), `repricing` (a leg refused `pool_spent`, the pool's row replaced),
+ * `returning` (a swap that stopped early moves its rows back), then `done` or `failed`.
+ */
 export type SwapProgress = {
     phase: "staging";
+    sats: bigint;
+    tokens: bigint;
 } | {
     phase: "relaying";
     leg: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    filled: LegResult[];
 } | {
     phase: "repricing";
     leg: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    filled: LegResult[];
+} | {
+    phase: "returning";
+    filled: LegResult[];
 } | {
     phase: "done";
     result: SwapResult;
@@ -396,8 +466,10 @@ export type SwapProgress = {
     error?: ClientError | Error;
 };
 export interface SwapOptions {
-    /** Called as the swap moves (D12): `staging` (the swap basket is filled for the legs), `relaying` (per leg), `repricing` (a leg refused `pool_spent`, re-quoted), then `done` (a leg filled) or `failed` (none did, or it threw). */
+    /** Called as the swap moves (see `SwapProgress`). */
     onProgress?: (p: SwapProgress) => void;
+    /** Aborted: the swap stops before its next leg (`cancelled`). */
+    signal?: AbortSignal;
 }
 /** What a client remembers between calls; shared by `withWallet`'s clients. */
 interface Shared {
@@ -407,12 +479,8 @@ interface Shared {
     claimRead: ClaimStatus | null;
     /** What each quote was planned from: kept for its execution. */
     planned: WeakMap<Quote, Planned>;
-    /** The legs whose answer did not come: their prepared swap, for "Check again" (D15). */
-    checks: Map<string, {
-        prepared: PreparedSwap;
-        base: string;
-        af: Signed;
-    }>;
+    /** A swap is running (0.40.0: one at a time). */
+    swapping: boolean;
     /** The positions last loaded, by the output a Close acts on (`<txid>.<vout>`): the wallet's row (its LP key) and the token. */
     loaded: Map<string, PositionRow>;
     /** `onDataChange`'s listeners. */
@@ -450,36 +518,47 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
         isRoot: (identityKey: string | null) => Promise<boolean>;
         claimExchange: () => Promise<boolean>;
         hostedTokens: () => Promise<HostedToken[]>;
-        watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+        tokenPools: (tokenId: string) => Promise<PoolsAnswer>;
+        watchPoolEvents: (tokenId: TokenId | "all", onEvent: (e: PoolEventMessage) => void, onError?: (e: unknown) => void) => () => void;
         trades: (tokenId: string, o?: {
             from?: number;
             to?: number;
             limit?: number;
             before?: string;
-            lp?: string;
+            pool?: string;
         } | undefined) => Promise<TradesPage>;
         trade: (tokenId: string, txid: string) => Promise<Trade | null>;
         candles: (tokenId: string, o: {
             tf: CandleTf;
             from: number;
             to: number;
+            series?: CandleSeries;
         }) => Promise<Candle[]>;
+        poolsAt: (tokenId: string, t: number) => Promise<PoolAt[]>;
+        poolHistory: (tokenId: string, o?: {
+            from?: number;
+            to?: number;
+            pool?: string;
+            limit?: number;
+            after?: string;
+        } | undefined) => Promise<PoolHistoryPage>;
+        spendsAll: (outpoints: string[]) => Promise<SpendAll[]>;
         stats: (tokenId: string) => Promise<TokenStats>;
         statsAll: (o?: {
             ids?: TokenId[];
+            fresh?: boolean;
         } | undefined) => Promise<TokenStats[]>;
         holders: (tokenId: string, o?: {
             limit?: number;
             skip?: number;
         } | undefined) => Promise<Holders>;
-        positionsAll: (lpKeys: string[]) => Promise<TokenPosition[]>;
+        positionsAll: (poolIds: string[]) => Promise<TokenPosition[]>;
         registeredTokens: () => Promise<RegisteredToken[]>;
         quoteSwap: (req: QuoteRequest, held: PoolsAnswer | null, meta: {
             sym: string;
             dec: number;
         }) => Quote;
         executeSwap: (quote: Quote, o?: SwapOptions) => Promise<SwapResult>;
-        checkSwapAgain: (leg: LegResult) => Promise<LegResult>;
         walletSats: () => Promise<bigint>;
         myPositions: () => Promise<Position[]>;
         validatorTerms: (tokenId: string) => Promise<NoTerms | ValidatorTerms>;
@@ -488,6 +567,8 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
         rebalancePosition: (req: RebalanceRequest) => Promise<RebalanceResult>;
         myTokens: () => Promise<WalletToken[]>;
         settleSwaps: () => Promise<string[]>;
+        swapBasketSats: () => Promise<number>;
+        moveBackStagedSats: () => Promise<MovedBack>;
         moveBackTokens: (tokenId: string) => Promise<MovedBack>;
         sendTokens: (tokenId: string, handle: string, amount: bigint, memo?: string | undefined) => Promise<Send1ColorResult>;
         deployBeef: (tokenId: string, wallet?: WalletInterface | null | undefined) => Promise<DeployFound>;
@@ -502,6 +583,7 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
             lpFeeBps: number;
             validatorFeeBps: number;
             commissionBps: number;
+            minLegSats: number;
         } | null>;
         setTokenTerms: (tokenId: string, t: TermsInput | null) => Promise<void>;
         clearDefaultTerms: () => Promise<void>;
@@ -520,36 +602,47 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
     isRoot: (identityKey: string | null) => Promise<boolean>;
     claimExchange: () => Promise<boolean>;
     hostedTokens: () => Promise<HostedToken[]>;
-    watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+    tokenPools: (tokenId: string) => Promise<PoolsAnswer>;
+    watchPoolEvents: (tokenId: TokenId | "all", onEvent: (e: PoolEventMessage) => void, onError?: (e: unknown) => void) => () => void;
     trades: (tokenId: string, o?: {
         from?: number;
         to?: number;
         limit?: number;
         before?: string;
-        lp?: string;
+        pool?: string;
     } | undefined) => Promise<TradesPage>;
     trade: (tokenId: string, txid: string) => Promise<Trade | null>;
     candles: (tokenId: string, o: {
         tf: CandleTf;
         from: number;
         to: number;
+        series?: CandleSeries;
     }) => Promise<Candle[]>;
+    poolsAt: (tokenId: string, t: number) => Promise<PoolAt[]>;
+    poolHistory: (tokenId: string, o?: {
+        from?: number;
+        to?: number;
+        pool?: string;
+        limit?: number;
+        after?: string;
+    } | undefined) => Promise<PoolHistoryPage>;
+    spendsAll: (outpoints: string[]) => Promise<SpendAll[]>;
     stats: (tokenId: string) => Promise<TokenStats>;
     statsAll: (o?: {
         ids?: TokenId[];
+        fresh?: boolean;
     } | undefined) => Promise<TokenStats[]>;
     holders: (tokenId: string, o?: {
         limit?: number;
         skip?: number;
     } | undefined) => Promise<Holders>;
-    positionsAll: (lpKeys: string[]) => Promise<TokenPosition[]>;
+    positionsAll: (poolIds: string[]) => Promise<TokenPosition[]>;
     registeredTokens: () => Promise<RegisteredToken[]>;
     quoteSwap: (req: QuoteRequest, held: PoolsAnswer | null, meta: {
         sym: string;
         dec: number;
     }) => Quote;
     executeSwap: (quote: Quote, o?: SwapOptions) => Promise<SwapResult>;
-    checkSwapAgain: (leg: LegResult) => Promise<LegResult>;
     walletSats: () => Promise<bigint>;
     myPositions: () => Promise<Position[]>;
     validatorTerms: (tokenId: string) => Promise<NoTerms | ValidatorTerms>;
@@ -558,6 +651,8 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
     rebalancePosition: (req: RebalanceRequest) => Promise<RebalanceResult>;
     myTokens: () => Promise<WalletToken[]>;
     settleSwaps: () => Promise<string[]>;
+    swapBasketSats: () => Promise<number>;
+    moveBackStagedSats: () => Promise<MovedBack>;
     moveBackTokens: (tokenId: string) => Promise<MovedBack>;
     sendTokens: (tokenId: string, handle: string, amount: bigint, memo?: string | undefined) => Promise<Send1ColorResult>;
     deployBeef: (tokenId: string, wallet?: WalletInterface | null | undefined) => Promise<DeployFound>;
@@ -572,6 +667,7 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
         lpFeeBps: number;
         validatorFeeBps: number;
         commissionBps: number;
+        minLegSats: number;
     } | null>;
     setTokenTerms: (tokenId: string, t: TermsInput | null) => Promise<void>;
     clearDefaultTerms: () => Promise<void>;