@dcasegr/amm-client 0.0.0-stage → 0.38.1

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @dcasegr/amm-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Open Exchange client (skein-amm): every read and every action the Open Exchange pages make —
+the token list, prices, quotes and swaps, pool deploy / close / rebalance, Move back, positions,
+the root's settings — over a BRC-100 wallet, bound by `createClient` to one exchange. ESM with
+type declarations; no React, no styles, no wallet provider (connect the wallet yourself and pass
+it in). The source is skein-amm's `web/ui/src` (the pages' own); the matching engine is
+[`@dcasegr/amm-engine`](../engine). Versions follow the skein-amm release.
+
+## Install
+
+```
+npm install @dcasegr/amm-client @bsv/sdk @1sat/templates @bsv/color-permission-module
+```
+
+`@bsv/sdk` (4), `@1sat/templates` and `@bsv/color-permission-module` are peer dependencies: one
+copy, the wallet's. The wallet must carry the BRC-207 1Color module (`@bsv/color-permission-module`)
+for the token actions.
+
+## createClient
+
+```ts
+import { createClient } from "@dcasegr/amm-client";
+
+const client = createClient({
+  origin: "https://swap.skein.nexus", // the exchange: an origin (the swap app at <origin>/amm) or the app's base URL
+  feeRateSatsPerKb: 100,              // the miner fee rate a swap leg's staged sats are sized with (default 100)
+  wallet,                             // a BRC-100 WalletInterface; null or absent: reads only
+  fetch,                              // optional: the plain fetch (default the global one)
+});
+```
+
+`createClient(opts: ClientOptions): AmmClient`, where `ClientOptions` is `{ origin: string;
+feeRateSatsPerKb?: number; wallet?: WalletInterface | null; fetch?: FetchLike; signedFor?: (base)
+=> Signed; identityKey?: string | null }` (`signedFor`: the wallet's BRC-104 client per instance,
+default one `AuthFetch` session per instance; `identityKey`: default read from the wallet when
+needed). Nothing reads `import.meta.env` or `location`. `client.withWallet(wallet)` is the same
+exchange with another wallet, keeping what was read and quoted.
+
+The client (each an async function unless noted):
+
+- the exchange: `enabledList`, `registeredTokens`, `tokenBaseOf`, `hostedTokens`,
+  `watchHostedPools` / `watchTokenPools` (event streams, sync, return the unsubscribe),
+  `claimStatus`, `isRoot`, `claimExchange`, `discoveryBase` (sync), `onDataChange` (sync);
+- 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`;
+- 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`;
+- settings (root): `deployBeef`, `enableToken`, `tokensToEnable`, `disableToken`, `defaults`,
+  `setDefaultTerms`, `clearDefaultTerms`, `setDefaultMarket`, `clearDefaultMarket`, `tokenTerms`,
+  `setTokenTerms`, `discoveryState`, `setDiscovery`.
+
+Pure helpers beside it: `hostedFrom`, `poolViews`, `poolFees`, `withLeg`, `hasTerms`,
+`enableCandidates`, `topicOf`, `lookupOf`, `ammLookupOf`, `walletDeployBeef`, `exchangeBase`,
+`tokenBase`; the types (`Quote`, `SwapResult`, `LegResult`, `Position`, `WalletToken`, …).
+
+## Errors
+
+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.
+
+## 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` +
+`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
+plan` labels), the receipt helpers `newReceivingKey` / `receiptOutput`, and `xTopics` (the BRC-22
+`x-topics` header: a JSON array).
+
+## A swap
+
+```ts
+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;
+  }
+});
+```
+
+## Build
+
+From skein-amm's `web/`: `npm ci` in `ui` and in `engine`, then `npm pack` here (the build
+compiles `../ui/src/index.ts` with `../ui`'s TypeScript into `dist/`, after building the engine).
+
+runar-sdk is vendored inside (`dist/vendor/runar`, MIT: its `LICENSE` and `NOTICE` there): the
+runar-sdk the pool template is built on is not published.

package/dist/client.d.ts

@@ -0,0 +1,534 @@
+/**
+ * The Open Exchange client (skein-amm 0.38.0, D8–D14, agent-env plans/history-api-2026-11-05.md):
+ * every read and every action the pages make, bound by `createClient` to one exchange, one miner
+ * fee rate, one wallet and one fetch — configuration as arguments (D9): nothing here reads
+ * `import.meta.env` or `location`. No React; the pages (src/data/exchange.ts) hold a client and
+ * wrap it in their hooks. Published as `@dcasegr/amm-client` (src/index.ts; README "The packages").
+ *
+ * 0.34.0 (agent-env plans/exchange-api-2026-11-04.md §0, D1–D25; docs/AMM.md "The public read
+ * API"): every read is a plain GET of the exchange's public read API (src/lib/overlay.ts), and the
+ * client sends `/lookup` nowhere. Where each comes from:
+ *
+ * - **The token list** (`GET <swap>/tokens`): read ONCE per client (D4; `enabledList`), again
+ *   only after its own enable or disable changed it.
+ * - **Prices** (D6, D22): the host-wide pools route `GET <origin>/amm/pools` (`hostedTokens`,
+ *   `watchHostedPools`); a token's price is Σsats / Σtokens over its listed pools.
+ * - **Swap** (D11–D16): the token's pools route `GET /@<token>/amm/pools` held as an event stream
+ *   (`watchTokenPools`): 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`.
+ * - **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.
+ * - **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`.
+ *
+ * Ids (David, 2026-10-09): every token id is the BRC-207 assetId
+ * `<txid>_<vout>`, `_0` included for a 1Color token (src/lib/tokenId.ts);
+ * an outpoint is `<txid>.<vout>`. Amounts are bigints in base units; prices
+ * are numbers: sats per whole token.
+ */
+import { type WalletInterface } from "@bsv/sdk";
+import { type Send1ColorResult } from "@1sat/actions";
+import { type PoolState, type Plan } from "@dcasegr/amm-engine";
+import { type LiveAnswer, type PoolRow, type PoolsAnswer, 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";
+/** 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`. */
+export interface Depth {
+    bps: number;
+    sats: bigint;
+}
+/** A token this overlay hosts (registered here), with its pools summed. */
+export interface HostedToken {
+    tokenId: TokenId;
+    sym: string;
+    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. */
+    marginalPrice: number | null;
+    depth: Depth | null;
+    /** Number of open pools. */
+    pools: number;
+    /** All pools summed. */
+    reserves: {
+        sats: bigint;
+        tokens: bigint;
+    };
+    /** Price change over 24 h, a fraction (0.018 = +1.8%). Absent when not known. */
+    change24h?: number;
+}
+/** One open pool of a token, as a quote routes over it. */
+export interface PoolView {
+    /** `<txid>.<vout>` */
+    outpoint: string;
+    tokenId: TokenId;
+    sats: bigint;
+    tokens: bigint;
+    validator: ValidatorRef;
+}
+export interface ValidatorRef {
+    identityKey: string;
+    live: boolean;
+}
+/** "buy": pay sats, receive the token. "sell": pay the token, receive sats. */
+export type Side = "buy" | "sell";
+export interface QuoteRequest {
+    tokenId: TokenId;
+    side: Side;
+    /** Base units of what is paid (sats on a buy, token base units on a sell). */
+    amountIn: bigint;
+    /** Max slippage against the quoted amount out, basis points. */
+    maxSlippageBps: number;
+    allowPartial: boolean;
+}
+export interface QuoteLeg {
+    /** The pool, `<txid>.<vout>`. */
+    poolOutpoint: string;
+    amountIn: bigint;
+    amountOut: bigint;
+    /** Share of the amount in, basis points (the legs sum to 10000). */
+    shareBps: number;
+    /** The pool's reserves before the leg. */
+    reserves: {
+        sats: bigint;
+        tokens: bigint;
+    };
+    validator: ValidatorRef;
+}
+export interface Quote {
+    request: QuoteRequest;
+    legs: QuoteLeg[];
+    amountOut: bigint;
+    /** The least amount out the swap accepts: amountOut less max slippage. */
+    minAmountOut: bigint;
+    /** Sats per whole token this swap pays (fees included). */
+    effectivePrice: number;
+    /** Sats per whole token before the swap. */
+    marginalPrice: number;
+    /** |effective − marginal| / marginal, basis points. */
+    impactBps: number;
+    /** The validator's fees applied to every leg. */
+    fees: Fees;
+}
+export interface LegResult {
+    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;
+}
+export interface SwapResult {
+    status: "filled" | "partial" | "failed";
+    legs: LegResult[];
+}
+/** The validator's fees, basis points of the amount in. The LP accepts them; there is no fee input. */
+export interface Fees {
+    lpBps: number;
+    validatorBps: number;
+    /** The relay's commission (the pool's CommissionBps); 0: none. */
+    commissionBps: number;
+}
+/**
+ * `amm.pool.terms`'s refusal when no terms are set (0.15.0, David Case
+ * 2026-10-23: terms are a runtime record root sets; unset, a market only).
+ */
+export declare const NO_VALIDATOR = "no validator here";
+/** What the pages show in place of the terms when none are set. */
+export declare const NO_TERMS_TEXT = "This exchange validates nothing: no terms are set.";
+/** No terms are set on this skein (`amm.pool.terms` answered "no validator here"): a market only. */
+export interface NoTerms {
+    none: true;
+}
+/** Whether `t` is a validator's terms (not "none set"). */
+export declare function hasTerms(t: ValidatorTerms | NoTerms | null | undefined): t is ValidatorTerms;
+/** The validator a new position is deployed with, and its fees (read-only on the page). */
+export interface ValidatorTerms {
+    validator: ValidatorRef;
+    /** "this exchange's" when the validator is this skein. */
+    isThisExchange: boolean;
+    fees: Fees;
+}
+/** 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;
+    tokenId: TokenId;
+    sym: string;
+    dec: number;
+    icon?: string;
+    sats: bigint;
+    tokens: bigint;
+    /** Fees the pool has earned the LP, when it can be told (0.32.0: the sats-in swaps' LP fees, `ls_amm_<assetId>` `{tokenId, lpPubKey}`). */
+    feesEarnedSats?: bigint;
+    /** 0.32.0: the token-in swaps' LP fees, token base units; told with `feesEarnedSats`. */
+    feesEarnedTokens?: bigint;
+    /** 0.32.0: the pool is closed (the LP's Close or a rescind's); kept for its fees, not listed as a card. */
+    closed?: boolean;
+    validator: ValidatorRef;
+    /** The validator rescinded the pool (0.13.0): no swaps; the LP closes it. */
+    rescinded?: boolean;
+}
+export interface DeployRequest {
+    tokenId: TokenId;
+    /** Token base units. */
+    tokens: bigint;
+    sats: bigint;
+}
+export interface DeployResult {
+    /** The new pool, `<txid>.<vout>`. */
+    outpoint: string;
+    txid: string;
+    /** What did not complete after the broadcast (the position row's filing, the page's own submit). */
+    warnings?: string[];
+}
+export interface CloseRequest {
+    outpoint: string;
+}
+export interface RebalanceRequest {
+    /** The position's pool, `<txid>.<vout>`. */
+    outpoint: string;
+    /** The new pool's tokens, base units. */
+    tokens: bigint;
+    /** The new pool's sats. */
+    sats: bigint;
+}
+export interface RebalanceResult {
+    /** The new pool, `<txid>.0`. */
+    outpoint: string;
+    txid: string;
+    /** The old pool's output the same transaction closed. */
+    closed: string;
+    /** What did not complete after the broadcast (the new position row's filing, the page's own submit). */
+    warnings?: string[];
+}
+export interface CloseResult {
+    txid: string;
+    /** Returned to the wallet. */
+    sats: bigint;
+    tokens: bigint;
+}
+/** One of the user's own 1Color tokens. */
+export interface WalletToken {
+    tokenId: TokenId;
+    sym: string;
+    dec: number;
+    icon?: string;
+    /** The wallet's balance: the sum of the token's held value outputs in `p color assets` (0.27.0; was the module's `p color balance`). */
+    balance: bigint;
+    /** How many wallet outputs hold it. */
+    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;
+}
+/** A token seen on the discovery topic (`tm_color`). */
+export interface DiscoveryToken {
+    tokenId: TokenId;
+    sym: string;
+    dec: number;
+    icon?: string;
+    /** When discovery first saw it, ms. */
+    seenAt?: number;
+}
+/** A token on this exchange's list (the swap instance's enable list), as Settings lists it. */
+export interface RegisteredToken {
+    tokenId: TokenId;
+    sym: string;
+    icon?: string;
+    status: EnabledToken["status"];
+}
+export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer };
+/** A token's symbol, decimals and icon, read off its deploy output. */
+export interface DeployMeta {
+    sym?: string;
+    dec?: number;
+    icon?: string;
+}
+/** A token's deploy as `deployBeef` finds it: its Atomic BEEF, its metadata, and where it came from. */
+export interface DeployFound {
+    beef: number[];
+    meta: DeployMeta;
+    from: "wallet" | "discovery";
+}
+/**
+ * Whether the exchange is claimed, its admin, and swap's identity (0.28.0: swap is born owned by the
+ * host's key, so `/.well-known/skein`'s `claimed` is always true; the claim is the swap app's own record,
+ * `GET <base>/admin` → `{claimant?, since?}`). `identity` from `/.well-known/skein` (the claim's recipient).
+ * A swap with no `/admin` read (pages older than open-exchange 0.5.0): `claimed` as `/.well-known/skein` says.
+ */
+export interface ClaimStatus {
+    claimed: boolean;
+    identity: string;
+    claimant?: string;
+}
+/**
+ * The hosted tokens (the enabled 1Color tokens at output 0), each priced from its rows of the
+ * host-wide pools route (D6, D22: P1, the pools whose validator is beating): Σsats / Σtokens.
+ * `rows` null: not read yet (no prices). Pure.
+ */
+export declare function hostedFrom(list: EnabledToken[], rows: PoolRow[] | null): HostedToken[];
+/** The pools the Swap page lists (D11, D13): the token's pools route's rows, every validator live (the host lists no other). */
+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;
+/**
+ * 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
+ * pulls ~560 kB into the bundle; test/exchange.test.ts checks it equals the toolbox's.
+ */
+export declare const SPEC_OP_WALLET_BALANCE = "893b7646de0e1c9f741bd6e9169b76a8847ae34adef7bef1e6a285371206d2e8";
+/** The topic a token's pools are admitted under (BRC-207; skein-amm 0.8.0): derived, never typed. */
+export declare function topicOf(tokenId: TokenId): string;
+/** The lookup service of a token (BRC-207): derived, never typed. */
+export declare function lookupOf(tokenId: TokenId): string;
+/** The AMM lookup's service of a token, `ls_amm_<assetId>` (0.21.0): a token instance's config names it, so it beats its prices on `ls_amm_<assetId>-live` (skein-overlay 0.17.0: a configured lookup beats). */
+export declare function ammLookupOf(tokenId: TokenId): string;
+/**
+ * A token deploy's BEEF from the connected wallet (0.17.0), as the 1Color tokens page gets it
+ * (skein-1color web/src/overlay.ts `walletDeployBeef`): the deploy output in the module's basket
+ * `p color <txid>v<vout>` (then its `authority` basket), its transaction as BEEF (`include: "entire
+ * transactions"`), as an Atomic BEEF of the deploy. Undefined when the wallet holds it in neither
+ * (not the deployer's, or the output spent).
+ */
+export declare function walletDeployBeef(wallet: WalletInterface, tokenId: TokenId): Promise<number[] | undefined>;
+/** What enabling a token reports: where the deploy's BEEF came from (2026-10-31: the wallet's basket or discovery; no paste). */
+export interface EnableSent {
+    beefFrom: "wallet" | "discovery";
+}
+/** A token Settings offers to enable (2026-10-31): on discovery, in this wallet, or both; not on the list yet. */
+export interface EnableCandidate {
+    tokenId: TokenId;
+    sym?: string;
+    icon?: string;
+    onDiscovery: boolean;
+    inWallet: boolean;
+}
+/**
+ * The candidates to enable: discovery's token list (its order, newest first, with its metadata),
+ * then the tokens only this wallet holds (in the order held); every token already on the swap
+ * 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). */
+export interface TermsInput {
+    lpBps: number;
+    validatorBps: number;
+    commissionBps: number;
+}
+/** What a quote was planned from: kept for its execution. */
+interface Planned {
+    plan: Plan;
+    pools: PoolRow[];
+    live: LiveAnswer;
+    market: PoolsAnswer["market"];
+    dec: number;
+    sym: string;
+}
+/** A plain fetch (the reads, the submits, the BRC-104 transport). */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/** The wallet's BRC-104 client for one instance base (src/lib/skein.ts `authFetchPerInstance`). */
+export type Signed = SignedFetch & AuthFetchLike;
+export interface ClientOptions {
+    /**
+     * The exchange: its origin (`https://swap.skein.nexus`: the swap app at `<origin>/amm`) or the
+     * swap app's base URL with a path (`http://127.0.0.1:8100/@swap/amm`), as the pages compute it.
+     */
+    origin: string;
+    /** The miner fee rate the client sizes a swap leg's staged sats with, sats per 1000 bytes. Default 100. */
+    feeRateSatsPerKb?: number;
+    /** The connected BRC-100 wallet; null or absent: a client for the reads (actions answer "Connect a wallet first"). */
+    wallet?: WalletInterface | null;
+    /** The plain fetch for every unsigned request and the BRC-104 transport. Default: the global `fetch`, looked up at each call. */
+    fetch?: FetchLike;
+    /** The wallet's BRC-104 client per instance base. Default: `authFetchPerInstance(wallet, fetch)` (one session per instance). */
+    signedFor?: (base: string) => Signed;
+    /** 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. */
+export type SwapProgress = {
+    phase: "staging";
+} | {
+    phase: "relaying";
+    leg: string;
+} | {
+    phase: "repricing";
+    leg: string;
+} | {
+    phase: "done";
+    result: SwapResult;
+} | {
+    phase: "failed";
+    result?: SwapResult;
+    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). */
+    onProgress?: (p: SwapProgress) => void;
+}
+/** What a client remembers between calls; shared by `withWallet`'s clients. */
+interface Shared {
+    /** The token list read by this client (D4: once; again only after its own enable or disable). */
+    listRead: Promise<EnabledToken[]> | null;
+    /** swap's claim card read by this client (D21: the identity of the recipient of root's messages). */
+    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;
+    }>;
+    /** 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. */
+    listeners: Set<() => void>;
+}
+/**
+ * The client of one exchange (D9): its reads over `origin` (src/lib/overlay.ts, src/lib/skein.ts),
+ * the swap flow, the pool flows (deploy, close, rebalance, move back, positions) and the wallet
+ * pieces, bound to `feeRateSatsPerKb`, `wallet` and `fetch`. Errors of the kinds in
+ * `CLIENT_ERROR_KINDS` are `ClientError`s (D13), the message as before.
+ */
+export declare function createClient(opts: ClientOptions): AmmClient;
+export type AmmClient = ReturnType<typeof makeClient>;
+declare function makeClient(opts: ClientOptions, s: Shared): {
+    /** The swap app's base URL (`origin` as given, or `<origin>/amm`). */
+    base: string;
+    feeRateSatsPerKb: number;
+    wallet: WalletInterface | null;
+    withWallet: (wallet: WalletInterface | null, o?: {
+        signedFor?: (base: string) => Signed;
+        identityKey?: string | null;
+    }) => {
+        /** The swap app's base URL (`origin` as given, or `<origin>/amm`). */
+        base: string;
+        feeRateSatsPerKb: number;
+        wallet: WalletInterface | null;
+        withWallet: /*elided*/ any;
+        onDataChange: (fn: () => void) => () => void;
+        forgetReads: () => void;
+        enabledList: () => Promise<EnabledToken[]>;
+        tokenBaseOf: (tokenId: string) => Promise<string>;
+        hostRoot: () => string;
+        discoveryBase: () => string;
+        claimStatus: () => Promise<ClaimStatus>;
+        isRoot: (identityKey: string | null) => Promise<boolean>;
+        claimExchange: () => Promise<boolean>;
+        hostedTokens: () => Promise<HostedToken[]>;
+        watchHostedPools: (onRows: (rows: PoolRow[]) => void, onLive?: (live: boolean) => void) => () => void;
+        watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+        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>;
+        deployPosition: (req: DeployRequest) => Promise<DeployResult>;
+        closePosition: (req: CloseRequest) => Promise<CloseResult>;
+        rebalancePosition: (req: RebalanceRequest) => Promise<RebalanceResult>;
+        myTokens: () => Promise<WalletToken[]>;
+        settleSwaps: () => Promise<string[]>;
+        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>;
+        enableToken: (tokenId: string) => Promise<EnableSent>;
+        tokensToEnable: () => Promise<EnableCandidate[]>;
+        disableToken: (tokenId: string) => Promise<void>;
+        defaults: () => Promise<Defaults>;
+        setDefaultTerms: (t: TermsInput) => Promise<void>;
+        tokenTerms: (tokenId: string) => Promise<{
+            identity: string;
+            peerId: string | null;
+            lpFeeBps: number;
+            validatorFeeBps: number;
+            commissionBps: number;
+        } | null>;
+        setTokenTerms: (tokenId: string, t: TermsInput | null) => Promise<void>;
+        clearDefaultTerms: () => Promise<void>;
+        setDefaultMarket: (minCommissionBps: number) => Promise<void>;
+        clearDefaultMarket: () => Promise<void>;
+        discoveryState: () => Promise<Discovery>;
+        setDiscovery: (on: boolean) => Promise<void>;
+    };
+    onDataChange: (fn: () => void) => () => void;
+    forgetReads: () => void;
+    enabledList: () => Promise<EnabledToken[]>;
+    tokenBaseOf: (tokenId: string) => Promise<string>;
+    hostRoot: () => string;
+    discoveryBase: () => string;
+    claimStatus: () => Promise<ClaimStatus>;
+    isRoot: (identityKey: string | null) => Promise<boolean>;
+    claimExchange: () => Promise<boolean>;
+    hostedTokens: () => Promise<HostedToken[]>;
+    watchHostedPools: (onRows: (rows: PoolRow[]) => void, onLive?: (live: boolean) => void) => () => void;
+    watchTokenPools: (tokenId: TokenId, onAnswer: (a: PoolsAnswer) => void, onError?: (e: unknown) => void) => () => void;
+    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>;
+    deployPosition: (req: DeployRequest) => Promise<DeployResult>;
+    closePosition: (req: CloseRequest) => Promise<CloseResult>;
+    rebalancePosition: (req: RebalanceRequest) => Promise<RebalanceResult>;
+    myTokens: () => Promise<WalletToken[]>;
+    settleSwaps: () => Promise<string[]>;
+    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>;
+    enableToken: (tokenId: string) => Promise<EnableSent>;
+    tokensToEnable: () => Promise<EnableCandidate[]>;
+    disableToken: (tokenId: string) => Promise<void>;
+    defaults: () => Promise<Defaults>;
+    setDefaultTerms: (t: TermsInput) => Promise<void>;
+    tokenTerms: (tokenId: string) => Promise<{
+        identity: string;
+        peerId: string | null;
+        lpFeeBps: number;
+        validatorFeeBps: number;
+        commissionBps: number;
+    } | null>;
+    setTokenTerms: (tokenId: string, t: TermsInput | null) => Promise<void>;
+    clearDefaultTerms: () => Promise<void>;
+    setDefaultMarket: (minCommissionBps: number) => Promise<void>;
+    clearDefaultMarket: () => Promise<void>;
+    discoveryState: () => Promise<Discovery>;
+    setDiscovery: (on: boolean) => Promise<void>;
+};