@getomnichain/omnichain 0.2.0 → 0.3.0

package/dist/cjs/utxo/utxo_chain.js

@@ -0,0 +1,612 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UtxoChain = void 0;
+exports.sanitizeUtxoErrMessage = sanitizeUtxoErrMessage;
+const bitcoinjs_lib_1 = require("bitcoinjs-lib");
+const chain_ids_ts_1 = require("../chain_ids.js");
+const network_params_ts_1 = require("./btc/network_params.js");
+const chain_base_ts_1 = require("../chain.base.js");
+const errors_ts_1 = require("../errors.js");
+const network_type_ts_1 = require("../network_type.js");
+const priority_ts_1 = require("../priority.js");
+const token_ts_1 = require("../token.js");
+const transaction_status_ts_1 = require("../transaction_status.js");
+const utxo_transaction_status_ts_1 = require("./utxo_transaction_status.js");
+require("./ecc.js");
+const coin_selection_ts_1 = require("./coin_selection.js");
+const fee_ts_1 = require("./fee.js");
+const script_ts_1 = require("./script.js");
+const utxo_network_params_ts_1 = require("./utxo_network_params.js");
+const unsigned_utxo_transaction_ts_1 = require("./unsigned_utxo_transaction.js");
+const RESERVED_BTC_CHAIN_IDS = [
+    chain_ids_ts_1.CHAIN_ID_BITCOIN_MAINNET,
+    chain_ids_ts_1.CHAIN_ID_BITCOIN_TESTNET,
+    chain_ids_ts_1.CHAIN_ID_BITCOIN_SIGNET,
+];
+const DEFAULT_BLOCK_TIME_SECONDS = 600;
+const DEFAULT_FEE_TARGET_BLOCKS = 3;
+const DEFAULT_LONG_TERM_FEE_RATE = 5;
+const DEFAULT_NATIVE_DECIMALS = 8;
+class UtxoNativeToken extends token_ts_1.Token {
+    constructor(chainId, symbol, decimals) {
+        super(chainId, symbol, undefined, decimals);
+    }
+}
+class UtxoChain extends chain_base_ts_1.Chain {
+    params;
+    utxoProvider;
+    rawTxProvider;
+    feeEstimator;
+    broadcaster;
+    chainTipProvider;
+    walletExplorerTemplate;
+    tokenExplorerTemplate;
+    transactionExplorerTemplate;
+    _nativeToken;
+    defaultFeeTargetBlocks;
+    longTermFeeRateSatsPerVByte;
+    rbfEnabled;
+    constructor(init) {
+        // Reject a non-BTC UTXO chain (LTC/DOGE/DASH/ZEC/BCH — mainnet AND
+        // testnet) constructed with a reserved BTC chainId. The prior slip44
+        // heuristic let `litecoinTestnetChain({chainId: -2})` through because
+        // LTC testnet's slip44 is `Slip44.Testnet` (same as BTC testnet). Gate
+        // on the seeded BTC params directly: at reserved ids the constructor
+        // must present params shape-identical to what's already seeded, else
+        // it's a chain claiming a BTC id with foreign address rules.
+        if (RESERVED_BTC_CHAIN_IDS.includes(init.chainId)) {
+            const seeded = (0, network_params_ts_1.btcParamsForChainId)(BigInt(init.chainId));
+            const paramsAsBtc = init.params;
+            // Use the strict comparator exported from btc/network_params.ts so
+            // both this guard and registerBtcChainParams share ONE invariant.
+            // A non-BtcNetworkParams (missing `name`, `hrp`, etc.) fails the
+            // comparator on the first field mismatch.
+            if (init.params !== seeded && !(0, network_params_ts_1.btcParamsShapeMatches)(seeded, paramsAsBtc)) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `chainId ${init.chainId} is reserved for BTC; UtxoChain construction with foreign params (slip44=${init.params.slip44CoinId}) is not permitted. Choose a distinct chainId for this network.`, { chainId: init.chainId });
+            }
+        }
+        super(init.chainId, init.name, network_type_ts_1.NetworkType.BTC, init.blockTimeSeconds ?? DEFAULT_BLOCK_TIME_SECONDS, init.nativeSymbol, init.walletExplorerUrlTemplate);
+        this.params = init.params;
+        this.utxoProvider = init.utxoProvider;
+        this.rawTxProvider = init.rawTxProvider;
+        this.feeEstimator = init.feeEstimator;
+        this.broadcaster = init.broadcaster;
+        this.chainTipProvider = init.chainTipProvider;
+        this.walletExplorerTemplate = init.walletExplorerUrlTemplate;
+        this.tokenExplorerTemplate = init.tokenExplorerUrlTemplate ?? init.walletExplorerUrlTemplate;
+        this.transactionExplorerTemplate = init.transactionExplorerUrlTemplate;
+        this._nativeToken = new UtxoNativeToken(init.chainId, init.nativeSymbol, init.nativeDecimals ?? DEFAULT_NATIVE_DECIMALS);
+        this.defaultFeeTargetBlocks = init.defaultFeeTargetBlocks ?? DEFAULT_FEE_TARGET_BLOCKS;
+        this.longTermFeeRateSatsPerVByte = init.longTermFeeRateSatsPerVByte ?? DEFAULT_LONG_TERM_FEE_RATE;
+        this.rbfEnabled = init.rbfEnabled ?? true;
+        (0, network_type_ts_1.registerNonEvmChain)(init.chainId, network_type_ts_1.NetworkType.BTC);
+    }
+    get nativeToken() {
+        return this._nativeToken;
+    }
+    get slip44CoinId() {
+        return this.params.slip44CoinId;
+    }
+    get supportedDerivationPurposes() {
+        return this.params.supportedDerivationPurposes;
+    }
+    get dustValueSats() {
+        return this.params.dustValueSats;
+    }
+    getWalletExplorerUrl(address) {
+        return this.walletExplorerTemplate.replace('{wallet_address}', address);
+    }
+    getTokenExplorerUrl(_tokenIdentifier) {
+        return this.tokenExplorerTemplate.replace('{wallet_address}', '');
+    }
+    getTransactionExplorerUrl(txHash) {
+        return this.transactionExplorerTemplate.replace('{tx_hash}', txHash);
+    }
+    validateAddress(raw) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            return false;
+        return this.params.walletAddressRegex.test(raw);
+    }
+    validateTokenIdentifier(raw) {
+        return raw === undefined;
+    }
+    async getUtxos(addresses, _options) {
+        if (addresses.length === 0)
+            return [];
+        const lists = await Promise.all(addresses.map((address) => this.utxoProvider.getUtxos(address)));
+        return lists.flat();
+    }
+    async getBalance(owner, tokenIdentifier) {
+        if (!this.validateTokenIdentifier(tokenIdentifier)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidTokenIdentifier, `${this.name}: only the native token is supported (got ${tokenIdentifier})`, { chainId: this.chainId, identifier: tokenIdentifier });
+        }
+        if (!this.validateAddress(owner)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `${this.name}: invalid wallet address ${owner}`, { chainId: this.chainId, address: owner });
+        }
+        const balance = await this.utxoProvider.getAddressBalance(owner);
+        return BigInt(balance.confirmedSats);
+    }
+    async getChainTipHeight() {
+        return this.chainTipProvider.getChainTipHeight();
+    }
+    async getTransactionStatus(txHash, opts) {
+        if (opts?.wait || (opts?.confirmations !== undefined && opts.confirmations > 1)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `UtxoChain.getTransactionStatus does not honor wait/confirmations opts in 0.3.0 (would silently return immediately). Poll the block-tip provider consumer-side or omit the opts.`, { chainId: this.chainId });
+        }
+        if (Array.isArray(txHash)) {
+            const results = new Array(txHash.length);
+            let cursor = 0;
+            let aborted = false;
+            const spawn = async () => {
+                while (!aborted) {
+                    const idx = cursor++;
+                    if (idx >= txHash.length)
+                        return;
+                    try {
+                        results[idx] = await this.getUtxoStatusOnce(txHash[idx]);
+                    }
+                    catch (err) {
+                        aborted = true;
+                        throw err;
+                    }
+                }
+            };
+            const workerCount = Math.min(8, txHash.length);
+            await Promise.all(Array.from({ length: workerCount }, spawn));
+            return results;
+        }
+        return this.getUtxoStatusOnce(txHash);
+    }
+    async getUtxoStatusOnce(txHash) {
+        // Narrow the try to the provider call only. Constructor asserts and
+        // upsert failures must NOT be silently coerced into NotFound.
+        // Classify: (a) provider signalled "no such tx" (Esplora HTTP 404,
+        // Bitcoin Core RPC code -5) → NotFound; (b) any other throw →
+        // RpcError so consumers can retry rather than treating a 429/timeout
+        // as a definitive miss.
+        let tx;
+        try {
+            tx = await this.rawTxProvider.getTransaction(txHash);
+        }
+        catch (err) {
+            if (err instanceof errors_ts_1.ChainError)
+                throw err;
+            if (isProviderNotFoundError(err)) {
+                return new utxo_transaction_status_ts_1.UtxoTransactionStatus({
+                    chainId: this.chainId,
+                    status: transaction_status_ts_1.TransactionStatusTypes.NotFound,
+                    confirmationAt: null,
+                    balanceChanges: null,
+                });
+            }
+            const rawMsg = err instanceof Error ? err.message : String(err);
+            const sanitizedMsg = sanitizeUtxoErrMessage(rawMsg);
+            // Build a scrubbed cause: sanitizeCause strips axios `.config`/
+            // `.request`/`.response` object trees (which carry Authorization
+            // headers + query-string keys) by rebuilding a plain Error with
+            // only sanitized message+stack. Consumers walking `.cause` in a
+            // structured logger no longer leak API keys.
+            const safeCause = err instanceof Error
+                ? sanitizedCauseForUtxo(err, sanitizedMsg)
+                : undefined;
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, `Failed to read UTXO tx ${txHash}: ${sanitizedMsg}`, { chainId: this.chainId, txHash }, safeCause);
+        }
+        // Bitcoin Core reports `confirmations: -1` for a conflicted/RBF-
+        // replaced tx (a reorged-out deposit). Do not run the shape asserts
+        // that would throw InvalidArgument on the way out — surface as
+        // NotFound so the status poll doesn't crash.
+        if (tx.confirmations < 0) {
+            return new utxo_transaction_status_ts_1.UtxoTransactionStatus({
+                chainId: this.chainId,
+                status: transaction_status_ts_1.TransactionStatusTypes.NotFound,
+                confirmationAt: null,
+                balanceChanges: null,
+                error: {
+                    code: 'CONFLICTED',
+                    reason: `Provider reports confirmations=${tx.confirmations} (RBF-replaced / reorged)`,
+                },
+            });
+        }
+        // Wrap the decode block so a non-integer valueSats/absoluteSats from a
+        // consumer's provider tool (BTC-float→sats overflow) or a
+        // Transaction.fromHex failure surfaces as a typed
+        // ChainError(TransactionDecodeFailed) rather than a raw RangeError.
+        // Mirrors evm_chain.ts:decodeBalanceChanges catch.
+        try {
+            // Populate outputs on both pending AND confirmed paths — a 0-conf
+            // mempool tx still has visible outputs, and BTC/LTC/DOGE deposit
+            // detectors need them. balanceChanges stays null on Pending per the
+            // TransactionStatus base invariant.
+            const outputs = tx.vout.map((o) => new utxo_transaction_status_ts_1.UtxoTransactionOutput({
+                scriptPubkeyHex: o.scriptPubKeyHex,
+                address: o.address,
+                valueSats: BigInt(o.valueSats),
+            }));
+            // Derive vsize from the raw hex — bitcoinjs-lib is already a dep
+            // and both Esplora + Bitcoin Core populate tx.hex. Falls back to
+            // null on malformed hex so the status still returns.
+            let vsize = null;
+            try {
+                if (tx.hex && tx.hex.length > 0) {
+                    vsize = bitcoinjs_lib_1.Transaction.fromHex(tx.hex).virtualSize();
+                }
+            }
+            catch {
+                vsize = null;
+            }
+            const fees = tx.fees !== null
+                ? new utxo_transaction_status_ts_1.UtxoTransactionFees({ absoluteSats: BigInt(tx.fees.absoluteSats), vsize })
+                : null;
+            const isPending = tx.confirmations === 0;
+            if (isPending) {
+                return new utxo_transaction_status_ts_1.UtxoTransactionStatus({
+                    chainId: this.chainId,
+                    status: transaction_status_ts_1.TransactionStatusTypes.Pending,
+                    confirmationAt: null,
+                    balanceChanges: null,
+                    confirmations: 0,
+                    outputs,
+                    vsize,
+                    fees,
+                });
+            }
+            // Outputs-only per-address native deltas. Full input-side accounting
+            // to compute net native change (Python's `_native_balance_changes`
+            // parity) is deferred — the raw-tx provider currently returns only
+            // vin.txid+vout, no address/value/scriptPubKeyHex. Noted in
+            // SINAN_OPEN_QUESTIONS.md.
+            const balanceChanges = new Map();
+            const perAddressSats = new Map();
+            for (const out of tx.vout) {
+                if (!out.address)
+                    continue;
+                perAddressSats.set(out.address, (perAddressSats.get(out.address) ?? 0n) + BigInt(out.valueSats));
+            }
+            for (const [address, sats] of perAddressSats) {
+                transaction_status_ts_1.AssetBalanceChange.upsert(balanceChanges, address, this._nativeToken, transaction_status_ts_1.AssetBalanceChange.fromMr(sats, this._nativeToken.decimals));
+            }
+            return new utxo_transaction_status_ts_1.UtxoTransactionStatus({
+                chainId: this.chainId,
+                status: transaction_status_ts_1.TransactionStatusTypes.Success,
+                confirmationAt: tx.blockTime,
+                balanceChanges,
+                confirmations: tx.confirmations,
+                outputs,
+                vsize,
+                fees,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_ts_1.ChainError)
+                throw err;
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.TransactionDecodeFailed, `Failed to decode UTXO tx ${txHash}: ${err instanceof Error ? err.message : String(err)}`, { chainId: this.chainId, txHash }, err instanceof Error ? err : undefined);
+        }
+    }
+    async createTransferUnsignedTransaction(req) {
+        return this.buildTransfer(req, undefined);
+    }
+    async broadcast(signed, opts) {
+        if (opts && opts.signal !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.FeatureNotSupported, `UTXO broadcast: signal is not honored in 0.3.0 (silently ignoring would let a caller conclude 'not sent' while the tx still lands). Cancellation returns in 0.3.1.`, { chainId: this.chainId });
+        }
+        let hex;
+        let txBytes;
+        if (typeof signed === 'string') {
+            const stripped = signed.startsWith('0x') ? signed.slice(2) : signed;
+            if (!/^[0-9a-fA-F]+$/.test(stripped) || stripped.length % 2 !== 0 || stripped.length === 0) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `UTXO broadcast: signed transaction must be Uint8Array or hex string (got malformed string of length ${signed.length})`, { chainId: this.chainId });
+            }
+            hex = stripped;
+            txBytes = Buffer.from(stripped, 'hex');
+        }
+        else {
+            if (signed.length === 0) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `UTXO broadcast: signed transaction bytes are empty`, { chainId: this.chainId });
+            }
+            hex = Buffer.from(signed).toString('hex');
+            txBytes = Buffer.from(signed);
+        }
+        try {
+            const { txid } = await this.broadcaster.broadcast(hex);
+            return txid;
+        }
+        catch (err) {
+            const resp = err.response;
+            const body = resp?.data;
+            const httpStatus = resp?.status;
+            const bodyStr = body === undefined ? '' : ` — node response: ${typeof body === 'string' ? body : JSON.stringify(body)}`;
+            const rawMsg = (err instanceof Error ? err.message : String(err)) + bodyStr;
+            const sanitizedMsg = sanitizeUtxoErrMessage(rawMsg);
+            const lowerMsg = rawMsg.toLowerCase();
+            const safeCause = err instanceof Error ? sanitizedCauseForUtxo(err, sanitizedMsg) : undefined;
+            if (/already in block chain|txn-already-known|txn-already-in-mempool|already[- ]?known|already[- ]?in mempool/.test(lowerMsg)) {
+                return this.computeUtxoTxidLE(txBytes);
+            }
+            if (/econnreset|econnrefused|econnaborted|etimedout|enotfound|socket hang up|network request failed|fetch failed|too\s+many\s+requests|rate.?limit/.test(lowerMsg)
+                || (typeof httpStatus === 'number' && (httpStatus === 429 || httpStatus === 502 || httpStatus === 503 || httpStatus === 504))) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, `UTXO broadcast RPC transport failure on ${this.name}: ${sanitizedMsg}`, { chainId: this.chainId }, safeCause);
+            }
+            if (/insufficient|-6\b|not enough funds/.test(lowerMsg)) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InsufficientFunds, `UTXO broadcast rejected on ${this.name}: ${sanitizedMsg}`, { chainId: this.chainId }, safeCause);
+            }
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.BroadcastRejected, `UTXO broadcast rejected on ${this.name}: ${sanitizedMsg}`, { chainId: this.chainId }, safeCause);
+        }
+    }
+    computeUtxoTxidLE(txBytes) {
+        try {
+            const first = bitcoinjs_lib_1.Transaction.fromBuffer(txBytes).getHash();
+            return Buffer.from(first).reverse().toString('hex');
+        }
+        catch (err) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.BroadcastRejected, `UTXO already-known path: node reported the tx as already accepted, but the local bytes could not be parsed by bitcoinjs to derive a txid. Do NOT re-sign — poll by the txid the consumer computed pre-broadcast.`, { chainId: this.chainId }, err instanceof Error ? err : undefined);
+        }
+    }
+    async buildTransfer(req, getUtxosOptions) {
+        // UTXO builder does not yet consume the CreateTransferRequest fields
+        // introduced in Wave 2B (Python-parity amountHr / isFullBalance /
+        // gasPricing). Rejecting them at entry — silently letting an
+        // amountHr-only request through would produce `amount === undefined`
+        // downstream and end in a NaN cointoss after several RPC round-trips.
+        if (req.amountHr !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: CreateTransferRequest.amountHr is not yet supported — pass \`amount\` (bigint sats) or \`outputs\` (multi-recipient) instead.`, { chainId: this.chainId });
+        }
+        if (req.isFullBalance === true) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: CreateTransferRequest.isFullBalance is not yet supported — pass \`amount\` explicitly and reserve fees yourself.`, { chainId: this.chainId });
+        }
+        if (req.gasPricing !== undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: CreateTransferRequest.gasPricing is not yet consumed by UtxoChain (Phase 2 follow-up). Use \`feeRateSatsPerVByte\` / \`feeTargetBlocks\` on CreateUtxoTransferOptions for now.`, { chainId: this.chainId });
+        }
+        if (!this.validateTokenIdentifier(req.tokenIdentifier)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidTokenIdentifier, `${this.name}: only the native token is supported`, { chainId: this.chainId, identifier: req.tokenIdentifier });
+        }
+        if (req.from === undefined || !this.validateAddress(req.from)) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `${this.name}: invalid sender address ${req.from ?? '<missing>'}`, { chainId: this.chainId, address: req.from });
+        }
+        const fromAddress = req.from;
+        const opts = req;
+        // Normalize: single-output form (to/amount) OR multi-output form (outputs[]).
+        // Exactly one must be provided; the multi-output form is preferred going forward.
+        const hasSingle = req.to !== undefined || req.amount !== undefined;
+        const hasMulti = Array.isArray(opts.outputs) && opts.outputs.length > 0;
+        if (hasSingle && hasMulti) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: cannot specify both single-output (to/amount) and multi-output (outputs[]) forms`, { chainId: this.chainId });
+        }
+        if (!hasSingle && !hasMulti) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: must specify either (to, amount) or a non-empty outputs[] array`, { chainId: this.chainId });
+        }
+        // Wave 2B made `amount` optional on the base CreateTransferRequest so
+        // `amountHr` could coexist. UTXO's single-output form still needs
+        // `amount: bigint` — reject `{to, memo}`-without-amount up front
+        // rather than let it propagate through as NaN downstream.
+        if (hasSingle && !hasMulti && req.amount === undefined) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: single-output form requires \`amount: bigint\` (bitcoin satoshis) — omitting amount would produce NaN downstream`, { chainId: this.chainId });
+        }
+        const normalizedOutputs = hasMulti
+            ? opts.outputs.slice()
+            : [{ to: req.to, amount: req.amount }];
+        for (let i = 0; i < normalizedOutputs.length; i++) {
+            const o = normalizedOutputs[i];
+            if (!this.validateAddress(o.to)) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidAddress, `${this.name}: invalid recipient address at outputs[${i}]: ${o.to}`, { chainId: this.chainId, address: o.to });
+            }
+            if (typeof o.amount !== 'bigint') {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: outputs[${i}].amount must be a bigint (got ${typeof o.amount})`, { chainId: this.chainId });
+            }
+            if (o.amount <= 0n) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: outputs[${i}] amount must be > 0`, { chainId: this.chainId });
+            }
+            const sats = bigintToNumber(o.amount);
+            if (sats < this.params.dustValueSats) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: outputs[${i}] amount ${sats} below dust ${this.params.dustValueSats}`, { chainId: this.chainId });
+            }
+        }
+        const totalTargetSats = normalizedOutputs.reduce((acc, o) => acc + bigintToNumber(o.amount), 0);
+        const recipientTypes = normalizedOutputs.map((o) => (0, script_ts_1.scriptTypeForAddress)(o.to, this.params.networkInfo));
+        const memoBytes = encodeMemo(req.memo);
+        const feeRateSatsPerVByte = await this.resolveFeeRate(opts.feeRateSatsPerVByte, opts.feeTargetBlocks);
+        const utxos = await this.getUtxos([fromAddress], getUtxosOptions);
+        if (utxos.length === 0) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: no spendable UTXOs available for ${fromAddress}`, { chainId: this.chainId, address: fromAddress });
+        }
+        const changeAddress = opts.changeAddress ?? fromAddress;
+        const changeType = (0, script_ts_1.scriptTypeForAddress)(changeAddress, this.params.networkInfo);
+        const outputsFixedVBytes = recipientTypes.reduce((acc, t) => acc + (0, fee_ts_1.outputVBytes)(t), 0) +
+            (memoBytes ? memoBytes.length + 11 : 0);
+        const selection = this.runCoinSelection({
+            utxos,
+            targetSats: totalTargetSats,
+            feeRateSatsPerVByte,
+            changeOutputType: changeType,
+            outputsFixedVBytes,
+            costOfChangeSats: (0, fee_ts_1.costOfChangeSats)(changeType, feeRateSatsPerVByte, this.longTermFeeRateSatsPerVByte),
+        });
+        if (selection.outcome !== coin_selection_ts_1.CoinSelectionOutcomes.Success) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: coin selection failed (${selection.outcome}) for target ${totalTargetSats} sats`, { chainId: this.chainId });
+        }
+        const rbfEnabled = opts.rbfEnabled ?? this.rbfEnabled;
+        const sequence = rbfEnabled ? utxo_network_params_ts_1.RBF_SEQUENCE : utxo_network_params_ts_1.FINAL_SEQUENCE;
+        const psbt = new bitcoinjs_lib_1.Psbt({ network: this.params.networkInfo });
+        const rawTxByTxid = await this.fetchParentTransactions(selection.selected);
+        const inputsToSign = {};
+        selection.selected.forEach((utxo, index) => {
+            this.addInputToPsbt({
+                psbt,
+                utxo,
+                sequence,
+                parentTxHex: rawTxByTxid.get(utxo.txid),
+            });
+            const list = inputsToSign[utxo.ownerAddress] ?? [];
+            list.push(index);
+            inputsToSign[utxo.ownerAddress] = list;
+        });
+        for (const o of normalizedOutputs) {
+            psbt.addOutput({ address: o.to, value: BigInt(bigintToNumber(o.amount)) });
+        }
+        if (selection.hasChange) {
+            psbt.addOutput({ address: changeAddress, value: BigInt(selection.changeSats) });
+        }
+        if (memoBytes) {
+            psbt.addOutput({ script: (0, script_ts_1.buildOpReturnScript)(memoBytes), value: 0n });
+        }
+        const estimatedVBytes = (0, fee_ts_1.estimateTxVBytes)(selection.selected.map((u) => u.scriptType), selection.hasChange ? [...recipientTypes, changeType] : recipientTypes, memoBytes ? [memoBytes.length] : []);
+        return new unsigned_utxo_transaction_ts_1.UnsignedUtxoTransaction({
+            chainId: this.chainId,
+            params: this.params,
+            psbtBase64: psbt.toBase64(),
+            selectedInputs: selection.selected,
+            feeSats: selection.feeSats,
+            feeRateSatsPerVByte,
+            estimatedVBytes,
+            totalInputSats: selection.totalValueSats,
+            totalOutputSats: totalTargetSats + (selection.hasChange ? selection.changeSats : 0),
+            changeAddress: selection.hasChange ? changeAddress : null,
+            inputsToSign,
+        });
+    }
+    addInputToPsbt(args) {
+        const { psbt, utxo, sequence, parentTxHex } = args;
+        const scriptPubKey = Buffer.from(utxo.scriptPubKeyHex, 'hex');
+        const scriptType = (0, script_ts_1.detectScriptType)(scriptPubKey);
+        const parentTxBytes = Buffer.from(parentTxHex, 'hex');
+        const input = {
+            hash: utxo.txid,
+            index: utxo.vout,
+            sequence,
+            nonWitnessUtxo: parentTxBytes,
+        };
+        if (scriptType === script_ts_1.UtxoScriptTypes.P2WPKH ||
+            scriptType === script_ts_1.UtxoScriptTypes.P2WSH ||
+            scriptType === script_ts_1.UtxoScriptTypes.P2TR ||
+            scriptType === script_ts_1.UtxoScriptTypes.P2SH) {
+            input.witnessUtxo = { script: scriptPubKey, value: BigInt(utxo.valueSats) };
+        }
+        psbt.addInput(input);
+    }
+    async resolveFeeRate(overrideRate, targetBlocks) {
+        if (overrideRate !== undefined) {
+            if (overrideRate < 1) {
+                throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `${this.name}: feeRateSatsPerVByte must be >= 1 (got ${overrideRate})`, { chainId: this.chainId });
+            }
+            return Math.ceil(overrideRate);
+        }
+        const estimate = await this.feeEstimator.getFeeEstimate(targetBlocks ?? this.defaultFeeTargetBlocks);
+        return estimate.satsPerVByte;
+    }
+    static targetBlocksForPriority(priority) {
+        switch (priority) {
+            case priority_ts_1.Priority.FAST: return 1;
+            case priority_ts_1.Priority.NORMAL: return 3;
+            case priority_ts_1.Priority.SLOW: return 6;
+            default: {
+                const unreachable = priority;
+                throw new Error(`Unhandled Priority value: ${unreachable}`);
+            }
+        }
+    }
+    async suggestFeeRate(priority) {
+        return this.resolveFeeRate(undefined, UtxoChain.targetBlocksForPriority(priority));
+    }
+    async fetchParentTransactions(utxos) {
+        const uniqueTxids = Array.from(new Set(utxos.map((u) => u.txid)));
+        const hexes = await this.rawTxProvider.getRawTransactionHexBatch(uniqueTxids);
+        if (hexes.length !== uniqueTxids.length) {
+            throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.RpcError, `${this.name}: provider returned ${hexes.length} parent txs for ${uniqueTxids.length} requested`, { chainId: this.chainId });
+        }
+        return new Map(uniqueTxids.map((txid, i) => [txid, hexes[i]]));
+    }
+    runCoinSelection(params) {
+        return (0, coin_selection_ts_1.selectCoins)(params);
+    }
+}
+exports.UtxoChain = UtxoChain;
+function bigintToNumber(value) {
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `UTXO amount ${value} exceeds Number.MAX_SAFE_INTEGER`);
+    }
+    return Number(value);
+}
+/**
+ * Detect whether the underlying provider signalled "no such tx" (as opposed
+ * to a transport failure). Two canonical shapes are recognised:
+ *
+ *   - Esplora / any axios-based HTTP provider → `response.status === 404`
+ *   - Bitcoin Core `getrawtransaction` on an unknown txid → RPC error code
+ *     `-5` (surfaces via `bitcoin-core.tool.ts` as
+ *     `Error("bitcoin-core getrawtransaction: -5 <msg>")`).
+ *
+ * Everything else is treated as a transport failure and wrapped in
+ * `ChainError(RpcError)` so consumers can retry.
+ */
+function isProviderNotFoundError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const anyErr = err;
+    const status = anyErr.response?.status;
+    if (typeof status === 'number' && status === 404)
+        return true;
+    const message = typeof anyErr.message === 'string' ? anyErr.message : '';
+    if (/getrawtransaction:\s*-5\b/.test(message)) {
+        // Bitcoin Core RPC code -5 has TWO meanings:
+        //   - "No such mempool or blockchain transaction" → genuinely unknown
+        //     (node has -txindex enabled, or the tx is unknown even in mempool)
+        //   - "No such mempool transaction. Use -txindex or provide a block hash…"
+        //     → the tx MIGHT exist on-chain but the node can't look it up
+        //     without a block hash. Reporting NotFound here would silently
+        //     misreport every confirmed deposit as missing on a non-txindex
+        //     node — a real-money fail-open. Route it as RpcError so the
+        //     consumer sees a node-misconfiguration signal.
+        if (/mempool or blockchain/i.test(message))
+            return true;
+        return false;
+    }
+    return false;
+}
+/**
+ * Best-effort scrub for provider error messages so API keys and auth
+ * tokens don't leak into `TransactionErrorInfo.reason`. The UTXO
+ * providers (Esplora, Unisat, Ordiscan) carry keys in URL query strings,
+ * Authorization headers, AND URL paths (`/v1/<key>/tx/…`); a raw axios
+ * error stringifies the full request URL. Matches EVM's
+ * `sanitizeMessage` intent (errors.ts).
+ */
+function sanitizeUtxoErrMessage(msg) {
+    const utxoSpecific = msg
+        // Basic-auth credentials in a URL: http://user:pass@host — the
+        // canonical Bitcoin Core RPC form, which the -5 branch above
+        // specifically expects and could otherwise expose.
+        .replace(/(:\/\/)[^:@\s/]+:[^@\s/]+@/g, '$1***:***@')
+        // Provider-prefixed key markers (Blockstream/Unisat/Ordiscan style).
+        .replace(/\b(?:pk|sk|ghp|gho)_[A-Za-z0-9]{20,}\b/g, '***')
+        .replace(/\/[A-Fa-f0-9]{32,}\b/g, '/***');
+    // Route through the shared sanitizer so signed-tx redaction, apiKey/token
+    // params, Bearer headers, and path-embedded key rules apply uniformly
+    // across families (was: parallel UTXO-only sweep that had no signed-tx
+    // rule at all — a provider echoing the submitted hex would leak it).
+    return (0, errors_ts_1.sanitizeMessage)(utxoSpecific, null);
+}
+/**
+ * Rebuild a fresh Error from `cause` with the sanitized message + a
+ * sanitized stack. Drops axios `.config` / `.response` / `.request`
+ * object trees that carry Authorization headers and full request URLs.
+ * Symmetric with `sanitizeCause` (errors.ts) but with the UTXO-specific
+ * regex sweeps applied instead of a per-chain rpcUrl scrub.
+ */
+function sanitizedCauseForUtxo(cause, sanitizedMsg) {
+    const safe = new Error(sanitizedMsg);
+    safe.name = cause.name;
+    if (cause.stack)
+        safe.stack = sanitizeUtxoErrMessage(cause.stack);
+    return safe;
+}
+function encodeMemo(memo) {
+    if (memo === undefined || memo === null)
+        return null;
+    const buf = Buffer.from(memo, 'utf8');
+    if (buf.length === 0)
+        return null;
+    if (buf.length > utxo_network_params_ts_1.OP_RETURN_MAX_BYTES) {
+        throw new errors_ts_1.ChainError(errors_ts_1.ChainErrorKinds.InvalidArgument, `memo length ${buf.length} bytes exceeds OP_RETURN max ${utxo_network_params_ts_1.OP_RETURN_MAX_BYTES}`);
+    }
+    return buf;
+}
+//# sourceMappingURL=utxo_chain.js.map