@anywalletkit/wallet-btc 0.0.0-stage → 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,405 @@
+import { B as BtcClient, U as Utxo, a as BlockbookTx, b as BtcConfig, c as BtcTxDescription, d as BtcAddressType, e as BtcNetwork, f as BtcSpend, g as BtcTransferOptions, h as BtcMaxSpendableResult, i as BtcReceipt, j as BtcTransaction } from './history-B5fmsCjZ.js';
+export { k as BlockbookAddressPage, l as BlockbookClient, m as BlockbookTxDetails, n as BlockbookVin, o as BlockbookVout, p as BtcChainTx, q as BtcClientConfig, r as BtcHistoryCursor, s as BtcHistoryOptions, t as BtcHistoryPage, u as BtcHistoryRaw, v as BtcHistorySource, w as BtcTxInputDescription, x as BtcTxOutputDescription, y as BtcWarning, C as CAIP2_GENESIS, H as HistoryUnavailableError, z as btcExplorerTxUrl, A as createBtcHistory, D as decodeHistoryCursor, E as encodeHistoryCursor, F as mapBlockbookTx, G as unconfirmedOutgoing } from './history-B5fmsCjZ.js';
+import { Signer, IWalletAccountReadOnly, IWalletAccount, TransferResult, WalletManager, FeeRates } from '@anywalletkit/core';
+import { Transaction } from '@scure/btc-signer';
+import { BTC_NETWORK } from '@scure/btc-signer/utils.js';
+
+/** Why a spend was refused before signing. */
+type UnsafeTransactionCode = 
+/** Fee rate above `maxFeeRate`. */
+'fee-rate-too-high'
+/** An output that is neither the requested recipient/amount nor our change. */
+ | 'unexpected-output'
+/** The recipient output is missing or carries a different amount. */
+ | 'recipient-mismatch'
+/** A change output pays an address that is not ours. */
+ | 'change-not-ours'
+/** A coin the indexer reported does not match its previous transaction (txid, amount or script). */
+ | 'prevout-mismatch';
+/** A transaction failed a hard safety check and was not signed / broadcast. */
+declare class UnsafeTransactionError extends Error {
+    readonly code: UnsafeTransactionCode;
+    constructor(code: UnsafeTransactionCode, message: string);
+}
+/** Coin selection would need more inputs than `maxInputs` allows. */
+declare class TooManyInputsError extends Error {
+    readonly maxInputs: number;
+    constructor(maxInputs: number);
+}
+/** BIP-137 message signatures only exist for p2pkh/p2wpkh keys; taproot accounts have none (BIP-322 is not implemented). */
+declare class UnsupportedAddressTypeError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Esplora REST transport — the API served by mempool.space (`https://mempool.space/api`)
+ * and Blockstream (`https://blockstream.info/api`). Public instances exist, so it is
+ * the natural fallback behind a self-hosted Blockbook.
+ *
+ * Balance semantics: `unconfirmedOutgoing` is the mempool net outflow
+ * (spent − funded, clamped at 0), a conservative stand-in for Bitcoin Core's
+ * trusted-change rule that Blockbook's richer address record allows.
+ */
+declare class EsploraClient implements BtcClient {
+    private readonly base;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    constructor(config: {
+        url: string;
+    }, fetchFn?: typeof fetch, timeoutMs?: number);
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    private request;
+    private json;
+    private text;
+    getBalance(address: string): Promise<{
+        confirmed: bigint;
+        unconfirmed: bigint;
+        unconfirmedOutgoing: bigint;
+    }>;
+    listUnspent(address: string): Promise<Utxo[]>;
+    /** Esplora pages 25 (mempool.space: up to 50) txs per call; walk `/txs/chain/<last>` until a short page. */
+    getHistory(address: string): Promise<{
+        txid: string;
+        height: number;
+    }[]>;
+    getTransactionInfo(txid: string): Promise<BlockbookTx | undefined>;
+    getTransaction(txid: string): Promise<string>;
+    broadcast(rawTx: string): Promise<string>;
+    /** `/fee-estimates` → { "1": sat/vB, "2": …, "25": …, "144": … }; picks the nearest target ≥ `blocks`. */
+    estimateFee(blocks: number): Promise<number>;
+    getBlockHeight(): Promise<number>;
+}
+
+/** One client, or a failover client over the list: each call walks the list in order, `retries` extra rounds. */
+declare function createClient(config: BtcConfig): BtcClient | undefined;
+
+/** BIP-137 hash of a message (`Bitcoin Signed Message:` prefix, double SHA-256). */
+declare function magicHash(message: string | Uint8Array): Uint8Array;
+/** Address flavour a BIP-137 signature header is written for. */
+type SegwitType = 'p2wpkh' | 'p2sh(p2wpkh)';
+/** Encode `r‖s` + recovery id as a base64 BIP-137 signature. */
+declare function encodeMessageSignature(rs: Uint8Array, recovery: number, segwitType?: SegwitType | undefined): string;
+/** Sign with a raw private key (RFC-6979 deterministic, low-S). Kept for callers that hold a key outside a Signer. */
+declare function signMessage(message: string | Uint8Array, privateKey: Uint8Array, segwitType?: SegwitType | undefined): string;
+/** Sign through a {@link Signer} (`ecdsa-recoverable`, context `btc-message`). */
+declare function signMessageWith(message: string | Uint8Array, signer: Signer, segwitType?: SegwitType | undefined): Promise<string>;
+/** Recover the public key (compressed unless the header says otherwise) from a BIP-137 signature, or undefined when malformed. */
+declare function recoverMessagePublicKey(message: string | Uint8Array, signature: string): {
+    publicKey: Uint8Array;
+    segwitType: SegwitType | undefined;
+} | undefined;
+
+/** Most inputs one spend may use; above it the account asks to consolidate first. */
+declare const MAX_UTXO_INPUTS = 200;
+/** An output the selection must fund. */
+interface SelectionTarget {
+    value: bigint;
+    /** vbytes the output occupies (see `outputVBytes`). */
+    vbytes: number;
+}
+/** Input to {@link selectCoins}. */
+interface CoinSelectOptions {
+    utxos: Utxo[];
+    targets: SelectionTarget[];
+    /** sat/vB, ≥ 1. */
+    feeRate: bigint;
+    /** Weight units one of our inputs adds (`INPUT_WEIGHT[addressType]`). */
+    inputWeight: number;
+    /** vbytes a change output to our own address occupies. */
+    changeVBytes: number;
+    /** Dust threshold for our change output type. */
+    changeDust: bigint;
+    maxInputs?: number;
+}
+/** UTXOs chosen for a spend, the fee and the change. */
+interface CoinSelection {
+    utxos: Utxo[];
+    fee: bigint;
+    /** Change back to us; 0n when folded into the fee. */
+    change: bigint;
+    /** True when change existed but fell below dust and became fee. */
+    changeFolded: boolean;
+    /** Estimated vsize of the final transaction. */
+    vsize: number;
+    feeRate: bigint;
+}
+/** Virtual size (vB) of a segwit transaction with the given inputs and outputs. */
+declare function estimateVsize(inputs: number, inputWeight: number, outputVBytes: number[]): number;
+/** UTXOs worth spending at this fee rate, largest first. */
+declare function spendableUtxos(utxos: Utxo[], feeRate: bigint, inputWeight: number): Utxo[];
+/**
+ * Pick UTXOs to fund the targets at `feeRate` (sat/vB): change goes back when it is above dust,
+ * otherwise it joins the fee.
+ *
+ * @throws `InsufficientFundsError` (core) when the UTXOs cannot cover targets plus fee,
+ * `TooManyInputsError` above `maxInputs`, Error for a fee rate below 1 sat/vB.
+ */
+declare function selectCoins(o: CoinSelectOptions): CoinSelection;
+/** Sweep: every spendable input (largest first, capped), one output, no change. */
+declare function selectAll(o: Omit<CoinSelectOptions, 'targets' | 'changeVBytes' | 'changeDust'> & {
+    outputVBytes: number;
+}): {
+    utxos: Utxo[];
+    fee: bigint;
+    amount: bigint;
+    vsize: number;
+};
+
+/** Default fee-rate ceiling, sat/vB; a spend above it is refused. */
+declare const DEFAULT_MAX_FEE_RATE = 500;
+/** Replace-by-fee signalling: any sequence below 0xfffffffe (BIP-125). */
+declare const RBF_SEQUENCE = 4294967293;
+/** Opts out of RBF while still letting nLockTime apply. */
+declare const FINAL_SEQUENCE = 4294967294;
+/** What a description needs to tell recipient, change and unknown outputs apart. */
+interface DescribeContext {
+    network: BTC_NETWORK;
+    /** Our own address: outputs paying it are tagged `change`. */
+    ownAddress: string;
+    /** The spend the caller asked for. Outputs matching it are `recipient`; anything else is `unknown`. */
+    intended?: {
+        to: string;
+        value: bigint;
+    } | undefined;
+    maxFeeRate?: number | undefined;
+}
+/** Parse raw tx hex. Prevout amounts are not in the wire format — callers pass them in `inputValues`. */
+declare function parseRawTransaction(rawHex: string): Transaction;
+/**
+ * Describe a (signed or unsigned) btc-signer Transaction given the sat value of
+ * every input, in input order. Pure: no network, no signing.
+ */
+declare function describeTransaction(tx: Transaction, inputValues: bigint[], ctx: DescribeContext): BtcTxDescription;
+/**
+ * Hard checks run before signing and before broadcasting. Throws UnsafeTransactionError;
+ * never mutates. With `intended`, exactly one output must be the requested
+ * recipient/amount and every other output must be our change.
+ */
+declare function assertSafe(desc: BtcTxDescription, ctx: DescribeContext): void;
+
+/** Output-script families btc-signer recognises (`OutScript.decode(...).type`). */
+type ScriptKind = 'pk' | 'pkh' | 'sh' | 'wsh' | 'wpkh' | 'ms' | 'tr' | 'tr_ns' | 'tr_ms' | 'p2a' | 'unknown';
+/** An address decoded to its output script. */
+interface DecodedAddress {
+    script: Uint8Array;
+    kind: ScriptKind;
+}
+/** Decode and validate an address for `network`; throws on a malformed address or a foreign network. */
+declare function decodeAddress(address: string, network: BTC_NETWORK): DecodedAddress;
+/** Address for an output script, or undefined when the script has no address form. */
+declare function addressFromScript(script: Uint8Array, network: BTC_NETWORK): string | undefined;
+/** Type of an output script; `unknown` when it cannot be decoded. */
+declare function scriptKind(script: Uint8Array): ScriptKind;
+/** Address of a compressed public key: p2wpkh (`bc1q…`) or p2tr key-path (`bc1p…`). */
+declare function addressFromPublicKey(publicKey: Uint8Array, network: BTC_NETWORK, type?: BtcAddressType): string;
+/** Weight units one of OUR inputs adds once signed (prevout 41 B × 4 + witness). p2wpkh assumes a 72-byte DER sig. */
+declare const INPUT_WEIGHT: Record<BtcAddressType, number>;
+/** Virtual bytes an output of this script kind occupies (8 B value + 1 B len + script). */
+declare function outputVBytes(kind: ScriptKind, script?: Uint8Array): number;
+/** Bitcoin Core dust threshold (3 sat/vB discard rate) per output type, in sats. */
+declare function dustLimit(kind: ScriptKind): bigint;
+/** Smallest p2wpkh output relay policy accepts, in satoshis. */
+declare const DUST_LIMIT_P2WPKH: bigint;
+/** Smallest p2tr output relay policy accepts, in satoshis. */
+declare const DUST_LIMIT_P2TR: bigint;
+
+/** btc-signer ships mainnet + testnet; regtest only differs in the bech32 HRP. */
+declare const REGTEST_NETWORK: BTC_NETWORK;
+/** `@scure/btc-signer` parameters of a network. */
+declare function networkParams(network: BtcNetwork): BTC_NETWORK;
+/** SLIP-44 coin type: 0 for mainnet, 1 for every test network. */
+declare const coinType: (network: BtcNetwork) => 0 | 1;
+/** BIP purpose for the address type: 84 (p2wpkh) or 86 (p2tr). */
+declare const purposeFor: (type: BtcAddressType) => 84 | 86;
+
+/** A coin selection for one spend, with the recipient's script. */
+interface SpendPlan extends CoinSelection {
+    /** Sats the recipient gets (the requested value — never reduced). */
+    amount: bigint;
+    recipientScript: Uint8Array;
+    recipientKind: ScriptKind;
+}
+/** Watch-only Bitcoin account: balances, quotes, receipts, BIP-137 verification. No key. */
+declare class WalletAccountReadOnlyBtc implements IWalletAccountReadOnly {
+    /** The address. */
+    readonly address: string;
+    readonly chain: string;
+    /** Output script of `address`. */
+    readonly scriptPubKey: Uint8Array;
+    /** Script type of the address. */
+    readonly scriptKind: ScriptKind;
+    /** p2wpkh / p2tr when the address is one we know how to spend from; undefined for other script types. */
+    readonly addressType: BtcAddressType | undefined;
+    /** Smallest output this address type may create, in satoshis. */
+    readonly dustLimit: bigint;
+    protected readonly _config: BtcConfig;
+    protected readonly _client: BtcClient | undefined;
+    protected readonly _network: BTC_NETWORK;
+    protected readonly _networkName: BtcNetwork;
+    constructor(address: string, config?: BtcConfig);
+    protected requireClient(what: string): BtcClient;
+    /** Fee-rate ceiling in sat/vB: `BtcConfig.maxFeeRate` or {@link DEFAULT_MAX_FEE_RATE}. */
+    get maxFeeRate(): number;
+    /** The address. */
+    getAddress(): Promise<string>;
+    /** Confirmed minus pending outgoing (Bitcoin Core wallet semantics). */
+    getBalance(): Promise<bigint>;
+    /** Always throws: Bitcoin has no tokens. */
+    getTokenBalance(_token: string): Promise<bigint>;
+    /** Weight one of OUR inputs adds; throws for address types we cannot spend from. */
+    protected inputWeight(): number;
+    protected resolveFeeRate(spend: {
+        feeRate?: bigint | number;
+        confirmationTarget?: number;
+    }): Promise<bigint>;
+    /** Coin selection for a spend (see coinselect.ts). Validates the recipient and the dust floor first. */
+    protected planSpend(spend: BtcSpend): Promise<SpendPlan>;
+    /** Fee of a spend in satoshis, from a coin selection at the current fee rate. */
+    quoteSendTransaction(tx: BtcSpend): Promise<{
+        fee: bigint;
+    }>;
+    /**
+     * Fee of a transfer in satoshis.
+     *
+     * @throws Error when `token` is set.
+     */
+    quoteTransfer(o: BtcTransferOptions): Promise<{
+        fee: bigint;
+    }>;
+    /** Everything spendable in ONE transaction to a single output of our own address type, no change. */
+    getMaxSpendable(opts?: {
+        feeRate?: bigint | number;
+        confirmationTarget?: number;
+        to?: string;
+    }): Promise<BtcMaxSpendableResult>;
+    /** Undefined until the transaction is mined. */
+    getTransactionReceipt(hash: string): Promise<BtcReceipt | undefined>;
+    /** BIP-137: recover the key and compare its p2wpkh address with ours. Taproot addresses have no BIP-137 form. */
+    verify(message: string | Uint8Array, signature: string): Promise<boolean>;
+    /** Chain tip for anti-fee-sniping; undefined when disabled or the transport cannot tell. */
+    protected lockTimeHeight(): Promise<number>;
+}
+
+/** Address for a compressed public key; `network` may be a name or btc-signer params. */
+declare function addressFor(publicKey: Uint8Array, network?: BtcNetwork | BTC_NETWORK, type?: BtcAddressType): string;
+interface Built {
+    tx: Transaction;
+    fee: bigint;
+    plan: SpendPlan;
+    desc: BtcTxDescription;
+}
+/**
+ * Signing Bitcoin account — BIP-84 p2wpkh or BIP-86 p2tr (key-path). The key never
+ * enters this package: every signature is one `signer.sign(...)` call over a
+ * btc-signer-computed sighash — a {@link LocalSigner} for seed wallets, anything
+ * else (hardware, MPC, backend) through `externalSigner()`:
+ *
+ * ```text
+ * p2wpkh input  → `ecdsa`              over the BIP-143 sighash (SIGHASH_ALL), DER-encoded here
+ * p2tr input    → `schnorr` + `tweak`  over the BIP-341 sighash (DEFAULT), tweak = TapTweak(xonly)
+ * BIP-137 msg   → `ecdsa-recoverable`  over the magic hash
+ * ```
+ *
+ * Every spend is resolved to a full description ("what you sign") and run through
+ * the hard safety checks (fee-rate ceiling, recipient/amount exactness, change
+ * ownership) before signing AND before broadcast — also for caller-supplied raw hex.
+ */
+declare class WalletAccountBtc extends WalletAccountReadOnlyBtc implements IWalletAccount {
+    /** UTXOs, fee rate and tip height come from the network before signing. */
+    readonly needsNetwork = true;
+    /** Derivation path, or `external` for an external signer. */
+    readonly path: string;
+    /** Compressed secp256k1 public key. */
+    readonly publicKey: Uint8Array;
+    readonly addressType: BtcAddressType;
+    /** The signer that holds the key. */
+    readonly signer: Signer;
+    private _disposed;
+    private _readOnly;
+    /** `publicKey` is the signer's compressed secp256k1 key (33 bytes); it is needed synchronously for the address. */
+    constructor(signer: Signer, publicKey: Uint8Array, path: string, config?: BtcConfig);
+    /** Back-compat: wrap a raw derived key in a {@link LocalSigner} (the account takes ownership; it cannot derive). */
+    static fromPrivateKey(privateKey: Uint8Array, publicKey: Uint8Array, path: string, config?: BtcConfig): WalletAccountBtc;
+    /** Account index for the standard m/{84|86}'/{0|1}'/0'/0/i path. */
+    get index(): number | undefined;
+    private live;
+    /** BIP-137 p2wpkh signature, base64 (Electrum / Bitcoin Core encoding). Not available for taproot accounts. */
+    sign(message: string | Uint8Array): Promise<string>;
+    /** The x-only internal key and its BIP-86 tweak (no script tree) for taproot key-path spends. */
+    private taprootKeys;
+    /**
+     * Sign every input through the signer and attach the witness-ready signature:
+     * p2wpkh → `partialSig` (DER + SIGHASH_ALL), p2tr → `tapKeySig` (64 bytes, DEFAULT).
+     * btc-signer only computes the sighash and assembles the witness; it never sees a key.
+     */
+    private signInputs;
+    private ctx;
+    private buildAndSign;
+    /**
+     * Plan → sign → measure. The plan's fee assumes 72-byte DER signatures; if the
+     * signed vsize somehow needs more, the difference comes out of change (never the
+     * recipient) and the tx is re-signed once.
+     */
+    protected buildSignedTransaction(spend: BtcSpend): Promise<Built>;
+    private checkMax;
+    /**
+     * BIP-143 (p2wpkh) commits each input's signature to that input's CLAIMED amount
+     * only: an indexer that understates a different coin in each of two signing
+     * sessions can combine their signatures into one valid tx whose real fee the
+     * wallet never showed (scan 2026-10-23 F2). So every p2wpkh coin is read from
+     * its full previous transaction, which must hash to the claimed txid, and its
+     * amount and script must match before anything is signed. Taproot (BIP-341)
+     * commits to every input amount and skips the extra requests.
+     */
+    private verifyPrevouts;
+    /** Prevout values of a raw tx, fetched through the client (the wire format carries none). */
+    private inputValues;
+    /** Describe a raw signed tx (needs the network for prevout values) and run the safety checks. */
+    private describeRaw;
+    /** "What you sign": the fully resolved spend (signed, NOT broadcast) or a caller's raw hex. */
+    describeTransaction(tx: BtcTransaction): Promise<BtcTxDescription>;
+    /** Sign without broadcasting. Returns the raw transaction hex. Raw hex input is returned unchanged. */
+    signTransaction(tx: BtcTransaction): Promise<string>;
+    quoteSendTransaction(tx: BtcTransaction): Promise<{
+        fee: bigint;
+    }>;
+    sendTransaction(tx: BtcTransaction): Promise<TransferResult>;
+    /** Native BTC only (`token` is rejected). Subject to `transferMaxFee`. */
+    transfer(o: BtcTransferOptions): Promise<TransferResult>;
+    /** The same address as a {@link WalletAccountReadOnlyBtc}. */
+    toReadOnlyAccount(): IWalletAccountReadOnly;
+    dispose(): void;
+}
+
+/**
+ * One seed → Bitcoin accounts.
+ *   p2wpkh (default): BIP-84, m/84'/0'/0'/0/i on mainnet, m/84'/1'/0'/0/i on test networks — bc1q… / tb1q…
+ *   p2tr:             BIP-86, m/86'/0'/0'/0/i (key-path taproot) — bc1p… / tb1p…
+ * Paths may be relative to the purpose/coin prefix ("0'/0/i") or given in full.
+ *
+ * Built with a secp256k1 `Signer` instead of a seed, the manager wraps it:
+ * - a derivable `SeedSigner` sitting at the account branch (`m/84'/0'/0'/0` or
+ *   `m/86'/0'/0'/0`, per `addressType`/`network`) yields `getAccount(i)` children;
+ * - a `SeedSigner` at a leaf, or any external signer, is `getAccount(0)` (path = the
+ *   signer's path, or 'external') with the configured address type; other
+ *   indexes/paths throw.
+ */
+declare class WalletManagerBtc extends WalletManager<WalletAccountBtc, BtcConfig> {
+    constructor(seedOrSigner: string | Uint8Array | Signer, config?: BtcConfig);
+    /**
+     * `m/84'/0'` for p2wpkh or `m/86'/0'` for p2tr on mainnet (coin type 1 on test networks); account
+     * `i` is at `basePath/0'/0/i`.
+     */
+    get basePath(): string;
+    getAccount(index?: number): Promise<WalletAccountBtc>;
+    getAccountByPath(path: string): Promise<WalletAccountBtc>;
+    /** Resolve `path` against an injected signer: the signer itself, or a child when it can derive there. */
+    private fromSigner;
+    /** A read-only account for any address, with this manager's config. */
+    getReadOnlyAccount(address: string): WalletAccountReadOnlyBtc;
+    /** sat/vB from the client's estimator: fast = 1 block, normal = 3, slow = 6. */
+    getFeeRates(): Promise<FeeRates>;
+}
+
+export { BlockbookTx, BtcAddressType, BtcClient, BtcConfig, BtcMaxSpendableResult, BtcNetwork, BtcReceipt, BtcSpend, BtcTransaction, BtcTransferOptions, BtcTxDescription, type CoinSelectOptions, type CoinSelection, DEFAULT_MAX_FEE_RATE, DUST_LIMIT_P2TR, DUST_LIMIT_P2WPKH, type DecodedAddress, type DescribeContext, EsploraClient, FINAL_SEQUENCE, INPUT_WEIGHT, MAX_UTXO_INPUTS, RBF_SEQUENCE, REGTEST_NETWORK, type ScriptKind, type SegwitType, type SelectionTarget, type SpendPlan, TooManyInputsError, type UnsafeTransactionCode, UnsafeTransactionError, UnsupportedAddressTypeError, Utxo, WalletAccountBtc, WalletAccountReadOnlyBtc, WalletManagerBtc, addressFor, addressFromPublicKey, addressFromScript, assertSafe, coinType, createClient, decodeAddress, WalletManagerBtc as default, describeTransaction, dustLimit, encodeMessageSignature, estimateVsize, magicHash, networkParams, outputVBytes, parseRawTransaction, purposeFor, recoverMessagePublicKey, scriptKind, selectAll, selectCoins, signMessage, signMessageWith, spendableUtxos };