@dcasegr/amm-client 0.0.0-stage → 0.38.1

package/dist/errors.d.ts

@@ -0,0 +1,17 @@
+import type { SwapOutcome } from "./market/swapFlow.js";
+/** Every kind a `ClientError` names (D13). */
+export declare const CLIENT_ERROR_KINDS: readonly ["stale_pool", "fee_mismatch", "quote_mismatch", "slippage", "pool_spent", "user_rejected", "no_answer", "refused", "network"];
+export type ClientErrorKind = (typeof CLIENT_ERROR_KINDS)[number];
+/** An error of a named kind; `message` is the text the pages show. */
+export declare class ClientError extends Error {
+    readonly kind: ClientErrorKind;
+    constructor(kind: ClientErrorKind, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The kind of `e`, when it is one of `CLIENT_ERROR_KINDS`; undefined otherwise. */
+export declare function errorKind(e: unknown): ClientErrorKind | undefined;
+/** `e` as a `ClientError` of its kind (its message unchanged, `e` the cause) when it has one; else `e` itself. */
+export declare function toClientError(e: unknown): unknown;
+/** The kind of a relay outcome that did not fill (D13): undefined for an accepted one. */
+export declare function kindOfOutcome(o: SwapOutcome): ClientErrorKind | undefined;

package/dist/errors.js

@@ -0,0 +1,75 @@
+/**
+ * The client's named error kinds (0.38.0, D13): a `ClientError` carries one of `CLIENT_ERROR_KINDS`
+ * and the message the pages showed before (unchanged: the pages keep their texts). Thrown by the
+ * client's functions where the error is of one of these kinds; a swap leg's result carries the
+ * kind beside its text (`LegResult.kind`). Other errors (a missing wallet, a malformed answer…)
+ * stay plain `Error`s.
+ *
+ *   stale_pool      the pool moved since the quote or the read (the builder's `stale_pool`; a leg
+ *                   whose lookup tip is not the planned outpoint)
+ *   fee_mismatch    the pool's fees are not the ones quoted (the builder's `fee_mismatch`)
+ *   quote_mismatch  the pool's math does not give the quoted amounts (the builder's `quote_mismatch`)
+ *   slippage        the amount out fell below the order's minimum (the builder's `slippage`; a
+ *                   repriced leg below the order's bound)
+ *   pool_spent      the pool was spent since the quote (the quote's freshness read; the validator's
+ *                   `pool_spent` refusal)
+ *   user_rejected   the user declined in the wallet (the wallet's `ERR_PERMISSION_DENIED`, "denied")
+ *   no_answer       the relay gave no settled answer yet ("no answer yet"; a timed-out swap record)
+ *   refused         the validator, the relay or the host refused it (a refusal other than pool_spent)
+ *   network         the request did not get through (fetch threw)
+ */
+import { PoolBuildError } from "./pool/index.js";
+import { RelayError } from "./market/relay.js";
+/** Every kind a `ClientError` names (D13). */
+export const CLIENT_ERROR_KINDS = ["stale_pool", "fee_mismatch", "quote_mismatch", "slippage", "pool_spent", "user_rejected", "no_answer", "refused", "network"];
+/** An error of a named kind; `message` is the text the pages show. */
+export class ClientError extends Error {
+    kind;
+    constructor(kind, message, options) {
+        super(message, options);
+        this.kind = kind;
+        this.name = "ClientError";
+    }
+}
+const BUILD_KINDS = new Set(["stale_pool", "fee_mismatch", "quote_mismatch", "slippage"]);
+/** The kind of `e`, when it is one of `CLIENT_ERROR_KINDS`; undefined otherwise. */
+export function errorKind(e) {
+    if (e instanceof ClientError)
+        return e.kind;
+    if (e instanceof PoolBuildError)
+        return BUILD_KINDS.has(e.code) ? e.code : undefined;
+    if (e instanceof RelayError)
+        return e.httpStatus === 503 ? "no_answer" : "refused";
+    const msg = e instanceof Error ? e.message : typeof e === "string" ? e : "";
+    const code = e && typeof e === "object" && "code" in e ? String(e.code) : "";
+    if (code === "ERR_PERMISSION_DENIED" || /user has denied|permission denied|user rejected|denied by the user/i.test(msg))
+        return "user_rejected";
+    if (e instanceof TypeError && /fetch|network/i.test(msg))
+        return "network";
+    if (/^the pool moved\b/.test(msg))
+        return "stale_pool";
+    if (/^no answer yet\b/.test(msg))
+        return "no_answer";
+    return undefined;
+}
+/** `e` as a `ClientError` of its kind (its message unchanged, `e` the cause) when it has one; else `e` itself. */
+export function toClientError(e) {
+    if (e instanceof ClientError)
+        return e;
+    const kind = errorKind(e);
+    return kind ? new ClientError(kind, e instanceof Error ? e.message : String(e), { cause: e }) : e;
+}
+/** The kind of a relay outcome that did not fill (D13): undefined for an accepted one. */
+export function kindOfOutcome(o) {
+    switch (o.status) {
+        case "accepted":
+            return undefined;
+        case "refused":
+            return o.reason.startsWith("pool_spent") ? "pool_spent" : "refused";
+        case "timeout":
+        case "unknown":
+            return "no_answer";
+        case "failed":
+            return "refused";
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `@dcasegr/amm-client` (skein-amm 0.38.0, D8): the Open Exchange client without the pages —
+ * `createClient` (src/client.ts) and the names two sites must share to file identical wallet rows
+ * (D10). ESM + types, no React, no styles, no wallet provider: the caller connects a BRC-100 wallet
+ * and passes it in. README "The packages".
+ */
+export * from "./client.js";
+export { CLIENT_ERROR_KINDS, ClientError, errorKind, toClientError, type ClientErrorKind } from "./errors.js";
+export { DEFAULT_FEE_RATE_SATS_PER_KB, exchangeBase, tokenBase } from "./lib/config.js";
+/** The basket of the LP's position rows (`amm-pools`): one pool output per deploy, filed by basket insertion. */
+export { POOLS_BASKET } from "./wallet/color.js";
+/** The active swap basket (`amm-swap`): the token outputs and the sats each swap leg spends. */
+export { SWAP_BASKET } from "./wallet/color.js";
+/** The key protocol of every `amm-swap` row (`[2, "amm swap"]`, counterparty self). */
+export { SWAP_PROTOCOL } from "./wallet/color.js";
+/** The keyID prefix of an `amm-swap` row's key (`amm-swap-`). */
+export { SWAP_KEY_PREFIX } from "./market/activeSwap.js";
+/** The keyID of a staged `amm-swap` row: `amm-swap-<pool txid>.<vout>` (token row) or `…:sats` (its sats row). */
+export { swapKeyID } from "./market/activeSwap.js";
+/** customInstructions of an `amm-swap` token row (asset, amount and the key that spends it). */
+export { swapInstructions } from "./wallet/color.js";
+/** customInstructions of an `amm-swap` sats row (`sats: true`, the token it was staged for, its key). */
+export { swapSatsInstructions } from "./wallet/color.js";
+/** The key protocol of a pool's LP key (BRC-29, to self): the `amm-pools` row's protocolID. */
+export { LP_KEY_PROTOCOL } from "./lp/poolDeploy.js";
+/** The marker a deploy's pool output description ends with (` · amm-lp <hex>`): it names the LP keyID. */
+export { LP_KEY_MARK } from "./lp/poolDeploy.js";
+/** A deploy's pool output description: the readable text, then `LP_KEY_MARK` and the LP keyID's suffix. */
+export { lpKeyDescription } from "./lp/poolDeploy.js";
+/** The LP keyID a deploy's pool output description names, or null. */
+export { lpKeyIdOfDescription } from "./lp/poolDeploy.js";
+/** The tag (`amm-pool`) of an `amm-pools` row. */
+export { POOL_TAG } from "./lp/poolDeploy.js";
+/** The `op` (`amm-pool`) in an `amm-pools` row's customInstructions. */
+export { POOL_OP } from "./lp/poolDeploy.js";
+/** Whether a basket row is an `amm-pools` position row (its tag or its customInstructions `op`). */
+export { isPoolRow } from "./lp/poolDeploy.js";
+/** customInstructions of an `amm-pools` row: the token, the LP key, the validator, its fees and nonce. */
+export { poolCustomInstructions } from "./lp/poolDeploy.js";
+/** The label of a pool deploy's action (`amm-pool-deploy`): the positions reader's history. */
+export { POOL_DEPLOY_LABEL } from "./lp/positions.js";
+/** How long the relay may take a swap leg (the swap's `expires`), ms. */
+export { SWAP_TTL_MS } from "./market/swapAction.js";
+/** The `p color plan` labels of a transfer of one asset (BRC-207 plan version 1): every token action's. */
+export { transferPlanLabels } from "./wallet/color.js";
+/** A module receiving key for one output of an asset from a sender: its receipt, key and hash160. */
+export { newReceivingKey, type ReceivingKey } from "./wallet/color.js";
+/** A receipt's `basket insertion` into the asset's value basket (`p color <assetTag>`), for `internalizeAction`. */
+export { receiptOutput } from "./wallet/color.js";
+/** The `x-topics` header of a BRC-22 submit: the topics as a JSON array (D14). */
+export { xTopics } from "./lp/close.js";

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * `@dcasegr/amm-client` (skein-amm 0.38.0, D8): the Open Exchange client without the pages —
+ * `createClient` (src/client.ts) and the names two sites must share to file identical wallet rows
+ * (D10). ESM + types, no React, no styles, no wallet provider: the caller connects a BRC-100 wallet
+ * and passes it in. README "The packages".
+ */
+// The client (D9, D11–D13).
+export * from "./client.js";
+export { CLIENT_ERROR_KINDS, ClientError, errorKind, toClientError } from "./errors.js";
+export { DEFAULT_FEE_RATE_SATS_PER_KB, exchangeBase, tokenBase } from "./lib/config.js";
+// The shared names (D10): what each names in the wallet.
+/** The basket of the LP's position rows (`amm-pools`): one pool output per deploy, filed by basket insertion. */
+export { POOLS_BASKET } from "./wallet/color.js";
+/** The active swap basket (`amm-swap`): the token outputs and the sats each swap leg spends. */
+export { SWAP_BASKET } from "./wallet/color.js";
+/** The key protocol of every `amm-swap` row (`[2, "amm swap"]`, counterparty self). */
+export { SWAP_PROTOCOL } from "./wallet/color.js";
+/** The keyID prefix of an `amm-swap` row's key (`amm-swap-`). */
+export { SWAP_KEY_PREFIX } from "./market/activeSwap.js";
+/** The keyID of a staged `amm-swap` row: `amm-swap-<pool txid>.<vout>` (token row) or `…:sats` (its sats row). */
+export { swapKeyID } from "./market/activeSwap.js";
+/** customInstructions of an `amm-swap` token row (asset, amount and the key that spends it). */
+export { swapInstructions } from "./wallet/color.js";
+/** customInstructions of an `amm-swap` sats row (`sats: true`, the token it was staged for, its key). */
+export { swapSatsInstructions } from "./wallet/color.js";
+/** The key protocol of a pool's LP key (BRC-29, to self): the `amm-pools` row's protocolID. */
+export { LP_KEY_PROTOCOL } from "./lp/poolDeploy.js";
+/** The marker a deploy's pool output description ends with (` · amm-lp <hex>`): it names the LP keyID. */
+export { LP_KEY_MARK } from "./lp/poolDeploy.js";
+/** A deploy's pool output description: the readable text, then `LP_KEY_MARK` and the LP keyID's suffix. */
+export { lpKeyDescription } from "./lp/poolDeploy.js";
+/** The LP keyID a deploy's pool output description names, or null. */
+export { lpKeyIdOfDescription } from "./lp/poolDeploy.js";
+/** The tag (`amm-pool`) of an `amm-pools` row. */
+export { POOL_TAG } from "./lp/poolDeploy.js";
+/** The `op` (`amm-pool`) in an `amm-pools` row's customInstructions. */
+export { POOL_OP } from "./lp/poolDeploy.js";
+/** Whether a basket row is an `amm-pools` position row (its tag or its customInstructions `op`). */
+export { isPoolRow } from "./lp/poolDeploy.js";
+/** customInstructions of an `amm-pools` row: the token, the LP key, the validator, its fees and nonce. */
+export { poolCustomInstructions } from "./lp/poolDeploy.js";
+/** The label of a pool deploy's action (`amm-pool-deploy`): the positions reader's history. */
+export { POOL_DEPLOY_LABEL } from "./lp/positions.js";
+/** How long the relay may take a swap leg (the swap's `expires`), ms. */
+export { SWAP_TTL_MS } from "./market/swapAction.js";
+/** The `p color plan` labels of a transfer of one asset (BRC-207 plan version 1): every token action's. */
+export { transferPlanLabels } from "./wallet/color.js";
+/** A module receiving key for one output of an asset from a sender: its receipt, key and hash160. */
+export { newReceivingKey } from "./wallet/color.js";
+/** A receipt's `basket insertion` into the asset's value basket (`p color <assetTag>`), for `internalizeAction`. */
+export { receiptOutput } from "./wallet/color.js";
+/** The `x-topics` header of a BRC-22 submit: the topics as a JSON array (D14). */
+export { xTopics } from "./lp/close.js";

package/dist/lib/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The skein instances the client talks to (Open Exchange, shruggr/open-exchange#1): the SWAP
+ * instance whose app base the client is given (`createClient({origin})`, `exchangeBase`: the
+ * token list `GET <base>/tokens`, the defaults, root's enable / disable / defaults / discovery
+ * messages) and, per enabled token, that token's own instance (`tokenBase`:
+ * `<origin>/@<tokenId>/amm`, its pools, prices, liveness, `/call`, `/submit`, `/spends`). Every
+ * request goes to one of those (a GET by plain `fetch`; every POST through the connected
+ * wallet's BRC-104 `AuthFetch`, since a skein takes no unsigned POST; src/lib/overlay.ts), or to
+ * the connected BRC-100 wallet.
+ *
+ * 0.38.0 (D9): pure — no `import.meta.env`, no `location`. The pages compute their base and fee
+ * rate from their URL and env (src/ox/env.ts: `VITE_AMM_OVERLAY`, `VITE_FEE_RATE`, `appBaseOf`)
+ * and pass them to `createClient`.
+ */
+/**
+ * The app's base URL from the page's own URL: the directory the page is
+ * served from (`https://alice.skein.nexus/amm/` → `https://alice.skein.nexus/amm`,
+ * `http://127.0.0.1:8100/@alice/amm/index.html` → `http://127.0.0.1:8100/@alice/amm`).
+ * At the origin's root (the instance's root route `/` serving this app's www/,
+ * shruggr/skein#147: `https://alice.skein.nexus/`, or a host's dev form
+ * `http://127.0.0.1:8100/@alice/`) the page names no app, and the app is the
+ * same skein's `amm`: `<origin>/amm` (`…/@alice/amm`).
+ */
+export declare function appBaseOf(href: string): string | undefined;
+/** The app the pages are at the origin's root (skein#147): this one, installed as `amm`. */
+export declare const ROOT_APP = "amm";
+/** The app's name: the last segment of its base URL (`…/amm` → `amm`); undefined for an origin. */
+export declare function appName(base: string): string | undefined;
+/** The miner fee rate a client sizes a swap with when none is given, sats per 1000 bytes (D9: today's value). */
+export declare const DEFAULT_FEE_RATE_SATS_PER_KB = 100;
+/**
+ * The swap app's base URL of an exchange (`createClient({origin})`): an origin alone
+ * (`https://swap.skein.nexus`) is the app at its root, `<origin>/amm` (skein#147, as `appBaseOf`
+ * reads a page at the origin's root); a URL with a path is the base as given. No trailing slash.
+ */
+export declare function exchangeBase(origin: string): string;
+/**
+ * A token instance's AMM base (Open Exchange, shruggr/open-exchange#1): `<origin>/@<tokenId>/amm` on the
+ * origin the swap instance's base is on — the host makes each enabled token's instance at that path
+ * (skein#161: a token id is a path-only handle).
+ */
+export declare function tokenBase(tokenId: string, from: string): string;

package/dist/lib/config.js

@@ -0,0 +1,64 @@
+/**
+ * The skein instances the client talks to (Open Exchange, shruggr/open-exchange#1): the SWAP
+ * instance whose app base the client is given (`createClient({origin})`, `exchangeBase`: the
+ * token list `GET <base>/tokens`, the defaults, root's enable / disable / defaults / discovery
+ * messages) and, per enabled token, that token's own instance (`tokenBase`:
+ * `<origin>/@<tokenId>/amm`, its pools, prices, liveness, `/call`, `/submit`, `/spends`). Every
+ * request goes to one of those (a GET by plain `fetch`; every POST through the connected
+ * wallet's BRC-104 `AuthFetch`, since a skein takes no unsigned POST; src/lib/overlay.ts), or to
+ * the connected BRC-100 wallet.
+ *
+ * 0.38.0 (D9): pure — no `import.meta.env`, no `location`. The pages compute their base and fee
+ * rate from their URL and env (src/ox/env.ts: `VITE_AMM_OVERLAY`, `VITE_FEE_RATE`, `appBaseOf`)
+ * and pass them to `createClient`.
+ */
+/**
+ * The app's base URL from the page's own URL: the directory the page is
+ * served from (`https://alice.skein.nexus/amm/` → `https://alice.skein.nexus/amm`,
+ * `http://127.0.0.1:8100/@alice/amm/index.html` → `http://127.0.0.1:8100/@alice/amm`).
+ * At the origin's root (the instance's root route `/` serving this app's www/,
+ * shruggr/skein#147: `https://alice.skein.nexus/`, or a host's dev form
+ * `http://127.0.0.1:8100/@alice/`) the page names no app, and the app is the
+ * same skein's `amm`: `<origin>/amm` (`…/@alice/amm`).
+ */
+export function appBaseOf(href) {
+    const u = new URL(href);
+    const path = u.pathname.replace(/[^/]*$/, "").replace(/\/+$/, "");
+    const segs = path.split("/").filter((x) => x !== "");
+    if (segs.length === 0 || (segs.length === 1 && segs[0].startsWith("@")))
+        return `${u.origin}${path}/${ROOT_APP}`;
+    return u.origin + path;
+}
+/** The app the pages are at the origin's root (skein#147): this one, installed as `amm`. */
+export const ROOT_APP = "amm";
+/** The app's name: the last segment of its base URL (`…/amm` → `amm`); undefined for an origin. */
+export function appName(base) {
+    try {
+        const segs = new URL(base).pathname.split("/").filter((x) => x !== "");
+        const last = segs[segs.length - 1];
+        return last && !last.startsWith("@") ? decodeURIComponent(last) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The miner fee rate a client sizes a swap with when none is given, sats per 1000 bytes (D9: today's value). */
+export const DEFAULT_FEE_RATE_SATS_PER_KB = 100;
+/**
+ * The swap app's base URL of an exchange (`createClient({origin})`): an origin alone
+ * (`https://swap.skein.nexus`) is the app at its root, `<origin>/amm` (skein#147, as `appBaseOf`
+ * reads a page at the origin's root); a URL with a path is the base as given. No trailing slash.
+ */
+export function exchangeBase(origin) {
+    const u = new URL(origin);
+    const path = u.pathname.replace(/\/+$/, "");
+    return path === "" ? `${u.origin}/${ROOT_APP}` : `${u.origin}${path}`;
+}
+/**
+ * A token instance's AMM base (Open Exchange, shruggr/open-exchange#1): `<origin>/@<tokenId>/amm` on the
+ * origin the swap instance's base is on — the host makes each enabled token's instance at that path
+ * (skein#161: a token id is a path-only handle).
+ */
+export function tokenBase(tokenId, from) {
+    return `${new URL(from).origin}/@${tokenId}/${ROOT_APP}`;
+}

package/dist/lib/keys.d.ts

@@ -0,0 +1,42 @@
+import { type WalletProtocol } from "@bsv/sdk";
+/**
+ * Validator key derivation (docs/notes.md, "Validator derivation" and
+ * "Overlay and communication layer on skein" / "Identity"):
+ *
+ * BRC-43 security level 1, protocol "amm pool" (BRC-43 needs >= 5
+ * characters, so not "amm"), key ID `<txid display hex>_<vout>`, anyone
+ * counterparty: invoice `1-amm pool-<txid>_<vout>`.
+ *
+ * The pool's rotating `ValidatorPubKey` is always a child of the
+ * validator's own stable `ValidatorIdentity`. The first (a deploy's,
+ * skein-amm 0.13.0) is keyed by the validator's nonce, 64 lowercase hex
+ * digits (`deriveFirstValidatorPubKey`): the validator picks it at
+ * `amm.pool.affirm` and the pool's state carries it. Each Swap's next key is
+ * keyed by the pool outpoint the Swap spends (`deriveValidatorPubKey`).
+ * (Before 0.13.0 the first key was keyed by the deploy's first token input.)
+ *
+ * Because the counterparty is "anyone", this is a public one-way function
+ * of the validator's identity public key and the key ID: anyone holding
+ * `validatorIdentity` (published, part of every pool's state) can compute
+ * the derived child public key without the validator's private key: the
+ * page checks the validator's answer with it, and the lookup lists a pool
+ * only when it holds.
+ */
+export declare const AMM_POOL_PROTOCOL: WalletProtocol;
+/** `<txid display hex>_<vout>` key ID for a spent outpoint, per the convention above. */
+export declare function validatorKeyId(outpoint: {
+    txid: string;
+    vout: number;
+}): string;
+/**
+ * Derives the rotating validator signing public key (hex, compressed) as a
+ * child of `validatorIdentityHex`, keyed by the outpoint the validator is
+ * about to sign for (or, at deploy, the LP's first token-deposit input).
+ * Callable by anyone: only `validatorIdentityHex` (public) is needed.
+ */
+export declare function deriveValidatorPubKey(validatorIdentityHex: string, outpoint: {
+    txid: string;
+    vout: number;
+}): string;
+/** A pool's first validator key (0.13.0): the identity's anyone-child keyed by the nonce (64 hex digits). */
+export declare function deriveFirstValidatorPubKey(validatorIdentityHex: string, nonceHex: string): string;

package/dist/lib/keys.js

@@ -0,0 +1,48 @@
+import { KeyDeriver, PublicKey } from "@bsv/sdk";
+/**
+ * Validator key derivation (docs/notes.md, "Validator derivation" and
+ * "Overlay and communication layer on skein" / "Identity"):
+ *
+ * BRC-43 security level 1, protocol "amm pool" (BRC-43 needs >= 5
+ * characters, so not "amm"), key ID `<txid display hex>_<vout>`, anyone
+ * counterparty: invoice `1-amm pool-<txid>_<vout>`.
+ *
+ * The pool's rotating `ValidatorPubKey` is always a child of the
+ * validator's own stable `ValidatorIdentity`. The first (a deploy's,
+ * skein-amm 0.13.0) is keyed by the validator's nonce, 64 lowercase hex
+ * digits (`deriveFirstValidatorPubKey`): the validator picks it at
+ * `amm.pool.affirm` and the pool's state carries it. Each Swap's next key is
+ * keyed by the pool outpoint the Swap spends (`deriveValidatorPubKey`).
+ * (Before 0.13.0 the first key was keyed by the deploy's first token input.)
+ *
+ * Because the counterparty is "anyone", this is a public one-way function
+ * of the validator's identity public key and the key ID: anyone holding
+ * `validatorIdentity` (published, part of every pool's state) can compute
+ * the derived child public key without the validator's private key: the
+ * page checks the validator's answer with it, and the lookup lists a pool
+ * only when it holds.
+ */
+export const AMM_POOL_PROTOCOL = [1, "amm pool"];
+/** `<txid display hex>_<vout>` key ID for a spent outpoint, per the convention above. */
+export function validatorKeyId(outpoint) {
+    return `${outpoint.txid}_${outpoint.vout}`;
+}
+/**
+ * Derives the rotating validator signing public key (hex, compressed) as a
+ * child of `validatorIdentityHex`, keyed by the outpoint the validator is
+ * about to sign for (or, at deploy, the LP's first token-deposit input).
+ * Callable by anyone: only `validatorIdentityHex` (public) is needed.
+ */
+export function deriveValidatorPubKey(validatorIdentityHex, outpoint) {
+    const anyone = new KeyDeriver("anyone");
+    const identity = PublicKey.fromString(validatorIdentityHex);
+    const keyId = validatorKeyId(outpoint);
+    return anyone
+        .derivePublicKey(AMM_POOL_PROTOCOL, keyId, identity, false)
+        .toString();
+}
+/** A pool's first validator key (0.13.0): the identity's anyone-child keyed by the nonce (64 hex digits). */
+export function deriveFirstValidatorPubKey(validatorIdentityHex, nonceHex) {
+    const anyone = new KeyDeriver("anyone");
+    return anyone.derivePublicKey(AMM_POOL_PROTOCOL, nonceHex.toLowerCase(), PublicKey.fromString(validatorIdentityHex), false).toString();
+}

package/dist/lib/overlay.d.ts

@@ -0,0 +1,190 @@
+import type { PoolState } from "@dcasegr/amm-engine";
+export interface TokenTopic {
+    /** `tm_color_<txid>_<vout>` (`tm_color_<txid>_0` at output 0). */
+    topic: string;
+    /** Deploy txid, 64 lowercase hex, display order. */
+    txid: string;
+    vout: number;
+    kind: "native" | "legacy";
+    /** The token id, `<txid>_<vout>` (src/lib/tokenId.ts, BRC-162 "Token identification"). */
+    tokenId: string;
+}
+/** The AMM pool lookup service of a token (programs/amm-lookup; 0.21.0): `ls_amm_<assetId>`. A name only: the pages send it no query. */
+export declare function ammLookupService(tokenId: string): string;
+/** A token topic name, `tm_color_<txid>_<vout>` (BRC-207), or null for anything else. */
+export declare function parseTokenTopic(name: string): TokenTopic | null;
+/** A pool row on the wire (P2, P3, P4's `current`): JSON numbers, bigints here. */
+interface WirePool {
+    lpPubKey?: string;
+    outpoint: string;
+    bsvReserve: number | string;
+    tokenReserve: number | string;
+    liquidityFeeBps: number | string;
+    validationFeeBps: number | string;
+    commissionBps?: number | string;
+    validatorIdentityKey: string;
+    validatorPeerId?: string;
+    tokenId?: string;
+}
+/** The engine's PoolState from a wire row (the reserves and fees as bigints). */
+export declare function toPoolState(raw: WirePool): PoolState;
+/** A pool of the pools routes: the engine's PoolState, its LP key (the pool's id, D2), and (P2) its validator's peer ID. */
+export interface PoolRow extends PoolState {
+    lpPubKey: string;
+    /** P2: the validator's libp2p peer ID, from its beat (what the relay dials). */
+    validatorPeerId?: string;
+    /** P1: the token. */
+    tokenId?: string;
+}
+/** One pool row, or null when it is not one. */
+export declare function toPoolRow(raw: unknown): PoolRow | null;
+/** The market of a token instance, as P2 carries it: where its relay takes the commission (hash160 hex), its minimum commission. */
+export interface Market {
+    commissionPkh: string | null;
+    minCommissionBps: number;
+}
+/** A validator beating on the token's topic now (P2's `validators`, 0.34.1): its identity key and libp2p peer ID. */
+export interface BeatingValidator {
+    identity: string;
+    peerId: string;
+}
+/** P2's answer: the market, the pools a swap may use now, and (0.34.1) the validators beating on the token's topic now. */
+export interface PoolsAnswer {
+    market: Market;
+    pools: PoolRow[];
+    validators: BeatingValidator[];
+}
+/** P2's JSON. */
+export declare function parsePools(x: unknown): PoolsAnswer;
+/** P1's JSON: every enabled token's rows, each naming its `tokenId`. */
+export declare function parseAllPools(x: unknown): PoolRow[];
+/** A validator seen beating (the pages take it from the pools route's rows: the host joined the beats, D11). */
+export interface LiveValidator {
+    identityKey: string;
+    /** libp2p peer ID, text (base58): what the swap names for the relay to dial. */
+    peerId: string;
+    /** The beat's time, ms epoch (0: not told). */
+    at: number;
+    ageMs: number;
+    live: boolean;
+}
+export interface LiveAnswer {
+    now: number;
+    validators: LiveValidator[];
+    /** False when nothing about liveness is known. */
+    kept: boolean;
+}
+/** The validators of the pools route's rows (every one live: the host listed only those), as the plan reads liveness. */
+export declare function liveOfPools(rows: Pick<PoolRow, "validatorIdentityKey" | "validatorPeerId">[], now?: number): LiveAnswer;
+/** The connected wallet's BRC-104 client (`@bsv/sdk` `AuthFetch`, or a test's fake): the signed writes. */
+export interface SignedFetch {
+    fetch(url: string, config?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    }): Promise<Response>;
+}
+type FetchFn = (url: string, init?: RequestInit) => Promise<Response>;
+/** P1 / P2's URL: `<base>/pools` (the swap instance's app base: every token; a token instance's: that token). */
+export declare function poolsUrl(base: string): string;
+/** P2 once (a one-shot reader; the Swap page holds the stream, `watchPools`). */
+export declare function readPools(base: string, fetchFn?: FetchFn): Promise<PoolsAnswer>;
+/** What `watchPools` needs of the browser's `EventSource` (tests pass a fake). */
+export interface EventSourceLike {
+    addEventListener(type: string, fn: (e: {
+        data?: unknown;
+    }) => void): void;
+    close(): void;
+    onerror?: ((e: unknown) => void) | null;
+    onopen?: ((e: unknown) => void) | null;
+}
+export type EventSourceCtor = new (url: string) => EventSourceLike;
+/**
+ * Holds a pools route (P1 or P2) as an event stream (D16, D22): `GET <url>` with `Accept:
+ * text/event-stream` (the browser's EventSource sends it), the event `pools` carrying the answer,
+ * first the current one, then again each time it changes; `onAnswer` gets each. Without an
+ * EventSource (an old browser, a test): ONE plain GET, no poll. → the unsubscribe.
+ */
+export declare function watchPools<T>(url: string, parse: (x: unknown) => T, onAnswer: (a: T) => void, o?: {
+    onError?: (e: unknown) => void;
+    onOpen?: () => void;
+    EventSource?: EventSourceCtor | null;
+    fetch?: FetchFn;
+}): () => void;
+/** P3's answer: the LP keys' current pools and one BEEF of their transactions. */
+export interface PoolsBeef {
+    pools: PoolRow[];
+    beef: number[];
+}
+/** P3: `GET <base>/pools/beef?lp=k1,k2` (no `lpKeys`: every live pool). */
+export declare function readPoolsBeef(base: string, lpKeys?: string[], fetchFn?: FetchFn): Promise<PoolsBeef>;
+/** One output of a pool transaction with its BEEF (Atomic, the transaction its subject): what a spend of the pool is built from. */
+export interface LookupOutput {
+    beef: number[];
+    outputIndex: number;
+}
+/** The pool `outpoint` (`<txid>_<vout>`) out of P3's BEEF, as an Atomic BEEF of its transaction; null when the BEEF lacks it. */
+export declare function poolOutputOf(pb: PoolsBeef, outpoint: string): LookupOutput | null;
+/** One LP key's pool and fees (P4): `live` (its live pool), `rescinded` (the validator's Rescind wrote `outpoint`: the LP's Close takes it back), `closed`. */
+export interface LpPool {
+    lpPubKey: string;
+    status: "live" | "rescinded" | "closed";
+    /** The output a Close acts on, `<txid>_<vout>` (live and rescinded). */
+    outpoint: string | null;
+    /** That output's pool state (live and rescinded). */
+    current: PoolState | null;
+    /** The LP fees of sats-in swaps. */
+    sats: bigint;
+    /** The LP fees of token-in swaps, token base units. */
+    tokens: bigint;
+    swaps: number;
+}
+/** P4: `GET <base>/positions?lp=k1,k2` → one record per key in the same order. */
+export declare function readPositions(base: string, lpPubKeys: string[], fetchFn?: FetchFn): Promise<LpPool[]>;
+/** P7's answer: this instance's validator terms (null: none set, a market only) and its market. */
+export interface InstanceTerms {
+    validator: {
+        identity: string;
+        peerId: string | null;
+        lpFeeBps: number;
+        validatorFeeBps: number;
+        commissionBps: number;
+    } | null;
+    market: Market;
+}
+/** P7: `GET <base>/terms`, unsigned. */
+export declare function readTerms(base: string, fetchFn?: FetchFn): Promise<InstanceTerms>;
+/** The chain state of an outpoint (P8; amm-p2p reads.zig `spendOf`). */
+export interface Spend {
+    /** `<txid>.<vout>` */
+    outpoint: string;
+    spentBy?: string;
+    /** Followed from a pool output: its current output, `<txid>.<vout>`. */
+    current?: string;
+    hops: number;
+    closed: boolean;
+}
+/** P8: `GET <base>/spends?outpoint=a,b` → one record per outpoint in query order (one outpoint: its object, wrapped). */
+export declare function readSpends(base: string, outpoints: string[], fetchFn?: FetchFn): Promise<Spend[]>;
+/** P9: `GET <base>/tx?id=<txid>`: the transaction's BEEF (every input's source with it); null when the instance does not hold it. */
+export declare function readTx(base: string, txid: string, fetchFn?: FetchFn): Promise<number[] | null>;
+/** P10: `GET <base>/swaps?id=<id>`: the relay record (dag-json, as `amm.swap.status` answers it); null when unknown. */
+export declare function readSwap(base: string, id: string, fetchFn?: FetchFn): Promise<unknown | null>;
+/** A token on discovery (P13, P14): its metadata; `iconUrl` absolute (P13 gives it relative to the list). */
+export interface DiscoveryRow {
+    tokenId: string;
+    listed: boolean;
+    topic?: string;
+    sym?: string;
+    dec?: number;
+    iconUrl?: string;
+    txid?: string;
+    vout?: number;
+}
+/** P13 with `ids`: `GET <discovery>/tokens?ids=a,b` → one row per id in query order (`listed: false` for one not on discovery). */
+export declare function readDiscoveryIds(discovery: string, ids: string[], fetchFn?: FetchFn): Promise<DiscoveryRow[]>;
+/** P13 paged: discovery's whole token list, newest first, a page at a time. */
+export declare function readDiscoveryList(discovery: string, fetchFn?: FetchFn): Promise<DiscoveryRow[]>;
+/** P16: `GET <discovery>/<token>/deploy`: the deploy's BEEF; null when discovery does not hold it. */
+export declare function readDiscoveryDeploy(discovery: string, tokenId: string, fetchFn?: FetchFn): Promise<number[] | null>;
+export {};