@scure/btc-signer 2.2.0 → 2.4.0

package/net.d.ts

@@ -0,0 +1,355 @@
+import type * as psbt from './psbt.ts';
+import { type BTC_NETWORK } from './utils.ts';
+/** Subclass for all EsploraProvider related errors */
+export declare class EsploraError extends Error {
+    readonly status?: number;
+    readonly path?: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        path?: string;
+    });
+}
+type FetchOpts = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+};
+type FetchResponse = {
+    ok: boolean;
+    status: number;
+    statusText?: string;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+};
+/** Minimal fetch-compatible transport accepted by {@link EsploraProvider}. */
+export type FetchFn = (url: string, opts?: FetchOpts) => Promise<FetchResponse>;
+/** Confirmation metadata from Esplora-compatible transaction responses. */
+export type TxStatus = {
+    /** Whether the transaction is confirmed in a block. */
+    confirmed: boolean;
+    /** Confirming block height, absent for mempool transactions. */
+    block?: number;
+    /** Confirming block hash, absent for mempool transactions. */
+    blockHash?: string;
+    /** Confirming block timestamp in milliseconds, absent for mempool transactions. */
+    timestamp?: number;
+};
+/** Transaction output as reported by Esplora-compatible APIs. */
+export type TxOutput = {
+    /** Hex-encoded scriptPubKey. */
+    scriptPubKey: string;
+    /** Decoded address when the script has a known address form. */
+    scriptPubKeyAddress?: string;
+    /** Output value in satoshis. */
+    value: bigint;
+};
+/** Transaction input as reported by Esplora-compatible APIs. */
+export type TxInput = {
+    /** Previous transaction id for non-coinbase inputs. */
+    txid?: string;
+    /** Previous output index for non-coinbase inputs. */
+    index?: number;
+    /** Previous output details when supplied by the backend. */
+    prevout?: TxOutput;
+    /** Input sequence number. */
+    sequence?: number;
+    /** Whether this input is a coinbase input. */
+    isCoinbase?: boolean;
+};
+/** Full Bitcoin transaction metadata returned by {@link EsploraProvider.txInfo}. */
+export type TxInfo = {
+    /** Transaction id. */
+    txid: string;
+    /** Transaction version. */
+    version: number;
+    /** Transaction locktime. */
+    lockTime: number;
+    /** Serialized transaction size in bytes. */
+    size: number;
+    /** Transaction weight units. */
+    weight: number;
+    /** Fee paid by the transaction in satoshis. */
+    fee: bigint;
+    /** Transaction inputs. */
+    inputs: TxInput[];
+    /** Transaction outputs. */
+    outputs: TxOutput[];
+    /** Confirmation status. */
+    status: TxStatus;
+    /** Hex-encoded raw transaction. */
+    raw: string;
+};
+/** Block metadata returned by Esplora-compatible APIs. */
+export type BlockInfo = {
+    /** Block hash. */
+    hash: string;
+    /** Block number / height. */
+    number: number;
+    /** Block version. */
+    version: number;
+    /** Block timestamp in milliseconds. */
+    timestamp: number;
+    /** Serialized block size in bytes. */
+    size: number;
+    /** Block weight units. */
+    weight: number;
+    /** Merkle root hash. */
+    merkleRoot: string;
+    /** Previous block hash, absent for genesis. */
+    parentHash?: string;
+    /** Median block timestamp in milliseconds when the backend returns it. */
+    medianTime?: number;
+    /** Block nonce. */
+    nonce?: number;
+    /** Compact difficulty bits. */
+    bits?: number;
+    /** Floating-point network difficulty. */
+    difficulty?: number;
+    /** Transaction hashes in block order. */
+    transactions: string[];
+};
+/** Value movement entry derived from Bitcoin transaction inputs or outputs. */
+export type Transfer = {
+    /** Source address for input-side movements, absent when the backend cannot decode one. */
+    from?: string;
+    /** Destination address for output-side movements, absent for scripts without address form. */
+    to?: string;
+    /** Value in satoshis. */
+    value: bigint;
+};
+/** Address-history transaction with transfer records and compact transaction metadata. */
+export type TxTransfers = {
+    /** Transaction id. */
+    txid: string;
+    /** Confirming block timestamp in milliseconds, absent for mempool transactions. */
+    timestamp?: number;
+    /** Confirming block height, absent for mempool transactions. */
+    block?: number;
+    /** Input and output value movements for the whole transaction. */
+    transfers: Transfer[];
+    /** Compact transaction metadata useful for wallet history. */
+    info: {
+        /** Transaction version. */
+        version: number;
+        /** Transaction locktime. */
+        lockTime: number;
+        /** Serialized transaction size in bytes. */
+        size: number;
+        /** Transaction weight units. */
+        weight: number;
+        /** Transaction fee in satoshis. */
+        fee: bigint;
+        /** Confirming block hash, absent for mempool transactions. */
+        blockHash?: string;
+        /** Hex-encoded raw transaction. */
+        raw: string;
+    };
+};
+/** Merged multi-address history row from {@link EsploraProvider.historyMulti}. */
+export type MultiTxTransfers = TxTransfers & {
+    /** Watched addresses participating in this transaction's transfers. */
+    addresses: string[];
+};
+/** UTXO set for an address in a shape accepted by transaction builders. */
+export type Unspent = {
+    /** Asset symbol. */
+    symbol: 'BTC';
+    /** Decimal precision for BTC amounts. */
+    decimals: number;
+    /** Sum of returned spendable outputs in satoshis. */
+    balance: bigint;
+    /** Input updates that can be passed to `Transaction.addInput` or `selectUTXO`. */
+    utxo: psbt.TransactionInputUpdate[];
+};
+/** Lightweight address balance from Esplora stats, without enumerating UTXOs. */
+export type Balance = {
+    /** Asset symbol. */
+    symbol: 'BTC';
+    /** Decimal precision for BTC amounts. */
+    decimals: number;
+    /** Current address balance in satoshis. */
+    balance: bigint;
+    /** Confirmed plus mempool transaction count. */
+    txCount: number;
+};
+/** Scan progress reported by {@link EsploraProvider.history} while metadata pages arrive. */
+export type ScanProgress = {
+    /** Transactions scanned so far, before block-range and limit filters. */
+    scannedTxs: number;
+    /** Confirmed plus mempool transaction count for the address, from address stats. */
+    totalTxs: number;
+    /** Share of the address history scanned so far, 0-100. */
+    percent: number;
+    /** Height of the most recently scanned confirmed transaction, absent for mempool rows. */
+    currentBlock?: number;
+};
+/** Address-history pagination and filtering options. */
+export type TransfersOpts = {
+    /** Inclusive lower block bound. */
+    fromBlock?: number;
+    /** Inclusive upper block bound. */
+    toBlock?: number;
+    /** Maximum number of matching transactions to return. */
+    limit?: number;
+    /** Return transactions older than this address-history cursor txid. */
+    afterTxid?: string;
+    /** Aborts the scan; checked between requests and passed to the transport. */
+    signal?: AbortSignal;
+    /** Progress listener; costs one extra address-stats request to size the scan. */
+    onProgress?: (progress: ScanProgress) => void;
+    /** Maximum concurrent raw-transaction fetches (default 8). */
+    concurrency?: number;
+};
+/** {@link EsploraProvider.history} options: transfers filters plus yield direction. */
+export type HistoryOpts = TransfersOpts & {
+    /**
+     * Yield direction. `newest` (default) streams rows while pages arrive, so
+     * stopping early also stops fetching. `oldest` (the transfers() order) must
+     * buffer transaction metadata first, since Esplora only pages newest-first.
+     */
+    order?: 'newest' | 'oldest';
+};
+/** {@link EsploraProvider.unspent} scan options. */
+export type UnspentOpts = {
+    /** Aborts the scan; checked between requests and passed to the transport. */
+    signal?: AbortSignal;
+    /** Maximum concurrent raw-transaction fetches (default 8). */
+    concurrency?: number;
+};
+/** {@link EsploraProvider.waitForTx} options. */
+export type WaitTxOpts = {
+    /** Blocks on top of the inclusion block, default 1 (just included). */
+    confirmations?: number;
+    /** Delay between status polls in milliseconds, default 5000. */
+    pollIntervalMs?: number;
+    /** Give up (reject) after this long; default is to wait forever. */
+    timeoutMs?: number;
+    /** Aborts the wait; checked between polls and passed to the transport. */
+    signal?: AbortSignal;
+};
+/** Running balance snapshot attached by {@link calcTransfersDiff}. */
+export type Balances = {
+    /** Running satoshi balance by address after this transaction. */
+    balances: Record<string, bigint>;
+};
+/**
+ * Esplora-compatible Bitcoin HTTP provider.
+ *
+ * Runtime transport is caller-provided `fetch`. The repository `test/proxy.ts`
+ * bridge is test/dev tooling for serving the wallet/history HTTP subset from Electrum TCP.
+ * Transient backend failures (429/5xx, dropped connections) are retried with
+ * exponential backoff on GET requests; long-running scans accept `AbortSignal`.
+ * @param fetch - Fetch-compatible HTTP transport.
+ * @param url - Base URL of an Esplora-compatible HTTP API.
+ * @param network - Bitcoin address network parameters.
+ * @example
+ * Create a provider with a caller-owned transport.
+ * ```ts
+ * import { EsploraProvider } from '@scure/btc-signer/net.js';
+ * const httpFetch = async () => ({
+ *   ok: true,
+ *   status: 200,
+ *   text: async () => '1',
+ *   json: async () => ({ '2': 1 }),
+ * });
+ * const net = new EsploraProvider(httpFetch, 'http://127.0.0.1:3000');
+ * await net.height();
+ * ```
+ */
+export declare class EsploraProvider {
+    private fetch;
+    private url;
+    private address;
+    constructor(fetch: FetchFn, url: string, network?: BTC_NETWORK);
+    private request;
+    private requestBody;
+    private getJson;
+    private getText;
+    private addressPath;
+    private canonicalAddress;
+    private txHex;
+    /**
+     * Fetches raw tx hex and verifies it is actually the transaction the txid
+     * names, otherwise balances would be computed from whatever transaction the
+     * backend chose to serve. `memo` dedupes fetches within one scan: a tx
+     * shared by several watched addresses must cost one request, not one per
+     * address stream.
+     */
+    private fetchRawTx;
+    /**
+     * Pages through Esplora address history newest-first, one transaction at a
+     * time. The single owner of cursor pagination: the mempool-aware afterTxid
+     * jump, the full-page heuristic and the cursor-loop guard live here.
+     */
+    private addressTxs;
+    private historyInner;
+    private historyMultiInner;
+    height(opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
+    blockInfo(block: number): Promise<BlockInfo>;
+    fee(target?: number): Promise<bigint>;
+    /** Lightweight method to receive the "unspent" amount without getting the full UTXO list. */
+    balance(address: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Balance>;
+    txCount(address: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<number>;
+    sendTx(tx: string): Promise<string>;
+    /**
+     * Polls transaction status until it confirms (plus optional extra
+     * confirmations). A just-broadcast transaction may briefly be unknown to the
+     * backend, so 404 responses keep polling instead of failing.
+     */
+    waitForTx(txid: string, opts?: WaitTxOpts): Promise<TxStatus>;
+    txInfo(txid: string): Promise<TxInfo>;
+    unspent(address: string, opts?: UnspentOpts): Promise<Unspent>;
+    /**
+     * Streaming address history. Yields the same {@link TxTransfers} rows as
+     * {@link EsploraProvider.transfers}, one at a time, so callers can render or
+     * persist rows without waiting for the whole scan.
+     *
+     * `order: 'newest'` (default) follows Esplora pagination from the mempool
+     * backward and streams genuinely: stopping early (break / `limit`) also
+     * stops fetching. `order: 'oldest'` yields in transfers() order and must
+     * buffer transaction metadata first, since Esplora only pages newest-first;
+     * raw transactions still stream in bounded batches.
+     * @example
+     * ```ts
+     * for await (const tx of net.history(address, { limit: 10 })) console.log(tx.txid);
+     * ```
+     */
+    history(address: string, opts?: HistoryOpts): AsyncGenerator<TxTransfers, void>;
+    /**
+     * Merged history across several addresses (HD wallets, watch lists): one
+     * txid-deduplicated stream in `order`, k-way merged from per-address
+     * {@link EsploraProvider.history} streams. A transaction moving funds
+     * between two watched addresses appears once; its `addresses` field lists
+     * the watched participants. All options apply to each underlying stream, so
+     * `limit` caps rows per address, not the merged total; `afterTxid` is
+     * rejected because a chain cursor only exists in one address's history.
+     * Same-block rows from different addresses have no canonical order.
+     */
+    historyMulti(addresses: string[], opts?: HistoryOpts): AsyncGenerator<MultiTxTransfers, void>;
+    /**
+     * Address history as chronological transfer rows, oldest first. Buffered
+     * variant of {@link EsploraProvider.history}; use that to stream rows.
+     */
+    transfers(address: string, opts?: TransfersOpts): Promise<TxTransfers[]>;
+}
+/**
+ * Calculates balances at specific point in time after tx.
+ * Info from multiple addresses can be merged when transactions are already sorted.
+ * @param transfers - Transaction transfer records.
+ * @returns Same transfer records with running balance snapshots attached.
+ * @example
+ * Fold an address history into running balances.
+ * ```ts
+ * import { calcTransfersDiff } from '@scure/btc-signer/net.js';
+ * calcTransfersDiff([]);
+ * ```
+ */
+export declare function calcTransfersDiff(transfers: TxTransfers[]): (TxTransfers & Balances)[];
+export {};