@arkade-os/sdk 0.4.19 → 0.4.20

package/dist/cjs/providers/electrum.js

@@ -0,0 +1,663 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElectrumOnchainProvider = exports.WsElectrumChainSource = void 0;
+const btc_signer_1 = require("@scure/btc-signer");
+const utils_js_1 = require("@scure/btc-signer/utils.js");
+const base_1 = require("@scure/base");
+// 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 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 = base_1.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 = (0, utils_js_1.sha256)(headerBytes);
+    const hash2 = (0, utils_js_1.sha256)(hash1);
+    const hashStr = base_1.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";
+ * import { networks } from "./networks";
+ *
+ * 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();
+ * ```
+ */
+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;
+    }
+    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.ws.batchRequest(...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.ws.batchRequest(...requests);
+    }
+    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));
+        const responses = await this.ws.batchRequest(...scriptsHashes.map((s) => ({
+            method: GetHistoryMethod,
+            params: [s],
+        })));
+        return responses;
+    }
+    async fetchHistory(script) {
+        const scriptHash = toScriptHash(script);
+        return this.ws.request(GetHistoryMethod, scriptHash);
+    }
+    async fetchBlockHeaders(heights) {
+        const responses = await this.ws.batchRequest(...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 = btc_signer_1.OutScript.encode((0, btc_signer_1.Address)(this.network).decode(addr));
+            this.subscribeScriptStatus(script, (_, status) => {
+                if (status !== null) {
+                    resolve();
+                }
+            }).catch(reject);
+        });
+    }
+    async listUnspents(addr) {
+        const script = btc_signer_1.OutScript.encode((0, btc_signer_1.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 = btc_signer_1.Transaction.fromRaw(base_1.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 = base_1.hex.decode(scriptHex);
+            return (0, btc_signer_1.Address)(this.network).encode(btc_signer_1.OutScript.decode(script));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+exports.WsElectrumChainSource = WsElectrumChainSource;
+/**
+ * Electrum-based implementation of the OnchainProvider interface.
+ * Replaces esplora polling with electrum subscriptions where possible.
+ *
+ * @example
+ * ```typescript
+ * import { ElectrumWS } from "ws-electrumx-client";
+ * import { ElectrumOnchainProvider } from "./providers/electrum";
+ * import { networks } from "./networks";
+ *
+ * const ws = new ElectrumWS("wss://electrum.blockstream.info:50004");
+ * const provider = new ElectrumOnchainProvider(ws, networks.bitcoin);
+ *
+ * const coins = await provider.getCoins("bc1q...");
+ * ```
+ */
+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 = btc_signer_1.Transaction.fromRaw(base_1.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.ws.batchRequest(...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.ws.batchRequest(...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 = btc_signer_1.Transaction.fromRaw(base_1.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 &&
+                            base_1.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 [];
+        const txids = history.map((h) => h.tx_hash);
+        const verboseTxs = await this.chain.fetchVerboseTransactions(txids);
+        return verboseTxs.map((vtx) => this.verboseToExplorer(vtx));
+    }
+    /**
+     * Map an electrum verbose transaction to the ExplorerTransaction shape.
+     *
+     * Output values are derived from the raw transaction hex when available,
+     * never from the floating-point `value` field returned by the daemon.
+     * That field has 8 decimal places and `Math.round(value * 1e8)` is safe
+     * in the common case but a footgun for protocol-level money handling —
+     * the raw bytes are exact.
+     */
+    verboseToExplorer(vtx) {
+        const exactValuesByVout = parseExactSats(vtx);
+        return {
+            txid: vtx.txid,
+            vout: vtx.vout.map((v) => ({
+                scriptpubkey_address: v.scriptPubKey.address ||
+                    v.scriptPubKey.addresses?.[0] ||
+                    this.chain.addressForScript(v.scriptPubKey.hex) ||
+                    "",
+                value: exactValuesByVout?.get(v.n) ??
+                    String(Math.round(v.value * 1e8)),
+            })),
+            status: {
+                confirmed: vtx.confirmations > 0,
+                block_time: vtx.blocktime || vtx.time || 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 btc_signer_1.OutScript.encode((0, btc_signer_1.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) {
+        const vtx = await this.chain.fetchVerboseTransaction(txid);
+        if (vtx.confirmations <= 0) {
+            return { confirmed: false };
+        }
+        // Get block height from the verbose tx's blockhash
+        // We need the height, which is confirmations-based:
+        // height = tipHeight - confirmations + 1
+        const tip = await this.chain.subscribeHeaders();
+        const blockHeight = tip.height - vtx.confirmations + 1;
+        return {
+            confirmed: true,
+            blockTime: vtx.blocktime || vtx.time || 0,
+            blockHeight,
+        };
+    }
+    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 newTxids = history
+                .map((h) => h.tx_hash)
+                .filter((txid) => !known.has(txid));
+            if (newTxids.length === 0)
+                return;
+            for (const txid of newTxids)
+                known.add(txid);
+            knownTxids.set(scripthash, known);
+            const verboseTxs = await this.chain.fetchVerboseTransactions(newTxids);
+            eventCallback(verboseTxs.map((vtx) => this.verboseToExplorer(vtx)));
+        };
+        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();
+    }
+}
+exports.ElectrumOnchainProvider = ElectrumOnchainProvider;
+function toScriptHash(script) {
+    return base_1.hex.encode((0, utils_js_1.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";
+}
+/**
+ * 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 = btc_signer_1.Transaction.fromRaw(base_1.hex.decode(txHex), {
+        allowUnknownOutputs: true,
+        allowUnknownInputs: true,
+    });
+    return tx.id;
+}
+/**
+ * Decode `vtx.hex` (when the daemon includes it) and return a map of
+ * vout-index → exact sat amount as a base-10 string. Returns `null` if
+ * the hex is missing or unparseable; callers should fall back to the
+ * float-derived value in that case.
+ */
+function parseExactSats(vtx) {
+    if (!vtx.hex)
+        return null;
+    try {
+        const tx = btc_signer_1.Transaction.fromRaw(base_1.hex.decode(vtx.hex), {
+            allowUnknownOutputs: true,
+        });
+        const result = new Map();
+        for (let i = 0; i < tx.outputsLength; i++) {
+            const output = tx.getOutput(i);
+            if (output.amount === undefined)
+                continue;
+            result.set(i, output.amount.toString());
+        }
+        return result;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cjs/providers/indexer.js

@@ -196,7 +196,8 @@ class RestIndexerProvider {
                 }
             }
             catch (error) {
-                if (error instanceof Error && error.name === "AbortError") {
+                if (abortSignal?.aborted ||
+                    (error instanceof Error && error.name === "AbortError")) {
                     break;
                 }
                 // ignore timeout errors, they're expected when the server is not sending anything for 5 min
@@ -204,6 +205,9 @@ class RestIndexerProvider {
                     console.debug("Timeout error ignored");
                     continue;
                 }
+                if ((0, utils_1.isEventSourceError)(error)) {
+                    throw error;
+                }
                 console.error("Subscription error:", error);
                 throw error;
             }

package/dist/cjs/providers/utils.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.eventSourceIterator = eventSourceIterator;
+exports.isEventSourceError = isEventSourceError;
 /**
  * Creates an async iterator over EventSource messages that attaches listeners
  * eagerly (at call time) rather than lazily (at first .next() call).
@@ -69,3 +70,6 @@ function eventSourceIterator(eventSource) {
         }
     })();
 }
+function isEventSourceError(error) {
+    return error instanceof Error && error.name === "EventSourceError";
+}