@dcasegr/amm-client 0.41.1 → 0.42.3

package/README.md

@@ -72,7 +72,13 @@ The client (each an async function unless noted):
   every sats row: txid, amount, BEEF, submit), `moveBackStagedSats` (the sats alone), `sendTokens`;
 - settings (root): `deployBeef`, `enableToken`, `tokensToEnable`, `disableToken`, `defaults`,
   `setDefaultTerms`, `clearDefaultTerms`, `setDefaultMarket`, `clearDefaultMarket`, `tokenTerms`,
-  `setTokenTerms` (0.40.0: the terms `{lpBps, validatorBps, commissionBps, minLegSats?}`), `discoveryState`, `setDiscovery`.
+  `setTokenTerms` (0.40.0: the terms `{lpBps, validatorBps, commissionBps, minLegSats?}`), `discoveryState`, `setDiscovery`,
+  `setEnablePrice`, `exchangeWallet`, `withdrawAll`, `settleWithdrawals` (0.42.x);
+- the paid enable (0.42.2, anyone signed; open-exchange 0.15.3): `enableTokenPaid(tokenId, {deployBeef?})` — the price
+  from `/amm/defaults`, a BRC-29 payment to the exchange built as a protected noSend (0.42.3: BRC-177, `p nosend expiry seconds 600`; not sent: the exchange's take-in sends it),
+  ONE BEEF with the deploy and the payment, `POST /amm/enable?tokenId=&paymentTxid=&paymentVout=&derivationPrefix=
+  &derivationSuffix=` signed; the enabled row back; on any refusal or failure the unsent payment is aborted
+  (`abortAction`). Refusals are `ClientError` kind `refused`, the exchange's code first in the message.
 
 Pure helpers beside it: `hostedFrom`, `parsePoolEventMessage`, `poolViews`, `poolFees`, `poolsWithMinimums`, `pairPrice`, `legCarrySats`, `hasTerms`,
 `enableCandidates`, `topicOf`, `lookupOf`, `ammLookupOf`, `walletDeployBeef`, `exchangeBase`,

package/dist/client.d.ts

@@ -45,7 +45,7 @@ import { type WalletInterface } from "@bsv/sdk";
 import { type Send1ColorResult } from "@1sat/actions";
 import { type Leg, type PoolState, type Plan, type PricePair } from "@dcasegr/amm-engine";
 import { type Candle, type CandleSeries, type CandleTf, type PoolAt, type PoolHistoryPage, type SpendAll, type Holders, type TokenPosition, type TokenStats, type Trade, type TradesPage, type PoolRow, type PoolsAnswer, type PoolEventMessage, type SignedFetch } from "./lib/overlay.js";
-import { type Defaults, type Discovery, type EnabledToken, type ListedToken } from "./lib/skein.js";
+import { type Defaults, type Discovery, type EnabledToken, type ExchangeWallet, type ListedToken } from "./lib/skein.js";
 import type { AuthFetchLike } from "./market/relay.js";
 import { type MovedBack } from "./market/activeSwap.js";
 import { type PositionRow } from "./lp/positions.js";
@@ -308,7 +308,7 @@ export interface RegisteredToken {
     icon?: string;
     status: EnabledToken["status"];
 }
-export type { EnabledToken, Defaults, Discovery, PoolRow, PoolsAnswer, Candle, CandleSeries, CandleTf, Holders, PoolAt, PoolHistoryPage, SpendAll, TokenPosition, TokenStats, Trade, TradesPage };
+export type { EnabledToken, Defaults, Discovery, ExchangeWallet, PoolRow, PoolsAnswer, Candle, CandleSeries, CandleTf, Holders, PoolAt, PoolHistoryPage, SpendAll, TokenPosition, TokenStats, Trade, TradesPage };
 export type { PoolEvent, PoolEventMessage, PoolRevert } from "./lib/overlay.js";
 export type { Price } from "./lib/overlay.js";
 export { parsePoolEventMessage } from "./lib/overlay.js";
@@ -391,6 +391,8 @@ export interface EnableCandidate {
     onDiscovery: boolean;
     inWallet: boolean;
 }
+/** 0.42.3: the paid enable's payment is a protected noSend (BRC-177): the wallet reclaims it if nobody sends it within 600 s. */
+export declare const ENABLE_PAYMENT_EXPIRY_LABEL = "p nosend expiry seconds 600";
 /**
  * The candidates to enable: discovery's token list (its order, newest first, with its metadata),
  * then the tokens only this wallet holds (in the order held); every token already on the swap
@@ -591,6 +593,22 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
         clearDefaultMarket: () => Promise<void>;
         discoveryState: () => Promise<Discovery>;
         setDiscovery: (on: boolean) => Promise<void>;
+        setEnablePrice: (sats: number | null) => Promise<void>;
+        exchangeWallet: () => Promise<ExchangeWallet>;
+        withdrawAll: () => Promise<{
+            n: number;
+            txid: string;
+            sats: number;
+            at: number;
+            outputIndex: number;
+            derivationPrefix: string;
+            derivationSuffix: string;
+            senderIdentityKey: string;
+        }>;
+        enableTokenPaid: (tokenId: string, o?: {
+            deployBeef?: number[];
+        } | undefined) => Promise<EnabledToken & Record<string, unknown>>;
+        settleWithdrawals: () => Promise<string[]>;
     };
     onDataChange: (fn: () => void) => () => void;
     forgetReads: () => void;
@@ -675,4 +693,20 @@ declare function makeClient(opts: ClientOptions, s: Shared): {
     clearDefaultMarket: () => Promise<void>;
     discoveryState: () => Promise<Discovery>;
     setDiscovery: (on: boolean) => Promise<void>;
+    setEnablePrice: (sats: number | null) => Promise<void>;
+    exchangeWallet: () => Promise<ExchangeWallet>;
+    withdrawAll: () => Promise<{
+        n: number;
+        txid: string;
+        sats: number;
+        at: number;
+        outputIndex: number;
+        derivationPrefix: string;
+        derivationSuffix: string;
+        senderIdentityKey: string;
+    }>;
+    enableTokenPaid: (tokenId: string, o?: {
+        deployBeef?: number[];
+    } | undefined) => Promise<EnabledToken & Record<string, unknown>>;
+    settleWithdrawals: () => Promise<string[]>;
 };

package/dist/client.js

@@ -41,13 +41,14 @@
  * an outpoint is `<txid>.<vout>`. Amounts are bigints in base units; prices
  * are numbers: sats per whole token.
  */
-import { Beef, Transaction } from "@bsv/sdk";
+import { Beef, Transaction, createNonce } from "@bsv/sdk";
+import { BRC29_PROTOCOL, WALLET_PAYMENT, p2pkhHexOf } from "./wallet/brc29.js";
 import { send1Color } from "@1sat/actions";
 import { nextLeg, priceOf } from "@dcasegr/amm-engine";
 import { outpointText, parseOutpoint, parseTokenId, sdkTokenId, tokenIdText } from "./lib/tokenId.js";
 import { DEFAULT_FEE_RATE_SATS_PER_KB, appName, exchangeBase, tokenBase } from "./lib/config.js";
 import { ammLookupService, liveOfPools, parseTokenTopic, poolOutputOf, readDiscoveryDeploy, readDiscoveryIds, readDiscoveryList, readAllPositions, readAllStats, readCandles, readHolders, readPoolHistory, readPoolsAt, readPoolsBeef, readPools, readPositions, readSpendsAll, readStats, readTerms, readTrade, readTrades, readTx, eventsUrl, watchPoolEvents as watchFeed, } from "./lib/overlay.js";
-import { authFetchPerInstance, instanceBase, readDefaults, readDiscovery, readTokens, sendMessage } from "./lib/skein.js";
+import { authFetchPerInstance, instanceBase, readDefaults, readDiscovery, readTokens, readWallet, sendMessage } from "./lib/skein.js";
 import { depthOf } from "./market/prices.js";
 import { buildPlanRequest, legMinerFeeSats, quote as planQuote } from "./market/plan.js";
 import { prepareSwap, selectLegInputs } from "./market/swapAction.js";
@@ -211,6 +212,8 @@ export async function walletDeployBeef(wallet, tokenId) {
     }
     return undefined;
 }
+/** 0.42.3: the paid enable's payment is a protected noSend (BRC-177): the wallet reclaims it if nobody sends it within 600 s. */
+export const ENABLE_PAYMENT_EXPIRY_LABEL = "p nosend expiry seconds 600";
 const canonicalId = (tokenId) => {
     const ref = parseTokenId(tokenId);
     return ref ? tokenIdText(ref) : null;
@@ -1286,6 +1289,162 @@ function makeClient(opts, s) {
     async function clearDefaultMarket() {
         await sendDefaults({ market: null });
     }
+    /**
+     * Sets the price to enable a token (0.42.0, open-exchange 0.15.0): the admin's `{fn: "price", args: {sats}}`
+     * to swap's `<app>/admin`; the host sets it as the price of `POST /amm/enable` (any signed sender enables a
+     * token for it). `null` turns the paid enable off. Refused here unless a whole number of sats, 1 or more.
+     */
+    async function setEnablePrice(sats) {
+        if (sats !== null && (!Number.isSafeInteger(sats) || sats < 1))
+            throw new Error("sats: a whole number, 1 or more (or null: off)");
+        const { signedFor } = needWallet();
+        const me = await swapIdentity();
+        await sendMessage(signedFor(swapBase), swapBase, me, `${app()}/admin`, { fn: "price", args: { sats } });
+        emit();
+    }
+    /** The exchange's wallet (0.42.0, open-exchange 0.15.0; `GET <swap>/wallet`, the host's read): the sats swap's wallet holds and its coin count. */
+    async function exchangeWallet() {
+        return readWallet(swapBase, ff);
+    }
+    /**
+     * Enables a token for the exchange's fee (0.42.2, open-exchange 0.15.3: a BEEF submission; anyone signed, not the
+     * admin): the price from `GET <swap>/defaults` (`enablePriceSats`; none → refused, "paid enable is off"); the
+     * exchange's identity from `GET <swap's origin>/.well-known/skein`; the deploy's BEEF given, else discovery's
+     * (`GET <origin>/@discovery/1color/<token>/deploy`). The payment, ts-stack's standard (sdk BasicBRC29): a prefix and
+     * a suffix from `createNonce`, the payee key `getPublicKey({protocolID: [2, "3241645161d8"], keyID: "<prefix>
+     * <suffix>", counterparty: <the exchange>})`, ONE P2PKH output of exactly the price, `createAction` with
+     * `{noSend: true, randomizeOutputs: false}` and the BRC-177 label `ENABLE_PAYMENT_EXPIRY_LABEL` (0.42.3: a protected
+     * noSend — the wallet prefunds an exact anchor and stores the payment, no change; a plain noSend lived only in the
+     * toolbox's client-side batch, so the payer's storage never learned of it) — built and signed, NOT sent: the
+     * exchange's take-in sends it; a wallet whose storage has no BRC-177 fails the createAction (surfaced). Then ONE
+     * BEEF merging the deploy's and the payment's, `POST <swap>/enable?tokenId=&paymentTxid=&paymentVout=0
+     * &derivationPrefix=&derivationSuffix=` signed (BRC-104). On any refusal or failure after the payment was built, the
+     * unsent payment is aborted in the wallet (`abortAction`), so its coins are free again. → the enabled row.
+     * Refusals are `ClientError` kind `refused` (the exchange's code first in the message); a fetch that does not get
+     * through, `network`; the user declining in the wallet, `user_rejected`.
+     */
+    async function enableTokenPaid(tokenId, o = {}) {
+        const { wallet, signedFor } = needWallet();
+        const id = parseOutpoint(sdkTokenId(tokenId).replace("_", "."));
+        if (!id)
+            throw new Error(`not a token id: ${tokenId}`);
+        const canonical = tokenIdText(id);
+        const price = (await readDefaults(swapBase, freshFetch)).enablePriceSats;
+        if (!price)
+            throw new ClientError("refused", "paid enable is off");
+        const exchange = await swapIdentity();
+        let deploy = o.deployBeef;
+        if (!deploy) {
+            const res = await freshFetch(`${discoveryBase()}/${canonical}/deploy`);
+            if (!res.ok)
+                throw new ClientError("refused", `no deploy for ${canonical} on discovery (${res.status}): pass deployBeef`);
+            deploy = Array.from(new Uint8Array(await res.arrayBuffer()));
+        }
+        const derivationPrefix = await createNonce(wallet, "self");
+        const derivationSuffix = await createNonce(wallet, "self");
+        const { publicKey } = await wallet.getPublicKey({ protocolID: BRC29_PROTOCOL, keyID: `${derivationPrefix} ${derivationSuffix}`, counterparty: exchange });
+        const created = await wallet.createAction({
+            description: "Open Exchange: enable a token",
+            outputs: [{ satoshis: price, lockingScript: p2pkhHexOf(publicKey), outputDescription: "Open Exchange enable fee", customInstructions: JSON.stringify({ derivationPrefix, derivationSuffix, payee: exchange }) }],
+            // 0.42.3: a protected noSend (BRC-177, as @1sat/actions' payment to a handle): the wallet prefunds an exact anchor,
+            // stores the payment in its storage with no change, and reclaims it if nobody sends it in time.
+            labels: [ENABLE_PAYMENT_EXPIRY_LABEL],
+            options: { noSend: true, randomizeOutputs: false },
+        }).catch((e) => {
+            // No fallback to a plain noSend: a wallet that cannot make a protected one (BRC-177) says why.
+            const c = toClientError(e);
+            throw c instanceof ClientError ? c : new ClientError("refused", `the wallet could not build the protected payment (BRC-177 noSend): ${errText(e)}`, { cause: e });
+        });
+        const txid = created.txid;
+        if (!txid || !created.tx)
+            throw new Error("the wallet built no payment");
+        try {
+            const b = new Beef();
+            b.mergeBeef(deploy);
+            b.mergeBeef(created.tx);
+            const q = new URLSearchParams({ tokenId: canonical, paymentTxid: txid, paymentVout: "0", derivationPrefix, derivationSuffix });
+            let res;
+            try {
+                res = await signedFor(swapBase).fetch(`${swapBase}/enable?${q.toString()}`, { method: "POST", headers: { "content-type": "application/octet-stream" }, body: Uint8Array.from(b.toBinary()) });
+            }
+            catch (e) {
+                // The stock AuthFetch takes every 402 for its own payment wire and throws on this route's (no x-bsv-payment-* headers).
+                if (/x-bsv-payment/.test(errText(e)))
+                    throw new ClientError("refused", "ERR_PAYMENT_REQUIRED: the exchange did not take this payment (402; its price may have changed)", { cause: e });
+                throw e;
+            }
+            const v = (await res.json().catch(() => ({})));
+            if (res.status !== 200)
+                throw new ClientError("refused", `${String(v.code ?? res.status)}: ${String(v.description ?? v.message ?? "refused")}`);
+            s.listRead = null;
+            emit();
+            return v.result;
+        }
+        catch (e) {
+            await wallet.abortAction({ reference: txid }).catch(() => { });
+            throw e;
+        }
+    }
+    /** A withdrawal's payment taken in by the admin's wallet: `internalizeAction`, output `outputIndex` as a wallet payment from swap (BRC-29, ts-stack's recipient side). */
+    async function takeInWithdrawal(wallet, x, tx) {
+        const r = await wallet.internalizeAction({
+            tx,
+            outputs: [{ outputIndex: x.outputIndex, protocol: WALLET_PAYMENT, paymentRemittance: { derivationPrefix: x.derivationPrefix, derivationSuffix: x.derivationSuffix, senderIdentityKey: x.senderIdentityKey } }],
+            description: `Open Exchange withdraw ${x.n}`,
+        });
+        return r.accepted;
+    }
+    /** Withdrawal `n`'s Atomic BEEF (`GET <swap>/wallet/tx?n=`). */
+    async function withdrawalTx(n) {
+        const res = await freshFetch(`${swapBase}/wallet/tx?n=${n}`);
+        if (!res.ok)
+            throw new Error(`GET ${swapBase}/wallet/tx?n=${n}: ${res.status}`);
+        return Array.from(new Uint8Array(await res.arrayBuffer()));
+    }
+    /**
+     * Withdraws everything in the exchange's wallet to the admin's own (0.42.1, open-exchange 0.15.2): the admin's
+     * `{fn: "withdraw"}` to swap's `<app>/admin`. swap's program pays every coin to a BRC-29 key derived for the
+     * sender and hands the transaction over unsent; this function waits for the read to list it (`GET <swap>/wallet`,
+     * at most 10 s — the message's answer reaches no page), then takes it in (`internalizeAction`, a wallet payment:
+     * that is what sends it). → the withdrawal.
+     */
+    async function withdrawAll() {
+        const { wallet, signedFor } = needWallet();
+        const w = await readWallet(swapBase, freshFetch);
+        if (w.sats <= 0)
+            throw new Error("the exchange's wallet holds nothing to withdraw");
+        const me = await swapIdentity();
+        await sendMessage(signedFor(swapBase), swapBase, me, `${app()}/admin`, { fn: "withdraw" });
+        let x;
+        for (let i = 0; i < 40 && !x; i++) {
+            await new Promise((r) => setTimeout(r, 250));
+            x = (await readWallet(swapBase, freshFetch)).withdrawals.find((y) => y.n > w.withdrawals.length);
+        }
+        if (!x)
+            throw new Error("the exchange has not answered the withdraw yet: Settings takes it in when it does");
+        if (!(await takeInWithdrawal(wallet, x, await withdrawalTx(x.n))))
+            throw new Error("the wallet did not accept the withdrawal");
+        emit();
+        return x;
+    }
+    /**
+     * The latest withdrawal taken in again (0.42.1; on Settings load): for a page lost between the withdraw's answer
+     * and its take-in (taking in a payment the wallet holds is harmless). Never throws. → its txid, or none.
+     */
+    async function settleWithdrawals() {
+        if (!boundWallet)
+            return [];
+        try {
+            const w = await readWallet(swapBase, freshFetch);
+            const x = w.withdrawals.at(-1);
+            if (!x)
+                return [];
+            return (await takeInWithdrawal(boundWallet, x, await withdrawalTx(x.n))) ? [x.txid] : [];
+        }
+        catch {
+            return [];
+        }
+    }
     /** The discovery instance's record (0.18.0, shruggr/skein#137; `GET <config>/discovery`): `{on: false}` until root turns it on. */
     async function discoveryState() {
         return readDiscovery(swapBase, ff);
@@ -1370,5 +1529,10 @@ function makeClient(opts, s) {
         clearDefaultMarket: guard(clearDefaultMarket),
         discoveryState: guard(discoveryState),
         setDiscovery: guard(setDiscovery),
+        setEnablePrice: guard(setEnablePrice),
+        exchangeWallet: guard(exchangeWallet),
+        withdrawAll: guard(withdrawAll),
+        enableTokenPaid: guard(enableTokenPaid),
+        settleWithdrawals,
     };
 }

package/dist/lib/skein.d.ts

@@ -73,7 +73,27 @@ export interface Defaults {
     market?: {
         minCommissionBps: number;
     };
+    /** 0.42.0 (open-exchange 0.15.0): the price in sats to enable a token on `POST /amm/enable`, present when the admin set one. */
+    enablePriceSats?: number;
 }
+/** The exchange's wallet (0.42.0, open-exchange 0.15.0; `GET <swap>/wallet`, the host's read of swap's wallet): its sats and coin count. */
+export interface ExchangeWallet {
+    sats: number;
+    outputs: number;
+    /** The admin's withdrawals, each kept by the swap app once proven; n counts from 1. */
+    withdrawals: {
+        n: number;
+        txid: string;
+        sats: number;
+        at: number;
+        outputIndex: number;
+        derivationPrefix: string;
+        derivationSuffix: string;
+        senderIdentityKey: string;
+    }[];
+}
+/** `GET <swap>/wallet`: `{sats, outputs, withdrawals}`. */
+export declare function readWallet(base: string, fetchFn?: typeof fetch): Promise<ExchangeWallet>;
 /** 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;

package/dist/lib/skein.js

@@ -122,6 +122,19 @@ export async function readTokens(base, fetchFn = fetch) {
         since: typeof t.since === "number" ? t.since : 0,
     }));
 }
+/** `GET <swap>/wallet`: `{sats, outputs, withdrawals}`. */
+export async function readWallet(base, fetchFn = fetch) {
+    const a = (await getJson(`${base}/wallet`, fetchFn));
+    const ws = Array.isArray(a?.withdrawals) ? a.withdrawals : [];
+    return {
+        sats: typeof a?.sats === "number" ? a.sats : 0,
+        outputs: typeof a?.outputs === "number" ? a.outputs : 0,
+        withdrawals: ws.filter((w) => typeof w.n === "number" && typeof w.txid === "string").map((w) => ({
+            n: w.n, txid: w.txid, sats: Number(w.sats ?? 0), at: Number(w.at ?? 0), outputIndex: Number(w.outputIndex ?? 0),
+            derivationPrefix: String(w.derivationPrefix ?? ""), derivationSuffix: String(w.derivationSuffix ?? ""), senderIdentityKey: String(w.senderIdentityKey ?? ""),
+        })),
+    };
+}
 /** `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));
@@ -138,5 +151,7 @@ export async function readDefaults(base, fetchFn = fetch) {
     const m = a?.market;
     if (m && typeof m.minCommissionBps === "number")
         out.market = { minCommissionBps: m.minCommissionBps };
+    if (typeof a?.enablePriceSats === "number" && a.enablePriceSats > 0)
+        out.enablePriceSats = a.enablePriceSats;
     return out;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dcasegr/amm-client",
-  "version": "0.41.1",
+  "version": "0.42.3",
   "type": "module",
   "description": "The Open Exchange client (skein-amm): reads, swap, pool deploy / close / rebalance, move back and positions over a BRC-100 wallet, bound to one exchange by createClient. No React, no styles, no wallet provider.",
   "repository": {
@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@1sat/actions": "0.1.3",
-    "@dcasegr/amm-engine": "0.41.1",
+    "@dcasegr/amm-engine": "0.42.3",
     "cbor2": "^2.3.0"
   },
   "peerDependencies": {