bsv-pay-cli 0.2.0

package/dist/core/request.js

@@ -0,0 +1,77 @@
+import { CliError, EXIT } from '../errors.js';
+import { appendLedger } from '../ledger.js';
+import { satsToBsvString } from '../units.js';
+import { brc100ReceiveNotSupported } from '../wallet/brc100.js';
+import { resolveCore } from './context.js';
+import { unwrapWallet } from './internal.js';
+/** BIP-21-style URI with the BSV `sv` discriminator. Amount is in BSV. */
+export function buildPaymentUri(address, amountSats, memo) {
+    let uri = `bitcoin:${address}?sv&amount=${satsToBsvString(amountSats)}`;
+    if (memo)
+        uri += `&label=${encodeURIComponent(memo)}`;
+    return uri;
+}
+/**
+ * Issue a fresh receiving address (one per request, so matching is
+ * unambiguous) and build the BIP-21 URI. The address is persisted to the
+ * wallet counter and ledger immediately.
+ */
+export function createRequest(wallet, params) {
+    if (!Number.isSafeInteger(params.amountSats) || params.amountSats <= 0) {
+        throw new CliError(EXIT.USAGE, 'invalid_amount', `amountSats must be a positive integer of satoshis (got ${params.amountSats}).`);
+    }
+    if (wallet.backend === 'brc100')
+        throw brc100ReceiveNotSupported();
+    const inner = unwrapWallet(wallet);
+    const { address } = inner.issueAddress('request', params.memo);
+    return {
+        address,
+        amountSats: params.amountSats,
+        memo: params.memo,
+        uri: buildPaymentUri(address, params.amountSats, params.memo),
+        network: wallet.network,
+    };
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+/**
+ * Poll an address until the first incoming payment appears at 0-conf, then
+ * record the receive in the ledger (invariant 6) and return it. Transient
+ * chain failures keep polling until the deadline. Timeout throws code 4
+ * `request_timeout`.
+ */
+export async function awaitPayment(opts, params) {
+    const { network, config, provider } = resolveCore(opts);
+    const pollIntervalMs = params.pollIntervalMs ?? config.pollIntervalSecs * 1000;
+    const deadlineMs = Date.now() + params.timeoutMs;
+    for (;;) {
+        try {
+            const utxos = await provider.getUtxos(params.address);
+            if (utxos.length > 0) {
+                const txid = utxos[0].txid;
+                const receivedSats = utxos
+                    .filter((u) => u.txid === txid)
+                    .reduce((s, u) => s + u.satoshis, 0);
+                const confirmed = (utxos[0].height ?? 0) > 0;
+                appendLedger(network, {
+                    type: 'receive',
+                    txid,
+                    amount_sats: receivedSats,
+                    address: params.address,
+                    memo: params.memo,
+                    timestamp: new Date().toISOString(),
+                    status: confirmed ? 'confirmed' : 'pending',
+                });
+                return { address: params.address, txid, receivedSats, confirmed };
+            }
+        }
+        catch {
+            // transient network/rate-limit failure: keep polling until the deadline
+        }
+        if (Date.now() >= deadlineMs) {
+            throw new CliError(EXIT.NETWORK, 'request_timeout', `No payment seen on ${params.address} within ${Math.round(params.timeoutMs / 1000)}s.`, { address: params.address, timeout_ms: params.timeoutMs });
+        }
+        await sleep(Math.min(pollIntervalMs, Math.max(0, deadlineMs - Date.now())));
+    }
+}

package/dist/core/send.d.ts

@@ -0,0 +1,108 @@
+import type { Network } from '../paths.js';
+import { type SpendableUtxo } from '../tx.js';
+import { type CoreOptions } from './context.js';
+import type { CoreWallet } from './wallet.js';
+export declare function explorerTxUrl(network: Network, txid: string): string;
+export interface SendParams {
+    to: string;
+    amountSats: number;
+    memo?: string;
+    /** Spend only confirmed UTXOs (unconfirmed are spendable by default). */
+    confirmedOnly?: boolean;
+    /**
+     * The human confirmed the legacy soft spend limit (interactive prompt /
+     * --allow-large). Satisfies ONLY that confirmable limit — it can never
+     * cross a policy.toml rule (hard per-tx limit, budgets, lists, threshold).
+     */
+    allowAboveLimit?: boolean;
+    /**
+     * Authorize in evaluate-only mode: same policy verdicts, but nothing is
+     * persisted and the resulting plan can never be executed for real.
+     */
+    dryRun?: boolean;
+}
+/** A fully planned, not-yet-signed spend. Carries addresses and txids only. */
+export interface SendPlan {
+    to: string;
+    amountSats: number;
+    memo?: string;
+    feeSats: number;
+    /** 0 when sub-dust change was folded into the fee. */
+    changeSats: number;
+    balanceAfterSats: number;
+    inputCount: number;
+    /** UTXOs the transaction will spend. */
+    inputs: SpendableUtxo[];
+    /** Where change will go (derived but not persisted until execution). */
+    changeAddress: string;
+    /**
+     * BRC-100 custody (additive, M12): the external wallet funds and signs,
+     * so inputs/change are its business and feeSats is an estimate until the
+     * wallet returns the real transaction.
+     */
+    external?: true;
+}
+export interface SendResult {
+    txid: string;
+    to: string;
+    amountSats: number;
+    feeSats: number;
+    changeSats: number;
+    balanceAfterSats: number;
+    sizeBytes: number;
+    dryRun: boolean;
+    explorerUrl: string;
+    /**
+     * The signed transaction (public data once broadcast). Carried so a
+     * BRC-105 client can present the payment to the server (M11); contains
+     * signatures and public keys, never key material.
+     */
+    rawTxHex: string;
+    /** BRC-100 custody (additive, M12): the external wallet signed/broadcast. */
+    external?: true;
+    /**
+     * True when feeSats is bsv-pay's estimate, not the wallet's final fee
+     * (BRC-100 dry runs, or a wallet that returned an undecodable tx).
+     */
+    feeEstimated?: true;
+}
+/**
+ * Validate and plan a spend. The policy gate (invariant 2) runs HERE, before
+ * any network call: authorizeSpend ledgers the decision and throws exit 8 on
+ * deny or exit 9 when queued for approval; on allow the returned plan is
+ * registered as authorized for exactly this recipient and amount. Throws
+ * code 2 (bad address/amount) or 3 (insufficient funds) otherwise.
+ */
+export declare function planSend(wallet: CoreWallet, opts: CoreOptions, params: SendParams): Promise<SendPlan>;
+/**
+ * Plan a previously queued spend after the human passed the approval gate
+ * (TTY + approval secret). Re-runs every policy rule except the threshold.
+ * Internal: used by the approvals command, NOT exported from bsv-pay/core.
+ */
+export declare function planApprovedSend(wallet: CoreWallet, opts: CoreOptions, params: {
+    to: string;
+    amountSats: number;
+    memo?: string;
+    confirmedOnly?: boolean;
+}, approvalId: string): Promise<SendPlan>;
+/**
+ * Sign and (unless dryRun) broadcast a planned spend, recording it in the
+ * ledger (invariant 6). Refuses any plan the policy gate did not authorize:
+ * hand-built, altered, already-executed, or planned with dryRun. dryRun
+ * persists nothing — no ledger entry, no change-address counter bump. An
+ * ambiguous broadcast failure appends a `status: "unknown"` entry and throws
+ * code 6 carrying the txid; a definite rejection throws code 5 with nothing
+ * spent or recorded.
+ */
+export declare function executeSend(wallet: CoreWallet, opts: CoreOptions, plan: SendPlan, exec?: {
+    dryRun?: boolean;
+}): Promise<SendResult>;
+/**
+ * Plan and execute in one call. Never prompts; the policy gate applies.
+ * Single-flight per state dir + network: concurrent send() calls in one
+ * process (an MCP server, a library embedder) are serialized across the
+ * whole decide→broadcast→ledger span, so a later spend is decided only
+ * after every earlier one has hit the ledger — two simultaneous spends can
+ * never both pass the same remaining budget.
+ */
+export declare function send(wallet: CoreWallet, opts: CoreOptions, params: SendParams): Promise<SendResult>;

package/dist/core/send.js

@@ -0,0 +1,277 @@
+import { validateAddress } from '../address.js';
+import { CliError, EXIT } from '../errors.js';
+import { appendLedger } from '../ledger.js';
+import { addSessionSpent } from '../policy/budget.js';
+import { authorizeApprovedSpend, authorizeSpend, registerAuthorizedPlan, takeAuthorizedPlan, } from '../policy/engine.js';
+import { buildSignedTx, feeForTx, selectUtxos } from '../tx.js';
+import { resolveCore } from './context.js';
+import { unwrapBackend } from './internal.js';
+import { withSpendLock } from './spend-lock.js';
+export function explorerTxUrl(network, txid) {
+    return network === 'test'
+        ? `https://test.whatsonchain.com/tx/${txid}`
+        : `https://whatsonchain.com/tx/${txid}`;
+}
+async function gatherSpendableUtxos(wallet, chain, confirmedOnly) {
+    const utxos = [];
+    for (const tracked of wallet.trackedAddresses()) {
+        const rows = await chain.getUtxos(tracked.address);
+        for (const u of rows) {
+            // spend unconfirmed change by default; confirmedOnly restricts
+            if (confirmedOnly && (u.height === undefined || u.height <= 0))
+                continue;
+            utxos.push({ ...u, address: tracked.address });
+        }
+    }
+    return utxos;
+}
+function validateSpendInput(to, amountSats, network) {
+    validateAddress(to, network);
+    if (!Number.isSafeInteger(amountSats) || amountSats <= 0) {
+        throw new CliError(EXIT.USAGE, 'invalid_amount', `amountSats must be a positive integer of satoshis (got ${amountSats}).`);
+    }
+}
+/** Gather, select, and shape the plan. No policy, no persistence. */
+async function buildPlan(wallet, resolved, params) {
+    const backend = unwrapBackend(wallet);
+    if (backend.kind === 'brc100') {
+        // The external wallet funds and signs; coin selection and the real fee
+        // are its business. Pre-check only what is definitely insufficient and
+        // estimate the fee for display — the wallet's figure lands in the result.
+        const balance = await backend.wallet.getBalanceSats();
+        if (balance < params.amountSats) {
+            throw new CliError(EXIT.INSUFFICIENT_FUNDS, 'insufficient_funds', `Insufficient funds: trying to send ${params.amountSats} sats but the external wallet reports only ${balance} sats spendable. Fund the wallet or send less.`, { available_sats: balance, needed_sats: params.amountSats });
+        }
+        const feeEstimate = feeForTx(1, 2, resolved.config.feeRateSatsPerKb);
+        return {
+            to: params.to,
+            amountSats: params.amountSats,
+            memo: params.memo,
+            feeSats: feeEstimate,
+            changeSats: 0,
+            balanceAfterSats: balance - params.amountSats - feeEstimate,
+            inputCount: 0,
+            inputs: [],
+            changeAddress: '',
+            external: true,
+        };
+    }
+    const inner = backend.wallet;
+    const utxos = await gatherSpendableUtxos(inner, resolved.provider, Boolean(params.confirmedOnly));
+    const selection = selectUtxos(utxos, params.amountSats, resolved.config.feeRateSatsPerKb);
+    const totalAvailable = utxos.reduce((s, u) => s + u.satoshis, 0);
+    return {
+        to: params.to,
+        amountSats: params.amountSats,
+        memo: params.memo,
+        feeSats: selection.fee,
+        changeSats: selection.changeSats,
+        balanceAfterSats: totalAvailable - params.amountSats - selection.fee,
+        inputCount: selection.selected.length,
+        inputs: selection.selected,
+        changeAddress: inner.peekAddress('change').address,
+    };
+}
+/**
+ * Validate and plan a spend. The policy gate (invariant 2) runs HERE, before
+ * any network call: authorizeSpend ledgers the decision and throws exit 8 on
+ * deny or exit 9 when queued for approval; on allow the returned plan is
+ * registered as authorized for exactly this recipient and amount. Throws
+ * code 2 (bad address/amount) or 3 (insufficient funds) otherwise.
+ */
+export async function planSend(wallet, opts, params) {
+    const resolved = resolveCore(opts);
+    validateSpendInput(params.to, params.amountSats, resolved.network);
+    const auth = authorizeSpend({ network: resolved.network, config: resolved.config }, {
+        to: params.to,
+        amountSats: params.amountSats,
+        memo: params.memo,
+        softLimitConfirmed: params.allowAboveLimit,
+        confirmedOnly: params.confirmedOnly,
+    }, { mode: params.dryRun ? 'evaluate' : 'enforce' });
+    const plan = await buildPlan(wallet, resolved, params);
+    registerAuthorizedPlan(plan, auth);
+    return plan;
+}
+/**
+ * Plan a previously queued spend after the human passed the approval gate
+ * (TTY + approval secret). Re-runs every policy rule except the threshold.
+ * Internal: used by the approvals command, NOT exported from bsv-pay/core.
+ */
+export async function planApprovedSend(wallet, opts, params, approvalId) {
+    const resolved = resolveCore(opts);
+    validateSpendInput(params.to, params.amountSats, resolved.network);
+    const auth = authorizeApprovedSpend({ network: resolved.network, config: resolved.config }, { to: params.to, amountSats: params.amountSats, memo: params.memo }, approvalId);
+    const plan = await buildPlan(wallet, resolved, params);
+    registerAuthorizedPlan(plan, auth);
+    return plan;
+}
+/**
+ * Sign and (unless dryRun) broadcast a planned spend, recording it in the
+ * ledger (invariant 6). Refuses any plan the policy gate did not authorize:
+ * hand-built, altered, already-executed, or planned with dryRun. dryRun
+ * persists nothing — no ledger entry, no change-address counter bump. An
+ * ambiguous broadcast failure appends a `status: "unknown"` entry and throws
+ * code 6 carrying the txid; a definite rejection throws code 5 with nothing
+ * spent or recorded.
+ */
+export async function executeSend(wallet, opts, plan, exec = {}) {
+    const { network, provider } = resolveCore(opts);
+    // The other half of the policy gate: no authorization, no broadcast.
+    const auth = takeAuthorizedPlan(plan, { to: plan.to, amountSats: plan.amountSats }, !exec.dryRun);
+    const backend = unwrapBackend(wallet);
+    if (backend.kind === 'brc100') {
+        return executeBrc100Send(backend.wallet, network, plan, auth.decisionId, Boolean(exec.dryRun));
+    }
+    const inner = backend.wallet;
+    const tx = await buildSignedTx(inner, { selected: plan.inputs, fee: plan.feeSats, changeSats: plan.changeSats }, plan.to, plan.amountSats, plan.changeAddress);
+    const txid = tx.id('hex');
+    const rawTxHex = tx.toHex();
+    const result = {
+        txid,
+        to: plan.to,
+        amountSats: plan.amountSats,
+        feeSats: plan.feeSats,
+        changeSats: plan.changeSats,
+        balanceAfterSats: plan.balanceAfterSats,
+        sizeBytes: rawTxHex.length / 2,
+        dryRun: Boolean(exec.dryRun),
+        explorerUrl: explorerTxUrl(network, txid),
+        rawTxHex,
+    };
+    if (exec.dryRun)
+        return result;
+    // Persist the change address only on a real broadcast path.
+    if (plan.changeSats > 0)
+        inner.issueAddress('change', `change for ${txid.slice(0, 12)}`);
+    try {
+        const broadcast = await provider.broadcast(tx.toHex());
+        if (!broadcast.ok) {
+            throw new CliError(EXIT.BROADCAST_REJECTED, 'broadcast_rejected', `The network rejected the transaction: ${broadcast.error ?? 'no reason given'}. ` +
+                'Nothing was spent. Check the fee rate in config.toml or retry shortly.', { txid });
+        }
+    }
+    catch (e) {
+        if (e instanceof CliError && e.exitCode === EXIT.BROADCAST_REJECTED)
+            throw e;
+        // Ambiguous network failure: the tx may have propagated. Code 6, txid included.
+        appendLedger(network, {
+            type: 'send',
+            txid,
+            amount_sats: plan.amountSats,
+            address: plan.to,
+            memo: plan.memo,
+            timestamp: new Date().toISOString(),
+            status: 'unknown',
+            fee_sats: plan.feeSats,
+            decision_id: auth.decisionId,
+        });
+        addSessionSpent(network, plan.amountSats); // may have moved: count it
+        throw new CliError(EXIT.BROADCAST_UNKNOWN, 'broadcast_status_unknown', `Broadcast status unknown (network failure mid-send). txid ${txid} — check ${explorerTxUrl(network, txid)} before retrying; the funds may already have moved.`, { txid, explorer_url: explorerTxUrl(network, txid) });
+    }
+    appendLedger(network, {
+        type: 'send',
+        txid,
+        amount_sats: plan.amountSats,
+        address: plan.to,
+        memo: plan.memo,
+        timestamp: new Date().toISOString(),
+        status: 'pending',
+        fee_sats: plan.feeSats,
+        decision_id: auth.decisionId,
+    });
+    addSessionSpent(network, plan.amountSats);
+    return result;
+}
+/**
+ * BRC-100 custody: the gate has already authorized this exact spend; the
+ * external wallet now funds, signs, and broadcasts it in one createAction
+ * (so there is no separate broadcast site — the choke-point scan covers
+ * payToAddress instead). Ledger semantics mirror the local path: success
+ * appends `pending`, an ambiguous wallet-side outcome (exit 6) appends
+ * `unknown` and counts against the session budget, a definite refusal
+ * appends nothing. Dry runs return the estimated plan without touching
+ * the external wallet — there is no txid to show until it signs.
+ */
+async function executeBrc100Send(brc100, network, plan, decisionId, dryRun) {
+    if (dryRun) {
+        return {
+            txid: '',
+            to: plan.to,
+            amountSats: plan.amountSats,
+            feeSats: plan.feeSats,
+            changeSats: 0,
+            balanceAfterSats: plan.balanceAfterSats,
+            sizeBytes: 0,
+            dryRun: true,
+            explorerUrl: '',
+            rawTxHex: '',
+            external: true,
+            feeEstimated: true,
+        };
+    }
+    let paid;
+    try {
+        paid = await brc100.payToAddress({ to: plan.to, amountSats: plan.amountSats, memo: plan.memo });
+    }
+    catch (e) {
+        if (e instanceof CliError && e.exitCode === EXIT.BROADCAST_UNKNOWN) {
+            // The money may have moved (mirrors the local ambiguous-broadcast path).
+            appendLedger(network, {
+                type: 'send',
+                txid: typeof e.data?.txid === 'string' ? e.data.txid : '',
+                amount_sats: plan.amountSats,
+                address: plan.to,
+                memo: plan.memo,
+                timestamp: new Date().toISOString(),
+                status: 'unknown',
+                decision_id: decisionId,
+            });
+            addSessionSpent(network, plan.amountSats);
+        }
+        throw e;
+    }
+    appendLedger(network, {
+        type: 'send',
+        txid: paid.txid,
+        amount_sats: plan.amountSats,
+        address: plan.to,
+        memo: plan.memo,
+        timestamp: new Date().toISOString(),
+        status: 'pending',
+        fee_sats: paid.feeSats,
+        decision_id: decisionId,
+    });
+    addSessionSpent(network, plan.amountSats);
+    const feeKnown = paid.feeSats !== undefined;
+    const feeSats = paid.feeSats ?? plan.feeSats;
+    return {
+        txid: paid.txid,
+        to: plan.to,
+        amountSats: plan.amountSats,
+        feeSats,
+        changeSats: paid.changeSats,
+        // plan.balanceAfterSats was computed with the estimated fee; swap in the real one.
+        balanceAfterSats: plan.balanceAfterSats + plan.feeSats - feeSats,
+        sizeBytes: paid.sizeBytes,
+        dryRun: false,
+        explorerUrl: explorerTxUrl(network, paid.txid),
+        rawTxHex: paid.rawTxHex,
+        external: true,
+        ...(feeKnown ? {} : { feeEstimated: true }),
+    };
+}
+/**
+ * Plan and execute in one call. Never prompts; the policy gate applies.
+ * Single-flight per state dir + network: concurrent send() calls in one
+ * process (an MCP server, a library embedder) are serialized across the
+ * whole decide→broadcast→ledger span, so a later spend is decided only
+ * after every earlier one has hit the ledger — two simultaneous spends can
+ * never both pass the same remaining budget.
+ */
+export async function send(wallet, opts, params) {
+    return withSpendLock(opts.network, async () => {
+        const plan = await planSend(wallet, opts, params);
+        return executeSend(wallet, opts, plan, { dryRun: params.dryRun });
+    });
+}

package/dist/core/spend-lock.d.ts

@@ -0,0 +1,2 @@
+import { type Network } from '../paths.js';
+export declare function withSpendLock<T>(network: Network, fn: () => Promise<T>): Promise<T>;

package/dist/core/spend-lock.js

@@ -0,0 +1,25 @@
+import { baseDir } from '../paths.js';
+/**
+ * Single-flight for the spend critical section (decide → sign → broadcast →
+ * ledger). Budgets and rate limits are recomputed from the ledger when the
+ * policy gate decides, but the send entry that consumes them is appended
+ * only after broadcast — so two spends in flight at once could BOTH pass a
+ * budget check before either is recorded. Any long-running process that can
+ * receive concurrent spend calls (the MCP server, library embedders using
+ * send()) must serialize the whole span; a CLI invocation is one spend per
+ * process, where the lock is a no-op.
+ *
+ * Keyed by state dir + network, matching how budgets are scoped. A spend
+ * that throws (denied, insufficient funds, broadcast failure) releases the
+ * lock; the next spend in line re-reads usage from the ledger and is decided
+ * on the true state. Deliberately module-private to core: not exported from
+ * bsv-pay/core, no timeout, no reentrancy.
+ */
+const tails = new Map();
+export function withSpendLock(network, fn) {
+    const key = `${baseDir()}::${network}`;
+    const prev = tails.get(key) ?? Promise.resolve();
+    const run = prev.then(fn);
+    tails.set(key, run.then(() => undefined, () => undefined));
+    return run;
+}

package/dist/core/wallet.d.ts

@@ -0,0 +1,53 @@
+import type { Network } from '../paths.js';
+import { type Brc100Interface } from '../wallet/brc100.js';
+import type { CoreOptions } from './context.js';
+export interface OpenWalletOptions extends CoreOptions {
+    /** Passphrase or async supplier; default: BSV_PAY_PASSPHRASE env. Never prompts. */
+    passphrase?: string | (() => Promise<string>);
+    /** Receives human warnings (e.g. unencrypted wallet); default: collected on `warnings`. */
+    onWarning?: (text: string) => void;
+}
+/** Which custody backend an open wallet delegates to. */
+export type WalletBackendKind = 'local' | 'brc100';
+/**
+ * An open wallet as seen through the library boundary: addresses and
+ * metadata only. Signing keys (and, for BRC-100 custody, the external
+ * wallet handle — key-capable by proxy) stay inside src/wallet/
+ * (invariant 1) — core modules reach the signing backend through a private
+ * registry that is not exported from the public entrypoint, never through
+ * any member of this class.
+ */
+export declare class CoreWallet {
+    readonly network: Network;
+    /** False for single-address WIF wallets. */
+    readonly isHd: boolean;
+    /** Warnings raised during unlock when no onWarning sink was supplied. */
+    readonly warnings: readonly string[];
+    /** Custody backend (additive, M12): local seed or external BRC-100 wallet. */
+    readonly backend: WalletBackendKind;
+    constructor(network: Network, 
+    /** False for single-address WIF wallets. */
+    isHd: boolean, 
+    /** Warnings raised during unlock when no onWarning sink was supplied. */
+    warnings: readonly string[], 
+    /** Custody backend (additive, M12): local seed or external BRC-100 wallet. */
+    backend?: WalletBackendKind);
+    /**
+     * Every address this wallet has issued (receive + change chains). A
+     * BRC-100 wallet manages its own addresses internally: empty array.
+     */
+    addresses(): string[];
+}
+/**
+ * Unlock a wallet for library use. Unlike the CLI, this never prompts and
+ * never writes to stdout/stderr: the passphrase comes from the explicit
+ * option or BSV_PAY_PASSPHRASE; an encrypted wallet with neither throws
+ * code 7 (`passphrase_required`). A missing wallet file throws code 2
+ * (`no_wallet`).
+ *
+ * When the wallet file delegates to BRC-100 custody (EXPERIMENTAL), this
+ * connects to the external wallet app instead — no passphrase involved;
+ * an unreachable wallet app throws code 7 (`brc100_unreachable`).
+ */
+export declare function openWallet(opts: OpenWalletOptions): Promise<CoreWallet>;
+export type { Brc100Interface };

package/dist/core/wallet.js

@@ -0,0 +1,77 @@
+import { CliError, EXIT } from '../errors.js';
+import { connectBrc100 } from '../wallet/brc100.js';
+import { readWalletFile, Wallet } from '../wallet/wallet.js';
+import { registerWallet, unwrapBackend, unwrapWallet } from './internal.js';
+/**
+ * An open wallet as seen through the library boundary: addresses and
+ * metadata only. Signing keys (and, for BRC-100 custody, the external
+ * wallet handle — key-capable by proxy) stay inside src/wallet/
+ * (invariant 1) — core modules reach the signing backend through a private
+ * registry that is not exported from the public entrypoint, never through
+ * any member of this class.
+ */
+export class CoreWallet {
+    network;
+    isHd;
+    warnings;
+    backend;
+    constructor(network, 
+    /** False for single-address WIF wallets. */
+    isHd, 
+    /** Warnings raised during unlock when no onWarning sink was supplied. */
+    warnings, 
+    /** Custody backend (additive, M12): local seed or external BRC-100 wallet. */
+    backend = 'local') {
+        this.network = network;
+        this.isHd = isHd;
+        this.warnings = warnings;
+        this.backend = backend;
+    }
+    /**
+     * Every address this wallet has issued (receive + change chains). A
+     * BRC-100 wallet manages its own addresses internally: empty array.
+     */
+    addresses() {
+        if (unwrapBackend(this).kind === 'brc100')
+            return [];
+        return unwrapWallet(this)
+            .trackedAddresses()
+            .map((a) => a.address);
+    }
+}
+/**
+ * Unlock a wallet for library use. Unlike the CLI, this never prompts and
+ * never writes to stdout/stderr: the passphrase comes from the explicit
+ * option or BSV_PAY_PASSPHRASE; an encrypted wallet with neither throws
+ * code 7 (`passphrase_required`). A missing wallet file throws code 2
+ * (`no_wallet`).
+ *
+ * When the wallet file delegates to BRC-100 custody (EXPERIMENTAL), this
+ * connects to the external wallet app instead — no passphrase involved;
+ * an unreachable wallet app throws code 7 (`brc100_unreachable`).
+ */
+export async function openWallet(opts) {
+    const file = readWalletFile(opts.network);
+    if (file.backend === 'brc100') {
+        const brc100 = await connectBrc100(opts.network, {
+            url: file.brc100_url,
+            wallet: opts.brc100,
+        });
+        const pub = new CoreWallet(opts.network, true, [], 'brc100');
+        registerWallet(pub, { kind: 'brc100', wallet: brc100 });
+        return pub;
+    }
+    const warnings = [];
+    const onWarning = opts.onWarning ?? ((text) => warnings.push(text));
+    // Only consulted for encrypted wallets, so unencrypted wallets open
+    // without any passphrase — same as the CLI.
+    const passphrase = opts.passphrase ??
+        process.env.BSV_PAY_PASSPHRASE ??
+        (() => {
+            throw new CliError(EXIT.WALLET_LOCKED, 'passphrase_required', 'Wallet is encrypted. Pass `passphrase` to openWallet() or set BSV_PAY_PASSPHRASE.');
+        });
+    const wallet = await Wallet.unlock(opts.network, { passphrase, onWarning });
+    const pub = new CoreWallet(opts.network, wallet.isHd, warnings, 'local');
+    registerWallet(pub, { kind: 'local', wallet });
+    return pub;
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+/** Stable exit codes, documented in README. */
+export declare const EXIT: {
+    readonly OK: 0;
+    readonly UNEXPECTED: 1;
+    readonly USAGE: 2;
+    readonly INSUFFICIENT_FUNDS: 3;
+    readonly NETWORK: 4;
+    readonly BROADCAST_REJECTED: 5;
+    readonly BROADCAST_UNKNOWN: 6;
+    readonly WALLET_LOCKED: 7;
+    readonly SPEND_LIMIT: 8;
+    /** Phase 2: the spend was queued for human approval instead of sent. */
+    readonly PENDING_APPROVAL: 9;
+    /** Phase 2: a 402 payment broadcast but the server refused the content. */
+    readonly PAYMENT_NOT_REDEEMED: 10;
+};
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
+/**
+ * Error carrying a stable exit code and a snake_case machine-readable code
+ * for --json output. `data` is merged into the JSON error object (never
+ * include key material).
+ */
+export declare class CliError extends Error {
+    readonly exitCode: ExitCode;
+    readonly errorCode: string;
+    readonly data?: Record<string, unknown> | undefined;
+    constructor(exitCode: ExitCode, errorCode: string, message: string, data?: Record<string, unknown> | undefined);
+}
+export declare function usageError(errorCode: string, message: string): CliError;
+export declare function networkError(message: string, data?: Record<string, unknown>): CliError;