@dcasegr/amm-client 0.0.0-stage → 0.38.2

package/dist/vendor/runar/runar-sdk/src/types.d.ts

@@ -0,0 +1,227 @@
+import type { Transaction as BsvTransaction } from '@bsv/sdk';
+import type { Signer } from './signers/signer.js';
+/**
+ * Plain data shape returned by Provider.getTransaction().
+ * Renamed from `Transaction` to avoid collision with the @bsv/sdk Transaction class
+ * which is now the primary transaction type used throughout the SDK.
+ */
+export interface TransactionData {
+    txid: string;
+    version: number;
+    inputs: TxInput[];
+    outputs: TxOutput[];
+    locktime: number;
+    raw?: string;
+}
+/** Re-export @bsv/sdk Transaction as the primary transaction type. */
+export type { BsvTransaction as Transaction };
+export interface TxInput {
+    txid: string;
+    outputIndex: number;
+    script: string;
+    sequence: number;
+}
+export interface TxOutput {
+    satoshis: number;
+    script: string;
+}
+export interface UTXO {
+    txid: string;
+    outputIndex: number;
+    satoshis: number;
+    script: string;
+}
+export interface DeployOptions {
+    /** Satoshis to lock in the contract UTXO. Defaults to 1. */
+    satoshis?: number;
+    changeAddress?: string;
+    /**
+     * Signer for the P2PKH funding inputs (issue #134). When the funding UTXOs
+     * are owned by a different key than the connected deploy signer, set this so
+     * the funding inputs are signed by their real owner. Defaults to the
+     * connected signer (zero behaviour change).
+     */
+    fundingSigner?: Signer;
+    /**
+     * Builtins the caller accepts despite the compiler not claiming they are
+     * sound (R-062). Required — naming each one — when the artifact declares
+     * `unsoundPrimitives`; ignored otherwise. See `unsound-primitives.ts`.
+     */
+    acknowledgeUnsound?: string[];
+}
+/**
+ * Result of `prepareCall()` — contains everything needed for external signing
+ * and subsequent `finalizeCall()`.
+ *
+ * Public fields (`sighash`, `preimage`, `opPushTxSig`, `tx`, `sigIndices`)
+ * are for external signer coordination. Fields prefixed with `_` are opaque
+ * internals consumed by `finalizeCall()`.
+ */
+export interface PreparedCall {
+    /**
+     * BIP-143 sighash (hex) — `hash256(preimage)`, i.e. `sha256(sha256(...))`.
+     * External signers ECDSA-sign these 32 bytes DIRECTLY, with no further
+     * hashing (see `WalletSigner.signHash`).
+     */
+    sighash: string;
+    /** Full BIP-143 preimage (hex). */
+    preimage: string;
+    /** OP_PUSH_TX DER signature + sighash byte (hex). Empty if not needed. */
+    opPushTxSig: string;
+    /** Built transaction (P2PKH funding signed, primary contract input uses placeholder sigs). */
+    tx: BsvTransaction;
+    /** User-visible arg positions that need external Sig values. */
+    sigIndices: number[];
+    /** @internal */ _methodName: string;
+    /** @internal */ _resolvedArgs: unknown[];
+    /** @internal */ _methodSelectorHex: string;
+    /** @internal */ _isStateful: boolean;
+    /**
+     * @internal
+     * True when the contract extends StatefulSmartContract (from artifact
+     * `parentClass`), independent of whether it has mutable state fields.
+     * Gates the issue-#42/#44 terminal sighash subscript trim: a stateful
+     * contract with ZERO mutable fields still auto-injects checkPreimage at
+     * method entry, so its user checkSig runs after the OP_CODESEPARATOR.
+     */
+    _parentStateful: boolean;
+    /** @internal */ _isTerminal: boolean;
+    /** @internal */ _needsOpPushTx: boolean;
+    /** @internal */ _methodNeedsChange: boolean;
+    /** @internal Whether the unlocking script is prefixed with `_codePart` (issue #100). */ _methodUsesCodePart?: boolean;
+    /** @internal */ _changePKHHex: string;
+    /** @internal */ _changeAmount: number;
+    /** @internal */ _methodNeedsNewAmount: boolean;
+    /** @internal */ _newAmount: number;
+    /** @internal */ _preimageIndex: number;
+    /** @internal */ _contractUtxo: UTXO;
+    /** @internal */ _newLockingScript: string;
+    /** @internal */ _newSatoshis: number;
+    /** @internal */ _hasMultiOutput: boolean;
+    /** @internal */ _contractOutputs: Array<{
+        script: string;
+        satoshis: number;
+    }>;
+    /**
+     * @internal
+     * Pre-resolved intent-intrinsic witness hex (PUSHDATA-encoded
+     * `_prevOutScript_*` followed by `_serialisedOutputs`, ABI order).
+     * Empty when the method has no auto-injected intent params.
+     */
+    _intentWitnessHex: string;
+}
+export interface CallOptions {
+    satoshis?: number;
+    changeAddress?: string;
+    /** Override the public key used for the change output (hex-encoded).
+     *  Defaults to the signer's public key. */
+    changePubKey?: string;
+    /** New state values for the continuation output (stateful contracts). */
+    newState?: Record<string, unknown>;
+    /**
+     * Multiple continuation outputs for multi-output methods (e.g., `transfer`).
+     * Each entry specifies the satoshis and state for one output UTXO.
+     * When provided, replaces the single continuation output from `newState`.
+     */
+    outputs?: Array<{
+        satoshis: number;
+        state: Record<string, unknown>;
+    }>;
+    /**
+     * Additional contract UTXOs to include as inputs (e.g., for merge, swap,
+     * or any multi-input spending pattern). Each UTXO's unlocking script uses
+     * the same method as the primary call, with OP_PUSH_TX and Sig
+     * auto-computed per input.
+     */
+    additionalContractInputs?: UTXO[];
+    /**
+     * Per-input args for additional contract inputs. When provided,
+     * `additionalContractInputArgs[i]` overrides the args for
+     * `additionalContractInputs[i]`. Sig params (null) are still
+     * auto-computed per input.
+     *
+     * If not provided, all additional inputs use the same args as the
+     * primary call.
+     */
+    additionalContractInputArgs?: unknown[][];
+    /**
+     * Terminal outputs for methods that verify exact output structure via
+     * extractOutputHash(). When set, the transaction is built with ONLY
+     * the contract UTXO as input (no funding inputs, no change output).
+     * The fee comes from the contract balance. The contract is considered
+     * fully spent after this call (currentUtxo becomes null).
+     *
+     * Each output specifies the exact locking script hex and satoshis.
+     */
+    terminalOutputs?: Array<{
+        scriptHex: string;
+        satoshis: number;
+    }>;
+    /**
+     * Additional funding UTXOs to include as P2PKH inputs for terminal
+     * method calls. Enables terminal methods to receive additional funds
+     * when the contract's own balance is insufficient for outputs + fees.
+     */
+    fundingUtxos?: UTXO[];
+    /**
+     * A single plain P2PKH UTXO added to a terminal call tx purely to pay the
+     * miner fee (issue #118). A true terminal method pays out the full contract
+     * balance, so fee would be 0 and ARC rejects; the covenant asserts its exact
+     * output set, so no change output can absorb a fee. The fee input is added
+     * BEFORE the OP_PUSH_TX preimage is computed (so hashPrevouts covers it) and
+     * is consumed entirely as fee — no change output is created. Signed with
+     * `fundingSigner ?? signer`. The covenant's output assertions are untouched.
+     *
+     * IMPORTANT: because there is no change output, the ENTIRE feeUtxo is spent
+     * as fee — any amount beyond the actual miner fee is BURNED, not returned.
+     * Size the feeUtxo close to the intended fee (a few hundred sats at the BSV
+     * standard 0.1 sat/byte is typical for a small terminal tx). The SDK emits a
+     * `console.warn` when the supplied feeUtxo dwarfs the terminal tx's estimated
+     * fee (> 5x and > ~1000 sats of excess), so an accidental large coin is
+     * caught before broadcast.
+     */
+    feeUtxo?: UTXO;
+    /**
+     * Optional explicit override for data outputs emitted via
+     * `this.addDataOutput(...)` in the method body. When omitted, the SDK
+     * resolves data outputs automatically by running the ANF interpreter on
+     * the method body (the common case). Pass a non-empty array to bypass
+     * the interpreter.
+     */
+    dataOutputs?: Array<{
+        script: string;
+        satoshis: number | bigint;
+    }>;
+    /**
+     * Override the call tx's nLockTime field. Defaults to unset → SDK uses 0
+     * (legacy behavior, preserves existing contracts). Set for contracts that
+     * assert `extractLocktime(preimage) >= deadline` (e.g. auction close/claim).
+     * Threaded through both the non-terminal and terminal call-tx build sites.
+     */
+    locktime?: number;
+    /**
+     * Override the nSequence written onto EVERY input of the call tx (issue #131).
+     * Defaults are zero-config: when `locktime` is set and non-zero, sequence
+     * defaults to 0xfffffffe (non-final, so consensus actually enforces
+     * nLockTime); otherwise it stays 0xffffffff (final, legacy). Set explicitly
+     * only for RBF or custom relative-locktime scenarios. Threaded through the
+     * non-terminal and terminal call-tx build sites.
+     */
+    sequence?: number;
+    /**
+     * Cap the number of P2PKH funding inputs added to a non-terminal call tx
+     * (issue #133). Funding is chosen by smallest-sufficient, largest-first
+     * selection (the same `selectUtxos` strategy deploy uses). If covering the
+     * outputs + fee would need more than this many inputs, the call throws
+     * rather than silently sweeping the wallet. Unset → no cap.
+     */
+    maxFundingInputs?: number;
+    /**
+     * Signer for the P2PKH funding (and terminal fee) inputs (issue #134). When
+     * the funding/fee UTXOs are owned by a different key than the connected
+     * method signer, set this so those inputs are signed by their real owner.
+     * The method's own `Sig` args are still signed by the connected signer.
+     * Defaults to the connected signer (zero behaviour change).
+     */
+    fundingSigner?: Signer;
+}

package/dist/vendor/runar/runar-sdk/src/types.js

@@ -0,0 +1,4 @@
+// ---------------------------------------------------------------------------
+// runar-sdk/types.ts — Shared types for on-chain interaction
+// ---------------------------------------------------------------------------
+export {};

package/dist/vendor/runar/runar-sdk/src/unsound-primitives.d.ts

@@ -0,0 +1,30 @@
+/**
+ * R-062 / CL-BUG-105 — deploy-time gate on builtins the project does not claim
+ * are sound.
+ *
+ * The compiler refuses to emit a script reaching `verifySP1FRI` unless the
+ * author wrote `@acknowledgeUnsoundSP1FriVerifier` or the invoker passed
+ * `--acknowledge-unsound-sp1-fri` (R-012). That acknowledgement stopped at
+ * whoever ran the compiler: the artifact handed on afterwards looked like any
+ * other, carried no marker of the gap, and every SDK funded it in silence —
+ * which is how an acknowledged proof-of-concept verifier reaches a
+ * value-bearing deployment with no friction.
+ *
+ * The compiler now stamps `unsoundPrimitives` into the artifact. This guard is
+ * the SDK half: every deploy path calls it BEFORE any signing or broadcast, and
+ * the caller must name each listed primitive to proceed.
+ *
+ * Deploy only, deliberately. Spending an already-deployed contract is how funds
+ * are RECOVERED from one, and refusing that would strand coins whose risk was
+ * taken at deploy time. The friction belongs where the value first enters.
+ */
+import type { RunarArtifact } from '../../../../pool/runar-ir-schema.js';
+/**
+ * Throw unless every unsound primitive the artifact declares appears in
+ * `acknowledged`.
+ *
+ * @param artifact     the artifact about to be funded
+ * @param acknowledged primitives the caller explicitly accepts (DeployOptions.acknowledgeUnsound)
+ * @param context      call site for the message, e.g. `"Counter.deploy"`
+ */
+export declare function assertUnsoundPrimitivesAcknowledged(artifact: RunarArtifact, acknowledged: readonly string[] | undefined, context: string): void;

package/dist/vendor/runar/runar-sdk/src/unsound-primitives.js

@@ -0,0 +1,42 @@
+/**
+ * R-062 / CL-BUG-105 — deploy-time gate on builtins the project does not claim
+ * are sound.
+ *
+ * The compiler refuses to emit a script reaching `verifySP1FRI` unless the
+ * author wrote `@acknowledgeUnsoundSP1FriVerifier` or the invoker passed
+ * `--acknowledge-unsound-sp1-fri` (R-012). That acknowledgement stopped at
+ * whoever ran the compiler: the artifact handed on afterwards looked like any
+ * other, carried no marker of the gap, and every SDK funded it in silence —
+ * which is how an acknowledged proof-of-concept verifier reaches a
+ * value-bearing deployment with no friction.
+ *
+ * The compiler now stamps `unsoundPrimitives` into the artifact. This guard is
+ * the SDK half: every deploy path calls it BEFORE any signing or broadcast, and
+ * the caller must name each listed primitive to proceed.
+ *
+ * Deploy only, deliberately. Spending an already-deployed contract is how funds
+ * are RECOVERED from one, and refusing that would strand coins whose risk was
+ * taken at deploy time. The friction belongs where the value first enters.
+ */
+/**
+ * Throw unless every unsound primitive the artifact declares appears in
+ * `acknowledged`.
+ *
+ * @param artifact     the artifact about to be funded
+ * @param acknowledged primitives the caller explicitly accepts (DeployOptions.acknowledgeUnsound)
+ * @param context      call site for the message, e.g. `"Counter.deploy"`
+ */
+export function assertUnsoundPrimitivesAcknowledged(artifact, acknowledged, context) {
+    const declared = artifact.unsoundPrimitives ?? [];
+    if (declared.length === 0)
+        return;
+    const ok = new Set(acknowledged ?? []);
+    const missing = declared.filter((p) => !ok.has(p));
+    if (missing.length === 0)
+        return;
+    throw new Error(`${context}: this artifact reaches ${missing.length} builtin${missing.length === 1 ? '' : 's'} ` +
+        `the compiler does not claim is sound: ${missing.join(', ')}. ` +
+        `The compiler emitted it only because the gap was acknowledged at COMPILE time; ` +
+        `funding it is a second decision, and this SDK will not make it for you. ` +
+        `Pass acknowledgeUnsound: [${missing.map((p) => `'${p}'`).join(', ')}] to proceed.`);
+}

package/dist/vendor/runar/runar-sdk.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The runar-sdk names the Pool template uses (src/pool/template.ts, src/pool/artifact.ts), from
+ * the vendored modules beside this file (`runar-sdk/src`, runar d207ee8e; NOTICE). runar-sdk's
+ * own barrel also re-exports its providers, signers and codegen, which are not vendored.
+ */
+export { EMPTY_SIG, RunarContract, encodeArg, encodePushData, encodeScriptNumber } from "./runar-sdk/src/contract.js";
+export { extractConstructorArgs, matchesArtifact } from "./runar-sdk/src/script-utils.js";
+export { extractStateFromScript, findLastOpReturn, serializeState } from "./runar-sdk/src/state.js";
+export type { RunarArtifact } from "../../pool/runar-ir-schema.js";

package/dist/vendor/runar/runar-sdk.js

@@ -0,0 +1,8 @@
+/**
+ * The runar-sdk names the Pool template uses (src/pool/template.ts, src/pool/artifact.ts), from
+ * the vendored modules beside this file (`runar-sdk/src`, runar d207ee8e; NOTICE). runar-sdk's
+ * own barrel also re-exports its providers, signers and codegen, which are not vendored.
+ */
+export { EMPTY_SIG, RunarContract, encodeArg, encodePushData, encodeScriptNumber } from "./runar-sdk/src/contract.js";
+export { extractConstructorArgs, matchesArtifact } from "./runar-sdk/src/script-utils.js";
+export { extractStateFromScript, findLastOpReturn, serializeState } from "./runar-sdk/src/state.js";

package/dist/wallet/action.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A wallet-built action whose inputs the page unlocks (skein-amm 0.29.0, David Case 2026-11-02:
+ * Move back and Close are wallet createActions). The page names the inputs it spends (an
+ * `amm-swap` output, a pool), their source transactions (`inputBEEF`) and the outputs; the wallet
+ * adds its own inputs for the miner fee and its change, and hands the transaction back for
+ * signing (BRC-100: an input with `unlockingScriptLength` and no `unlockingScript`). The page
+ * computes its unlocking scripts over that transaction (`createSignature` under the key each
+ * input's row names) and passes them to `signAction`; the wallet signs its own inputs,
+ * broadcasts, and records the action, every output with the customInstructions the page gave it.
+ * Aborted when anything fails before the wallet has the signatures.
+ */
+import { Transaction, type CreateActionArgs, type WalletInterface } from "@bsv/sdk";
+export type Spends = Record<number, {
+    unlockingScript: string;
+}>;
+export interface SignedAction {
+    txid: string;
+    /** The signed transaction as the wallet's AtomicBEEF. */
+    tx: number[];
+}
+/**
+ * `createAction(args)` → `sign(the wallet's transaction)` → `signAction({reference, spends})`.
+ * `sign` gets the unsigned transaction with every input's source transaction linked (the
+ * signable BEEF) and answers the page's unlocking scripts by input index.
+ */
+export declare function runAppSignedAction(wallet: WalletInterface, args: CreateActionArgs, sign: (tx: Transaction) => Promise<Spends>): Promise<SignedAction>;
+/** The index of the input spending `txid.vout` in `tx`, or -1. */
+export declare function inputIndexOf(tx: Transaction, txid: string, vout: number): number;

package/dist/wallet/action.js

@@ -0,0 +1,42 @@
+/**
+ * A wallet-built action whose inputs the page unlocks (skein-amm 0.29.0, David Case 2026-11-02:
+ * Move back and Close are wallet createActions). The page names the inputs it spends (an
+ * `amm-swap` output, a pool), their source transactions (`inputBEEF`) and the outputs; the wallet
+ * adds its own inputs for the miner fee and its change, and hands the transaction back for
+ * signing (BRC-100: an input with `unlockingScriptLength` and no `unlockingScript`). The page
+ * computes its unlocking scripts over that transaction (`createSignature` under the key each
+ * input's row names) and passes them to `signAction`; the wallet signs its own inputs,
+ * broadcasts, and records the action, every output with the customInstructions the page gave it.
+ * Aborted when anything fails before the wallet has the signatures.
+ */
+import { Transaction } from "@bsv/sdk";
+/**
+ * `createAction(args)` → `sign(the wallet's transaction)` → `signAction({reference, spends})`.
+ * `sign` gets the unsigned transaction with every input's source transaction linked (the
+ * signable BEEF) and answers the page's unlocking scripts by input index.
+ */
+export async function runAppSignedAction(wallet, args, sign) {
+    const created = await wallet.createAction(args);
+    const signable = created.signableTransaction;
+    if (!signable)
+        throw new Error("the wallet did not hand the transaction back for the page's signatures");
+    const reference = signable.reference;
+    try {
+        const tx = Transaction.fromAtomicBEEF(Array.from(signable.tx));
+        for (const input of tx.inputs)
+            input.sourceTXID ??= input.sourceTransaction?.id("hex");
+        const spends = await sign(tx);
+        const signed = await wallet.signAction({ reference, spends, ...(args.options?.acceptDelayedBroadcast !== undefined ? { options: { acceptDelayedBroadcast: args.options.acceptDelayedBroadcast } } : {}) });
+        if (!signed.txid || !signed.tx)
+            throw new Error("the wallet returned no signed transaction");
+        return { txid: signed.txid, tx: Array.from(signed.tx) };
+    }
+    catch (err) {
+        await wallet.abortAction({ reference }).catch(() => undefined);
+        throw err;
+    }
+}
+/** The index of the input spending `txid.vout` in `tx`, or -1. */
+export function inputIndexOf(tx, txid, vout) {
+    return tx.inputs.findIndex((i) => (i.sourceTXID ?? i.sourceTransaction?.id("hex")) === txid && i.sourceOutputIndex === vout);
+}

package/dist/wallet/brc29.d.ts

@@ -0,0 +1,83 @@
+/**
+ * BRC-29 ("wallet payment") outputs to the user's own wallet: the sats a
+ * user receives from a pool (a token-in swap's payout, a RemoveLiquidity
+ * sats withdrawal). No basket: the wallet does not track the output when the
+ * action is created; it takes it in with `internalizeAction({protocol:
+ * "wallet payment", paymentRemittance})` once the transaction is final, and
+ * from then on spends it as its own change.
+ *
+ * The derivation, as wallet-toolbox checks it
+ * (src/signer/methods/internalizeAction.ts `setupWalletPaymentForOutput`):
+ *
+ *   keyID   = `${derivationPrefix} ${derivationSuffix}`
+ *   privKey = keyDeriver.derivePrivateKey([2, "3241645161d8"], keyID, senderIdentityKey)
+ *   lock    = P2PKH(privKey.toAddress())
+ *
+ * The page is both payer-side author and payee, so senderIdentityKey is the
+ * user's own identity key. The payee side of that derivation is
+ * `rootKey.deriveChild(identityPub, invoice)`; the page asks for the same
+ * key with `getPublicKey({protocolID: BRC29, keyID, counterparty: "self",
+ * forSelf: true})`, which is `rootKey.deriveChild(rootKey.toPublicKey(),
+ * invoice).toPublicKey()` (@bsv/sdk KeyDeriver: `normalizeCounterparty("self")`
+ * is `rootKey.toPublicKey()`, which is the identity key). "self" rather than
+ * the identity key's hex, because WalletPermissionsManager keys level-2
+ * grants by the exact counterparty string and the manifest can only name
+ * "self" (public/manifest.json, README "Permissions"). With counterparty =
+ * self, forSelf true and false give the same key (the ECDH secret is
+ * root·root·G either way).
+ */
+import { type WalletInterface, type WalletProtocol } from "@bsv/sdk";
+export declare const BRC29_PROTOCOL: WalletProtocol;
+export declare const WALLET_PAYMENT: "wallet payment";
+export interface PaymentRemittance {
+    derivationPrefix: string;
+    derivationSuffix: string;
+    senderIdentityKey: string;
+}
+/** A BRC-29 payout as the page records it: the output, its remittance. */
+export interface Brc29Payout {
+    outputIndex: number;
+    satoshis: number;
+    /** P2PKH to the derived key, hex. */
+    lockingScript: string;
+    remittance: PaymentRemittance;
+}
+/** Random base64, as wallet-toolbox's `randomBytesBase64(8)` for a payment's prefix and suffix. */
+export declare function randomBase64(bytes?: number): string;
+export declare function brc29KeyID(r: {
+    derivationPrefix: string;
+    derivationSuffix: string;
+}): string;
+/** `${prefix} ${suffix}` → the two parts, or null (base64 has no spaces). */
+export declare function splitBrc29KeyID(keyID: string): {
+    derivationPrefix: string;
+    derivationSuffix: string;
+} | null;
+export declare function isBrc29Protocol(p: WalletProtocol | readonly unknown[] | undefined): boolean;
+/** The user's identity key (one `getPublicKey({identityKey: true})`). */
+export declare function identityKeyOf(wallet: WalletInterface): Promise<string>;
+/** The payee key of a BRC-29 payment to self (see the module comment). */
+export declare function brc29PublicKey(wallet: WalletInterface, r: {
+    derivationPrefix: string;
+    derivationSuffix: string;
+}): Promise<string>;
+export declare function p2pkhHexOf(publicKey: string): string;
+/** A payout key: random prefix and suffix unless `derivation` names them (0.29.1: a swap leg's, derived from its input), sender = the user's identity. */
+export declare function newBrc29Payout(wallet: WalletInterface, identityKey?: string, derivation?: {
+    derivationPrefix: string;
+    derivationSuffix: string;
+}): Promise<{
+    remittance: PaymentRemittance;
+    publicKey: string;
+    lockingScript: string;
+}>;
+/**
+ * The final step: the wallet takes the payout in. `atomicBeef` is the
+ * AtomicBEEF of the final transaction (all signatures in).
+ */
+export declare function internalizePayout(wallet: WalletInterface, atomicBeef: number[], payout: {
+    outputIndex: number;
+    remittance: PaymentRemittance;
+}, description: string): Promise<{
+    accepted: boolean;
+}>;

package/dist/wallet/brc29.js

@@ -0,0 +1,80 @@
+/**
+ * BRC-29 ("wallet payment") outputs to the user's own wallet: the sats a
+ * user receives from a pool (a token-in swap's payout, a RemoveLiquidity
+ * sats withdrawal). No basket: the wallet does not track the output when the
+ * action is created; it takes it in with `internalizeAction({protocol:
+ * "wallet payment", paymentRemittance})` once the transaction is final, and
+ * from then on spends it as its own change.
+ *
+ * The derivation, as wallet-toolbox checks it
+ * (src/signer/methods/internalizeAction.ts `setupWalletPaymentForOutput`):
+ *
+ *   keyID   = `${derivationPrefix} ${derivationSuffix}`
+ *   privKey = keyDeriver.derivePrivateKey([2, "3241645161d8"], keyID, senderIdentityKey)
+ *   lock    = P2PKH(privKey.toAddress())
+ *
+ * The page is both payer-side author and payee, so senderIdentityKey is the
+ * user's own identity key. The payee side of that derivation is
+ * `rootKey.deriveChild(identityPub, invoice)`; the page asks for the same
+ * key with `getPublicKey({protocolID: BRC29, keyID, counterparty: "self",
+ * forSelf: true})`, which is `rootKey.deriveChild(rootKey.toPublicKey(),
+ * invoice).toPublicKey()` (@bsv/sdk KeyDeriver: `normalizeCounterparty("self")`
+ * is `rootKey.toPublicKey()`, which is the identity key). "self" rather than
+ * the identity key's hex, because WalletPermissionsManager keys level-2
+ * grants by the exact counterparty string and the manifest can only name
+ * "self" (public/manifest.json, README "Permissions"). With counterparty =
+ * self, forSelf true and false give the same key (the ECDH secret is
+ * root·root·G either way).
+ */
+import { P2PKH, PublicKey, Utils } from "@bsv/sdk";
+export const BRC29_PROTOCOL = [2, "3241645161d8"];
+export const WALLET_PAYMENT = "wallet payment";
+/** Random base64, as wallet-toolbox's `randomBytesBase64(8)` for a payment's prefix and suffix. */
+export function randomBase64(bytes = 8) {
+    return Utils.toBase64(Array.from(crypto.getRandomValues(new Uint8Array(bytes))));
+}
+export function brc29KeyID(r) {
+    return `${r.derivationPrefix} ${r.derivationSuffix}`;
+}
+/** `${prefix} ${suffix}` → the two parts, or null (base64 has no spaces). */
+export function splitBrc29KeyID(keyID) {
+    const parts = keyID.split(" ");
+    if (parts.length !== 2 || !parts[0] || !parts[1])
+        return null;
+    return { derivationPrefix: parts[0], derivationSuffix: parts[1] };
+}
+export function isBrc29Protocol(p) {
+    return Array.isArray(p) && p[0] === BRC29_PROTOCOL[0] && p[1] === BRC29_PROTOCOL[1];
+}
+/** The user's identity key (one `getPublicKey({identityKey: true})`). */
+export async function identityKeyOf(wallet) {
+    return (await wallet.getPublicKey({ identityKey: true })).publicKey;
+}
+/** The payee key of a BRC-29 payment to self (see the module comment). */
+export async function brc29PublicKey(wallet, r) {
+    const { publicKey } = await wallet.getPublicKey({ protocolID: BRC29_PROTOCOL, keyID: brc29KeyID(r), counterparty: "self", forSelf: true });
+    return publicKey;
+}
+export function p2pkhHexOf(publicKey) {
+    return new P2PKH().lock(PublicKey.fromString(publicKey).toAddress()).toHex();
+}
+/** A payout key: random prefix and suffix unless `derivation` names them (0.29.1: a swap leg's, derived from its input), sender = the user's identity. */
+export async function newBrc29Payout(wallet, identityKey, derivation) {
+    const senderIdentityKey = identityKey ?? (await identityKeyOf(wallet));
+    const remittance = { derivationPrefix: derivation?.derivationPrefix ?? randomBase64(), derivationSuffix: derivation?.derivationSuffix ?? randomBase64(), senderIdentityKey };
+    const publicKey = await brc29PublicKey(wallet, remittance);
+    return { remittance, publicKey, lockingScript: p2pkhHexOf(publicKey) };
+}
+/**
+ * The final step: the wallet takes the payout in. `atomicBeef` is the
+ * AtomicBEEF of the final transaction (all signatures in).
+ */
+export async function internalizePayout(wallet, atomicBeef, payout, description) {
+    const r = await wallet.internalizeAction({
+        tx: atomicBeef,
+        outputs: [{ outputIndex: payout.outputIndex, protocol: WALLET_PAYMENT, paymentRemittance: { ...payout.remittance } }],
+        description: description.length <= 50 ? description : `${description.slice(0, 49)}…`,
+        labels: ["amm-payout"],
+    });
+    return { accepted: r.accepted };
+}