@dcasegr/amm-client 0.39.0 → 0.42.2

package/dist/errors.d.ts

@@ -1,6 +1,6 @@
 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 declare const CLIENT_ERROR_KINDS: readonly ["stale_pool", "fee_mismatch", "quote_mismatch", "slippage", "pool_spent", "user_rejected", "no_answer", "below_minimum", "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 {

package/dist/errors.js

@@ -15,13 +15,16 @@
  *                   `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)
+ *   below_minimum   (0.40.0) under a validator's minimum leg (its `below_minimum` refusal; a quote no
+ *                   pool takes for its size)
+ *   refused         the validator, the relay or the host refused it (a refusal other than pool_spent
+ *                   and below_minimum)
  *   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"];
+export const CLIENT_ERROR_KINDS = ["stale_pool", "fee_mismatch", "quote_mismatch", "slippage", "pool_spent", "user_rejected", "no_answer", "below_minimum", "refused", "network"];
 /** An error of a named kind; `message` is the text the pages show. */
 export class ClientError extends Error {
     kind;
@@ -65,7 +68,7 @@ export function kindOfOutcome(o) {
         case "accepted":
             return undefined;
         case "refused":
-            return o.reason.startsWith("pool_spent") ? "pool_spent" : "refused";
+            return o.reason.startsWith("pool_spent") ? "pool_spent" : o.reason.startsWith("below_minimum") ? "below_minimum" : "refused";
         case "timeout":
         case "unknown":
             return "no_answer";

package/dist/index.d.ts

@@ -15,11 +15,23 @@ export { SWAP_BASKET } from "./wallet/color.js";
 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). */
+/** A staged `amm-swap` row's keyID (0.40.0): `amm-swap-<16 random bytes, hex>`. */
+export { newSwapKeyID } from "./market/activeSwap.js";
+/** The label of a staging action that carries tokens (`amm-swap-stage`, 0.40.0). */
+export { SWAP_STAGE_LABEL } from "./market/activeSwap.js";
+/** The marker a staged token output's description ends with (` · amm-swap <hex>`): it names the key id. */
+export { SWAP_KEY_MARK } from "./market/activeSwap.js";
+/** A staged token output's description: the readable text, then `SWAP_KEY_MARK` and the keyID's hex. */
+export { swapKeyDescription } from "./market/activeSwap.js";
+/** The keyID a staged token output's description names, or null. */
+export { swapKeyIdOfDescription } from "./market/activeSwap.js";
+/** The keyID of a leg's change kept in `amm-swap`: `amm-swap-<txid>.<vout>:change`, the leg's first input of that kind. */
+export { changeKeyID } from "./market/swapAction.js";
+/** An order's payout, own-commission and last-leg change derivation: from the order's key input. */
+export { legDerivation } from "./market/swapAction.js";
+/** customInstructions of an `amm-swap` token row (asset, amount, the key that spends it; a change row's `order`). */
 export { swapInstructions } from "./wallet/color.js";
-/** customInstructions of an `amm-swap` sats row (`sats: true`, the token it was staged for, its key). */
+/** customInstructions of an `amm-swap` sats row (`sats: true`, its key; a change row's `order`). */
 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";

package/dist/index.js

@@ -17,11 +17,23 @@ export { SWAP_BASKET } from "./wallet/color.js";
 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). */
+/** A staged `amm-swap` row's keyID (0.40.0): `amm-swap-<16 random bytes, hex>`. */
+export { newSwapKeyID } from "./market/activeSwap.js";
+/** The label of a staging action that carries tokens (`amm-swap-stage`, 0.40.0). */
+export { SWAP_STAGE_LABEL } from "./market/activeSwap.js";
+/** The marker a staged token output's description ends with (` · amm-swap <hex>`): it names the key id. */
+export { SWAP_KEY_MARK } from "./market/activeSwap.js";
+/** A staged token output's description: the readable text, then `SWAP_KEY_MARK` and the keyID's hex. */
+export { swapKeyDescription } from "./market/activeSwap.js";
+/** The keyID a staged token output's description names, or null. */
+export { swapKeyIdOfDescription } from "./market/activeSwap.js";
+/** The keyID of a leg's change kept in `amm-swap`: `amm-swap-<txid>.<vout>:change`, the leg's first input of that kind. */
+export { changeKeyID } from "./market/swapAction.js";
+/** An order's payout, own-commission and last-leg change derivation: from the order's key input. */
+export { legDerivation } from "./market/swapAction.js";
+/** customInstructions of an `amm-swap` token row (asset, amount, the key that spends it; a change row's `order`). */
 export { swapInstructions } from "./wallet/color.js";
-/** customInstructions of an `amm-swap` sats row (`sats: true`, the token it was staged for, its key). */
+/** customInstructions of an `amm-swap` sats row (`sats: true`, its key; a change row's `order`). */
 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";

package/dist/lib/overlay.d.ts

@@ -15,7 +15,9 @@ export declare function ammLookupService(tokenId: string): string;
 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 {
+    poolId?: string;
     lpPubKey?: string;
+    swaps?: number | string;
     outpoint: string;
     bsvReserve: number | string;
     tokenReserve: number | string;
@@ -28,9 +30,13 @@ interface WirePool {
 }
 /** 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. */
+/** A pool of the pools routes: the engine's PoolState, its id (0.40.0: the deploy outpoint `<txid>_<vout>`), its LP key, its swap count, and (P2) its validator's peer ID. */
 export interface PoolRow extends PoolState {
+    /** The pool's id: its deploy outpoint, `<txid>_<vout>` (0.40.0). */
+    poolId: string;
     lpPubKey: string;
+    /** The pool's swaps so far (0 at the deploy). */
+    swaps: number;
     /** P2: the validator's libp2p peer ID, from its beat (what the relay dials). */
     validatorPeerId?: string;
     /** P1: the token. */
@@ -43,10 +49,11 @@ 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. */
+/** A validator beating on the token's topic now (P2's `validators`, 0.34.1): its identity key and libp2p peer ID; 0.40.0, the minimum leg its terms announce (sats on the leg's sats side; absent: none). */
 export interface BeatingValidator {
     identity: string;
     peerId: string;
+    minLegSats?: bigint;
 }
 /** 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 {
@@ -87,43 +94,35 @@ export interface SignedFetch {
 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`). */
+/** P2: the token's pools as the host lists them now (0.41.0: a plain read only). */
 export declare function readPools(base: string, fetchFn?: FetchFn): Promise<PoolsAnswer>;
-/** What `watchPools` needs of the browser's `EventSource` (tests pass a fake). */
+/** What `watchPoolEvents` 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;
+/** E1's URL: `<base>/events` (a token instance's app base: that token's; the swap app's: every token's). */
+export declare function eventsUrl(base: string): string;
 /**
- * Holds a pools route as an event stream (D16; 0.39.0, D7): `GET <url>` with `Accept:
- * text/event-stream` (the browser's EventSource sends it). The event `pools` carries the whole
- * answer (first the current one; again when the host cannot say what changed): it replaces the held
- * answer. With `change` (P2), the event `change` carries one pool change: `change(held, x)` applies
- * it to the held answer (null: it cannot); one it cannot apply (no answer held yet, an unknown
- * kind, a row it names not held) → the route is read again ONCE (a plain GET) and that answer is
- * held (changes arriving while it is read are dropped: the answer read is the newer state). Each
- * new held answer goes to `onAnswer`. Without an EventSource (an old browser, a test): ONE plain
- * GET, no poll. → the unsubscribe.
+ * Listens to a host's pool event feed (E1, 0.41.0): each `pool` message parsed
+ * (`parsePoolEventMessage`) to `onEvent`; one it cannot parse is passed over. Reconnecting is the
+ * browser's EventSource's. Without an EventSource: nothing. → the unsubscribe.
  */
-export declare function watchPools<T>(url: string, parse: (x: unknown) => T, onAnswer: (a: T) => void, o?: {
+export declare function watchPoolEvents(url: string, onEvent: (e: PoolEventMessage) => void, o?: {
     onError?: (e: unknown) => void;
-    onOpen?: () => void;
     EventSource?: EventSourceCtor | null;
-    fetch?: FetchFn;
-    change?: (held: T, x: unknown) => T | null;
 }): () => void;
-/** P3's answer: the LP keys' current pools and one BEEF of their transactions. */
+/** P3's answer: the pools' current outputs 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>;
+/** P3: `GET <base>/pools/beef?pool=id1,id2` (0.40.0: by pool id; no `poolIds`: every live pool). */
+export declare function readPoolsBeef(base: string, poolIds?: 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[];
@@ -131,9 +130,12 @@ export interface LookupOutput {
 }
 /** 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`. */
+/** One pool's state and fees (P4, 0.40.0: by pool id): `live` (its live output), `rescinded` (the validator's Rescind wrote `outpoint`: the LP's Close takes it back), `closed`. */
 export interface LpPool {
-    lpPubKey: string;
+    /** The pool's id, `<txid>_<vout>` (its deploy outpoint). */
+    poolId: string;
+    /** Its LP key (null for an id this instance does not know). */
+    lpPubKey: string | null;
     status: "live" | "rescinded" | "closed";
     /** The output a Close acts on, `<txid>_<vout>` (live and rescinded). */
     outpoint: string | null;
@@ -145,16 +147,18 @@ export interface LpPool {
     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[]>;
+/** P4: `GET <base>/positions?pool=id1,id2` (0.40.0) → one record per pool id in the same order. */
+export declare function readPositions(base: string, poolIds: 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 {
+    /** 0.40.0: `minLegSats` the minimum leg (sats on the leg's sats side), 0 = none. */
     validator: {
         identity: string;
         peerId: string | null;
         lpFeeBps: number;
         validatorFeeBps: number;
         commissionBps: number;
+        minLegSats: number;
     } | null;
     market: Market;
 }
@@ -201,7 +205,11 @@ export interface Price {
 /** A Swap's trade row (H1; the `swap` change's `trade`): amounts in base units, fees in the input asset, the pool's reserves after it. */
 export interface Trade {
     txid: string;
+    /** The pool's id, `<txid>_<vout>` (0.40.0). */
+    poolId: string;
     lpPubKey: string;
+    /** The hash160 (hex) the payout went to (the call's `userPkh`, 0.40.0): an order's legs share it. */
+    payoutPkh: string;
     /** `buy`: sats in, tokens out; `sell`: tokens in. */
     side: "buy" | "sell";
     amountIn: bigint;
@@ -237,8 +245,17 @@ export type CandleTf = "1m" | "5m" | "15m" | "1h" | "4h" | "1d";
 /** A token at the read's time (H3, H4): the changes in bps (null without a trade at or before the window's start). */
 export interface TokenStats {
     tokenId: string;
-    /** The last trade's, else the deepest live pool's, else null. */
+    /**
+     * 0.40.0 (the host's): the midpoint of what a buy and a sell of 1% of the pooled sats would pay
+     * now (the engine's `priceOf(listed pools).mid`), null with no pool.
+     */
     price: Price | null;
+    /** What that buy would pay (sats per tokens), null with no pool. */
+    buyPrice: Price | null;
+    /** What that sell would pay, null with no pool. */
+    sellPrice: Price | null;
+    /** The last trade's price, null without one. */
+    lastTradePrice: Price | null;
     change1h: number | null;
     change24h: number | null;
     volume24hSats: bigint;
@@ -262,44 +279,28 @@ export interface Holders {
 export interface TokenPosition extends LpPool {
     tokenId: string;
 }
-/** One pool change on P2's stream (event `change`, D7). */
-export interface PoolChange {
-    kind: "deploy" | "swap" | "close" | "rescind";
-    /** The new pool output (deploy, swap) or the one gone (close, rescind). */
-    outpoint: string;
-    /** deploy, swap: the pool's row. */
-    pool?: PoolRow;
-    /** swap: its trade row. */
-    trade?: Trade;
-}
 /** A trade row, or null when it is not one. */
 export declare function toTrade(x: unknown): Trade | null;
 /** A stats record (H3), or null when it is not one. */
 export declare function toStats(x: unknown): TokenStats | null;
-/** A `change` event's data, or null when it is not one this client knows. */
-export declare function parseChange(x: unknown): PoolChange | null;
-/**
- * One `change` applied to a held P2 answer (D7) → the new answer, or null when it cannot be applied
- * (the caller reads the route again): `swap` — the row of `trade.lpPubKey` replaced by `pool` (its
- * outpoint moved); `deploy` — `pool` added; `close` / `rescind` — the row at `outpoint` removed.
- * The market and the validators are kept (a change of either comes as a whole `pools` answer).
- */
-export declare function applyPoolChange(held: PoolsAnswer, x: unknown): PoolsAnswer | null;
-/** H1: `GET <base>/trades?from=&to=&limit=&before=&lp=` → the page, newest first. */
+/** H1: `GET <base>/trades?from=&to=&limit=&before=&pool=` (0.40.0: `pool` one pool's) → the page, newest first. */
 export declare function readTrades(base: string, o?: {
     from?: number;
     to?: number;
     limit?: number;
     before?: string;
-    lp?: string;
+    pool?: string;
 }, fetchFn?: FetchFn): Promise<TradesPage>;
 /** H1 with `txid`: one Swap's trade row; null when the transaction has none (404). */
 export declare function readTrade(base: string, txid: string, fetchFn?: FetchFn): Promise<Trade | null>;
-/** H2: `GET <base>/candles?tf=&from=&to=` → one candle per non-empty bucket, oldest first. */
+/** The candle series (0.40.0): `fill` the trades' prices (the instance's), `market` the price after each pool event (the host's). */
+export type CandleSeries = "fill" | "market";
+/** H2: `GET <base>/candles?tf=&from=&to=&series=` → one candle per non-empty bucket, oldest first. */
 export declare function readCandles(base: string, o: {
     tf: CandleTf;
     from: number;
     to: number;
+    series?: CandleSeries;
 }, fetchFn?: FetchFn): Promise<Candle[]>;
 /** H3: `GET <base>/stats`. */
 export declare function readStats(base: string, fetchFn?: FetchFn): Promise<TokenStats>;
@@ -310,6 +311,87 @@ export declare function readHolders(base: string, tokenId: string, o?: {
     limit?: number;
     skip?: number;
 }, fetchFn?: FetchFn): Promise<Holders>;
-/** H5: `GET <swap base>/positions?lp=k1,k2` → every enabled token's rows for the keys, each with its token. */
-export declare function readAllPositions(swapBase: string, lpPubKeys: string[], fetchFn?: FetchFn): Promise<TokenPosition[]>;
+/** H5: `GET <swap base>/positions?pool=id1,id2` (0.40.0) → every enabled token's rows for the pools, each with its token. */
+export declare function readAllPositions(swapBase: string, poolIds: string[], fetchFn?: FetchFn): Promise<TokenPosition[]>;
+/** A pool as it was listed at a time (H7): its id, output, reserves, keys, rates, the event's time and its swap count. */
+export interface PoolAt extends PoolRow {
+    /** The time of the pool's last event at or before the read's `t`, ms. */
+    at: number;
+}
+/** H7: `GET <base>/pools/at?t=<ms>` → every pool listed at `t`. */
+export declare function readPoolsAt(base: string, t: number, fetchFn?: FetchFn): Promise<PoolAt[]>;
+/** One event of a pool's history (H8): a deploy, a swap (with its trade fields), a close or a rescind, at the admitting step's time. */
+export interface PoolEvent {
+    kind: "deploy" | "swap" | "close" | "rescind";
+    txid: string;
+    poolId: string;
+    /** The pool's output after the event (deploy, swap, rescind), `<txid>_<vout>`. */
+    outpoint?: string;
+    bsvReserve?: bigint;
+    tokenReserve?: bigint;
+    lpPubKey: string;
+    liquidityFeeBps: bigint;
+    validationFeeBps: bigint;
+    commissionBps: bigint;
+    validatorIdentityKey: string;
+    at: number;
+    swaps: number;
+    /** A swap's trade. */
+    side?: "buy" | "sell";
+    amountIn?: bigint;
+    amountOut?: bigint;
+    feeLp?: bigint;
+    feeValidator?: bigint;
+    feeCommission?: bigint;
+    commissionPkh?: string;
+    payoutPkh?: string;
+}
+/** H8's page: the events oldest first, `next` the cursor to pass as `after` for the page after (null: none left). */
+export interface PoolHistoryPage {
+    events: PoolEvent[];
+    next: string | null;
+}
+/**
+ * A revert (0.41.0): an admitted transaction later rejected — `txid` the rejected transaction, `at`
+ * the step's time, and the pool as it stands after the undo (its outpoint, reserves, fields,
+ * `swaps`), or none of those when the pool no longer exists.
+ */
+export interface PoolRevert {
+    kind: "revert";
+    txid: string;
+    poolId: string;
+    at: number;
+    outpoint?: string;
+    bsvReserve?: bigint;
+    tokenReserve?: bigint;
+    lpPubKey?: string;
+    liquidityFeeBps?: bigint;
+    validationFeeBps?: bigint;
+    commissionBps?: bigint;
+    validatorIdentityKey?: string;
+    swaps?: number;
+}
+/** One message of a pool event feed (E1, 0.41.0): `{tokenId, …row}`, the row an H8 event or a revert. */
+export type PoolEventMessage = {
+    tokenId: string;
+} & (PoolEvent | PoolRevert);
+/** A pool event feed message's data, or null when it is not one. */
+export declare function parsePoolEventMessage(x: unknown): PoolEventMessage | null;
+/** H8: `GET <base>/pools/history?from=&to=&pool=&limit=&after=` → the page, oldest first. */
+export declare function readPoolHistory(base: string, o?: {
+    from?: number;
+    to?: number;
+    pool?: string;
+    limit?: number;
+    after?: string;
+}, fetchFn?: FetchFn): Promise<PoolHistoryPage>;
+/** One outpoint's spender as the host's H9 answers it: the token whose instance named it. */
+export interface SpendAll {
+    /** `<txid>.<vout>` */
+    outpoint: string;
+    tokenId?: string;
+    spentBy?: string;
+}
+/** H9: `GET <swap base>/spends?outpoint=a,b` (the host's: every enabled token's `/spends`, the first naming a spender) → one record per outpoint. */
+export declare function readSpendsAll(swapBase: string, outpoints: string[], fetchFn?: FetchFn): Promise<SpendAll[]>;
 export {};