@dcasegr/amm-client 0.38.2 → 0.41.1

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,37 +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 (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.
+ * 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;
 }): () => 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[];
@@ -125,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;
@@ -139,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;
 }
@@ -187,4 +197,201 @@ export declare function readDiscoveryIds(discovery: string, ids: string[], fetch
 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>;
+/** A price, exact (H1–H4): `sats` satoshis per `tokens` token base units (divide in the caller). */
+export interface Price {
+    sats: bigint;
+    tokens: bigint;
+}
+/** 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;
+    amountOut: bigint;
+    feeLp: bigint;
+    feeValidator: bigint;
+    feeCommission: bigint;
+    bsvReserve: bigint;
+    tokenReserve: bigint;
+    /** The admitting step's time, ms. */
+    at: number;
+    /** The block height where the overlay has the transaction placed, else null. */
+    height: number | null;
+}
+/** H1's page: the trades newest first, `next` the cursor of the page after (null: the last page). */
+export interface TradesPage {
+    trades: Trade[];
+    next: string | null;
+}
+/** One non-empty bucket (H2): its start (ms), the first, highest, lowest and last trade's prices, each side's amounts summed, the trade count. */
+export interface Candle {
+    t: number;
+    o: Price;
+    h: Price;
+    l: Price;
+    c: Price;
+    volumeSats: bigint;
+    volumeTokens: bigint;
+    n: number;
+}
+/** A candle's resolution (H2). */
+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;
+    /**
+     * 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;
+    volume24hTokens: bigint;
+    buys24h: number;
+    sells24h: number;
+    lastTradeAt: number | null;
+    tvlSats: bigint;
+    tvlTokens: bigint;
+    pools: number;
+}
+/** A token's holders (H6): `count` the addresses with a balance, `rows` largest balance first. */
+export interface Holders {
+    count: number;
+    rows: {
+        address: string;
+        balance: bigint;
+    }[];
+}
+/** One LP key's position on one token (H5): P4's record with its token. */
+export interface TokenPosition extends LpPool {
+    tokenId: string;
+}
+/** 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;
+/** 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;
+    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>;
+/** 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>;
+/** H4: `GET <swap base>/stats` (`ids`: those enabled tokens only, in that order) → every enabled token's stats. */
+export declare function readAllStats(swapBase: string, ids?: string[], fetchFn?: FetchFn): Promise<TokenStats[]>;
+/** H6: `GET <token base>/color/<token>/holders?limit=&skip=` → the count and the rows, largest first. */
+export declare function readHolders(base: string, tokenId: string, o?: {
+    limit?: number;
+    skip?: number;
+}, fetchFn?: FetchFn): Promise<Holders>;
+/** 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 {};