@dcasegr/amm-client 0.0.0-stage → 0.38.1

package/dist/lib/overlay.js

@@ -0,0 +1,302 @@
+/**
+ * The exchange's public read API (skein-amm 0.34.0; agent-env plans/exchange-api-2026-11-04.md §0,
+ * D1–D25; docs/AMM.md "The public read API"): plain GETs (D7), JSON unless the row says bytes, list
+ * parameters comma-separated, one record per key in query order (D1). The pages read these and
+ * nothing else of the overlay: they send `/lookup` nowhere (D8: `/submit` and `/lookup` are the
+ * overlay protocol other overlays and the wallet's module speak; the pages submit at the host
+ * root, `<origin>/submit` + `X-Topics`, src/lp/close.ts `submitToOverlay`).
+ *
+ * | # | route | answer |
+ * |---|---|---|
+ * | P1 | `GET <origin>/amm/pools` (and as an event stream) | `[{tokenId, …P2 row}]`, every enabled token's live pools (the host's) |
+ * | P2 | `GET <origin>/@<token>/amm/pools` (and as an event stream) | `{market: {commissionPkh, minCommissionBps}, validators: [{identity, peerId}] (0.34.1: beating now), pools: [{lpPubKey, outpoint, bsvReserve, tokenReserve, liquidityFeeBps, validationFeeBps, commissionBps, validatorIdentityKey, validatorPeerId}]}`: only pools whose validator beats now and whose commission is at or above the market's minimum (the host's) |
+ * | P3 | `GET /@<token>/amm/pools/beef?lp=k1,k2` | `{pools: [P2 row without validatorPeerId], beef: <base64 BEEF of their transactions>}` |
+ * | P4 | `GET /@<token>/amm/positions?lp=k1,k2` | `[{lpPubKey, status: live|rescinded|closed, outpoint?, current?, sats, tokens, swaps}]` |
+ * | P5 | `GET /@<token>/amm/fees/validator?id=k1,k2` | `[{validatorIdentityKey, sats, tokens, swaps, pools}]` |
+ * | P6 | `GET /@<token>/amm/fees/commission?pkh=h1,h2` | `[{commissionPkh, sats, tokens, swaps}]` |
+ * | P7 | `GET /@<token>/amm/terms` | `{validator: {identity, peerId, lpFeeBps, validatorFeeBps, commissionBps} | null, market: {commissionPkh, minCommissionBps}}` |
+ * | P8 | `GET /@<token>/amm/spends?outpoint=a,b` | `[{outpoint, spentBy?, current?, hops, closed}]` (one outpoint: the object) |
+ * | P9 | `GET /@<token>/amm/tx?id=<txid>` | the transaction's BEEF (bytes) |
+ * | P10 | `GET /@<token>/amm/swaps?id=<id>` | the relay record, as `amm.swap.status` answers it |
+ * | P11 | `GET /@<token>/amm/token` | the token's record |
+ * | P12 | `GET <origin>/amm/tokens` | the exchange's token list (src/lib/skein.ts `readTokens`) |
+ * | P13 | `GET /@discovery/1color/tokens?ids=a,b` (or paged `?limit=&skip=`) | `[{tokenId, topic, sym, dec, iconUrl?, txid, vout}]`; an id not on discovery `{tokenId, listed: false}` |
+ * | P14 | `GET /@discovery/1color/<token>` | `{tokenId, topic, sym, dec, txid, vout, iconUrl?}` |
+ * | P15 | `GET /@discovery/1color/<token>/icon` | the icon's bytes |
+ * | P16 | `GET /@discovery/1color/<token>/deploy` | the deploy's BEEF (bytes) |
+ * | P17 | `GET <origin>/.well-known/skein`, `/skeins?key=`, `/amm/admin`, `/amm/defaults`, `/amm/discovery` | as before |
+ *
+ * Writes stay what they were: `POST <origin>/submit` (BRC-22, plain), `/call` and `/sendMessage`
+ * (signed, the wallet's BRC-104 client).
+ *
+ * Names (skein-1color docs/1COLOR.md "The topic"): a token's topic is `tm_color_<assetId>`
+ * (BRC-207), the asset id `<txid>_<vout>`, `_0` included.
+ */
+import { Beef, Utils } from "@bsv/sdk";
+import { parseTokenId, tokenIdText } from "./tokenId.js";
+/** 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 function ammLookupService(tokenId) {
+    const ref = parseTokenId(tokenId);
+    if (!ref)
+        throw new Error(`not a token id: ${tokenId}`);
+    return `ls_amm_${tokenIdText(ref)}`;
+}
+const TOPIC = /^tm_color_([0-9a-f]{64})_(0|[1-9]\d*)$/;
+/** A token topic name, `tm_color_<txid>_<vout>` (BRC-207), or null for anything else. */
+export function parseTokenTopic(name) {
+    const m = TOPIC.exec(name);
+    if (!m)
+        return null;
+    const txid = m[1];
+    const vout = Number(m[2]);
+    return { topic: name, txid, vout, kind: vout === 0 ? "native" : "legacy", tokenId: tokenIdText({ txid, vout }) };
+}
+/** The engine's PoolState from a wire row (the reserves and fees as bigints). */
+export function toPoolState(raw) {
+    return {
+        outpoint: raw.outpoint,
+        bsvReserve: BigInt(raw.bsvReserve),
+        tokenReserve: BigInt(raw.tokenReserve),
+        liquidityFeeBps: BigInt(raw.liquidityFeeBps),
+        validationFeeBps: BigInt(raw.validationFeeBps),
+        commissionBps: BigInt(raw.commissionBps ?? 0),
+        validatorIdentityKey: raw.validatorIdentityKey,
+    };
+}
+function isWirePool(x) {
+    const r = x;
+    return !!r && typeof r === "object" && typeof r.outpoint === "string" && typeof r.validatorIdentityKey === "string" && r.bsvReserve !== undefined && r.tokenReserve !== undefined;
+}
+/** One pool row, or null when it is not one. */
+export function toPoolRow(raw) {
+    if (!isWirePool(raw))
+        return null;
+    return {
+        ...toPoolState(raw),
+        lpPubKey: typeof raw.lpPubKey === "string" ? raw.lpPubKey.toLowerCase() : "",
+        ...(typeof raw.validatorPeerId === "string" && raw.validatorPeerId ? { validatorPeerId: raw.validatorPeerId } : {}),
+        ...(typeof raw.tokenId === "string" ? { tokenId: raw.tokenId } : {}),
+    };
+}
+function poolRows(x) {
+    return (Array.isArray(x) ? x : []).map(toPoolRow).filter((r) => r !== null);
+}
+function toMarket(x) {
+    const m = x;
+    const pkh = typeof m?.commissionPkh === "string" && /^[0-9a-fA-F]{40}$/.test(m.commissionPkh) ? m.commissionPkh.toLowerCase() : null;
+    const min = typeof m?.minCommissionBps === "number" && Number.isInteger(m.minCommissionBps) ? m.minCommissionBps : 0;
+    return { commissionPkh: pkh, minCommissionBps: min };
+}
+/** P2's JSON. */
+export function parsePools(x) {
+    const a = x;
+    const validators = (Array.isArray(a?.validators) ? a.validators : [])
+        .filter((v) => v && typeof v.identity === "string")
+        .map((v) => ({ identity: String(v.identity).toLowerCase(), peerId: typeof v.peerId === "string" ? v.peerId : "" }));
+    return { market: toMarket(a?.market), pools: poolRows(a?.pools), validators };
+}
+/** P1's JSON: every enabled token's rows, each naming its `tokenId`. */
+export function parseAllPools(x) {
+    return poolRows(x).filter((r) => typeof r.tokenId === "string");
+}
+/** The validators of the pools route's rows (every one live: the host listed only those), as the plan reads liveness. */
+export function liveOfPools(rows, now = Date.now()) {
+    const byKey = new Map();
+    for (const r of rows) {
+        const k = r.validatorIdentityKey.toLowerCase();
+        if (!r.validatorPeerId || byKey.has(k))
+            continue;
+        byKey.set(k, { identityKey: k, peerId: r.validatorPeerId, at: 0, ageMs: 0, live: true });
+    }
+    return { now, validators: [...byKey.values()], kept: true };
+}
+const plain = (url, init) => fetch(url, init);
+async function getJson(url, fetchFn = plain) {
+    const res = await fetchFn(url, { headers: { accept: "application/json" } });
+    if (!res.ok)
+        throw new Error(`GET ${url}: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return res.json();
+}
+async function getBytes(url, fetchFn = plain) {
+    const res = await fetchFn(url, { headers: { accept: "application/octet-stream" } });
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`GET ${url}: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return Array.from(new Uint8Array(await res.arrayBuffer()));
+}
+const trim = (base) => base.replace(/\/+$/, "");
+const list = (xs) => xs.map(encodeURIComponent).join(",");
+/** P1 / P2's URL: `<base>/pools` (the swap instance's app base: every token; a token instance's: that token). */
+export function poolsUrl(base) {
+    return `${trim(base)}/pools`;
+}
+/** P2 once (a one-shot reader; the Swap page holds the stream, `watchPools`). */
+export async function readPools(base, fetchFn) {
+    return parsePools(await getJson(poolsUrl(base), fetchFn));
+}
+function eventSourceCtor() {
+    const g = globalThis;
+    return typeof g.EventSource === "function" ? g.EventSource : null;
+}
+/**
+ * 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 function watchPools(url, parse, onAnswer, o = {}) {
+    const ES = o.EventSource === undefined ? eventSourceCtor() : o.EventSource;
+    let stopped = false;
+    if (!ES) {
+        getJson(url, o.fetch).then((x) => {
+            if (!stopped)
+                onAnswer(parse(x));
+        }, (e) => {
+            if (!stopped)
+                o.onError?.(e);
+        });
+        return () => {
+            stopped = true;
+        };
+    }
+    const es = new ES(url);
+    es.addEventListener("pools", (e) => {
+        if (stopped)
+            return;
+        try {
+            onAnswer(parse(JSON.parse(String(e.data))));
+        }
+        catch (err) {
+            o.onError?.(err);
+        }
+    });
+    es.onopen = () => o.onOpen?.();
+    es.onerror = (e) => o.onError?.(e);
+    return () => {
+        stopped = true;
+        es.close();
+    };
+}
+/** P3: `GET <base>/pools/beef?lp=k1,k2` (no `lpKeys`: every live pool). */
+export async function readPoolsBeef(base, lpKeys, fetchFn) {
+    const url = `${trim(base)}/pools/beef${lpKeys ? `?lp=${list(lpKeys)}` : ""}`;
+    const a = (await getJson(url, fetchFn));
+    return { pools: poolRows(a?.pools), beef: typeof a?.beef === "string" && a.beef ? Utils.toArray(a.beef, "base64") : [] };
+}
+/** The pool `outpoint` (`<txid>_<vout>`) out of P3's BEEF, as an Atomic BEEF of its transaction; null when the BEEF lacks it. */
+export function poolOutputOf(pb, outpoint) {
+    const m = /^([0-9a-f]{64})[._](\d+)$/i.exec(outpoint);
+    if (!m || pb.beef.length === 0)
+        return null;
+    const beef = Beef.fromBinary(pb.beef);
+    if (!beef.findTxid(m[1].toLowerCase()))
+        return null;
+    return { beef: beef.toBinaryAtomic(m[1].toLowerCase()), outputIndex: Number(m[2]) };
+}
+const wireBig = (x) => (typeof x === "number" || typeof x === "string" || typeof x === "bigint" ? BigInt(x) : 0n);
+/** P4: `GET <base>/positions?lp=k1,k2` → one record per key in the same order. */
+export async function readPositions(base, lpPubKeys, fetchFn) {
+    const url = `${trim(base)}/positions?lp=${list(lpPubKeys)}`;
+    const a = await getJson(url, fetchFn);
+    if (!Array.isArray(a) || a.length !== lpPubKeys.length)
+        throw new Error(`GET ${url}: not one record per key`);
+    return a.map((r, i) => {
+        const status = r.status === "live" || r.status === "rescinded" ? r.status : "closed";
+        return {
+            lpPubKey: typeof r.lpPubKey === "string" ? r.lpPubKey : lpPubKeys[i],
+            status,
+            outpoint: typeof r.outpoint === "string" ? r.outpoint : null,
+            current: isWirePool(r.current) ? toPoolState(r.current) : null,
+            sats: wireBig(r.sats),
+            tokens: wireBig(r.tokens),
+            swaps: Number(r.swaps ?? 0),
+        };
+    });
+}
+/** P7: `GET <base>/terms`, unsigned. */
+export async function readTerms(base, fetchFn) {
+    const url = `${trim(base)}/terms`;
+    const a = (await getJson(url, fetchFn));
+    const v = a?.validator;
+    const int = (x, name) => {
+        if (typeof x !== "number" || !Number.isInteger(x))
+            throw new Error(`GET ${url}: no ${name}`);
+        return x;
+    };
+    return {
+        validator: v && typeof v === "object"
+            ? {
+                identity: String(v.identity ?? "").toLowerCase(),
+                peerId: typeof v.peerId === "string" ? v.peerId : null,
+                lpFeeBps: int(v.lpFeeBps, "lpFeeBps"),
+                validatorFeeBps: int(v.validatorFeeBps, "validatorFeeBps"),
+                commissionBps: int(v.commissionBps, "commissionBps"),
+            }
+            : null,
+        market: toMarket(a?.market),
+    };
+}
+/** P8: `GET <base>/spends?outpoint=a,b` → one record per outpoint in query order (one outpoint: its object, wrapped). */
+export async function readSpends(base, outpoints, fetchFn) {
+    if (outpoints.length === 0)
+        return [];
+    const a = await getJson(`${trim(base)}/spends?outpoint=${list(outpoints)}`, fetchFn);
+    return (Array.isArray(a) ? a : [a]);
+}
+/** 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 async function readTx(base, txid, fetchFn) {
+    return getBytes(`${trim(base)}/tx?id=${encodeURIComponent(txid)}`, fetchFn);
+}
+/** P10: `GET <base>/swaps?id=<id>`: the relay record (dag-json, as `amm.swap.status` answers it); null when unknown. */
+export async function readSwap(base, id, fetchFn) {
+    const res = await (fetchFn ?? plain)(`${trim(base)}/swaps?id=${encodeURIComponent(id)}`, { headers: { accept: "application/json" } });
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`GET ${trim(base)}/swaps: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return res.json();
+}
+function discoveryRow(x, listUrl) {
+    const listed = x.listed !== false;
+    const dec = typeof x.dec === "number" ? x.dec : typeof x.dec === "string" && /^\d+$/.test(x.dec) ? Number(x.dec) : undefined;
+    const icon = typeof x.iconUrl === "string" && x.iconUrl ? new URL(x.iconUrl, listUrl).href : undefined;
+    return {
+        tokenId: String(x.tokenId),
+        listed,
+        ...(typeof x.topic === "string" ? { topic: x.topic } : {}),
+        ...(typeof x.sym === "string" ? { sym: x.sym } : {}),
+        ...(dec !== undefined ? { dec } : {}),
+        ...(icon ? { iconUrl: icon } : {}),
+        ...(typeof x.txid === "string" ? { txid: x.txid } : {}),
+        ...(typeof x.vout === "number" ? { vout: x.vout } : {}),
+    };
+}
+/** P13 with `ids`: `GET <discovery>/tokens?ids=a,b` → one row per id in query order (`listed: false` for one not on discovery). */
+export async function readDiscoveryIds(discovery, ids, fetchFn) {
+    if (ids.length === 0)
+        return [];
+    const url = `${trim(discovery)}/tokens?ids=${list(ids)}`;
+    const a = await getJson(url, fetchFn);
+    return (Array.isArray(a) ? a : []).filter((t) => typeof t?.tokenId === "string").map((t) => discoveryRow(t, url));
+}
+/** The route's page size (skein-1color color-lookup `tokens`: `limit` 1 to 100, `skip` up to 100000). */
+const PAGE = 100;
+const MAX_SKIP = 100_000;
+/** P13 paged: discovery's whole token list, newest first, a page at a time. */
+export async function readDiscoveryList(discovery, fetchFn) {
+    const out = [];
+    for (let skip = 0; skip <= MAX_SKIP; skip += PAGE) {
+        const url = `${trim(discovery)}/tokens?limit=${PAGE}&skip=${skip}`;
+        const a = await getJson(url, fetchFn);
+        const page = (Array.isArray(a) ? a : []).filter((t) => typeof t?.tokenId === "string").map((t) => discoveryRow(t, url));
+        out.push(...page);
+        if (page.length < PAGE)
+            break;
+    }
+    return out;
+}
+/** P16: `GET <discovery>/<token>/deploy`: the deploy's BEEF; null when discovery does not hold it. */
+export async function readDiscoveryDeploy(discovery, tokenId, fetchFn) {
+    return getBytes(`${trim(discovery)}/${encodeURIComponent(tokenId)}/deploy`, fetchFn);
+}

package/dist/lib/skein.d.ts

@@ -0,0 +1,82 @@
+import { AuthFetch, type WalletInterface } from "@bsv/sdk";
+export interface SignedPost {
+    fetch(url: string, config?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: unknown;
+    }): Promise<Response>;
+}
+/** The instance's base under which `/sendMessage` lives: the AMM base without its app segment. */
+export declare function instanceBase(base: string): string;
+/**
+ * The fetch an instance's BRC-104 client uses (skein `src/client/raw.ts`, copied: the pages do not
+ * depend on the skein package). `@bsv/sdk`'s AuthFetch keeps one session per ORIGIN and shakes
+ * hands at `<origin>/.well-known/auth`, which the router gives to the root instance; an instance
+ * under a path prefix (`<origin>/@<handle>`) takes its handshake at `<prefix>/.well-known/auth`
+ * (each instance holds its own sessions). So for a base with a prefix the handshake is sent there;
+ * every other request goes as it is. `fetchFn`: the browser's fetch, bound (it must be called on
+ * the window), unless a test passes its own.
+ */
+export declare function instanceFetch(base: string, fetchFn?: typeof fetch): typeof fetch;
+/** The instance's key for its BRC-104 session: its origin and path prefix (`instanceBase`). */
+export declare function sessionKey(base: string): string;
+/**
+ * The wallet's BRC-104 clients, one per instance (its origin + path prefix): `<origin>/amm` and
+ * `<origin>/@<tokenId>/amm` are two instances with two sessions. The same instance gets the same
+ * client back.
+ */
+export declare function authFetchPerInstance(wallet: WalletInterface, fetchFn?: typeof fetch): (base: string) => AuthFetch;
+/** dag-cbor (CDE: canonical key order, shortest forms) of a plain value. */
+export declare function dagCbor(v: unknown): Uint8Array;
+/**
+ * A message from the connected wallet's key to the instance's `box` (`<app>/<box>`): its id. The
+ * instance's identity is `recipient` (hex).
+ */
+export declare function sendMessage(af: SignedPost, base: string, recipient: string, box: string, body: unknown): Promise<string>;
+/** A token's id, topic and metadata, as a token list names it. */
+export interface ListedToken {
+    tokenId: string;
+    topic: string;
+    sym?: string;
+    dec?: number;
+    icon?: string;
+}
+/**
+ * A token on the swap instance's enable list (`GET <swap>/tokens`; Open Exchange, shruggr/open-exchange#1:
+ * root's decision as a fact, enabled or disabled; the host makes its instance, `<origin>/@<tokenId>`).
+ */
+export interface EnabledToken {
+    tokenId: string;
+    topic: string;
+    sym: string;
+    dec: number;
+    icon?: string;
+    status: "enabled" | "disabled";
+    /** When root last enabled or disabled it, ms. */
+    since: number;
+}
+/**
+ * The config instance's enable list, newest first as the read lists it. A row's icon: its `icon`
+ * (a data URL, open-exchange before 0.11.0), else its `iconUrl` (0.34.0, P12: origin-relative,
+ * `/@discovery/1color/<token>/icon`) made absolute against the list's URL.
+ */
+export declare function readTokens(base: string, fetchFn?: typeof fetch): Promise<EnabledToken[]>;
+/** The defaults a new token instance is created with (0.17.0, `GET <config>/defaults`): each absent when unset. */
+export interface Defaults {
+    terms?: {
+        lpFeeBps: number;
+        validatorFeeBps: number;
+        commissionBps: number;
+    };
+    market?: {
+        minCommissionBps: number;
+    };
+}
+/** Discovery (`GET <swap>/discovery`): root's last decision, on or off, and since when (ms); the host starts or stops the discovery instance. */
+export interface Discovery {
+    on: boolean;
+    since?: number;
+}
+/** `GET <swap>/discovery`: `{on, since?}`, or `{on: false}` (none, or another shape). */
+export declare function readDiscovery(base: string, fetchFn?: typeof fetch): Promise<Discovery>;
+export declare function readDefaults(base: string, fetchFn?: typeof fetch): Promise<Defaults>;

package/dist/lib/skein.js

@@ -0,0 +1,142 @@
+/**
+ * The skein's own doors the Open Exchange pages use beside the AMM's routes
+ * (skein-amm 0.9.0):
+ *
+ * - **A message to a box** (`sendMessage`): the BRC-104-signed `POST
+ *   <instance>/sendMessage`, BRC-231 CBOR `{message: {recipient, messageBox,
+ *   body}}` — what `skein send`, skein-1color's Token topics page and any
+ *   BRC-100 wallet send (skein docs/MESSAGES.md "The messagebox"). `body` is
+ *   dag-cbor. The instance is the AMM base's origin (or its `/@<handle>`
+ *   prefix); the recipient its identity key. Root's register messages
+ *   (`amm/register`).
+ * - **The token list** (0.17.0, shruggr/skein-amm#4: `readTokens`): `GET
+ *   <config>/tokens`, the config instance's enable list — each token's id,
+ *   topic, metadata, status and its own instance's `url`; and the defaults a
+ *   new token instance is created with (`readDefaults`, `GET <config>/defaults`).
+ * - The public read API (0.34.0: the pools, positions, terms, spends, transactions, swaps, and
+ *   discovery's token reads) is src/lib/overlay.ts.
+ */
+import { encode, decode } from "cbor2";
+import { AuthFetch, Utils } from "@bsv/sdk";
+import { appName } from "./config.js";
+/** The instance's base under which `/sendMessage` lives: the AMM base without its app segment. */
+export function instanceBase(base) {
+    const name = appName(base);
+    return name ? base.replace(new RegExp(`/${name}/?$`), "") : base;
+}
+/**
+ * The fetch an instance's BRC-104 client uses (skein `src/client/raw.ts`, copied: the pages do not
+ * depend on the skein package). `@bsv/sdk`'s AuthFetch keeps one session per ORIGIN and shakes
+ * hands at `<origin>/.well-known/auth`, which the router gives to the root instance; an instance
+ * under a path prefix (`<origin>/@<handle>`) takes its handshake at `<prefix>/.well-known/auth`
+ * (each instance holds its own sessions). So for a base with a prefix the handshake is sent there;
+ * every other request goes as it is. `fetchFn`: the browser's fetch, bound (it must be called on
+ * the window), unless a test passes its own.
+ */
+export function instanceFetch(base, fetchFn) {
+    const u = new URL(instanceBase(base));
+    const prefix = u.pathname.replace(/\/+$/, "");
+    const f = fetchFn ?? ((input, init) => globalThis.fetch(input, init));
+    if (!prefix)
+        return f;
+    return ((input, init) => {
+        const s = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const w = new URL(s);
+        if (w.origin === u.origin && w.pathname === "/.well-known/auth")
+            w.pathname = `${prefix}/.well-known/auth`;
+        return f(input instanceof Request ? new Request(w, input) : w.href, init);
+    });
+}
+/** The instance's key for its BRC-104 session: its origin and path prefix (`instanceBase`). */
+export function sessionKey(base) {
+    return instanceBase(base).replace(/\/+$/, "");
+}
+/**
+ * The wallet's BRC-104 clients, one per instance (its origin + path prefix): `<origin>/amm` and
+ * `<origin>/@<tokenId>/amm` are two instances with two sessions. The same instance gets the same
+ * client back.
+ */
+export function authFetchPerInstance(wallet, fetchFn) {
+    const clients = new Map();
+    return (base) => {
+        const key = sessionKey(base);
+        let af = clients.get(key);
+        if (!af) {
+            af = new AuthFetch(wallet, undefined, undefined, undefined, {}, instanceFetch(base, fetchFn));
+            clients.set(key, af);
+        }
+        return af;
+    };
+}
+/** dag-cbor (CDE: canonical key order, shortest forms) of a plain value. */
+export function dagCbor(v) {
+    return encode(v, { cde: true });
+}
+/**
+ * A message from the connected wallet's key to the instance's `box` (`<app>/<box>`): its id. The
+ * instance's identity is `recipient` (hex).
+ */
+export async function sendMessage(af, base, recipient, box, body) {
+    const url = `${instanceBase(base)}/sendMessage`;
+    const res = await af.fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/cbor" },
+        body: dagCbor({ message: { recipient: Uint8Array.from(Utils.toArray(recipient, "hex")), messageBox: box, body: dagCbor(body) } }),
+    });
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    let v = {};
+    try {
+        v = decode(bytes);
+    }
+    catch {
+        v = { description: new TextDecoder().decode(bytes) };
+    }
+    if (res.status !== 200)
+        throw new Error(`sendMessage ${box}: HTTP ${res.status} ${String(v.code ?? "")} ${String(v.description ?? "")}`.trim());
+    return String(v.id ?? v.messageId ?? "");
+}
+async function getJson(url, fetchFn = fetch) {
+    const res = await fetchFn(url, { headers: { accept: "application/json" } });
+    if (!res.ok)
+        throw new Error(`GET ${url}: ${res.status} ${(await res.text()).slice(0, 200)}`);
+    return res.json();
+}
+const STATUSES = new Set(["enabled", "disabled"]);
+/**
+ * The config instance's enable list, newest first as the read lists it. A row's icon: its `icon`
+ * (a data URL, open-exchange before 0.11.0), else its `iconUrl` (0.34.0, P12: origin-relative,
+ * `/@discovery/1color/<token>/icon`) made absolute against the list's URL.
+ */
+export async function readTokens(base, fetchFn = fetch) {
+    const url = `${base}/tokens`;
+    const a = await getJson(url, fetchFn);
+    return (Array.isArray(a) ? a : [])
+        .filter((t) => typeof t.tokenId === "string" && typeof t.status === "string" && STATUSES.has(t.status))
+        .map((t) => ({
+        tokenId: String(t.tokenId),
+        topic: typeof t.topic === "string" ? t.topic : `tm_color_${String(t.tokenId)}`,
+        sym: typeof t.sym === "string" ? t.sym : "",
+        dec: typeof t.dec === "number" ? t.dec : 0,
+        ...(typeof t.icon === "string" ? { icon: t.icon } : typeof t.iconUrl === "string" && t.iconUrl ? { icon: new URL(t.iconUrl, url).href } : {}),
+        status: t.status,
+        since: typeof t.since === "number" ? t.since : 0,
+    }));
+}
+/** `GET <swap>/discovery`: `{on, since?}`, or `{on: false}` (none, or another shape). */
+export async function readDiscovery(base, fetchFn = fetch) {
+    const a = (await getJson(`${base}/discovery`, fetchFn));
+    if (!a || typeof a.on !== "boolean")
+        return { on: false };
+    return { on: a.on, ...(typeof a.since === "number" ? { since: a.since } : {}) };
+}
+export async function readDefaults(base, fetchFn = fetch) {
+    const a = (await getJson(`${base}/defaults`, fetchFn));
+    const out = {};
+    const t = a?.terms;
+    if (t && typeof t.lpFeeBps === "number" && typeof t.validatorFeeBps === "number" && typeof t.commissionBps === "number")
+        out.terms = { lpFeeBps: t.lpFeeBps, validatorFeeBps: t.validatorFeeBps, commissionBps: t.commissionBps };
+    const m = a?.market;
+    if (m && typeof m.minCommissionBps === "number")
+        out.market = { minCommissionBps: m.minCommissionBps };
+    return out;
+}

package/dist/lib/tokenId.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Token ids and outpoints, written and read in one place (skein-amm 0.6.3,
+ * 0.7.1).
+ *
+ * A token id is written `<txid>_<vout>` for every token, 1Color (BRC-162
+ * binary) and legacy BSV-21 (BRC-161 JSON) alike, `_0` included: BRC-162
+ * "Token identification" ("For display and APIs, the string form is
+ * `<txid>_<vout>` ... fixed for BSV-21 and Mandala ... for a 32-byte id,
+ * appends `_0`"). David, 2026-10-07 (shruggr/skein#120; supersedes 0.6.3's
+ * bare txid). The bare 32-byte txid is the wire form only.
+ * On input every form names the same token: `<txid>`, `<txid>_<vout>`,
+ * `<txid>.<vout>` (no vout = vout 0).
+ *
+ * An outpoint is shown `<txid>.<vout>`. David, 2026-10-08: "Outpoints are
+ * always to be shown in the txid.vout format, not underscores. The ONLY
+ * remnant of underscores is for legacy tokenIds".
+ *
+ * The wallet's BRC-207 module's asset id, 1sat-sdk's `OneColor` string id and
+ * the exchange's own filings take the same `<txid>_<vout>` (`sdkTokenId`); the
+ * module's baskets name it by its asset tag, `p color <txid>v<vout>`
+ * (src/wallet/color.ts); the Zig programs' outpoint fields
+ * (amm-lookup's `{outpoint}`, the relay's) and the LP key derivations keep
+ * `<txid>_<vout>` as before.
+ */
+export interface TokenRef {
+    /** 64 lowercase hex, display order. */
+    txid: string;
+    vout: number;
+}
+/** Any token id form (`<txid>`, `<txid>_<vout>`, `<txid>.<vout>`) → its deploy outpoint; null for anything else. */
+export declare function parseTokenId(text: string): TokenRef | null;
+/** An outpoint (`<txid>.<vout>` or `<txid>_<vout>`) → txid and vout; null for anything else. */
+export declare function parseOutpoint(text: string): TokenRef | null;
+/** BRC-207's two lookup queries (wallet/0207.md "Overlay spendability contract"). */
+export type Brc207Type = "color-spendability" | "color-admission";
+/** A BRC-24 lookup request: its service and query. */
+export interface LookupRequest {
+    service: string;
+    query: Record<string, unknown>;
+}
+/**
+ * A BRC-207 query for outpoints of token `tokenId` at a token instance (0.20.1): service
+ * `ls_color_<assetId>`, topic `tm_color_<assetId>`, exactly BRC-207's shape. A token instance
+ * serves no `ls_color`.
+ */
+export declare function colorQuery(type: Brc207Type, tokenId: string, outpoints: string[]): LookupRequest;
+/** The discovery lookup (0.20.0): `ls_color`, color-lookup over the discovery topic `tm_color`. */
+export declare const DISCOVERY_LOOKUP = "ls_color";
+/**
+ * A token's deploy asked of the discovery lookup (0.20.1; David, 2026-10-29: BRC-207's form):
+ * `{service: "ls_color", query: {type: "color-admission", version: 1, assetId: "<txid>_<vout>",
+ * topic: "tm_color", outpoints: ["<txid>.<vout>"]}}` — the token id IS the deploy's outpoint.
+ */
+export declare function deployQuery(tokenId: string): LookupRequest;
+/** The token id of a deploy outpoint: `<txid>_<vout>`, `_0` included (BRC-162 "Token identification"). */
+export declare function tokenIdText(ref: TokenRef): string;
+/**
+ * The token id a 1Color output names by its BRC-162 wire id (internal byte
+ * order): 32 bytes is `<txid>_0`, 36 bytes (a legacy BRC-161 token at
+ * vout > 0) `<txid>_<vout>`; as 1sat-sdk's `OneColor` prints it.
+ */
+export declare function tokenIdOfWire(idBytes: Uint8Array | number[]): string;
+/** Any token id form → the token id string, `<txid>_<vout>` (a `<txid>` as `<txid>_0`): the form shown and the BRC-207 asset id (the module's receipts, `OneColor`'s string id). */
+export declare function sdkTokenId(text: string): string;
+/** Whether two token id strings, in any form, name the same token. */
+export declare function sameToken(a: string, b: string): boolean;
+/** An outpoint for display: `<txid>.<vout>`; anything that is not an outpoint as given. */
+export declare function outpointText(op: string): string;
+/** An outpoint shortened for display (the txid to its first and last 8, as skein-1color 0.7.4 shows ids): `abcdef01…456789ab.0`. */
+export declare function shortOutpoint(op: string): string;
+/** A token id shortened for display, in the form it is written: `abcdef01…456789ab_0`; a bare txid (not a token id) as `abcdef01…456789ab`. */
+export declare function shortTokenId(id: string): string;