@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/lp/positions.js

@@ -0,0 +1,144 @@
+/**
+ * 0.34.0 (D9): the rows are read here; their pools' state and fees come from ONE `GET
+ * /@<token>/amm/positions?lp=k1,k2` per token (src/client.ts `myPositions`), not from
+ * `/spends` per row as below; the pool output's BEEF is read only when the LP acts (Close: `GET
+ * /@<token>/amm/pools/beef?lp=<its key>`).
+ *
+ * The connected wallet's positions (skein-amm 0.9.0, David Case 2026-10-09;
+ * 0.12.0: the rows in the exchange's basket `amm-pools`, no claim): the pool
+ * rows its deploys filed (op `amm-pool`, the LP key in their
+ * customInstructions), each read from the CHAIN STATE by outpoint —
+ * `GET <base>/spends` (amm-p2p reads.zig, the chain app's `spent` as the
+ * overlay reads it): the pool followed from the deploy's output to its
+ * current output (each swap's continuation), or closed (by the LP or by the
+ * validator, docs/AMM.md "The validator's Close").
+ *
+ * 0.29.3: the deploy HISTORY is the first source (`historyPoolRows`): 0.29.4,
+ * each `amm-pool-deploy` action's pool output names its LP keyID in its
+ * description (`… · amm-lp <hex>`) and its script is the pool (no
+ * customInstructions needed: BRC-100's listActions does not answer them). 0.28.0: the rows also come from the wallet's HISTORY (`historyPoolRows`):
+ * `listOutputs` answers spendable outputs only, so a pool output the wallet
+ * itself spent (the LP swapped against its own pool) left no row and the
+ * position vanished; the deploys' actions (label `amm-pool-deploy`) still
+ * carry the output filed in `amm-pools` with its customInstructions. Both
+ * sets, deduped by outpoint, are followed by `/spends` as before.
+ *
+ * The current output's BEEF comes from the token's 1Color lookup
+ * (0.20.1: BRC-207's `color-spendability` at `ls_color_<tokenId>`: the
+ * output if admitted and unspent, with its BEEF; `ls_color {txid,
+ * outputIndex}` until 0.19.0).
+ */
+import { Utils } from "@bsv/sdk";
+import { PoolTemplate } from "../pool/index.js";
+import { parseOutpoint, sdkTokenId, tokenIdOfWire, tokenIdText } from "../lib/tokenId.js";
+import { POOLS_BASKET } from "../wallet/color.js";
+import { POOL_TAG, isPoolRow } from "./poolRows.js";
+import { LP_KEY_PROTOCOL, lpKeyIdOfDescription, poolCustomInstructions } from "./poolDeploy.js";
+/** The label a pool deploy gives its action (src/lp/poolDeploy.ts). */
+export const POOL_DEPLOY_LABEL = "amm-pool-deploy";
+/**
+ * The pool rows of the wallet's deploy actions (0.28.0): every output of an action labelled
+ * `amm-pool-deploy` filed in `amm-pools` as a pool row (tag `amm-pool` or op `amm-pool` in its
+ * customInstructions), spent or not. `listActions` with `includeOutputs` (and, where the wallet
+ * takes it, `includeCustomInstructions`), paged; a wallet that refuses the read: none.
+ */
+export async function historyPoolRows(wallet) {
+    const out = [];
+    const limit = 1000;
+    try {
+        for (let offset = 0; offset < 100_000; offset += limit) {
+            const r = await wallet.listActions({ labels: [POOL_DEPLOY_LABEL], includeOutputs: true, includeOutputLockingScripts: true, includeCustomInstructions: true, limit, offset });
+            for (const a of r.actions ?? []) {
+                for (const o of a.outputs ?? []) {
+                    const outpoint = `${a.txid}.${o.outputIndex}`;
+                    // 0.29.4: the LP keyID from the pool output's description (`… · amm-lp <hex>`), the pool from its script.
+                    const keyID = lpKeyIdOfDescription(o.outputDescription);
+                    const pool = keyID && o.lockingScript ? PoolTemplate.decode(o.lockingScript) : null;
+                    if (pool && keyID) {
+                        const tokenId = sdkTokenId(tokenIdOfWire(Utils.toArray(pool.args.assetId, "hex")));
+                        out.push({
+                            outpoint,
+                            satoshis: o.satoshis,
+                            lockingScript: o.lockingScript,
+                            tags: [POOL_TAG],
+                            customInstructions: poolCustomInstructions({ tokenId, protocolID: LP_KEY_PROTOCOL, keyID, args: pool.args, validatorIdentity: pool.state.validatorIdentity, ...(pool.state.nonce ? { nonce: pool.state.nonce } : {}) }),
+                        });
+                        continue;
+                    }
+                    // A wallet that answers the output's customInstructions (0.28.0): the filed row as it is.
+                    if (o.basket !== POOLS_BASKET)
+                        continue;
+                    const row = { outpoint, satoshis: o.satoshis, ...(o.lockingScript ? { lockingScript: o.lockingScript } : {}), ...(o.tags ? { tags: o.tags } : {}), ...(o.customInstructions ? { customInstructions: o.customInstructions } : {}) };
+                    if (isPoolRow(row))
+                        out.push(row);
+                }
+            }
+            if ((r.actions?.length ?? 0) < limit || offset + limit >= (r.totalActions ?? 0))
+                break;
+        }
+    }
+    catch {
+        /* no history read: the basket's rows alone */
+    }
+    return out;
+}
+/** Rows deduped by outpoint (`<txid>.<vout>`), the first kept (the basket's before the history's). */
+export function mergePoolRows(...sets) {
+    const seen = new Set();
+    const out = [];
+    for (const r of sets.flat()) {
+        const op = parseOutpoint(r.outpoint);
+        const k = op ? `${op.txid}.${op.vout}` : r.outpoint;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(r);
+    }
+    return out;
+}
+/** The wallet's pool rows (`isPoolRow`). */
+export function positionRowsOf(rows) {
+    const out = [];
+    for (const r of rows) {
+        if (!isPoolRow(r))
+            continue;
+        const op = parseOutpoint(r.outpoint);
+        if (!op)
+            continue;
+        try {
+            const ci = JSON.parse(r.customInstructions ?? "{}");
+            if (!Array.isArray(ci.protocolID) || typeof ci.keyID !== "string" || typeof ci.id !== "string")
+                continue;
+            const tid = parseOutpoint(ci.id.replace("_", "."));
+            const filed = r.lockingScript ? PoolTemplate.decode(r.lockingScript) : null;
+            out.push({
+                deployOutpoint: `${op.txid}.${op.vout}`,
+                tokenId: tid ? tokenIdText(tid) : ci.id,
+                ...(ci.sym ? { sym: ci.sym } : {}),
+                ...(ci.dec !== undefined ? { dec: Number(ci.dec) } : {}),
+                lpKey: { protocolID: ci.protocolID, keyID: ci.keyID, counterparty: typeof ci.counterparty === "string" ? ci.counterparty : "self" },
+                ...(typeof ci.amm?.validatorIdentity === "string" ? { validatorIdentity: ci.amm.validatorIdentity } : {}),
+                ...(filed ? { lpPubKey: filed.state.lpPubKey } : {}),
+            });
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return out;
+}
+/** Positions (live and closed) summed per token, in the order each token first appears; fees not told count as 0. */
+export function feesByToken(ps) {
+    const by = new Map();
+    for (const p of ps) {
+        let t = by.get(p.tokenId);
+        if (!t) {
+            t = { tokenId: p.tokenId, sym: p.sym, dec: p.dec, positions: 0, sats: 0n, tokens: 0n };
+            by.set(p.tokenId, t);
+        }
+        t.positions += 1;
+        t.sats += p.feesEarnedSats ?? 0n;
+        t.tokens += p.feesEarnedTokens ?? 0n;
+    }
+    return [...by.values()];
+}

package/dist/lp/rebalance.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Rebalance (skein-amm 0.38.0, D11, David Case 2026-11-05): a position's pool closed and a new
+ * one deployed in ONE wallet createAction — what Close (src/lp/close.ts) and the deploy
+ * (src/lp/poolDeploy.ts) do, in the same transaction. A position is still only deployed or
+ * closed (the pool A's Close, a new pool B with a new LP key); wallet-built, so nothing is
+ * broadcast-then-taken-in (that is the page-built swap's).
+ *
+ *   1. The old pool A's current output and its BEEF (the caller's: `GET
+ *      /@<token>/amm/pools/beef?lp=<A's LP key>`), A's LP key checked against the wallet's.
+ *   2. The new pool B as the deploy makes it: a new LP key (`newLpKey`), the proposed pool
+ *      (`planPoolDeploy`), the validator's affirmation (`amm.pool.affirm`, `affirmPool`: the same
+ *      call a deploy makes, with B's sats and tokens).
+ *   3. ONE createAction through the wallet's BRC-207 module, a `p color plan` transfer:
+ *      - input 0: A, explicit (its BEEF in `inputBEEF`, `unlockingScriptLength`
+ *        `PoolTemplate.maxCallUnlockLength`) — to the module a FOREIGN token input, checked
+ *        admitted and unspent on the token's overlay, its tokens counted;
+ *      - output 0: B (a foreign script to the module; its description the deploy's, naming B's
+ *        LP keyID: `lpKeyDescription`);
+ *      - the token difference through the module: B holding MORE tokens than A — the module
+ *        selects the wallet's token inputs for the rest and adds token change (the deploy's
+ *        path); FEWER — output 1, the rest to a NEW module receiving key of the user's own, the
+ *        plan's owned output 1 (the Close's path; the module files it in `p color <assetTag>`);
+ *      - the sats difference: the wallet funds what B needs beyond A's sats, its change takes
+ *        what A had beyond B's (and pays the fee);
+ *      - labels: the plan's, `amm-pool-deploy` (the deploy's: the positions reader finds B in the
+ *        history) and `amm-close` (the Close's); `randomizeOutputs: false`.
+ *      The page fills A's input over the wallet's transaction at signAction (`callUnlock` + the
+ *      LP's `createSignature`, checked with `Spend`; Close's outputs are free, so the preimage
+ *      covers B and every output the module and the wallet added); the module signs its inputs,
+ *      approves and submits; the wallet broadcasts.
+ *   4. The page's own submit at the host root (`tm_color_<assetId>`), then B's position row filed
+ *      in `amm-pools` (basket insertion, as the deploy files it).
+ */
+import { type WalletInterface } from "@bsv/sdk";
+import type { LookupOutput } from "../lib/overlay.js";
+import type { AuthFetchLike } from "../market/relay.js";
+import type { LpKeyRef } from "./positions.js";
+import { type HeldOutput } from "../wallet/color.js";
+import { newLpKey, type Affirmation, type BasketFiling, type PoolDeployPlan, type ValidatorChoice } from "./poolDeploy.js";
+export declare class RebalanceShapeError extends Error {
+    constructor(message: string);
+}
+export interface RebalanceInput {
+    wallet: WalletInterface;
+    /** The wallet's BRC-104 client for the token instance (`amm.pool.affirm` on `/call`). */
+    af: AuthFetchLike;
+    /** The token instance's AMM base URL. */
+    base: string;
+    tokenId: string;
+    /** The old pool A's current output (step 1). */
+    poolOutput: LookupOutput;
+    /** A's LP key in the wallet. */
+    lpKey: LpKeyRef;
+    /** The new pool B's reserves: token base units and sats. */
+    tokens: bigint;
+    sats: bigint;
+    /** B's fees: the validator's terms now, as a deploy takes them. */
+    fees: {
+        lpFeeBps: bigint;
+        validatorFeeBps: bigint;
+        commissionBps: bigint;
+    };
+    validator: ValidatorChoice;
+    /** The wallet's held token outputs (`p color assets`): B holding more than A needs the rest there. */
+    held: HeldOutput[];
+    meta?: {
+        sym?: string;
+        dec?: number;
+    };
+    /** The submit to this skein (default: `POST <origin>/submit`, plain fetch). */
+    submit?: (topic: string, beef: number[]) => Promise<{
+        steak?: unknown;
+    }>;
+}
+export interface RebalancedPool {
+    /** A's output spent, `txid.vout`. */
+    closed: string;
+    plan: PoolDeployPlan;
+    lpKey: Awaited<ReturnType<typeof newLpKey>>;
+    affirmation: Affirmation;
+    /** The createAction arguments the wallet was given. */
+    createArgs: Parameters<WalletInterface["createAction"]>[0];
+    txid: string;
+    /** The transaction as the wallet's AtomicBEEF. */
+    tx: number[];
+    /** B, `<txid>.0`. */
+    outpoint: string;
+    /** B's token difference against A: positive, taken from the wallet; negative, returned to it (output 1). */
+    tokenDelta: bigint;
+    /** B's sats difference against A: positive, funded by the wallet; negative, into its change. */
+    satsDelta: bigint;
+    /** B's position row (`amm-pools`). */
+    filing: BasketFiling;
+    filed: boolean;
+    /** The page's own submit, in words (src/lp/close.ts `steakText`), or its error. */
+    submitted: string;
+    /** Filing or submit errors (the transaction itself is broadcast). */
+    errors: string[];
+}
+/** Steps 1-4 (see the module comment). Throws before the wallet's action exists or when it is refused; after the broadcast, errors are collected. */
+export declare function rebalancePool(i: RebalanceInput): Promise<RebalancedPool>;

package/dist/lp/rebalance.js

@@ -0,0 +1,168 @@
+/**
+ * Rebalance (skein-amm 0.38.0, D11, David Case 2026-11-05): a position's pool closed and a new
+ * one deployed in ONE wallet createAction — what Close (src/lp/close.ts) and the deploy
+ * (src/lp/poolDeploy.ts) do, in the same transaction. A position is still only deployed or
+ * closed (the pool A's Close, a new pool B with a new LP key); wallet-built, so nothing is
+ * broadcast-then-taken-in (that is the page-built swap's).
+ *
+ *   1. The old pool A's current output and its BEEF (the caller's: `GET
+ *      /@<token>/amm/pools/beef?lp=<A's LP key>`), A's LP key checked against the wallet's.
+ *   2. The new pool B as the deploy makes it: a new LP key (`newLpKey`), the proposed pool
+ *      (`planPoolDeploy`), the validator's affirmation (`amm.pool.affirm`, `affirmPool`: the same
+ *      call a deploy makes, with B's sats and tokens).
+ *   3. ONE createAction through the wallet's BRC-207 module, a `p color plan` transfer:
+ *      - input 0: A, explicit (its BEEF in `inputBEEF`, `unlockingScriptLength`
+ *        `PoolTemplate.maxCallUnlockLength`) — to the module a FOREIGN token input, checked
+ *        admitted and unspent on the token's overlay, its tokens counted;
+ *      - output 0: B (a foreign script to the module; its description the deploy's, naming B's
+ *        LP keyID: `lpKeyDescription`);
+ *      - the token difference through the module: B holding MORE tokens than A — the module
+ *        selects the wallet's token inputs for the rest and adds token change (the deploy's
+ *        path); FEWER — output 1, the rest to a NEW module receiving key of the user's own, the
+ *        plan's owned output 1 (the Close's path; the module files it in `p color <assetTag>`);
+ *      - the sats difference: the wallet funds what B needs beyond A's sats, its change takes
+ *        what A had beyond B's (and pays the fee);
+ *      - labels: the plan's, `amm-pool-deploy` (the deploy's: the positions reader finds B in the
+ *        history) and `amm-close` (the Close's); `randomizeOutputs: false`.
+ *      The page fills A's input over the wallet's transaction at signAction (`callUnlock` + the
+ *      LP's `createSignature`, checked with `Spend`; Close's outputs are free, so the preimage
+ *      covers B and every output the module and the wallet added); the module signs its inputs,
+ *      approves and submits; the wallet broadcasts.
+ *   4. The page's own submit at the host root (`tm_color_<assetId>`), then B's position row filed
+ *      in `amm-pools` (basket insertion, as the deploy files it).
+ */
+import { Beef, PublicKey, Transaction } from "@bsv/sdk";
+import { PoolTemplate } from "../pool/index.js";
+import { poolUtxoFrom, spendValid } from "../market/swapAction.js";
+import { identityKeyOf, isBrc29Protocol } from "../wallet/brc29.js";
+import { sdkTokenId } from "../lib/tokenId.js";
+import { POOLS_BASKET, newReceivingKey, transferPlanLabels } from "../wallet/color.js";
+import { inputIndexOf, runAppSignedAction } from "../wallet/action.js";
+import { submitToOverlay, steakText } from "./close.js";
+import { POOL_TAG, PoolDeployError, affirmPool, lpKeyDescription, newLpKey, planPoolDeploy, poolCustomInstructions, tokenP2pkhScript, valueOutputsOf } from "./poolDeploy.js";
+import { POOL_DEPLOY_LABEL } from "./positions.js";
+export class RebalanceShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RebalanceShapeError";
+    }
+}
+function describe(text) {
+    return text.length <= 50 ? text : `${text.slice(0, 49)}…`;
+}
+/** Steps 1-4 (see the module comment). Throws before the wallet's action exists or when it is refused; after the broadcast, errors are collected. */
+export async function rebalancePool(i) {
+    const { wallet } = i;
+    const meta = i.meta ?? {};
+    const sdkId = sdkTokenId(i.tokenId);
+    const sym = meta.sym ?? "token";
+    // 1. A, and its LP key.
+    const poolUtxo = poolUtxoFrom(i.poolOutput);
+    const old = PoolTemplate.decode(poolUtxo.script);
+    if (!old)
+        throw new RebalanceShapeError("the output is not a pool");
+    if (!isBrc29Protocol(i.lpKey.protocolID) || i.lpKey.counterparty !== "self")
+        throw new RebalanceShapeError(`the LP key ${i.lpKey.keyID} is not a BRC-29 key to self`);
+    const lpArgs = { protocolID: i.lpKey.protocolID, keyID: i.lpKey.keyID, counterparty: i.lpKey.counterparty };
+    const { publicKey: lpPub } = await wallet.getPublicKey({ ...lpArgs, forSelf: true });
+    if (PublicKey.fromString(lpPub).toString() !== old.state.lpPubKey)
+        throw new RebalanceShapeError(`the wallet key ${i.lpKey.keyID} is not this pool's LP key`);
+    const tokenDelta = i.tokens - old.state.tokenReserve;
+    const satsDelta = i.sats - BigInt(poolUtxo.satoshis);
+    if (tokenDelta > 0n) {
+        const held = valueOutputsOf(i.held, i.tokenId).reduce((a, o) => a + o.amount, 0n);
+        if (held < tokenDelta)
+            throw new PoolDeployError(`Your wallet holds fewer than ${tokenDelta} base units of that token`);
+    }
+    // 2. B: a new LP key, the proposed pool, the validator's affirmation.
+    const lpKey = await newLpKey(wallet);
+    const plan = planPoolDeploy({
+        tokenId: i.tokenId,
+        tokens: i.tokens,
+        sats: i.sats,
+        ...i.fees,
+        lpPubKey: lpKey.publicKey,
+        lpKeyId: lpKey.keyID,
+        validator: i.validator,
+        ...(meta.dec !== undefined ? { dec: meta.dec } : {}),
+    });
+    const affirmation = await affirmPool(i.af, i.base, plan);
+    const poolScript = affirmation.lockingScript;
+    // 3. The one action: A in, B at output 0, the token difference through the module.
+    const outputs = [{ lockingScript: poolScript, satoshis: Number(plan.sats), outputDescription: lpKeyDescription(describe(`AMM pool: ${sym} / BSV`), lpKey.keyID) }];
+    let owned = {};
+    if (tokenDelta < 0n) {
+        const me = await identityKeyOf(wallet);
+        const k = await newReceivingKey(wallet, sdkId, me);
+        outputs.push({ lockingScript: tokenP2pkhScript(sdkId, -tokenDelta, k.publicKey), satoshis: 1, outputDescription: describe(`${sym} pool tokens to you`) });
+        owned = { ownedOutputs: [{ outputIndex: 1, ...k.receipt }] };
+    }
+    const first = PoolTemplate.planClose({ pool: poolUtxo, outputs: outputs.map((o) => ({ satoshis: BigInt(o.satoshis), script: o.lockingScript })) });
+    const poolOutpoint = `${poolUtxo.txid}.${poolUtxo.vout}`;
+    const lpSigner = async (sighash) => (await wallet.createSignature({ ...lpArgs, hashToDirectlySign: sighash })).signature;
+    const createArgs = {
+        description: describe(`AMM close + pool deploy: ${sym}`),
+        inputBEEF: Beef.fromBinary(i.poolOutput.beef).toBinary(),
+        inputs: [{ outpoint: poolOutpoint, unlockingScriptLength: PoolTemplate.maxCallUnlockLength(first), inputDescription: describe(`The ${sym} pool`) }],
+        outputs,
+        labels: [...transferPlanLabels(sdkId, owned), POOL_DEPLOY_LABEL, "amm-close"],
+        options: { randomizeOutputs: false, acceptDelayedBroadcast: false },
+    };
+    const signed = await runAppSignedAction(wallet, createArgs, async (tx) => {
+        // The contract reads input 0 (the preimage is input 0's); the wallet places named inputs first.
+        if (inputIndexOf(tx, poolUtxo.txid, poolUtxo.vout) !== 0)
+            throw new RebalanceShapeError("the wallet did not place the pool as input 0");
+        outputs.forEach((o, n) => {
+            if (tx.outputs[n]?.lockingScript.toHex() !== o.lockingScript || tx.outputs[n]?.satoshis !== o.satoshis)
+                throw new RebalanceShapeError(`the wallet moved output ${n} of the rebalance`);
+        });
+        // Close's outputs are free: the call's preimage covers B and every output the wallet added.
+        const callPlan = PoolTemplate.planClose({ pool: poolUtxo, outputs: tx.outputs.map((o) => ({ satoshis: BigInt(o.satoshis), script: o.lockingScript.toHex() })) });
+        tx.inputs[0].unlockingScript = PoolTemplate.callUnlock(callPlan, tx, null).unlockingScript;
+        await PoolTemplate.signPoolInput({ tx, pool: callPlan.pool, method: "close", unsigned: ["lp"], sourceSatoshis: poolUtxo.satoshis }, "lp", lpSigner);
+        if (!spendValid(tx, 0))
+            throw new RebalanceShapeError("input 0 of the rebalance does not validate");
+        return { 0: { unlockingScript: tx.inputs[0].unlockingScript.toHex() } };
+    });
+    const out = {
+        closed: poolOutpoint,
+        plan,
+        lpKey,
+        affirmation,
+        createArgs,
+        txid: signed.txid,
+        tx: signed.tx,
+        outpoint: `${signed.txid}.0`,
+        tokenDelta,
+        satsDelta,
+        filing: {
+            outputIndex: 0,
+            basket: POOLS_BASKET,
+            tags: [POOL_TAG],
+            customInstructions: poolCustomInstructions({ tokenId: sdkId, ...meta, protocolID: lpKey.protocolID, keyID: lpKey.keyID, args: plan.args, validatorIdentity: plan.state.validatorIdentity, nonce: affirmation.nonce }),
+        },
+        filed: false,
+        submitted: "not submitted",
+        errors: [],
+    };
+    if (Transaction.fromAtomicBEEF(signed.tx).outputs[0]?.lockingScript.toHex() !== poolScript)
+        out.errors.push("the wallet's transaction has another output 0 than the affirmed pool");
+    // 4. The page's own submit, then B's position row.
+    try {
+        const submit = i.submit ?? ((topic, beef) => submitToOverlay(i.base, topic, beef));
+        out.submitted = steakText((await submit(plan.topic, signed.tx)));
+    }
+    catch (err) {
+        out.submitted = "the submit failed";
+        out.errors.push(`submit: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const row = { outputIndex: 0, protocol: "basket insertion", insertionRemittance: { basket: out.filing.basket, tags: out.filing.tags, customInstructions: out.filing.customInstructions } };
+    try {
+        const r = await wallet.internalizeAction({ tx: signed.tx, outputs: [row], description: describe(`AMM pool deploy: ${sym}`), labels: [POOL_DEPLOY_LABEL] });
+        out.filed = r.accepted;
+    }
+    catch (err) {
+        out.errors.push(`internalizeAction: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return out;
+}

package/dist/lp/wallet.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The wallet reads of the exchange's own baskets (skein-amm 0.12.0): the
+ * LP's position rows (`amm-pools`) and the active swap basket (`amm-swap`),
+ * src/wallet/color.ts. The user's tokens themselves are the BRC-207
+ * module's (`p color assets`, `p color balance <assetTag>`), read there.
+ * Nothing here talks to an overlay.
+ */
+import { Beef, type WalletInterface, type WalletOutput } from "@bsv/sdk";
+/** A basket's outputs with locking scripts, tags and customInstructions. */
+export declare function basketRows(wallet: WalletInterface, basket: string): Promise<WalletOutput[]>;
+/** A basket's source transactions (for a spend's BEEF), or null when the wallet answers none. */
+export declare function basketBeef(wallet: WalletInterface, basket: string): Promise<Beef | null>;

package/dist/lp/wallet.js

@@ -0,0 +1,19 @@
+/**
+ * The wallet reads of the exchange's own baskets (skein-amm 0.12.0): the
+ * LP's position rows (`amm-pools`) and the active swap basket (`amm-swap`),
+ * src/wallet/color.ts. The user's tokens themselves are the BRC-207
+ * module's (`p color assets`, `p color balance <assetTag>`), read there.
+ * Nothing here talks to an overlay.
+ */
+import { Beef } from "@bsv/sdk";
+import { LIST_LIMIT } from "../wallet/color.js";
+/** A basket's outputs with locking scripts, tags and customInstructions. */
+export async function basketRows(wallet, basket) {
+    const r = await wallet.listOutputs({ basket, include: "locking scripts", includeTags: true, includeCustomInstructions: true, limit: LIST_LIMIT });
+    return r.outputs;
+}
+/** A basket's source transactions (for a spend's BEEF), or null when the wallet answers none. */
+export async function basketBeef(wallet, basket) {
+    const r = await wallet.listOutputs({ basket, include: "entire transactions", limit: LIST_LIMIT });
+    return r.BEEF ? Beef.fromBinary(Array.from(r.BEEF)) : null;
+}

package/dist/market/activeSwap.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The active swap basket (skein-amm 0.12.0, David Case 2026-10-21/22; 0.29.0,
+ * 2026-11-02): everything the swap legs spend, held outside the BRC-207 module
+ * in the exchange's own basket `amm-swap` (src/wallet/color.ts): the token
+ * outputs and each leg's sats.
+ *
+ *   - **In** (`sendToSwapBasket`): before the legs of a tokens-in swap, ONE
+ *     wallet-built send through the module: one 1Color value output per leg
+ *     not covered by what `amm-swap` already holds, each exactly the leg's
+ *     amount in (the pool takes no token change, so a leg needs inputs that
+ *     sum to its amount exactly), locked to a key derived from the leg's pool outpoint (`swapKeyID`) under `[2, "amm
+ *     swap"]` (counterparty self), the plan naming them a transfer out; and
+ *     (0.29.0) one P2PKH sats output per leg not covered (the leg's exact
+ *     sats, `swapFunding`), to that outpoint's `:sats` key, filed in
+ *     `amm-swap` by the createAction itself (customInstructions `{sats: true,
+ *     assetId, protocolID, keyID, counterparty}`). The module passes the sats outputs
+ *     through, selects the token inputs, adds change, asks once, signs and
+ *     submits to `tm_color_<assetId>`; the wallet funds the sats; the page
+ *     submits it to this skein too (a repeat is harmless), then files each
+ *     token output in `amm-swap` (basket insertion, customInstructions
+ *     `{assetId, amount, protocolID, keyID, counterparty}`). A sats-in swap,
+ *     or a tokens-in swap whose tokens are all staged already, sends only the
+ *     sats (`sendSatsToSwapBasket`: a plain createAction, no `p color` labels).
+ *   - **Spent** by the legs (src/market/swapAction.ts): app-built,
+ *     `createSignature` under the key the customInstructions name; the
+ *     wallet marks them spent when it takes the accepted swap in (0.29.0: no
+ *     relinquishOutput). An output a failed leg did not spend stays for a
+ *     later swap.
+ *   - **Move back** (`moveBack`, the recovery path; 0.29.3: a module plan,
+ *     David Case 2026-11-02): ONE createAction through the wallet's BRC-207
+ *     module, a `p color plan` transfer: every `amm-swap` token output of the
+ *     token and (0.29.1) the sats rows staged for its legs (their `assetId`)
+ *     as explicit inputs (their source transactions in `inputBEEF`) — to the
+ *     module FOREIGN inputs (not in a `p color` basket): the token rows
+ *     checked admitted and unspent on the token's overlay, the sats rows
+ *     adding nothing; one output, the whole amount to a NEW module receiving
+ *     key of the user's own, the plan's owned output 0 (the module checks it
+ *     pays the remittance's key and files it in `p color <assetTag>` with its
+ *     custody in the same call). The page unlocks its inputs at signAction;
+ *     the wallet funds the fee and takes the sats rows into its change; the
+ *     module approves and submits, the wallet broadcasts. The page submits it
+ *     to this skein's token topic too. Nothing is taken in afterwards and
+ *     nothing is kept in the browser. *     (0.29.6) With no token row and only sats rows staged for the token
+ *     (a sats-in leg that failed): one plain createAction (no `p color`
+ *     labels), the sats rows as explicit inputs and no outputs — the wallet
+ *     keeps them as its change and pays the fee (`moveBackSats`).
+ */
+import { Beef, Transaction, type WalletInterface } from "@bsv/sdk";
+import { type Steak } from "../lp/close.js";
+import { type Spends } from "../wallet/action.js";
+import { type SatsInput, type TokenInput } from "./swapAction.js";
+/** The keyID prefix of an `amm-swap` key (`SWAP_PROTOCOL`, counterparty self). */
+export declare const SWAP_KEY_PREFIX = "amm-swap-";
+/**
+ * The keyID of a staged `amm-swap` output (0.29.2, David Case 2026-11-02: derived, not random):
+ * `amm-swap-<txid>.<vout>` for a leg's token row and `amm-swap-<txid>.<vout>:sats` for its sats
+ * row, `<txid>.<vout>` the leg's pool outpoint as quoted (`leg.outpoint`, `_` written `.`).
+ * Protocol `[2, "amm swap"]`, counterparty self, as before. A leg refused and retried against the
+ * same pool outpoint stages to the same key again, which is fine.
+ */
+export declare function swapKeyID(poolOutpoint: string, kind: "token" | "sats"): string;
+/** The `amm-swap` outputs of `tokenId` the legs can spend. */
+export declare function swapHoldings(wallet: WalletInterface, tokenId: string): Promise<TokenInput[]>;
+/** The `amm-swap` sats outputs the legs can spend (0.29.0). */
+export declare function swapSatsHoldings(wallet: WalletInterface): Promise<SatsInput[]>;
+/**
+ * What `amm-swap` holds, per token id: the token amount and the number of token outputs, and
+ * (0.29.6) the sats staged for the token's legs (the sats rows whose customInstructions name its
+ * `assetId`). A token with only sats staged has amount 0n and outputs 0.
+ */
+export declare function swapTotals(wallet: WalletInterface): Promise<Map<string, {
+    amount: bigint;
+    outputs: number;
+    sats: number;
+}>>;
+/** The source transactions of `amm-swap`'s outputs (a leg's BEEF), with `extra` merged in. */
+export declare function swapHoldingBeef(wallet: WalletInterface, extra?: number[]): Promise<Beef>;
+export interface SentToSwapBasket {
+    txid: string;
+    /** The send as the wallet's AtomicBEEF. */
+    tx: number[];
+    /** The new `amm-swap` token outputs, in the order of `stage.tokens`. */
+    holdings: TokenInput[];
+    /** The new `amm-swap` sats outputs, in the order of `stage.sats` (0.29.0). */
+    sats: SatsInput[];
+    filed: boolean;
+    submitted: string;
+    errors: string[];
+}
+/** A staged sats output: the leg's exact sats, keyed by the leg's pool outpoint (`swapKeyID`). */
+export interface StagedSats {
+    satoshis: number;
+    /** The leg's pool outpoint, `<txid>_<vout>` or `<txid>.<vout>`. */
+    pool: string;
+}
+/** What one send stages: a token output per leg (its amount in), then a sats output per leg. */
+export interface SwapStage {
+    tokens: {
+        amount: bigint;
+        pool: string;
+    }[];
+    sats: StagedSats[];
+}
+/**
+ * "In" (see the module comment): one module send of `stage.tokens` (each one
+ * output) to `amm-swap` keys derived from each leg's pool (`swapKeyID`), filed in `amm-swap`, and of `stage.sats`
+ * (each one output) after them. Throws when the wallet refuses or fails the
+ * send; filing and the page's own submit are reported in `errors`.
+ */
+export declare function sendToSwapBasket(wallet: WalletInterface, base: string, tokenId: string, stage: SwapStage, meta?: {
+    sym?: string;
+}, submit?: (topic: string, beef: number[]) => Promise<{
+    steak?: Steak;
+}>): Promise<SentToSwapBasket>;
+export interface SentSats {
+    txid: string;
+    /** The send as the wallet's AtomicBEEF. */
+    tx: number[];
+    /** The new `amm-swap` sats outputs, in the order of `sats`. */
+    sats: SatsInput[];
+    errors: string[];
+}
+/**
+ * The sats-only send (0.29.0): one plain createAction (no `p color` labels: the module is not in
+ * the path) with one P2PKH output per amount to the leg's "amm swap" `:sats` key (`swapKeyID`), filed in `amm-swap`; the
+ * wallet funds it, adds change and broadcasts. Throws when the wallet refuses or fails it.
+ */
+export declare function sendSatsToSwapBasket(wallet: WalletInterface, tokenId: string, sats: StagedSats[], meta?: {
+    sym?: string;
+}): Promise<SentSats>;
+export interface MovedBack {
+    txid: string;
+    amount: bigint;
+    /** The transaction as the wallet's AtomicBEEF. */
+    beef: number[];
+    submitted: string;
+    errors: string[];
+}
+/** The page's unlocking scripts for the `amm-swap` outputs `holdings` in the wallet's transaction `tx`, each checked with `Spend`. */
+export declare function swapBasketSpends(wallet: WalletInterface, tx: Transaction, holdings: (TokenInput | SatsInput)[], what: string): Promise<Spends>;
+/**
+ * "Move back" (see the module comment; 0.29.3: a module plan). Throws before anything is
+ * broadcast (no outputs, a wallet or module refusal, an input that does not validate: the action
+ * is aborted). The module files the output in `p color <assetTag>` with its custody in the same
+ * createAction: no take-in afterwards, nothing kept in the browser. The page's own submit to this
+ * skein's token topic (the module submitted at the wallet's overlay too) is reported in `errors`.
+ */
+export declare function moveBack(i: {
+    wallet: WalletInterface;
+    base: string;
+    tokenId: string;
+    meta?: {
+        sym?: string;
+    };
+    submit?: (topic: string, beef: number[]) => Promise<{
+        steak?: Steak;
+    }>;
+}): Promise<MovedBack>;