@arkade-os/sdk 0.4.27 → 0.4.28

package/dist/esm/providers/electrum.js

@@ -1,864 +0,0 @@
-import { Address, OutScript, Transaction } from "@scure/btc-signer";
-import { sha256 } from "@scure/btc-signer/utils.js";
-import { hex } from "@scure/base";
-/**
- * Default WebSocket Electrum endpoints. Mainnet, mutinynet, and signet
- * point at Ark Labs–operated Fulcrum 2.1 deployments (which support
- * `blockchain.transaction.broadcast_package` for atomic 1P1C TRUC
- * relay; see `ElectrumOnchainProvider.broadcastTransaction`). Testnet
- * defaults to Blockstream's public Fulcrum because Ark doesn't host
- * it. Regtest assumes the `electrum-ws` websocat bridge from
- * `vulpemventures/nigiri`.
- *
- * @example
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import { ELECTRUM_WS_URL, ElectrumOnchainProvider, networks } from "@arkade-os/sdk";
- *
- * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- * ```
- */
-export const ELECTRUM_WS_URL = {
-    bitcoin: "wss://electrum.arkade.sh",
-    testnet: "wss://electrum.blockstream.info:60004",
-    signet: "wss://electrum.signet.arkade.sh",
-    mutinynet: "wss://electrum.mutinynet.arkade.sh",
-    regtest: "ws://localhost:50003",
-};
-/**
- * Hostnames for Electrum endpoints reachable over raw TCP. Provided as
- * a reference for Node-side consumers — the SDK's
- * {@link ElectrumOnchainProvider} only speaks WebSocket because it has
- * to run in browsers, so this map is informational only and not
- * consumed by any built-in provider.
- *
- * Public Ark Labs Fulcrum instances expose:
- *   - port 50001 — plain TCP (Electrum protocol)
- *   - port 50002 — TCP + TLS (Electrum protocol)
- *   - port 50003 — WebSocket (Electrum-over-WS, see {@link ELECTRUM_WS_URL})
- */
-export const ELECTRUM_TCP_HOST = {
-    bitcoin: "electrum.arkade.sh",
-    testnet: null,
-    signet: "electrum.signet.arkade.sh",
-    mutinynet: "electrum.mutinynet.arkade.sh",
-    regtest: "localhost",
-};
-// Electrum protocol method names
-const BroadcastTransaction = "blockchain.transaction.broadcast";
-const BroadcastPackageMethod = "blockchain.transaction.broadcast_package";
-const EstimateFee = "blockchain.estimatefee";
-const GetBlockHeader = "blockchain.block.header";
-const GetHistoryMethod = "blockchain.scripthash.get_history";
-const GetTransactionMethod = "blockchain.transaction.get";
-const GetTransactionMerkleMethod = "blockchain.transaction.get_merkle";
-const SubscribeStatusMethod = "blockchain.scripthash";
-const SubscribeHeadersMethod = "blockchain.headers";
-const GetRelayFeeMethod = "blockchain.relayfee";
-const ListUnspentMethod = "blockchain.scripthash.listunspent";
-const MISSING_TRANSACTION = "missingtransaction";
-const MAX_FETCH_TRANSACTIONS_ATTEMPTS = 5;
-// Bitcoin block header is 80 bytes
-const BLOCK_HEADER_SIZE = 80;
-/**
- * Parse a raw block header (80 bytes hex = 160 chars) to extract fields.
- * Bitcoin block header layout:
- *   - version: 4 bytes (LE)
- *   - prevHash: 32 bytes
- *   - merkleRoot: 32 bytes
- *   - timestamp: 4 bytes (LE)
- *   - bits: 4 bytes
- *   - nonce: 4 bytes
- */
-function parseBlockHeader(headerHex) {
-    const headerBytes = hex.decode(headerHex);
-    if (headerBytes.length !== BLOCK_HEADER_SIZE) {
-        throw new Error(`Invalid block header size: ${headerBytes.length}, expected ${BLOCK_HEADER_SIZE}`);
-    }
-    // timestamp is at offset 68 (4+32+32), 4 bytes little-endian
-    const view = new DataView(headerBytes.buffer, headerBytes.byteOffset);
-    const timestamp = view.getUint32(68, true);
-    // block hash = double SHA256 of header, reversed
-    const hash1 = sha256(headerBytes);
-    const hash2 = sha256(hash1);
-    const hashStr = hex.encode(new Uint8Array(hash2).reverse());
-    return { hash: hashStr, timestamp };
-}
-/**
- * WebSocket-based Electrum chain source using ws-electrumx-client.
- * Provides low-level methods for the Electrum protocol.
- *
- * @example
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import { WsElectrumChainSource } from "./providers/electrum.js";
- * import { networks } from "./networks.js";
- *
- * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
- * const chain = new WsElectrumChainSource(ws, networks.bitcoin);
- *
- * const history = await chain.fetchHistories([script]);
- * await chain.close();
- * ```
- */
-export class WsElectrumChainSource {
-    constructor(ws, network) {
-        this.ws = ws;
-        this.network = network;
-        // Cached chain tip kept fresh by the headers subscription. Initialized
-        // lazily on first call to subscribeHeaders().
-        this.cachedTip = null;
-        this.headersSubscribePromise = null;
-    }
-    /**
-     * Send N requests in parallel and aggregate the results, replacement
-     * for `ws.batchRequest`. The library's batchRequest is implemented as
-     * `Promise.all` over individual request promises — when one element
-     * rejects, the others remain pending. When their (often error)
-     * responses arrive later, the library rejects them too, and nobody is
-     * awaiting them: the rejections become unhandled and crash the test
-     * runner / pollute production logs.
-     *
-     * `safeBatchRequest` issues each request through `ws.request` (so each
-     * has its own request-promise lifecycle), waits for all of them via
-     * `Promise.allSettled` (every promise gets an explicit handler), and
-     * then surfaces the first error if any failed. Same wall-clock cost
-     * as the library's batch (parallel send), no orphan rejections.
-     *
-     * Use this in place of `ws.batchRequest` for any call where one or
-     * more elements may legitimately error (e.g. electrs index lag
-     * surfacing as `missingheight` for a subset of heights/txids).
-     */
-    async safeBatchRequest(requests) {
-        if (requests.length === 0)
-            return [];
-        const settled = await Promise.allSettled(requests.map((req) => this.ws.request(req.method, ...req.params)));
-        for (const r of settled) {
-            if (r.status === "rejected")
-                throw r.reason;
-        }
-        return settled.map((r) => r.value);
-    }
-    async fetchTransactions(txids) {
-        const requests = txids.map((txid) => ({
-            method: GetTransactionMethod,
-            params: [txid],
-        }));
-        for (let i = 0; i < MAX_FETCH_TRANSACTIONS_ATTEMPTS; i++) {
-            try {
-                const responses = await this.safeBatchRequest(requests);
-                return responses.map((hexStr, i) => ({
-                    txID: txids[i],
-                    hex: hexStr,
-                }));
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                if (msg.toLowerCase().includes(MISSING_TRANSACTION)) {
-                    console.warn("missing transaction error, retrying");
-                    await new Promise((resolve) => setTimeout(resolve, 1000));
-                    continue;
-                }
-                throw e;
-            }
-        }
-        throw new Error("Unable to fetch transactions: " + txids);
-    }
-    async fetchVerboseTransaction(txid) {
-        return this.ws.request(GetTransactionMethod, txid, true);
-    }
-    async fetchVerboseTransactions(txids) {
-        if (txids.length === 0)
-            return [];
-        const requests = txids.map((txid) => ({
-            method: GetTransactionMethod,
-            params: [txid, true],
-        }));
-        return this.safeBatchRequest(requests);
-    }
-    /**
-     * Look up the block height of a confirmed transaction without relying
-     * on the verbose-tx endpoint. `blockchain.transaction.get_merkle` is
-     * part of the standard SPV protocol and is supported by both Fulcrum
-     * and electrs (whereas `blockchain.transaction.get` with verbose=true
-     * is Fulcrum-only). Returns `null` when the tx is in the mempool —
-     * electrs in that case rejects with a "not yet in a block" error.
-     */
-    async fetchTxMerkle(txid) {
-        let result;
-        try {
-            result = await this.ws.request(GetTransactionMerkleMethod, txid);
-        }
-        catch (err) {
-            // electrs/Fulcrum raise specific errors when the tx isn't yet in
-            // a block — either "not in a block" wording, or "missingheight"
-            // when get_merkle hits the same index-lag race that block.header
-            // hits (the tx is reportedly confirmed but the height isn't
-            // queryable yet). Map both to mempool/unknown; everything else
-            // (auth failure, network outage, malformed response) must surface
-            // so callers can fail rather than silently treat the tx as
-            // unconfirmed forever.
-            if (isTxNotInBlockError(err) || isMissingHeightError(err))
-                return null;
-            throw err;
-        }
-        if (!result ||
-            typeof result.block_height !== "number" ||
-            result.block_height <= 0) {
-            return null;
-        }
-        return { blockHeight: result.block_height };
-    }
-    async unsubscribeScriptStatus(script) {
-        await this.ws
-            .unsubscribe(SubscribeStatusMethod, toScriptHash(script))
-            .catch(() => { });
-    }
-    async subscribeScriptStatus(script, callback) {
-        const scriptHash = toScriptHash(script);
-        await this.ws.subscribe(SubscribeStatusMethod, (scripthash, status) => {
-            if (scripthash === scriptHash) {
-                callback(scripthash, status);
-            }
-        }, scriptHash);
-    }
-    async fetchHistories(scripts) {
-        const scriptsHashes = scripts.map((s) => toScriptHash(s));
-        return this.safeBatchRequest(scriptsHashes.map((s) => ({
-            method: GetHistoryMethod,
-            params: [s],
-        })));
-    }
-    async fetchHistory(script) {
-        const scriptHash = toScriptHash(script);
-        return this.ws.request(GetHistoryMethod, scriptHash);
-    }
-    async fetchBlockHeaders(heights) {
-        const responses = await this.safeBatchRequest(heights.map((h) => ({ method: GetBlockHeader, params: [h] })));
-        return responses.map((hexStr, i) => ({
-            height: heights[i],
-            hex: hexStr,
-        }));
-    }
-    async fetchBlockHeader(height) {
-        const headerHex = await this.ws.request(GetBlockHeader, height);
-        return { height, hex: headerHex };
-    }
-    /**
-     * Returns the current chain tip and keeps it fresh via a single
-     * server-side subscription. Subsequent calls return the cached tip
-     * (updated by background notifications) without round-tripping to the
-     * server. Previously each call issued `blockchain.headers.subscribe` as
-     * a regular request, leaving a stale subscription on the server every
-     * time — under polling that adds up. ws-electrumx-client deduplicates
-     * `subscribe()` by method+params, so registering once is enough.
-     */
-    async subscribeHeaders() {
-        if (this.cachedTip)
-            return this.cachedTip;
-        if (this.headersSubscribePromise)
-            return this.headersSubscribePromise;
-        this.headersSubscribePromise = new Promise((resolve, reject) => {
-            let resolved = false;
-            this.ws
-                .subscribe(SubscribeHeadersMethod, (header) => {
-                if (!isHeaderSubscribeResult(header))
-                    return;
-                this.cachedTip = header;
-                if (!resolved) {
-                    resolved = true;
-                    resolve(header);
-                }
-            })
-                .catch((err) => {
-                if (!resolved) {
-                    resolved = true;
-                    reject(err);
-                }
-            });
-        });
-        try {
-            return await this.headersSubscribePromise;
-        }
-        catch (err) {
-            // Allow the next call to retry from scratch.
-            this.headersSubscribePromise = null;
-            throw err;
-        }
-    }
-    async estimateFees(targetNumberBlocks) {
-        const feeRate = await this.ws.request(EstimateFee, targetNumberBlocks);
-        return feeRate;
-    }
-    async broadcastTransaction(txHex) {
-        return this.ws.request(BroadcastTransaction, txHex);
-    }
-    /**
-     * Submit a package of raw transactions atomically via Fulcrum's
-     * `blockchain.transaction.broadcast_package` method, the on-the-wire
-     * equivalent of bitcoind's `submitpackage` RPC.
-     *
-     * Required for TRUC (BIP 431) 1P1C relay where the parent has zero
-     * (or below-minfee) fee and depends on the child to pay for both via
-     * CPFP — sequential broadcast cannot work in that case because the
-     * parent would be rejected from the mempool on its own.
-     *
-     * @param txHexes - Topologically sorted raw transactions; child must
-     *                  be the last element. Currently must be a 1P1C pair
-     *                  (length 2). Parents may not depend on each other.
-     * @returns The child transaction id (the last entry in the array),
-     *          computed locally — `broadcast_package` itself returns
-     *          `{success, errors}` rather than a txid.
-     * @throws If the server does not implement `broadcast_package` (e.g.
-     *         ElectrumX, or older Fulcrum, or Fulcrum backed by bitcoind
-     *         < v28.0.0). Callers must surface this clearly to users —
-     *         this method does NOT silently fall back to sequential
-     *         broadcasts because doing so would let TRUC packages fail
-     *         in subtle ways.
-     * @throws If the server returns `success=false`, surfacing the
-     *         underlying mempool rejection in the error message.
-     */
-    async broadcastPackage(txHexes) {
-        const result = await this.ws.request(BroadcastPackageMethod, txHexes, false);
-        if (!result.success) {
-            const detail = result.errors
-                ? JSON.stringify(result.errors)
-                : "unknown error";
-            throw new Error(`Package broadcast rejected: ${detail}`);
-        }
-        // The child txid is not in the response — derive it from the raw
-        // bytes (double-SHA256 of the serialized tx, reversed).
-        return childTxidFromHex(txHexes[txHexes.length - 1]);
-    }
-    async getRelayFee() {
-        return this.ws.request(GetRelayFeeMethod);
-    }
-    async close() {
-        try {
-            await this.ws.close("close");
-        }
-        catch (e) {
-            console.debug("error closing ws:", e);
-        }
-    }
-    waitForAddressReceivesTx(addr) {
-        return new Promise((resolve, reject) => {
-            const script = OutScript.encode(Address(this.network).decode(addr));
-            this.subscribeScriptStatus(script, (_, status) => {
-                if (status !== null) {
-                    resolve();
-                }
-            }).catch(reject);
-        });
-    }
-    async listUnspents(addr) {
-        const script = OutScript.encode(Address(this.network).decode(addr));
-        const scriptHash = toScriptHash(script);
-        const unspentsFromElectrum = await this.ws.request(ListUnspentMethod, scriptHash);
-        const txs = await this.fetchTransactions(unspentsFromElectrum.map((u) => u.tx_hash));
-        return unspentsFromElectrum.map((u, index) => {
-            const tx = Transaction.fromRaw(hex.decode(txs[index].hex), {
-                allowUnknownOutputs: true,
-            });
-            const output = tx.getOutput(u.tx_pos);
-            if (!output.script || output.amount === undefined) {
-                throw new Error(`Missing output data for ${u.tx_hash}:${u.tx_pos}`);
-            }
-            return {
-                txid: u.tx_hash,
-                vout: u.tx_pos,
-                witnessUtxo: {
-                    script: output.script,
-                    value: output.amount,
-                },
-            };
-        });
-    }
-    /**
-     * Get the address string for a script output, if decodable.
-     */
-    addressForScript(scriptHex) {
-        try {
-            const script = hex.decode(scriptHex);
-            return Address(this.network).encode(OutScript.decode(script));
-        }
-        catch {
-            return undefined;
-        }
-    }
-}
-/**
- * Electrum-based implementation of the {@link OnchainProvider} interface.
- *
- * Built around the subset of the Electrum protocol that both **Fulcrum**
- * and **electrs** support — listunspent, get_history, transaction.get
- * (non-verbose), transaction.get_merkle, block.header,
- * headers.subscribe, scripthash.subscribe, estimatefee, relayfee, and
- * broadcast. The verbose form of `transaction.get` is **not** used (it's
- * Fulcrum-only and rejected by electrs); confirmation status is derived
- * from `transaction.get_merkle` plus parsed block headers.
- *
- * Output amounts are derived from parsed raw transaction bytes (exact
- * bigints), never the floating-point `value` fields some servers return.
- *
- * Atomic 1P1C package broadcast (TRUC / BIP 431) is supported via
- * Fulcrum's `blockchain.transaction.broadcast_package`. There is **no
- * fallback** to sequential parent-then-child broadcasts — TRUC packages
- * with a zero-fee parent would silently fail, so the call surfaces an
- * error against servers that don't support the method.
- *
- * @example Default URL via {@link ELECTRUM_WS_URL}
- * ```typescript
- * import { ElectrumWS } from "ws-electrumx-client";
- * import {
- *   ElectrumOnchainProvider,
- *   ELECTRUM_WS_URL,
- *   networks,
- * } from "@arkade-os/sdk";
- *
- * const ws = new ElectrumWS(ELECTRUM_WS_URL.bitcoin);
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- *
- * const coins = await provider.getCoins("bc1q...");
- * await provider.close();
- * ```
- *
- * @example Custom server
- * ```typescript
- * const ws = new ElectrumWS("wss://my-fulcrum.example:50004");
- * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
- * ```
- */
-export class ElectrumOnchainProvider {
-    constructor(ws, network) {
-        this.ws = ws;
-        this.network = network;
-        this.chain = new WsElectrumChainSource(ws, network);
-    }
-    async getCoins(address) {
-        const script = this.encodeAddress(address);
-        const scriptHash = toScriptHash(script);
-        const unspents = await this.ws.request(ListUnspentMethod, scriptHash);
-        return unspents.map((u) => ({
-            txid: u.tx_hash,
-            vout: u.tx_pos,
-            value: u.value,
-            status: {
-                confirmed: u.height > 0,
-                block_height: u.height > 0 ? u.height : undefined,
-            },
-        }));
-    }
-    async getFeeRate() {
-        // electrum returns BTC/kB, we need sat/vB
-        // 1 BTC = 100_000_000 sat, 1 kB = 1000 bytes
-        // sat/vB = (BTC/kB) * 100_000_000 / 1000 = (BTC/kB) * 100_000
-        const feePerKb = await this.chain.estimateFees(1);
-        if (feePerKb < 0) {
-            // -1 means the daemon cannot estimate
-            return undefined;
-        }
-        return Math.max(1, Math.ceil(feePerKb * 100000));
-    }
-    /**
-     * Broadcast a single transaction or a TRUC (BIP 431) 1P1C package
-     * atomically.
-     *
-     * **Server requirements for 1P1C packages:** the backing Electrum
-     * server must implement `blockchain.transaction.broadcast_package`
-     * (Fulcrum ≥ 1.10) and be backed by bitcoind ≥ v28.0.0. ElectrumX
-     * does not implement this method. There is **no fallback** to
-     * sequential parent-then-child broadcast: TRUC packages typically
-     * have a zero-fee parent and would be rejected from the mempool on
-     * their own, so a fallback would silently fail in subtle ways.
-     * Callers receiving a "method not found" error here should route
-     * through a different provider for that submission.
-     *
-     * @param txs - One transaction (single broadcast) or two
-     *              topologically-sorted transactions (parent first,
-     *              child last) for 1P1C package relay.
-     * @returns The broadcast txid (or the child txid for 1P1C packages).
-     */
-    async broadcastTransaction(...txs) {
-        if (txs.length === 1) {
-            return this.chain.broadcastTransaction(txs[0]);
-        }
-        if (txs.length === 2) {
-            return this.chain.broadcastPackage(txs);
-        }
-        throw new Error("Only 1 or 1P1C package can be broadcast");
-    }
-    async getTxOutspends(txid) {
-        // Step 1: fetch the creating tx to get its output scripts (1 round trip)
-        const [txResult] = await this.chain.fetchTransactions([txid]);
-        const tx = Transaction.fromRaw(hex.decode(txResult.hex), {
-            allowUnknownOutputs: true,
-        });
-        const outputCount = tx.outputsLength;
-        const outputScriptHashes = [];
-        for (let i = 0; i < outputCount; i++) {
-            const output = tx.getOutput(i);
-            outputScriptHashes.push(output.script ? toScriptHash(output.script) : undefined);
-        }
-        const validScriptHashes = outputScriptHashes.filter((h) => h !== undefined);
-        const results = Array.from({ length: outputCount }, () => ({ spent: false, txid: "" }));
-        if (validScriptHashes.length === 0)
-            return results;
-        // Step 2: batch listunspent for all output scripthashes (1 round trip)
-        // This tells us exactly which txid:vout pairs are still unspent.
-        const unspentBatch = await this.chain.safeBatchRequest(validScriptHashes.map((sh) => ({
-            method: ListUnspentMethod,
-            params: [sh],
-        })));
-        const unspentSet = new Set();
-        let validIdx = 0;
-        for (let i = 0; i < outputCount; i++) {
-            if (outputScriptHashes[i] !== undefined) {
-                for (const u of unspentBatch[validIdx]) {
-                    unspentSet.add(`${u.tx_hash}:${u.tx_pos}`);
-                }
-                validIdx++;
-            }
-        }
-        // Step 3: batch get_history only for spent outputs (1 round trip)
-        const spentIndices = [];
-        const spentScriptHashes = [];
-        for (let i = 0; i < outputCount; i++) {
-            const sh = outputScriptHashes[i];
-            if (sh && !unspentSet.has(`${txid}:${i}`)) {
-                spentIndices.push(i);
-                spentScriptHashes.push(sh);
-            }
-        }
-        if (spentIndices.length === 0)
-            return results;
-        const histories = await this.chain.safeBatchRequest(spentScriptHashes.map((sh) => ({
-            method: GetHistoryMethod,
-            params: [sh],
-        })));
-        // For each spent output find the spender in its history.
-        // Common case: history has exactly 2 entries (creating + spending tx).
-        // Ambiguous case (same script reused): batch-fetch all candidates at once.
-        const ambiguousIndices = [];
-        const ambiguousCandidates = [];
-        for (let j = 0; j < spentIndices.length; j++) {
-            const i = spentIndices[j];
-            const candidates = histories[j]
-                .map((h) => h.tx_hash)
-                .filter((hash) => hash !== txid);
-            if (candidates.length === 1) {
-                // Fast path: one candidate = the spender
-                results[i] = { spent: true, txid: candidates[0] };
-            }
-            else if (candidates.length > 1) {
-                ambiguousIndices.push(i);
-                ambiguousCandidates.push(candidates);
-            }
-            // candidates.length === 0 → mempool eviction, treat as unspent
-        }
-        // Step 4 (rare): batch-fetch all ambiguous candidate txs at once
-        if (ambiguousIndices.length > 0) {
-            const allCandidateTxids = [...new Set(ambiguousCandidates.flat())];
-            const fetched = await this.chain.fetchTransactions(allCandidateTxids);
-            const txMap = new Map(fetched.map((t) => [t.txID, t.hex]));
-            for (let j = 0; j < ambiguousIndices.length; j++) {
-                const i = ambiguousIndices[j];
-                for (const candidateTxid of ambiguousCandidates[j]) {
-                    const rawHex = txMap.get(candidateTxid);
-                    if (!rawHex)
-                        continue;
-                    const candidateTx = Transaction.fromRaw(hex.decode(rawHex), { allowUnknownOutputs: true, allowUnknownInputs: true });
-                    let found = false;
-                    for (let k = 0; k < candidateTx.inputsLength; k++) {
-                        const input = candidateTx.getInput(k);
-                        if (input.txid &&
-                            hex.encode(input.txid) === txid &&
-                            input.index === i) {
-                            results[i] = { spent: true, txid: candidateTxid };
-                            found = true;
-                            break;
-                        }
-                    }
-                    if (found)
-                        break;
-                }
-            }
-        }
-        return results;
-    }
-    async getTransactions(address) {
-        const script = this.encodeAddress(address);
-        const history = await this.chain.fetchHistory(script);
-        if (history.length === 0)
-            return [];
-        return this.historyToExplorerTxs(history);
-    }
-    /**
-     * Resolve a list of `{tx_hash, height}` entries (as returned by the
-     * scripthash history endpoint) into ExplorerTransaction shape **without
-     * using the verbose-tx endpoint**, which only Fulcrum implements. We
-     * reconstruct everything the verbose response would have given us:
-     *   - vouts ← parse the raw tx (exact sat amounts, no float precision risk)
-     *   - block_time ← batch-fetch the block headers for the heights present
-     *   - addresses ← decode each output's scriptPubKey via @scure/btc-signer
-     */
-    async historyToExplorerTxs(history) {
-        const txids = history.map((h) => h.tx_hash);
-        const rawTxs = await this.chain.fetchTransactions(txids);
-        const rawHexByTxid = new Map(rawTxs.map((t) => [t.txID, t.hex]));
-        // De-duplicated batch lookup of block headers (now safe — see
-        // safeBatchRequest above). Heights whose headers fail to resolve
-        // surface via the wrapper's first-error throw; we tolerate that
-        // here by falling back to per-height calls under Promise.allSettled
-        // so one missing header doesn't poison the whole history mapping.
-        // The old verbose-tx code had the same tolerance via
-        // `vtx.blocktime || vtx.time || 0`.
-        const confirmedHeights = [
-            ...new Set(history.map((h) => h.height).filter((h) => h > 0)),
-        ];
-        const blockTimeByHeight = new Map();
-        if (confirmedHeights.length > 0) {
-            try {
-                const headers = await this.chain.fetchBlockHeaders(confirmedHeights);
-                for (const header of headers) {
-                    blockTimeByHeight.set(header.height, parseBlockHeader(header.hex).timestamp);
-                }
-            }
-            catch {
-                const settled = await Promise.allSettled(confirmedHeights.map((h) => this.chain.fetchBlockHeader(h)));
-                settled.forEach((res) => {
-                    if (res.status === "fulfilled") {
-                        blockTimeByHeight.set(res.value.height, parseBlockHeader(res.value.hex).timestamp);
-                    }
-                    // Rejections leave the height absent → block_time = 0.
-                });
-            }
-        }
-        return history.map((entry) => this.buildExplorerTx(entry, rawHexByTxid.get(entry.tx_hash), blockTimeByHeight));
-    }
-    /**
-     * Build an ExplorerTransaction from a history entry plus the raw tx hex
-     * (when known) and a height→block_time map. Parse errors propagate —
-     * silently returning an empty vout would hide real outputs (e.g. a
-     * deposit) and is far worse for protocol-level money handling than
-     * failing the whole batch.
-     */
-    buildExplorerTx(entry, rawHex, blockTimeByHeight) {
-        const vout = [];
-        if (rawHex) {
-            let tx;
-            try {
-                tx = Transaction.fromRaw(hex.decode(rawHex), {
-                    allowUnknownOutputs: true,
-                    allowUnknownInputs: true,
-                });
-            }
-            catch (err) {
-                throw new Error(`Failed to parse raw tx for ${entry.tx_hash}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            for (let i = 0; i < tx.outputsLength; i++) {
-                const output = tx.getOutput(i);
-                const scriptHex = output.script
-                    ? hex.encode(output.script)
-                    : "";
-                vout.push({
-                    scriptpubkey_address: scriptHex
-                        ? (this.chain.addressForScript(scriptHex) ?? "")
-                        : "",
-                    value: (output.amount ?? 0n).toString(),
-                });
-            }
-        }
-        return {
-            txid: entry.tx_hash,
-            vout,
-            status: {
-                confirmed: entry.height > 0,
-                block_time: blockTimeByHeight.get(entry.height) ?? 0,
-            },
-        };
-    }
-    /**
-     * Decode `address` into its scriptPubKey, throwing a clear error if the
-     * input is malformed. @scure/btc-signer raises a generic decode error
-     * which is hard to map back to user input — this wraps it.
-     */
-    encodeAddress(address) {
-        try {
-            return OutScript.encode(Address(this.network).decode(address));
-        }
-        catch (err) {
-            const reason = err instanceof Error ? err.message : String(err);
-            throw new Error(`Invalid address ${address}: ${reason}`);
-        }
-    }
-    async getTxStatus(txid) {
-        // Use `transaction.get_merkle` rather than the verbose `transaction.get`
-        // because electrs (used by mempool.space, blockstream.info, and the
-        // nigiri regtest) doesn't implement verbose. get_merkle is part of the
-        // standard SPV protocol and supported by every Electrum server.
-        const merkle = await this.chain.fetchTxMerkle(txid);
-        if (!merkle)
-            return { confirmed: false };
-        // Header lookup can transiently race with electrs's index right
-        // after a fresh block — listunspent/get_merkle expose the new
-        // height before block.header(N) is queryable. Tolerate that the
-        // same way historyToExplorerTxs does: confirmation status and
-        // height are still authoritative; only block_time degrades.
-        let blockTime = 0;
-        try {
-            const header = await this.chain.fetchBlockHeader(merkle.blockHeight);
-            blockTime = parseBlockHeader(header.hex).timestamp;
-        }
-        catch (err) {
-            if (!isMissingHeightError(err))
-                throw err;
-        }
-        return {
-            confirmed: true,
-            blockHeight: merkle.blockHeight,
-            blockTime,
-        };
-    }
-    async getChainTip() {
-        const tip = await this.chain.subscribeHeaders();
-        const { hash, timestamp } = parseBlockHeader(tip.hex);
-        return {
-            height: tip.height,
-            time: timestamp,
-            hash,
-        };
-    }
-    async watchAddresses(addresses, eventCallback) {
-        const scripts = addresses.map((addr) => this.encodeAddress(addr));
-        const scriptHashes = scripts.map(toScriptHash);
-        // O(1) scripthash → script lookup, kept in sync with the
-        // scripts/scriptHashes arrays. Server notifications hit this on
-        // every push, so the previous indexOf was O(n) per event.
-        const scriptByHash = new Map(scriptHashes.map((h, i) => [h, scripts[i]]));
-        // Track known history per script to detect new txs.
-        const knownTxids = new Map();
-        // Initialize known-set in parallel — for a wallet watching many
-        // addresses this avoids n sequential round trips on first call.
-        const initialHistories = await Promise.all(scripts.map((s) => this.chain.fetchHistory(s)));
-        initialHistories.forEach((history, i) => {
-            knownTxids.set(scriptHashes[i], new Set(history.map((h) => h.tx_hash)));
-        });
-        // Per-scripthash mutex serializing concurrent notifications so
-        // two pushes for the same address can't fetch history in parallel
-        // and emit duplicate events. Each call chains onto the previous
-        // one's tail; failures are swallowed to keep the chain alive.
-        const inFlight = new Map();
-        const processStatusChange = async (scripthash) => {
-            const script = scriptByHash.get(scripthash);
-            if (!script)
-                return;
-            const history = await this.chain.fetchHistory(script);
-            const known = knownTxids.get(scripthash) ?? new Set();
-            const newEntries = history.filter((entry) => !known.has(entry.tx_hash));
-            if (newEntries.length === 0)
-                return;
-            // Map the new history entries through the same non-verbose
-            // pipeline getTransactions uses, so subscribe-driven and
-            // poll-driven callers see ExplorerTransactions of identical shape.
-            // The dedupe set is updated ONLY after delivery succeeds —
-            // otherwise a failed fetch or callback would permanently mark
-            // these txids as seen and the next notification wouldn't
-            // re-deliver them.
-            const explorerTxs = await this.historyToExplorerTxs(newEntries);
-            eventCallback(explorerTxs);
-            for (const entry of newEntries)
-                known.add(entry.tx_hash);
-            knownTxids.set(scripthash, known);
-        };
-        const handleStatusChange = (scripthash) => {
-            const previous = inFlight.get(scripthash) ?? Promise.resolve();
-            const next = previous.then(() => processStatusChange(scripthash));
-            // Keep the chain alive even when one link rejects.
-            inFlight.set(scripthash, next.catch(() => undefined));
-            return next;
-        };
-        // Register all subscriptions in parallel; if any one fails, tear
-        // down the others so we don't leak server-side subscriptions on
-        // a connection the caller never gets a stop() handle for.
-        const subscribed = [];
-        try {
-            await Promise.all(scripts.map(async (script) => {
-                await this.chain.subscribeScriptStatus(script, (scripthash, status) => {
-                    if (status !== null) {
-                        handleStatusChange(scripthash).catch(console.error);
-                    }
-                });
-                subscribed.push(script);
-            }));
-        }
-        catch (err) {
-            await Promise.allSettled(subscribed.map((s) => this.chain.unsubscribeScriptStatus(s)));
-            throw err;
-        }
-        return () => {
-            for (const script of scripts) {
-                this.chain.unsubscribeScriptStatus(script).catch(() => { });
-            }
-        };
-    }
-    /** Close the underlying WebSocket connection. */
-    async close() {
-        await this.chain.close();
-    }
-}
-function toScriptHash(script) {
-    return hex.encode(sha256(script).reverse());
-}
-function isHeaderSubscribeResult(v) {
-    if (typeof v !== "object" || v === null)
-        return false;
-    const obj = v;
-    return typeof obj.height === "number" && typeof obj.hex === "string";
-}
-/**
- * Recognise the "block header not yet indexable" failure shape returned by
- * electrum servers (electrs in particular) when `block.header(N)` runs
- * against a height that's already in `listunspent`/`get_merkle` but hasn't
- * been indexed yet. Surfaced as `missingheight`. Tolerated by callers so
- * the index-lag race doesn't poison confirmed-status reads; genuine
- * failures (auth/network) propagate.
- */
-function isMissingHeightError(err) {
-    const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
-    return msg.toLowerCase().includes("missingheight");
-}
-/**
- * Recognise the "transaction not in a block yet" failure shape returned by
- * electrum servers when `blockchain.transaction.get_merkle` is asked about a
- * mempool tx. electrs surfaces this as the strings below; Fulcrum mirrors
- * the wording. We match conservatively so genuine errors (auth, network,
- * malformed response) still propagate.
- */
-function isTxNotInBlockError(err) {
-    const msg = err instanceof Error ? err.message : typeof err === "string" ? err : "";
-    const normalized = msg.toLowerCase();
-    return (normalized.includes("not yet in a block") ||
-        normalized.includes("not in a block") ||
-        normalized.includes("not in block") ||
-        normalized.includes("no confirmed transaction"));
-}
-/**
- * Compute the txid of a serialized transaction. For segwit transactions
- * (every Ark transaction), the broadcast hex includes witness data, but
- * the txid is the double-SHA256 of the legacy (witness-stripped)
- * serialization. Hashing the raw broadcast bytes directly would yield
- * the wtxid instead — silently breaking any caller that tracks the tx
- * by id (round settlement, forfeit monitoring, exit paths).
- *
- * Delegating to `Transaction.fromRaw(...).id` lets @scure/btc-signer
- * handle the witness-stripping correctly.
- */
-function childTxidFromHex(txHex) {
-    const tx = Transaction.fromRaw(hex.decode(txHex), {
-        allowUnknownOutputs: true,
-        allowUnknownInputs: true,
-    });
-    return tx.id;
-}