@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/pool/template.js

@@ -0,0 +1,715 @@
+/**
+ * The AMM Pool script template (pool/Pool.runar.go) over runar-sdk.
+ *
+ * On chain a pool output is a BRC-162 (1Color) value output wrapped around the
+ * Rúnar contract:
+ *
+ *   0x20 <assetId:32> <push tokenReserve> OP_2DROP || code || OP_RETURN || state
+ *
+ * One layout (artifact.ts `PoolVersion`; 0.29.1: layout 1, 0.9.0-0.12.x, dropped). Layout 2 (skein-amm 0.13.0): `state` is
+ * TokenReserve (8 bytes LE sign-magnitude) ‖ LpPubKey ‖ ValidatorPubKey ‖ ValidatorIdentity
+ * (33 each) ‖ Nonce (32) ‖ Affirmation (its length byte, then the validator's DER signature
+ * over sha256 of `affirmationMessage`, docs/AMM.md "The deploy and the affirmation"); no
+ * payload; methods Swap, Close (the LP's, outputs free) and Rescind (the validator's: the
+ * ValidatorPubKey cleared to 33 zero bytes). A layout-1 script (the 0.9.0-0.12.x contract)
+ * decodes as no pool.
+ *
+ * `code` is the artifact's template with the readonly constructor args
+ * (assetId, lpFeeBps, validatorFeeBps, commissionBps) spliced in.
+ * runar-sdk knows nothing of the prefix, so this module splits it off and hands
+ * runar-sdk only `code || OP_RETURN || state`.
+ *
+ * A method call (input 0's unlocking script) is pushes only, in the order the
+ * compiled contract reads them:
+ *
+ *   _codePart  arg0 .. argN-1  _changePKH  _changeAmount  txPreimage  methodIndex
+ *
+ * The preimage is BIP-143 (ALL|FORKID) over the pool input with the scriptCode
+ * after Rúnar's leading `OP_NOP OP_CODESEPARATOR`; every signature a method
+ * checks (validator's, LP's) is over sha256d of that preimage. BIP-143 does not
+ * cover any unlocking script, so the builder (taker or LP) finishes the whole
+ * transaction, signs its own inputs, and leaves the validator's slot empty
+ * (`OP_0`); the validator then fills its slot with `signPoolInput` without
+ * invalidating anything else. That is the sequence pool/pool_test.go and
+ * programs/amm-topic/gen use.
+ *
+ * Uses from runar-sdk: artifact matching, constructor-arg and state extraction,
+ * state serialization, the code part, the BIP-143 preimage at the code
+ * separator (`computeOpPushTxWithCodeSep`), and its push encoders.
+ * `RunarContract.prepareCall` is not used: it needs a Provider to select
+ * funding and sets the fee from a fee rate, it builds the continuation from
+ * the bare artifact script (no BRC-162 prefix), and this contract's outputs
+ * come from `addRawOutput` with a prefix the SDK cannot predict.
+ */
+import { EMPTY_SIG, RunarContract, encodeArg, encodePushData, encodeScriptNumber, extractConstructorArgs, extractStateFromScript, findLastOpReturn, matchesArtifact, serializeState, } from "../vendor/runar/runar-sdk.js";
+import { Hash, LockingScript, P2PKH, PrivateKey, PublicKey, Signature, Transaction, UnlockingScript, Utils, } from "@bsv/sdk";
+import { METHOD_INDEX, artifactOf, poolArtifact } from "./artifact.js";
+import { decodeOneColor, oneColorValuePrefix } from "./oneColor.js";
+import { deriveFirstValidatorPubKey, deriveValidatorPubKey } from "../lib/keys.js";
+/** A cleared ValidatorPubKey (Rescind, 0.13.0): 33 zero bytes. */
+export const RESCINDED_KEY = "00".repeat(33);
+/** A refusal by the builder's own checks: nothing was signed. */
+export class PoolBuildError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+        this.name = "PoolBuildError";
+    }
+}
+// ---------------------------------------------------------------------------
+// Script helpers
+// ---------------------------------------------------------------------------
+const toHex = (b) => Utils.toHex(Array.from(b));
+const fromHex = (h) => Utils.toArray(h, "hex");
+const scriptHex = (s) => (typeof s === "string" ? s.toLowerCase() : s.toHex());
+const p2pkhHex = (pkh) => `76a914${pkh}88ac`;
+const pkhOf = (pubKeyHex) => toHex(Hash.hash160(fromHex(pubKeyHex)));
+function tokenPrefixHex(assetId, amount) {
+    return toHex(oneColorValuePrefix(fromHex(assetId), amount));
+}
+/** `tokenP2pkh` in Pool.runar.go: a 1Color value output of `amount` to `pkh`. */
+function tokenP2pkhHex(assetId, amount, pkh) {
+    return tokenPrefixHex(assetId, amount) + p2pkhHex(pkh);
+}
+/** The constructor args in the artifact's order (its ABI's names). */
+function ctorArgs(version, args, state) {
+    const v = {
+        tokenReserve: state.tokenReserve,
+        lpPubKey: state.lpPubKey,
+        validatorPubKey: state.validatorPubKey,
+        validatorIdentity: state.validatorIdentity,
+        nonce: state.nonce ?? "00".repeat(32),
+        affirmation: state.affirmation ?? "",
+        assetId: args.assetId,
+        lpFeeBps: args.lpFeeBps,
+        validatorFeeBps: args.validatorFeeBps,
+        commissionBps: args.commissionBps,
+    };
+    return artifactOf(version).abi.constructor.params.map((p) => v[p.name]);
+}
+function stateHex(version, state) {
+    const fields = {
+        tokenReserve: state.tokenReserve,
+        lpPubKey: state.lpPubKey,
+        validatorPubKey: state.validatorPubKey,
+        validatorIdentity: state.validatorIdentity,
+        nonce: state.nonce ?? "00".repeat(32),
+        affirmation: state.affirmation ?? "",
+    };
+    return serializeState(artifactOf(version).stateFields, fields);
+}
+/** Whether `method` takes Rúnar's change parameters (`_changePKH`, `_changeAmount`): a method that writes outputs. Close writes none. */
+function takesChange(version, method) {
+    const m = artifactOf(version).abi.methods.find((x) => x.name === method);
+    return Boolean(m?.params.some((p) => p.name === "_changePKH"));
+}
+/** The affirmation message's tag (0.13.0: message v2). */
+const AFFIRM_TAG = "skein-amm affirm 2";
+/** `n` as 8 bytes, little-endian two's complement (an int64 or a uint64 below 2^63). */
+function le64(n) {
+    let v = BigInt.asUintN(64, n);
+    const out = [];
+    for (let i = 0; i < 8; i++) {
+        out.push(Number(v & 0xffn));
+        v >>= 8n;
+    }
+    return out;
+}
+function isHex(s, bytes) {
+    return typeof s === "string" && s.length === bytes * 2 && /^[0-9a-f]*$/.test(s);
+}
+// ---------------------------------------------------------------------------
+// The template
+// ---------------------------------------------------------------------------
+export class PoolTemplate {
+    /**
+     * Decodes a pool locking script: a 1Color value prefix with a 32-byte id (no payload), then the Pool artifact
+     * (template bytes between the constructor slots), then the state. Also requires
+     * prefix id == assetId and prefix amount == TokenReserve (the admission check of
+     * Pool.runar.go's doc). Returns null for anything else.
+     */
+    static decode(script) {
+        const bytes = Array.isArray(script) ? script : fromHex(scriptHex(script));
+        const prefix = decodeOneColor(bytes);
+        if (!prefix || prefix.role !== "value")
+            return null;
+        if (prefix.idBytes?.length !== 32)
+            return null;
+        const contractScript = toHex(bytes.slice(prefix.length));
+        for (const version of [2]) {
+            const artifact = artifactOf(version);
+            if (!matchesArtifact(artifact, contractScript))
+                continue;
+            const ctor = extractConstructorArgs(artifact, contractScript);
+            let raw;
+            try {
+                raw = extractStateFromScript(artifact, contractScript);
+            }
+            catch {
+                return null;
+            }
+            if (!raw)
+                return null;
+            const { assetId, lpFeeBps, validatorFeeBps, commissionBps } = ctor;
+            const { tokenReserve, lpPubKey, validatorPubKey, validatorIdentity, nonce, affirmation } = raw;
+            if (!isHex(assetId, 32) || typeof lpFeeBps !== "bigint" || typeof validatorFeeBps !== "bigint" || typeof commissionBps !== "bigint")
+                return null;
+            if (typeof tokenReserve !== "bigint" || !isHex(lpPubKey, 33) || !isHex(validatorPubKey, 33) || !isHex(validatorIdentity, 33))
+                return null;
+            if (!isHex(nonce, 32) || typeof affirmation !== "string" || !/^[0-9a-f]*$/.test(affirmation))
+                return null;
+            if (prefix.payload !== undefined)
+                return null; // a pool writes no payload
+            if (assetId !== toHex(prefix.idBytes) || tokenReserve !== prefix.amount)
+                return null;
+            const opReturn = findLastOpReturn(contractScript);
+            return {
+                version,
+                args: { assetId, lpFeeBps, validatorFeeBps, commissionBps },
+                state: { tokenReserve, lpPubKey, validatorPubKey, validatorIdentity, nonce: nonce, affirmation: affirmation },
+                code: contractScript.slice(0, opReturn),
+                contractScript,
+            };
+        }
+        return null;
+    }
+    /** Whether the pool was rescinded by its validator (layout 2: ValidatorPubKey 33 zero bytes). */
+    static rescinded(pool) {
+        return pool.state.validatorPubKey === RESCINDED_KEY;
+    }
+    /**
+     * A new pool's locking script (layout 2, 0.13.0): the 1Color prefix for TokenReserve (which
+     * the contract writes itself on every continuation, but nothing on chain writes for a deploy)
+     * in front of runar-sdk's locking script for the constructor args. `state` may leave the
+     * ValidatorPubKey, Nonce and Affirmation to come (33 zero bytes, absent, absent: the pool as
+     * `amm.pool.affirm` is asked about it); the deploy carries the validator's three.
+     */
+    static lockDeploy(args, state) {
+        if (!isHex(args.assetId, 32))
+            throw new Error("lockDeploy: assetId must be 32 bytes of hex");
+        for (const k of ["lpPubKey", "validatorPubKey", "validatorIdentity"]) {
+            if (k === "validatorPubKey" && state[k] === RESCINDED_KEY)
+                continue; // still to come
+            PublicKey.fromString(state[k]); // throws on a malformed key
+        }
+        if (state.nonce !== undefined && !isHex(state.nonce, 32))
+            throw new Error("lockDeploy: the nonce must be 32 bytes of hex");
+        const af = (state.affirmation ?? "").toLowerCase();
+        if (!/^[0-9a-f]*$/.test(af) || af.length % 2 !== 0 || af.length > 0x4b * 2)
+            throw new Error("lockDeploy: the affirmation must be a DER signature, hex");
+        const contract = new RunarContract(poolArtifact, ctorArgs(2, args, { ...state, affirmation: af }));
+        return LockingScript.fromHex(tokenPrefixHex(args.assetId, state.tokenReserve) + contract.getLockingScript());
+    }
+    /**
+     * The bytes the validator's affirmation signs (0.13.0, message v2, docs/AMM.md "The deploy
+     * and the affirmation"; src/pool.zig `affirmMessage`): "skein-amm affirm 2" ‖ AssetId (32,
+     * wire order) ‖ LpFeeBps ‖ ValidatorFeeBps ‖ CommissionBps (int64 LE) ‖ TokenReserve ‖ the
+     * pool output's satoshis (uint64 LE) ‖ LpPubKey ‖ ValidatorPubKey ‖ ValidatorIdentity (33
+     * each) ‖ Nonce (32). 221 bytes.
+     */
+    static affirmationMessage(pool, satoshis) {
+        const { args, state } = pool;
+        if (!isHex(state.nonce, 32))
+            throw new Error("affirmationMessage: the pool has no nonce");
+        return [
+            ...Utils.toArray(AFFIRM_TAG, "utf8"),
+            ...fromHex(args.assetId),
+            ...le64(args.lpFeeBps),
+            ...le64(args.validatorFeeBps),
+            ...le64(args.commissionBps),
+            ...le64(state.tokenReserve),
+            ...le64(satoshis),
+            ...fromHex(state.lpPubKey),
+            ...fromHex(state.validatorPubKey),
+            ...fromHex(state.validatorIdentity),
+            ...fromHex(state.nonce),
+        ];
+    }
+    /**
+     * Whether the pool output (`script`, holding `satoshis`) attests itself (0.13.0, amm-lookup's
+     * deploy rule, src/pool.zig `affirmed`): layout 2, not rescinded, its ValidatorPubKey the
+     * ValidatorIdentity's child keyed by its Nonce (derived here), and its Affirmation that key's
+     * signature of `affirmationMessage`.
+     */
+    static affirmed(script, satoshis) {
+        const pool = PoolTemplate.decode(script);
+        if (!pool || pool.version !== 2 || PoolTemplate.rescinded(pool) || !pool.state.nonce || !pool.state.affirmation)
+            return false;
+        try {
+            if (deriveFirstValidatorPubKey(pool.state.validatorIdentity, pool.state.nonce) !== pool.state.validatorPubKey)
+                return false;
+            const message = PoolTemplate.affirmationMessage(pool, satoshis); // PublicKey.verify hashes it (sha256)
+            return PublicKey.fromString(pool.state.validatorPubKey).verify(message, Signature.fromDER(fromHex(pool.state.affirmation)));
+        }
+        catch {
+            return false;
+        }
+    }
+    /** The continuation script: `code` kept byte for byte, prefix and state rewritten. */
+    static lockContinuation(pool, state) {
+        return LockingScript.fromHex(tokenPrefixHex(pool.args.assetId, state.tokenReserve) + pool.code + "6a" + stateHex(pool.version, state));
+    }
+    // -------------------------------------------------------------------------
+    // Methods
+    // -------------------------------------------------------------------------
+    /**
+     * Swap (method 0). Outputs: 0 pool, 1 the taker's payout, then the LP fee,
+     * the validator fee and the commission (each only when nonzero, each in
+     * the input asset), then change. Token payouts and token fees are 1-sat
+     * 1Color outputs; BSV ones are P2PKH. The validator's slot is left empty.
+     */
+    static async swap(p) {
+        const plan = PoolTemplate.planSwap(p);
+        // Tokens in: the token inputs must carry exactly amountIn (no token change
+        // output exists). BSV in: no token of this asset may be spent (it would burn).
+        checkTokenInputs(p.inputs, plan.pool.args.assetId, p.bsvIn ? 0n : p.amountIn);
+        const call = await buildCall({
+            common: p,
+            pool: plan.pool,
+            method: "swap",
+            outputs: plan.outputs,
+            args: plan.args,
+            sigSlots: plan.sigSlots,
+        });
+        call.next = plan.next;
+        call.next.script = call.tx.outputs[0].lockingScript;
+        call.swap = plan.swap;
+        return call;
+    }
+    /**
+     * The Swap call without its funding: the outputs the contract requires (in
+     * order: pool, payout, LP fee, validator fee, commission; no change) and
+     * the method arguments, with the validator's slot empty. For a builder that
+     * does not pick the funding itself (a BRC-100 wallet's `createAction` picks
+     * inputs and change): hand these outputs over, then fill input 0 with
+     * `callUnlock` over the transaction the wallet produced. Same checks and
+     * refusals as `swap` except the funding ones.
+     */
+    static planSwap(p) {
+        const pool = decodeUtxo(p.pool);
+        const { args, state } = pool;
+        const bsvReserve = BigInt(p.pool.satoshis);
+        const e = p.expect ?? {};
+        if (e.bsvReserve !== undefined && e.bsvReserve !== bsvReserve) {
+            throw new PoolBuildError("stale_pool", `BSV reserve is ${bsvReserve}, priced against ${e.bsvReserve}`);
+        }
+        if (e.tokenReserve !== undefined && e.tokenReserve !== state.tokenReserve) {
+            throw new PoolBuildError("stale_pool", `token reserve is ${state.tokenReserve}, priced against ${e.tokenReserve}`);
+        }
+        if (e.lpFeeBps !== undefined && e.lpFeeBps !== args.lpFeeBps) {
+            throw new PoolBuildError("fee_mismatch", `pool LP fee is ${args.lpFeeBps} bps, priced at ${e.lpFeeBps}`);
+        }
+        if (e.validatorFeeBps !== undefined && e.validatorFeeBps !== args.validatorFeeBps) {
+            throw new PoolBuildError("fee_mismatch", `pool validator fee is ${args.validatorFeeBps} bps, priced at ${e.validatorFeeBps}`);
+        }
+        if (e.commissionBps !== undefined && e.commissionBps !== args.commissionBps) {
+            throw new PoolBuildError("fee_mismatch", `pool commission is ${args.commissionBps} bps, priced at ${e.commissionBps}`);
+        }
+        if (!isHex(p.commissionPkh, 20))
+            throw new PoolBuildError("invalid", "commissionPkh must be 20 bytes of hex");
+        if (!isHex(p.userPkh, 20))
+            throw new PoolBuildError("invalid", "userPkh must be 20 bytes of hex");
+        // Pool.runar.go Swap, line for line.
+        const amountIn = p.amountIn;
+        if (amountIn <= 0n)
+            throw new PoolBuildError("invalid", "amountIn must be > 0");
+        const lpFee = (amountIn * args.lpFeeBps + 9999n) / 10000n;
+        const validatorFee = (amountIn * args.validatorFeeBps + 9999n) / 10000n;
+        const commission = (amountIn * args.commissionBps + 9999n) / 10000n;
+        const net = amountIn - lpFee - validatorFee - commission;
+        if (net <= 0n)
+            throw new PoolBuildError("invalid", "amountIn does not cover the fees");
+        let out = (net * bsvReserve) / (state.tokenReserve + net);
+        let newBsv = bsvReserve - out;
+        let newTokens = state.tokenReserve + net;
+        if (p.bsvIn) {
+            out = (net * state.tokenReserve) / (bsvReserve + net);
+            newBsv = bsvReserve + net;
+            newTokens = state.tokenReserve - out;
+        }
+        if (out <= 0n)
+            throw new PoolBuildError("invalid", "amountIn too small: nothing out");
+        if (newBsv <= 0n || newTokens <= 0n)
+            throw new PoolBuildError("invalid", "the swap would empty the pool");
+        if (e.lpFee !== undefined && e.lpFee !== lpFee) {
+            throw new PoolBuildError("fee_mismatch", `LP fee is ${lpFee}, priced at ${e.lpFee}`);
+        }
+        if (e.validatorFee !== undefined && e.validatorFee !== validatorFee) {
+            throw new PoolBuildError("fee_mismatch", `validator fee is ${validatorFee}, priced at ${e.validatorFee}`);
+        }
+        if (e.commission !== undefined && e.commission !== commission) {
+            throw new PoolBuildError("fee_mismatch", `commission is ${commission}, priced at ${e.commission}`);
+        }
+        if (e.amountOut !== undefined && e.amountOut !== out) {
+            throw new PoolBuildError("quote_mismatch", `amount out is ${out}, quoted ${e.amountOut}`);
+        }
+        if (e.minAmountOut !== undefined && out < e.minAmountOut) {
+            throw new PoolBuildError("slippage", `amount out ${out} is below the minimum ${e.minAmountOut}`);
+        }
+        const nextValidatorPubKey = p.nextValidatorPubKey ?? deriveValidatorPubKey(state.validatorIdentity, { txid: p.pool.txid, vout: p.pool.vout });
+        PublicKey.fromString(nextValidatorPubKey);
+        const nextState = { ...state, tokenReserve: newTokens, validatorPubKey: nextValidatorPubKey };
+        const lpPkh = pkhOf(state.lpPubKey);
+        const validatorPkh = pkhOf(state.validatorPubKey);
+        const payout = (amount, pkh, isBsv) => isBsv ? { satoshis: amount, script: p2pkhHex(pkh) } : { satoshis: 1n, script: tokenP2pkhHex(args.assetId, amount, pkh) };
+        const continuation = PoolTemplate.lockContinuation(pool, nextState);
+        const outputs = [
+            { satoshis: newBsv, script: continuation.toHex() },
+            payout(out, p.userPkh, !p.bsvIn),
+        ];
+        if (lpFee > 0n)
+            outputs.push(payout(lpFee, lpPkh, p.bsvIn));
+        if (validatorFee > 0n)
+            outputs.push(payout(validatorFee, validatorPkh, p.bsvIn));
+        if (commission > 0n)
+            outputs.push(payout(commission, p.commissionPkh, p.bsvIn));
+        return {
+            pool,
+            poolUtxo: p.pool,
+            method: "swap",
+            outputs,
+            args: [EMPTY_SIG, nextValidatorPubKey, amountIn, p.bsvIn, p.userPkh, p.commissionPkh],
+            sigSlots: { validator: 0 },
+            next: { pool: { ...pool, state: nextState, contractScript: pool.code + "6a" + stateHex(pool.version, nextState) }, satoshis: Number(newBsv), script: continuation },
+            swap: { amountOut: out, lpFee, validatorFee, commission },
+        };
+    }
+    /**
+     * The pool input's unlocking script for `plan` over a finished transaction
+     * `tx` whose input 0 spends `plan.poolUtxo` and whose outputs are
+     * `plan.outputs`, then (optionally) one P2PKH change output: `change` names
+     * it (`{pkh, satoshis}`), or `null` when there is none. Signature slots stay
+     * empty (`OP_0`), to be filled with `signPoolInput`. Throws when `tx` does
+     * not have that shape (the contract would refuse it).
+     */
+    static callUnlock(plan, tx, change) {
+        const in0 = tx.inputs[0];
+        if (!in0 || in0.sourceTXID !== plan.poolUtxo.txid || in0.sourceOutputIndex !== plan.poolUtxo.vout) {
+            throw new PoolBuildError("invalid", "input 0 does not spend the pool");
+        }
+        const want = plan.outputs.length + (change ? 1 : 0);
+        if (tx.outputs.length !== want)
+            throw new PoolBuildError("invalid", `the transaction has ${tx.outputs.length} outputs, the call needs ${want}`);
+        plan.outputs.forEach((o, i) => {
+            const got = tx.outputs[i];
+            if (BigInt(got.satoshis ?? -1) !== o.satoshis || got.lockingScript.toHex() !== o.script) {
+                throw new PoolBuildError("invalid", `output ${i} is not the one the contract requires`);
+            }
+        });
+        if (change) {
+            if (!isHex(change.pkh, 20))
+                throw new PoolBuildError("invalid", "change pkh must be 20 bytes of hex");
+            const got = tx.outputs[plan.outputs.length];
+            if (got.satoshis !== change.satoshis || got.lockingScript.toHex() !== p2pkhHex(change.pkh)) {
+                throw new PoolBuildError("invalid", "the last output is not the named P2PKH change");
+            }
+        }
+        const methodIndex = METHOD_INDEX[plan.method];
+        const preimage = contractPreimage(tx, plan.pool, plan.poolUtxo.satoshis, methodIndex);
+        const hex = callUnlockHex(plan.pool, plan.method, plan.args, change?.pkh ?? "00".repeat(20), BigInt(change?.satoshis ?? 0), preimage, methodIndex);
+        return { unlockingScript: UnlockingScript.fromHex(hex), preimage, sighash: toHex(Hash.hash256(fromHex(preimage))) };
+    }
+    /**
+     * An upper bound on the length of `plan`'s pool unlocking script once every
+     * signature slot is filled: what a wallet's `createAction` is told as the
+     * pool input's `unlockingScriptLength` before the transaction exists (the
+     * fee is sized from it). The preimage's length depends only on the code, so
+     * it is exact; the change amount is bounded by 2^53.
+     */
+    static maxCallUnlockLength(plan) {
+        const tx = new Transaction();
+        tx.addInput({ sourceTXID: plan.poolUtxo.txid, sourceOutputIndex: plan.poolUtxo.vout, unlockingScript: new UnlockingScript(), sequence: 0xffffffff });
+        for (const o of plan.outputs)
+            tx.addOutput({ satoshis: Number(o.satoshis), lockingScript: LockingScript.fromHex(o.script) });
+        const methodIndex = METHOD_INDEX[plan.method];
+        const preimage = contractPreimage(tx, plan.pool, plan.poolUtxo.satoshis, methodIndex);
+        const hex = callUnlockHex(plan.pool, plan.method, plan.args, "00".repeat(20), BigInt(Number.MAX_SAFE_INTEGER), preimage, methodIndex);
+        return hex.length / 2 + Object.keys(plan.sigSlots).length * (SIG_PUSH_LEN - 1);
+    }
+    /**
+     * Close (method 1; skein-amm 0.9.0, David Case 2026-10-09: a position is deployed or closed,
+     * never resized in place), the LP's, built here: the outputs are the LP's (`outputs`), then
+     * change. No continuation.
+     */
+    static async close(p) {
+        const plan = PoolTemplate.planClose(p);
+        checkTokenInputs(p.inputs, plan.pool.args.assetId, 0n);
+        const call = await buildCall({
+            common: p,
+            pool: plan.pool,
+            method: "close",
+            outputs: plan.outputs,
+            args: plan.args,
+            sigSlots: plan.sigSlots,
+        });
+        call.next = null;
+        if (p.lpKey)
+            await PoolTemplate.signPoolInput(call, "lp", p.lpKey);
+        return call;
+    }
+    /**
+     * The Close call without its funding (as `planSwap` for Swap), the LP's slot empty
+     * (`Close(lpSig)`, outputs free): `outputs` are the LP's choice, passed through (at least one).
+     */
+    static planClose(p) {
+        const pool = decodeUtxo(p.pool);
+        const next = { pool, satoshis: 0, script: new LockingScript() };
+        if (p.outputs.length === 0)
+            throw new PoolBuildError("invalid", "a Close needs the LP's outputs");
+        return { pool, poolUtxo: p.pool, method: "close", outputs: p.outputs, args: [EMPTY_SIG], sigSlots: { lp: 0 }, next };
+    }
+    // -------------------------------------------------------------------------
+    // The pool input's signatures
+    // -------------------------------------------------------------------------
+    /**
+     * The BIP-143 preimage of `tx`'s pool input (input 0), computed from the
+     * transaction itself. Needs the pool output being spent: `source`, or input
+     * 0's `sourceTransaction`.
+     */
+    static preimage(tx, source) {
+        const in0 = tx.inputs[0];
+        if (!in0)
+            throw new Error("preimage: no input 0");
+        let satoshis;
+        let lock;
+        if (source) {
+            satoshis = source.satoshis;
+            lock = source.script;
+        }
+        else {
+            const out = in0.sourceTransaction?.outputs[in0.sourceOutputIndex];
+            satoshis = out?.satoshis;
+            lock = out?.lockingScript;
+        }
+        if (satoshis === undefined || lock === undefined)
+            throw new Error("preimage: the spent pool output is unknown");
+        const pool = PoolTemplate.decode(lock);
+        if (!pool)
+            throw new Error("preimage: input 0 does not spend a pool");
+        const call = parseCall(tx.inputs[0].unlockingScript?.toHex() ?? "");
+        const methodIndex = call ? Number(call.methodIndex) : 0;
+        return contractPreimage(tx, pool, satoshis, methodIndex);
+    }
+    /**
+     * Fills signature slot `slot` of the pool input with `signer`'s signature
+     * over the preimage recomputed from `call.tx` (which must agree with the
+     * preimage pushed in the call). Every other push is kept byte for byte;
+     * no other input's signature is affected.
+     */
+    static async signPoolInput(call, slot, signer) {
+        const tx = call.tx;
+        const unlock = tx.inputs[0].unlockingScript?.toHex() ?? "";
+        const parsed = parseCall(unlock);
+        if (!parsed)
+            throw new Error("signPoolInput: input 0 is not a pool call");
+        const methodIndex = METHOD_INDEX[call.method];
+        if (parsed.methodIndex !== BigInt(methodIndex))
+            throw new Error("signPoolInput: method index differs");
+        const satoshis = call.sourceSatoshis ?? sourceSatoshisOf(tx);
+        const preimage = contractPreimage(tx, call.pool, satoshis, methodIndex);
+        if (preimage !== parsed.preimage)
+            throw new Error("signPoolInput: the pushed preimage does not match the transaction");
+        const argIndex = SIG_SLOTS[call.method][slot];
+        if (argIndex === undefined)
+            throw new Error(`signPoolInput: ${call.method} has no ${slot} signature`);
+        const expected = slot === "validator" ? call.pool.state.validatorPubKey : call.pool.state.lpPubKey;
+        if (signer instanceof PrivateKey && signer.toPublicKey().toString() !== expected) {
+            throw new Error(`signPoolInput: that key is not the pool's ${slot} key (${expected})`);
+        }
+        const sighash = Hash.hash256(fromHex(preimage));
+        const der = signer instanceof PrivateKey ? signer.sign(Hash.sha256(fromHex(preimage))).toDER() : await signer(sighash);
+        const sigHex = toHex(der) + "41";
+        tx.inputs[0].unlockingScript = UnlockingScript.fromHex(replacePush(unlock, parsed.pushes, 1 + argIndex, encodePushData(sigHex)));
+        call.unsigned = call.unsigned.filter((s) => s !== slot);
+    }
+}
+/** Arg index of each signature, per method (Pool.runar.go's parameter order). */
+const SIG_SLOTS = {
+    swap: { validator: 0 },
+    close: { lp: 0 },
+    rescind: { validator: 0 },
+};
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function decodeUtxo(utxo) {
+    const pool = PoolTemplate.decode(utxo.script);
+    if (!pool)
+        throw new PoolBuildError("not_a_pool", `${utxo.txid}:${utxo.vout} is not a pool output`);
+    if (!Number.isSafeInteger(utxo.satoshis) || utxo.satoshis <= 0)
+        throw new PoolBuildError("invalid", "pool satoshis");
+    return pool;
+}
+function checkTokenInputs(inputs, assetId, expected) {
+    let sum = 0n;
+    for (const i of inputs) {
+        const t = decodeOneColor(fromHex(scriptHex(i.lockingScript)));
+        if (t && t.idBytes && toHex(t.idBytes) === assetId)
+            sum += t.amount;
+    }
+    if (sum !== expected) {
+        throw new PoolBuildError("token_mismatch", `token inputs carry ${sum} of the pool's token, the call needs exactly ${expected}`);
+    }
+}
+function sourceSatoshisOf(tx) {
+    const in0 = tx.inputs[0];
+    const sats = in0.sourceTransaction?.outputs[in0.sourceOutputIndex]?.satoshis;
+    if (sats === undefined)
+        throw new Error("the pool input's source satoshis are unknown");
+    return sats;
+}
+function contractPreimage(tx, pool, satoshis, methodIndex) {
+    if (!tx.inputs[0].sourceTXID) {
+        throw new Error("the pool input needs its sourceTXID");
+    }
+    const contract = RunarContract.fromUtxo(artifactOf(pool.version), {
+        txid: tx.inputs[0].sourceTXID,
+        outputIndex: tx.inputs[0].sourceOutputIndex,
+        satoshis,
+        script: pool.contractScript,
+    });
+    return contract.computeOpPushTxWithCodeSep(tx, 0, pool.contractScript, satoshis, methodIndex).preimageHex;
+}
+/** Splits a pushes-only unlocking script; null when it is not one. */
+function parseCall(hex) {
+    const pushes = [];
+    let pos = 0;
+    while (pos < hex.length) {
+        const op = parseInt(hex.slice(pos, pos + 2), 16);
+        let len;
+        let at = pos + 2;
+        if (op === 0)
+            len = 0;
+        else if (op <= 0x4b)
+            len = op;
+        else if (op === 0x4c) {
+            len = parseInt(hex.slice(at, at + 2), 16);
+            at += 2;
+        }
+        else if (op === 0x4d) {
+            len = parseInt(hex.slice(at + 2, at + 4) + hex.slice(at, at + 2), 16);
+            at += 4;
+        }
+        else if (op === 0x4e) {
+            len = parseInt(hex.slice(at + 6, at + 8) + hex.slice(at + 4, at + 6) + hex.slice(at + 2, at + 4) + hex.slice(at, at + 2), 16);
+            at += 8;
+        }
+        else if (op === 0x4f || (op >= 0x51 && op <= 0x60))
+            len = 0;
+        else
+            return null;
+        const end = at + len * 2;
+        if (end > hex.length)
+            return null;
+        pushes.push({ start: pos, end, data: hex.slice(at, end), op });
+        pos = end;
+    }
+    if (pushes.length < 3)
+        return null;
+    const sel = pushes[pushes.length - 1];
+    const methodIndex = sel.op === 0 ? 0n : sel.op >= 0x51 && sel.op <= 0x60 ? BigInt(sel.op - 0x50) : -1n;
+    return { pushes, preimage: pushes[pushes.length - 2].data, methodIndex };
+}
+function replacePush(hex, pushes, i, push) {
+    const p = pushes[i];
+    return hex.slice(0, p.start) + push + hex.slice(p.end);
+}
+/** `_codePart args… [_changePKH _changeAmount] txPreimage methodIndex`, as pushes (layout 2's Close takes no change). */
+function callUnlockHex(pool, method, args, changePkh, change, preimage, methodIndex) {
+    let hex = encodePushData(pool.code);
+    for (const a of args)
+        hex += encodeArg(a);
+    if (takesChange(pool.version, method))
+        hex += encodePushData(changePkh) + encodeArg(change);
+    return hex + encodePushData(preimage) + encodeScriptNumber(BigInt(methodIndex));
+}
+const P2PKH_UNLOCK_LEN = 107;
+const SIG_PUSH_LEN = 74; // length byte + a DER signature (<= 72) + the sighash byte
+async function buildCall(o) {
+    const { common, pool, method } = o;
+    if (!isHex(common.changePkh, 20))
+        throw new PoolBuildError("invalid", "changePkh must be 20 bytes of hex");
+    const methodIndex = METHOD_INDEX[method];
+    const totalIn = BigInt(common.pool.satoshis) + common.inputs.reduce((s, i) => s + BigInt(i.satoshis), 0n);
+    const totalOut = o.outputs.reduce((s, x) => s + x.satoshis, 0n);
+    const assemble = (change) => {
+        const tx = new Transaction();
+        tx.version = 1;
+        tx.lockTime = 0;
+        tx.addInput({
+            sourceTXID: common.pool.txid,
+            sourceOutputIndex: common.pool.vout,
+            sourceTransaction: common.pool.sourceTransaction,
+            unlockingScript: new UnlockingScript(),
+            sequence: 0xffffffff,
+        });
+        for (const i of common.inputs) {
+            tx.addInput({
+                sourceTXID: i.txid,
+                sourceOutputIndex: i.vout,
+                sourceTransaction: i.sourceTransaction,
+                unlockingScript: new UnlockingScript(),
+                sequence: 0xffffffff,
+            });
+        }
+        for (const x of o.outputs)
+            tx.addOutput({ satoshis: Number(x.satoshis), lockingScript: LockingScript.fromHex(x.script) });
+        if (change > 0n)
+            tx.addOutput({ satoshis: Number(change), lockingScript: LockingScript.fromHex(p2pkhHex(common.changePkh)) });
+        return tx;
+    };
+    const unlockFor = (tx, change) => {
+        const preimage = contractPreimage(tx, pool, common.pool.satoshis, methodIndex);
+        return { hex: callUnlockHex(pool, method, o.args, common.changePkh, change, preimage, methodIndex), preimage };
+    };
+    // The fee: fixed, or iterated to a fixed point over the finished size (the
+    // change push and output depend on the fee).
+    let fee;
+    if ("sats" in common.fee) {
+        fee = BigInt(common.fee.sats);
+    }
+    else {
+        const rate = common.fee.satsPerKb;
+        const otherUnlocks = await Promise.all(common.inputs.map(async (i) => (i.unlock ? await i.unlock.estimateLength() : (i.estimatedUnlockLength ?? P2PKH_UNLOCK_LEN))));
+        const emptySigs = Object.keys(o.sigSlots).length;
+        fee = 0n;
+        for (let round = 0; round < 4; round++) {
+            const change = totalIn - totalOut - fee;
+            const tx = assemble(change > 0n ? change : 0n);
+            const { hex } = unlockFor(tx, change > 0n ? change : 0n);
+            tx.inputs[0].unlockingScript = UnlockingScript.fromHex(hex);
+            const size = tx.toBinary().length + emptySigs * (SIG_PUSH_LEN - 1) + otherUnlocks.reduce((s, n) => s + n + (n < 0xfd ? 0 : 2), 0);
+            const next = BigInt(Math.ceil((size * rate) / 1000));
+            if (next === fee)
+                break;
+            fee = next;
+        }
+    }
+    const change = totalIn - totalOut - fee;
+    if (change < 0n) {
+        throw new PoolBuildError("insufficient_funds", `inputs ${totalIn} sats, outputs ${totalOut} + fee ${fee}`);
+    }
+    const tx = assemble(change);
+    const { hex, preimage } = unlockFor(tx, change);
+    tx.inputs[0].unlockingScript = UnlockingScript.fromHex(hex);
+    for (const [n, i] of common.inputs.entries()) {
+        if (i.unlock)
+            tx.inputs[n + 1].unlockingScript = await i.unlock.sign(tx, n + 1);
+    }
+    return {
+        tx,
+        method,
+        pool,
+        next: null,
+        preimage,
+        sighash: toHex(Hash.hash256(fromHex(preimage))),
+        unsigned: Object.keys(o.sigSlots),
+        change: Number(change),
+        fee: Number(fee),
+    };
+}
+/** A P2PKH unlocker for a builder input (also a 1Color token held on P2PKH). */
+export function p2pkhUnlock(key, satoshis, lockingScript) {
+    return new P2PKH().unlock(key, "all", false, satoshis, typeof lockingScript === "string" ? LockingScript.fromHex(lockingScript) : lockingScript);
+}