bsv-pay-cli 0.2.0

package/dist/tx.d.ts

@@ -0,0 +1,29 @@
+import { Transaction } from '@bsv/sdk';
+import type { Utxo } from './chain/provider.js';
+import type { Wallet } from './wallet/wallet.js';
+/** A UTXO annotated with the wallet address that owns it. */
+export interface SpendableUtxo extends Utxo {
+    address: string;
+}
+/**
+ * Outputs below this are not worth creating as change — spending a P2PKH
+ * input costs ~148 bytes, so tiny change is folded into the fee instead.
+ */
+export declare const DUST_LIMIT_SATS = 135;
+/** Standard P2PKH size estimate: 10 overhead + 148/input + 34/output. */
+export declare function estimateTxSizeBytes(nIn: number, nOut: number): number;
+export declare function feeForTx(nIn: number, nOut: number, rateSatsPerKb: number): number;
+export interface Selection {
+    selected: SpendableUtxo[];
+    fee: number;
+    /** 0 when change was folded into the fee (sub-dust). */
+    changeSats: number;
+}
+/**
+ * Largest-first selection with a fee feedback loop. Assumes 2 outputs
+ * (recipient + change); sub-dust change is folded into the fee.
+ * Throws exit 3 when funds cannot cover amount + fee.
+ */
+export declare function selectUtxos(utxos: SpendableUtxo[], amountSats: number, rateSatsPerKb: number): Selection;
+/** Build and sign a P2PKH transaction spending the selection. */
+export declare function buildSignedTx(wallet: Wallet, selection: Selection, recipientAddress: string, amountSats: number, changeAddress: string): Promise<Transaction>;

package/dist/tx.js

@@ -0,0 +1,68 @@
+import { P2PKH, Transaction } from '@bsv/sdk';
+import { CliError, EXIT } from './errors.js';
+import { formatSats } from './units.js';
+/**
+ * Outputs below this are not worth creating as change — spending a P2PKH
+ * input costs ~148 bytes, so tiny change is folded into the fee instead.
+ */
+export const DUST_LIMIT_SATS = 135;
+/** Standard P2PKH size estimate: 10 overhead + 148/input + 34/output. */
+export function estimateTxSizeBytes(nIn, nOut) {
+    return 10 + 148 * nIn + 34 * nOut;
+}
+export function feeForTx(nIn, nOut, rateSatsPerKb) {
+    return Math.max(1, Math.ceil((estimateTxSizeBytes(nIn, nOut) * rateSatsPerKb) / 1000));
+}
+/**
+ * Largest-first selection with a fee feedback loop. Assumes 2 outputs
+ * (recipient + change); sub-dust change is folded into the fee.
+ * Throws exit 3 when funds cannot cover amount + fee.
+ */
+export function selectUtxos(utxos, amountSats, rateSatsPerKb) {
+    const pool = [...utxos].sort((a, b) => b.satoshis - a.satoshis);
+    const selected = [];
+    let total = 0;
+    for (const utxo of pool) {
+        selected.push(utxo);
+        total += utxo.satoshis;
+        const fee = feeForTx(selected.length, 2, rateSatsPerKb);
+        if (total >= amountSats + fee) {
+            const change = total - amountSats - fee;
+            if (change < DUST_LIMIT_SATS) {
+                // fold sub-dust change into the fee (single-output tx)
+                return { selected, fee: total - amountSats, changeSats: 0 };
+            }
+            return { selected, fee, changeSats: change };
+        }
+    }
+    const available = utxos.reduce((s, u) => s + u.satoshis, 0);
+    const feeGuess = feeForTx(Math.max(1, utxos.length), 2, rateSatsPerKb);
+    throw new CliError(EXIT.INSUFFICIENT_FUNDS, 'insufficient_funds', `Insufficient funds: trying to send ${formatSats(amountSats)} plus ~${feeGuess} sats fee, ` +
+        `but only ${formatSats(available)} is spendable. Fund the wallet or send less.`, { available_sats: available, needed_sats: amountSats + feeGuess });
+}
+/** Build and sign a P2PKH transaction spending the selection. */
+export async function buildSignedTx(wallet, selection, recipientAddress, amountSats, changeAddress) {
+    const tx = new Transaction();
+    for (const utxo of selection.selected) {
+        const key = wallet.privKeyForAddress(utxo.address);
+        if (!key) {
+            throw new CliError(EXIT.UNEXPECTED, 'missing_key', `No signing key for tracked address ${utxo.address}.`);
+        }
+        const sourceLock = new P2PKH().lock(utxo.address);
+        tx.addInput({
+            sourceTXID: utxo.txid,
+            sourceOutputIndex: utxo.vout,
+            unlockingScriptTemplate: new P2PKH().unlock(key, 'all', false, utxo.satoshis, sourceLock),
+            sequence: 0xffffffff,
+        });
+    }
+    tx.addOutput({ lockingScript: new P2PKH().lock(recipientAddress), satoshis: amountSats });
+    if (selection.changeSats > 0) {
+        tx.addOutput({
+            lockingScript: new P2PKH().lock(changeAddress),
+            satoshis: selection.changeSats,
+        });
+    }
+    await tx.sign();
+    return tx;
+}

package/dist/units.d.ts

@@ -0,0 +1,13 @@
+export declare const SATS_PER_BSV = 100000000;
+/**
+ * Parse a user-supplied amount into satoshis.
+ *
+ * Rules (invariant 1): bare integers are satoshis; `sats` and `bsv` suffixes
+ * are accepted (case-insensitive, optional space before suffix). Anything
+ * ambiguous or unparseable throws a usage error (exit 2) — never guess.
+ */
+export declare function parseAmount(input: string): number;
+/** Format satoshis for human output, e.g. "5,000 sats (0.00005 BSV)". */
+export declare function formatSats(sats: number): string;
+/** Satoshis -> BSV decimal string (for BIP-21 URIs). */
+export declare function satsToBsvString(sats: number): string;

package/dist/units.js

@@ -0,0 +1,53 @@
+import { usageError } from './errors.js';
+export const SATS_PER_BSV = 100_000_000;
+/**
+ * Parse a user-supplied amount into satoshis.
+ *
+ * Rules (invariant 1): bare integers are satoshis; `sats` and `bsv` suffixes
+ * are accepted (case-insensitive, optional space before suffix). Anything
+ * ambiguous or unparseable throws a usage error (exit 2) — never guess.
+ */
+export function parseAmount(input) {
+    const raw = input.trim();
+    if (raw === '')
+        throw usageError('invalid_amount', 'Amount is empty. Pass satoshis (e.g. 5000), 5000sats, or 0.0001bsv.');
+    const m = /^([0-9]+(?:\.[0-9]+)?)\s*(sats?|bsv)?$/i.exec(raw);
+    if (!m || !m[1]) {
+        throw usageError('invalid_amount', `Cannot parse amount "${input}". Use bare satoshis (5000), a sats suffix (5000sats), or a bsv suffix (0.0001bsv).`);
+    }
+    const numberPart = m[1];
+    const suffix = (m[2] ?? '').toLowerCase();
+    let sats;
+    if (suffix === 'bsv') {
+        const [whole = '0', frac = ''] = numberPart.split('.');
+        if (frac.length > 8) {
+            throw usageError('invalid_amount', `"${input}" has more than 8 decimal places — BSV is divisible to 8 places (1 satoshi). Reduce the precision.`);
+        }
+        sats = Number(whole) * SATS_PER_BSV + Number(frac.padEnd(8, '0') || '0');
+    }
+    else {
+        // bare or sats suffix: must be an integer count of satoshis
+        if (numberPart.includes('.')) {
+            throw usageError('invalid_amount', `"${input}" is fractional but satoshis are indivisible. Use a whole number of sats or a bsv suffix (e.g. 0.0001bsv).`);
+        }
+        sats = Number(numberPart);
+    }
+    if (!Number.isSafeInteger(sats)) {
+        throw usageError('invalid_amount', `Amount "${input}" is too large to represent safely.`);
+    }
+    if (sats <= 0) {
+        throw usageError('invalid_amount', `Amount must be greater than zero (got "${input}").`);
+    }
+    return sats;
+}
+/** Format satoshis for human output, e.g. "5,000 sats (0.00005 BSV)". */
+export function formatSats(sats) {
+    const bsv = (sats / SATS_PER_BSV).toFixed(8).replace(/0+$/, '').replace(/\.$/, '');
+    return `${sats.toLocaleString('en-US')} sats (${bsv} BSV)`;
+}
+/** Satoshis -> BSV decimal string (for BIP-21 URIs). */
+export function satsToBsvString(sats) {
+    const whole = Math.floor(sats / SATS_PER_BSV);
+    const frac = (sats % SATS_PER_BSV).toString().padStart(8, '0').replace(/0+$/, '');
+    return frac ? `${whole}.${frac}` : `${whole}`;
+}

package/dist/wallet/brc100.d.ts

@@ -0,0 +1,105 @@
+import type { CreateActionArgs, CreateActionResult, ListOutputsArgs, ListOutputsResult } from '@bsv/sdk';
+import { CliError } from '../errors.js';
+import type { Network } from '../paths.js';
+/**
+ * BRC-100 custody backend (EXPERIMENTAL — Phase 2 M12). Keys live in an
+ * external wallet app (BSV Desktop / Metanet Desktop); bsv-pay constructs
+ * actions and the external wallet funds, signs, and broadcasts them.
+ *
+ * The policy engine stays IN FRONT of external custody: the policy gate in
+ * core decides and ledgers every spend BEFORE anything reaches this module
+ * (invariant 2), exactly as for local-seed wallets. The connection handle
+ * is key-capable by proxy — it can make the external wallet sign — so it
+ * never crosses the core boundary (invariant 1 extended to wallet handles):
+ * this module hands out txids, amounts, and addresses only.
+ */
+/** Default JSON-API endpoint exposed by BSV Desktop / Metanet Desktop. */
+export declare const DEFAULT_BRC100_URL = "http://localhost:3321";
+/**
+ * The subset of the BRC-100 wallet interface bsv-pay uses (structural, so
+ * tests and embedders can inject a mock). Matches @bsv/sdk WalletInterface.
+ */
+export interface Brc100Interface {
+    getVersion(args: object): Promise<{
+        version: string;
+    }>;
+    getNetwork(args: object): Promise<{
+        network: 'mainnet' | 'testnet';
+    }>;
+    waitForAuthentication(args: object): Promise<{
+        authenticated: true;
+    }>;
+    getPublicKey(args: {
+        identityKey: true;
+    }): Promise<{
+        publicKey: string;
+    }>;
+    createAction(args: CreateActionArgs): Promise<CreateActionResult>;
+    listOutputs(args: ListOutputsArgs): Promise<ListOutputsResult>;
+}
+export interface ConnectBrc100Options {
+    /** Wallet JSON-API URL; default BSV_PAY_BRC100_URL env, then localhost:3321. */
+    url?: string;
+    /** Inject a connected wallet interface (tests, library embedders). */
+    wallet?: Brc100Interface;
+}
+export interface Brc100PayParams {
+    to: string;
+    amountSats: number;
+    memo?: string;
+}
+export interface Brc100PayResult {
+    txid: string;
+    /** Empty string when the wallet returned a txid but no decodable tx. */
+    rawTxHex: string;
+    /** Exact fee decoded from the returned transaction; undefined if undecodable. */
+    feeSats?: number;
+    /** Satoshis the wallet routed back to itself (its own change). */
+    changeSats: number;
+    sizeBytes: number;
+}
+/**
+ * Receive-side surfaces (request/watch/serve, MCP request tools) refuse
+ * under BRC-100 custody: a payment address issued outside the wallet app
+ * would be invisible to it — the funds would land somewhere the wallet
+ * cannot see or spend. Receiving stays in the wallet app (documented
+ * limitation of the experimental backend; see DECISIONS.md M12).
+ */
+export declare function brc100ReceiveNotSupported(): CliError;
+/**
+ * An external BRC-100 wallet, connected and network-verified. Exposes only
+ * public data (txids, satoshis, the identity public key); the underlying
+ * interface stays module-private and is never returned by any method.
+ */
+export declare class Brc100Wallet {
+    readonly network: Network;
+    private readonly iface;
+    readonly url: string;
+    constructor(network: Network, iface: Brc100Interface, url: string);
+    /** Block until the wallet app has authenticated this origin (may prompt). */
+    waitForAuthentication(): Promise<void>;
+    /** The wallet's identity public key (public data, safe to display). */
+    identityKey(): Promise<string>;
+    version(): Promise<string>;
+    /** Spendable balance as the external wallet reports it (default basket). */
+    getBalanceSats(): Promise<number>;
+    /**
+     * Ask the external wallet to pay `amountSats` to a P2PKH address. The
+     * wallet funds, signs, and broadcasts (acceptDelayedBroadcast: false, so
+     * failures surface here, not in a background queue). Only called by core
+     * executeSend AFTER the policy gate authorized this exact spend.
+     *
+     * Errors: exit 3 (wallet reports insufficient funds), exit 7 (wallet
+     * unreachable — nothing spent), exit 6 (the wallet created the action but
+     * its broadcast outcome is unknown; txid in data when available), exit 5
+     * (the wallet refused — e.g. the human declined the prompt; nothing spent).
+     */
+    payToAddress(params: Brc100PayParams): Promise<Brc100PayResult>;
+}
+/**
+ * Connect to the external BRC-100 wallet and verify it is on the expected
+ * network (invariant 7: a testnet bsv-pay wallet refuses a mainnet wallet
+ * app and vice versa). Throws exit 7 `brc100_unreachable` when no wallet
+ * answers and exit 2 `brc100_network_mismatch` on a network mismatch.
+ */
+export declare function connectBrc100(network: Network, opts?: ConnectBrc100Options): Promise<Brc100Wallet>;

package/dist/wallet/brc100.js

@@ -0,0 +1,217 @@
+import { HTTPWalletJSON, P2PKH, Transaction, WERR_INSUFFICIENT_FUNDS } from '@bsv/sdk';
+import { CliError, EXIT } from '../errors.js';
+/**
+ * BRC-100 custody backend (EXPERIMENTAL — Phase 2 M12). Keys live in an
+ * external wallet app (BSV Desktop / Metanet Desktop); bsv-pay constructs
+ * actions and the external wallet funds, signs, and broadcasts them.
+ *
+ * The policy engine stays IN FRONT of external custody: the policy gate in
+ * core decides and ledgers every spend BEFORE anything reaches this module
+ * (invariant 2), exactly as for local-seed wallets. The connection handle
+ * is key-capable by proxy — it can make the external wallet sign — so it
+ * never crosses the core boundary (invariant 1 extended to wallet handles):
+ * this module hands out txids, amounts, and addresses only.
+ */
+/** Default JSON-API endpoint exposed by BSV Desktop / Metanet Desktop. */
+export const DEFAULT_BRC100_URL = 'http://localhost:3321';
+/** Originator shown to the user by the wallet app when it asks permission. */
+const ORIGINATOR = 'bsv-pay';
+/**
+ * Receive-side surfaces (request/watch/serve, MCP request tools) refuse
+ * under BRC-100 custody: a payment address issued outside the wallet app
+ * would be invisible to it — the funds would land somewhere the wallet
+ * cannot see or spend. Receiving stays in the wallet app (documented
+ * limitation of the experimental backend; see DECISIONS.md M12).
+ */
+export function brc100ReceiveNotSupported() {
+    return new CliError(EXIT.USAGE, 'brc100_receive_not_supported', 'Receiving through bsv-pay is not supported with BRC-100 custody (experimental): an address ' +
+        'issued by bsv-pay would be invisible to the wallet app and the funds unspendable from it. ' +
+        "Use the wallet app's own receive screen, or a local-seed wallet for request/watch/serve.");
+}
+function unreachable(url, cause) {
+    return new CliError(EXIT.WALLET_LOCKED, 'brc100_unreachable', `No BRC-100 wallet answered at ${url} (${cause}). Start your wallet app ` +
+        '(e.g. Metanet Desktop) and make sure its JSON-API is enabled, or set ' +
+        'BSV_PAY_BRC100_URL if it listens elsewhere. Nothing was spent.', { url });
+}
+/** Connection failures (TCP refused, DNS, timeout) — the request never landed. */
+function isConnectionFailure(e) {
+    if (!(e instanceof Error))
+        return false;
+    const text = `${e.message} ${e.cause instanceof Error ? e.cause.message : String(e.cause ?? '')}`;
+    return /fetch failed|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|timeout/i.test(text);
+}
+function truncateBytes(text, maxBytes) {
+    let out = text;
+    while (Buffer.byteLength(out, 'utf8') > maxBytes)
+        out = out.slice(0, -1);
+    return out;
+}
+/** BRC-100 action description: 5–50 bytes, shown in the wallet app's UI. */
+function actionDescription(memo) {
+    return truncateBytes(`bsv-pay: ${memo ?? 'payment'}`, 50);
+}
+/**
+ * An external BRC-100 wallet, connected and network-verified. Exposes only
+ * public data (txids, satoshis, the identity public key); the underlying
+ * interface stays module-private and is never returned by any method.
+ */
+export class Brc100Wallet {
+    network;
+    iface;
+    url;
+    constructor(network, iface, url) {
+        this.network = network;
+        this.iface = iface;
+        this.url = url;
+    }
+    /** Block until the wallet app has authenticated this origin (may prompt). */
+    async waitForAuthentication() {
+        try {
+            await this.iface.waitForAuthentication({});
+        }
+        catch (e) {
+            if (isConnectionFailure(e))
+                throw unreachable(this.url, 'connection lost');
+            throw new CliError(EXIT.WALLET_LOCKED, 'brc100_not_authenticated', `The wallet app did not authenticate bsv-pay: ${e instanceof Error ? e.message : String(e)}.`, { url: this.url });
+        }
+    }
+    /** The wallet's identity public key (public data, safe to display). */
+    async identityKey() {
+        const { publicKey } = await this.iface.getPublicKey({ identityKey: true });
+        return publicKey;
+    }
+    async version() {
+        const { version } = await this.iface.getVersion({});
+        return version;
+    }
+    /** Spendable balance as the external wallet reports it (default basket). */
+    async getBalanceSats() {
+        let total = 0;
+        let offset = 0;
+        for (;;) {
+            let res;
+            try {
+                res = await this.iface.listOutputs({ basket: 'default', limit: 10_000, offset });
+            }
+            catch (e) {
+                if (isConnectionFailure(e))
+                    throw unreachable(this.url, 'connection lost');
+                throw new CliError(EXIT.NETWORK, 'brc100_error', `The external wallet could not list its funds: ${e instanceof Error ? e.message : String(e)}.`, { url: this.url });
+            }
+            for (const o of res.outputs)
+                if (o.spendable)
+                    total += o.satoshis;
+            offset += res.outputs.length;
+            if (res.outputs.length === 0 || offset >= res.totalOutputs)
+                return total;
+        }
+    }
+    /**
+     * Ask the external wallet to pay `amountSats` to a P2PKH address. The
+     * wallet funds, signs, and broadcasts (acceptDelayedBroadcast: false, so
+     * failures surface here, not in a background queue). Only called by core
+     * executeSend AFTER the policy gate authorized this exact spend.
+     *
+     * Errors: exit 3 (wallet reports insufficient funds), exit 7 (wallet
+     * unreachable — nothing spent), exit 6 (the wallet created the action but
+     * its broadcast outcome is unknown; txid in data when available), exit 5
+     * (the wallet refused — e.g. the human declined the prompt; nothing spent).
+     */
+    async payToAddress(params) {
+        let result;
+        try {
+            result = await this.iface.createAction({
+                description: actionDescription(params.memo),
+                outputs: [
+                    {
+                        lockingScript: new P2PKH().lock(params.to).toHex(),
+                        satoshis: params.amountSats,
+                        outputDescription: 'bsv-pay payment',
+                    },
+                ],
+                labels: ['bsv-pay'],
+                options: { acceptDelayedBroadcast: false },
+            });
+        }
+        catch (e) {
+            throw mapActionError(e, this.url);
+        }
+        if (!result.txid) {
+            throw new CliError(EXIT.UNEXPECTED, 'brc100_bad_result', 'The external wallet returned no txid for the created action.');
+        }
+        // Decode the returned AtomicBEEF for the exact fee/size/change. The
+        // payment is already broadcast at this point, so decoding problems must
+        // not throw the result away — degrade to txid-only.
+        try {
+            if (!result.tx)
+                throw new Error('no tx in result');
+            const tx = Transaction.fromAtomicBEEF(result.tx);
+            const rawTxHex = tx.toHex();
+            const recipientScript = new P2PKH().lock(params.to).toHex();
+            let recipientSeen = false;
+            let changeSats = 0;
+            for (const out of tx.outputs) {
+                const isRecipient = !recipientSeen &&
+                    out.satoshis === params.amountSats &&
+                    out.lockingScript.toHex() === recipientScript;
+                if (isRecipient)
+                    recipientSeen = true;
+                else
+                    changeSats += out.satoshis ?? 0;
+            }
+            return {
+                txid: result.txid,
+                rawTxHex,
+                feeSats: tx.getFee(),
+                changeSats,
+                sizeBytes: rawTxHex.length / 2,
+            };
+        }
+        catch {
+            return { txid: result.txid, rawTxHex: '', feeSats: undefined, changeSats: 0, sizeBytes: 0 };
+        }
+    }
+}
+/** Map a createAction failure onto the stable exit-code families. */
+function mapActionError(e, url) {
+    if (e instanceof CliError)
+        return e;
+    if (e instanceof WERR_INSUFFICIENT_FUNDS) {
+        return new CliError(EXIT.INSUFFICIENT_FUNDS, 'insufficient_funds', `The external wallet reports insufficient funds: ${e.moreSatoshisNeeded} more satoshis needed. Fund the wallet or send less.`, { needed_sats: e.totalSatoshisNeeded, more_sats_needed: e.moreSatoshisNeeded });
+    }
+    // WERR_REVIEW_ACTIONS (duck-typed: injected mocks may not share the class):
+    // the wallet created the action but the broadcast outcome needs review —
+    // the money may have moved. Conservative: status unknown, txid if present.
+    if (e instanceof Error && 'reviewActionResults' in e) {
+        const txid = e.txid;
+        return new CliError(EXIT.BROADCAST_UNKNOWN, 'brc100_broadcast_unknown', `The external wallet created the payment but its broadcast outcome is unknown${txid ? ` (txid ${txid})` : ''}. ` +
+            'Check the wallet app before retrying; the funds may already have moved.', txid ? { txid } : undefined);
+    }
+    if (isConnectionFailure(e))
+        return unreachable(url, 'connection failed mid-request');
+    return new CliError(EXIT.BROADCAST_REJECTED, 'brc100_action_rejected', `The external wallet did not complete the payment: ${e instanceof Error ? e.message : String(e)}. ` +
+        'If you declined the request in the wallet app, nothing was sent.');
+}
+/**
+ * Connect to the external BRC-100 wallet and verify it is on the expected
+ * network (invariant 7: a testnet bsv-pay wallet refuses a mainnet wallet
+ * app and vice versa). Throws exit 7 `brc100_unreachable` when no wallet
+ * answers and exit 2 `brc100_network_mismatch` on a network mismatch.
+ */
+export async function connectBrc100(network, opts = {}) {
+    const url = opts.url ?? process.env.BSV_PAY_BRC100_URL ?? DEFAULT_BRC100_URL;
+    const iface = opts.wallet ?? new HTTPWalletJSON(ORIGINATOR, url);
+    let walletNetwork;
+    try {
+        ({ network: walletNetwork } = await iface.getNetwork({}));
+    }
+    catch (e) {
+        throw unreachable(url, e instanceof Error ? e.message : String(e));
+    }
+    const expected = network === 'test' ? 'testnet' : 'mainnet';
+    if (walletNetwork !== expected) {
+        throw new CliError(EXIT.USAGE, 'brc100_network_mismatch', `The external wallet is on ${walletNetwork} but this bsv-pay wallet is ${expected}. ` +
+            'Switch the wallet app to the matching network (state never mixes across networks).', { wallet_network: walletNetwork, expected_network: expected });
+    }
+    return new Brc100Wallet(network, iface, url);
+}

package/dist/wallet/crypto.d.ts

@@ -0,0 +1,25 @@
+export interface KdfParams {
+    algo: 'argon2id';
+    salt: string;
+    t: number;
+    m: number;
+    p: number;
+}
+export interface CipherBlob {
+    algo: 'aes-256-gcm';
+    iv: string;
+    tag: string;
+    ciphertext: string;
+}
+/**
+ * OWASP-recommended argon2id configuration (19 MiB, t=2, p=1). Parameters are
+ * stored alongside the wallet so they can be raised later without breaking
+ * existing wallets.
+ */
+export declare const DEFAULT_KDF: Pick<KdfParams, 't' | 'm' | 'p'>;
+export declare function encryptSecret(plaintext: string, passphrase: string): {
+    kdf: KdfParams;
+    cipher: CipherBlob;
+};
+/** Throws exit 7 (wallet locked) when the passphrase is wrong. */
+export declare function decryptSecret(kdf: KdfParams, cipher: CipherBlob, passphrase: string): string;

package/dist/wallet/crypto.js

@@ -0,0 +1,46 @@
+import crypto from 'node:crypto';
+import { argon2id } from '@noble/hashes/argon2';
+import { CliError, EXIT } from '../errors.js';
+/**
+ * OWASP-recommended argon2id configuration (19 MiB, t=2, p=1). Parameters are
+ * stored alongside the wallet so they can be raised later without breaking
+ * existing wallets.
+ */
+export const DEFAULT_KDF = { t: 2, m: 19_456, p: 1 };
+function deriveKey(passphrase, params) {
+    const pass = new TextEncoder().encode(passphrase.normalize('NFKD'));
+    const salt = Buffer.from(params.salt, 'hex');
+    return Buffer.from(argon2id(pass, salt, { t: params.t, m: params.m, p: params.p, dkLen: 32 }));
+}
+export function encryptSecret(plaintext, passphrase) {
+    const kdf = {
+        algo: 'argon2id',
+        salt: crypto.randomBytes(16).toString('hex'),
+        ...DEFAULT_KDF,
+    };
+    const key = deriveKey(passphrase, kdf);
+    const iv = crypto.randomBytes(12);
+    const c = crypto.createCipheriv('aes-256-gcm', key, iv);
+    const ciphertext = Buffer.concat([c.update(plaintext, 'utf8'), c.final()]);
+    return {
+        kdf,
+        cipher: {
+            algo: 'aes-256-gcm',
+            iv: iv.toString('hex'),
+            tag: c.getAuthTag().toString('hex'),
+            ciphertext: ciphertext.toString('hex'),
+        },
+    };
+}
+/** Throws exit 7 (wallet locked) when the passphrase is wrong. */
+export function decryptSecret(kdf, cipher, passphrase) {
+    const key = deriveKey(passphrase, kdf);
+    try {
+        const d = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(cipher.iv, 'hex'));
+        d.setAuthTag(Buffer.from(cipher.tag, 'hex'));
+        return Buffer.concat([d.update(Buffer.from(cipher.ciphertext, 'hex')), d.final()]).toString('utf8');
+    }
+    catch {
+        throw new CliError(EXIT.WALLET_LOCKED, 'bad_passphrase', 'Wrong passphrase. Try again, or set BSV_PAY_PASSPHRASE for scripted use.');
+    }
+}

package/dist/wallet/wallet.d.ts

@@ -0,0 +1,86 @@
+import { PrivateKey } from '@bsv/sdk';
+import { type Network } from '../paths.js';
+import { type CipherBlob, type KdfParams } from './crypto.js';
+export interface SecretPayload {
+    type: 'mnemonic' | 'wif';
+    value: string;
+}
+export interface WalletFile {
+    version: 1;
+    network: Network;
+    encrypted: boolean;
+    /**
+     * 'brc100' delegates custody to an external BRC-100 wallet app
+     * (EXPERIMENTAL, M12): no secret is stored and the local signing Wallet
+     * never exists. Absent = local-seed custody.
+     */
+    backend?: 'brc100';
+    /** JSON-API URL of the external wallet (backend === 'brc100' only). */
+    brc100_url?: string;
+    /** Present only when encrypted === false (explicit opt-in at init). */
+    secret?: SecretPayload;
+    kdf?: KdfParams;
+    cipher?: CipherBlob;
+    next_receive_index: number;
+    next_change_index: number;
+    created_at: string;
+}
+export declare function walletExists(network: Network): boolean;
+export declare function readWalletFile(network: Network): WalletFile;
+export declare function writeWalletFile(network: Network, wallet: WalletFile): void;
+export declare function buildWalletFile(network: Network, secret: SecretPayload, passphrase: string | null): WalletFile;
+/** Wallet file for external BRC-100 custody: no secret, no counters in use. */
+export declare function buildBrc100WalletFile(network: Network, url: string): WalletFile;
+export declare const UNENCRYPTED_WALLET_WARNING: string;
+/**
+ * How unlock obtains the passphrase and reports warnings. Defaults preserve
+ * CLI behavior (env var, then interactive prompt; warnings to stderr); the
+ * core library passes explicit values so it never prompts or prints.
+ */
+export interface UnlockOptions {
+    /** Passphrase or async supplier; default: BSV_PAY_PASSPHRASE env, then interactive prompt. */
+    passphrase?: string | (() => Promise<string>);
+    /** Sink for human warnings (e.g. unencrypted wallet); default: stderr. */
+    onWarning?: (text: string) => void;
+}
+/**
+ * Resolve the passphrase: env var for scripts, otherwise interactive prompt.
+ * Exported so CLI commands can hand this exact flow to core's openWallet().
+ */
+export declare function obtainPassphrase(supplied?: string | (() => Promise<string>)): Promise<string>;
+export interface TrackedAddress {
+    address: string;
+    chain: 0 | 1;
+    index: number;
+}
+/** An unlocked wallet: can derive addresses and signing keys. */
+export declare class Wallet {
+    readonly network: Network;
+    private file;
+    private readonly secret;
+    private readonly hd;
+    private constructor();
+    static unlock(network: Network, options?: UnlockOptions): Promise<Wallet>;
+    /**
+     * Read-only view (no passphrase needed): tracked addresses can be derived
+     * only for unencrypted wallets; encrypted wallets still require unlock, so
+     * commands that just need addresses use the ledger instead. Kept private —
+     * commands should use Wallet.unlock or the ledger.
+     */
+    get isHd(): boolean;
+    keyAt(chain: 0 | 1, index: number): PrivateKey;
+    addressAt(chain: 0 | 1, index: number): string;
+    /** Every address this wallet has ever issued (receive + change chains). */
+    trackedAddresses(): TrackedAddress[];
+    privKeyForAddress(address: string): PrivateKey | undefined;
+    /** Next address for a purpose WITHOUT persisting anything (dry runs). */
+    peekAddress(purpose: 'receive' | 'change'): {
+        address: string;
+        index: number;
+    };
+    /** Derive a fresh address, persist the counter, and record it in the ledger. */
+    issueAddress(purpose: 'receive' | 'change' | 'request', memo?: string): {
+        address: string;
+        index: number;
+    };
+}