@defillama/sdk 5.0.240 → 5.0.244

package/build/chains/utxo.js

@@ -0,0 +1,678 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CACHE_API_CHUNK_SIZE = exports.MULTIADDR_SLEEP_MS = exports.MULTIADDR_CHUNK_SIZE = exports.DEFAULT_MULTIADDR_API = exports.DEFAULT_MEMPOOL_API = exports.PROVIDER_KINDS = exports.utxoChains = exports.CHAINS = void 0;
+exports.isUtxoChain = isUtxoChain;
+exports.getChainConfig = getChainConfig;
+exports.getEndpoints = getEndpoints;
+exports.isBitcoinAddress = isBitcoinAddress;
+exports.toBigInt = toBigInt;
+exports.toBaseUnits = toBaseUnits;
+exports.fromBaseUnits = fromBaseUnits;
+exports.parseBlockstreamAddressStats = parseBlockstreamAddressStats;
+exports.parseBalanceResponse = parseBalanceResponse;
+exports.getBalance = getBalance;
+exports.getBalances = getBalances;
+exports.getMultiaddrEndpoints = getMultiaddrEndpoints;
+exports.getBitcoinBalancesMultiaddr = getBitcoinBalancesMultiaddr;
+exports.getBitcoinCacheApi = getBitcoinCacheApi;
+exports.getCachedBitcoinTotal = getCachedBitcoinTotal;
+exports.getTotalBalance = getTotalBalance;
+exports.getUtxos = getUtxos;
+exports.getAddressTxs = getAddressTxs;
+exports.getBitcoinBalanceAt = getBitcoinBalanceAt;
+exports.getLatestBlock = getLatestBlock;
+exports.getBlock = getBlock;
+exports.getMempoolEndpoints = getMempoolEndpoints;
+exports.getBlockAtTimestamp = getBlockAtTimestamp;
+/**
+ * Balance client for bitcoin-like UTXO chains via public explorer APIs
+ * (esplora/blockstream, mempool.space, blockbook, blockcypher, tatum, insight,
+ * whatsonchain, blockchair, haskoin, kaspa REST, mvcapi).
+ *
+ * Replaces the chain access parts of:
+ *   - DefiLlama-Adapters  projects/helper/chain/bitcoin.js (getBalanceNow,
+ *     getBalance(addr, timestamp), getCachedBitcoinBalances / cachedBTCBalCall,
+ *     blockchain.info multiaddr batching)
+ *   - DefiLlama-Adapters  projects/helper/chain/litecoin.js, doge.js, dash.js,
+ *     bsv.js, zcash.js, kaspa.js, mvc.js, bitcoincash.js (per-chain getBalance)
+ *   - defillama-server    coins/src/adapters/other/others2.ts getBtcBalanceSats
+ *     (blockstream -> mempool.space failover)
+ *
+ * TVL coupling (sumTokens, Balances, getUniqueAddresses) is intentionally left
+ * out; every balance is returned in base units (satoshis, litoshis, zatoshi,
+ * sompi, ...) as a decimal string.
+ *
+ * Explorer base urls are overridable per chain with `<CHAIN>_EXPLORER_API`
+ * (comma separated fallbacks, also `SDK_` / `LLAMA_SDK_` prefixed). Known hosts
+ * pick their dialect automatically; unknown hosts use `<CHAIN>_EXPLORER_PROVIDER`
+ * (one of the provider kinds below) and otherwise the chain's default dialect.
+ *
+ * Chains not listed in `CHAINS` can be enabled purely through env: setting
+ * `<CHAIN>_EXPLORER_API` (or `<CHAIN>_WHITELISTED_RPC`) makes `isUtxoChain`
+ * accept the chain, with `<CHAIN>_DECIMALS` (default 8), `<CHAIN>_EXPLORER_PROVIDER`
+ * (default esplora) and `<CHAIN>_RPC_CONCURRENCY` (default 5) completing the config.
+ *
+ * Usage: `sdk.chains.utxo.getBalance({ chain: 'bitcoin', address: 'bc1q...' })`
+ */
+const debugLog_1 = require("../util/debugLog");
+const env_1 = require("../util/env");
+const rpc_1 = require("./rpc");
+exports.CHAINS = {
+    bitcoin: {
+        decimals: 8,
+        endpoints: ['https://blockstream.info/api', 'https://mempool.space/api', 'https://rpc.ankr.com/http/btc_blockbook/api/v2'],
+        concurrency: 5,
+    },
+    bitcoincash: {
+        decimals: 8,
+        // haskoin (also mirrored by blockchain.com) takes cashaddr with or without the
+        // `bitcoincash:` prefix as well as legacy base58 addresses
+        endpoints: ['https://api.haskoin.com/bch', 'https://api.blockchain.info/haskoin-store/bch', 'https://api.tatum.io/v3/bcash', 'https://api.blockchair.com/bitcoin-cash'],
+        concurrency: 5,
+    },
+    litecoin: {
+        decimals: 8,
+        endpoints: ['https://litecoinspace.org/api', 'https://api.blockchair.com/litecoin'],
+        concurrency: 5,
+    },
+    doge: {
+        decimals: 8,
+        // blockcypher free tier: ~3 req/s, 100 req/h per IP
+        endpoints: ['https://api.blockcypher.com/v1/doge/main', 'https://api.tatum.io/v3/dogecoin', 'https://api.blockchair.com/dogecoin'],
+        concurrency: 1,
+        sleepMs: 2000,
+    },
+    dash: {
+        decimals: 8,
+        endpoints: ['https://insight.dash.org/insight-api', 'https://api.blockchair.com/dash'],
+        concurrency: 5,
+    },
+    bsv: {
+        decimals: 8,
+        // whatsonchain throttles aggressively and answers with a body missing `confirmed`
+        endpoints: ['https://api.whatsonchain.com/v1/bsv/main'],
+        concurrency: 1,
+    },
+    zcash: {
+        decimals: 8,
+        // blockchair free tier: ~30 req/min per IP; zelcore blockbook is unthrottled; nownodes needs NOWNODES_API_KEY.
+        // Dead or gated as of 2026-10: zcha.in, zcashblockexplorer.com, zcashnetwork.info, zcashexplorer.app (403),
+        // trezor blockbooks (cloudflare), ankr zec_blockbook (plan-gated), cryptoid (no zec), tatum (no zec), 3xpl (token)
+        endpoints: ['https://api.blockchair.com/zcash', 'https://blockbook.zec.zelcore.io/api/v2', 'https://zecbook.nownodes.io/api/v2'],
+        concurrency: 1,
+        sleepMs: 5000,
+    },
+    kaspa: {
+        decimals: 8,
+        endpoints: ['https://api.kaspa.org'],
+        concurrency: 5,
+    },
+    mvc: {
+        decimals: 8,
+        endpoints: ['https://mainnet.mvcapi.com'],
+        concurrency: 5,
+    },
+};
+/** Built-in chains; env-defined chains (see `getChainConfig`) are not listed here. */
+exports.utxoChains = Object.keys(exports.CHAINS);
+exports.PROVIDER_KINDS = ['esplora', 'blockbook', 'blockcypher', 'tatum', 'insight', 'whatsonchain', 'blockchair', 'haskoin', 'kaspa', 'mvc'];
+const ENV_CHAIN_DEFAULT_DECIMALS = 8;
+const ENV_CHAIN_DEFAULT_CONCURRENCY = 5;
+/** mempool.space base url, used for the timestamp -> block lookup (`BITCOIN_MEMPOOL_API`). */
+exports.DEFAULT_MEMPOOL_API = 'https://mempool.space/api';
+/** blockchain.info multiaddr endpoint for bulk bitcoin balances (`BITCOIN_MULTIADDR_API`). */
+exports.DEFAULT_MULTIADDR_API = 'https://blockchain.info/multiaddr';
+/** blockchain.info multiaddr accepts ~100 addresses per call */
+exports.MULTIADDR_CHUNK_SIZE = 100;
+/** pause between multiaddr chunks (blockchain.info rate limit), as in the adapters helper */
+exports.MULTIADDR_SLEEP_MS = 10000;
+/** bitcoin cache api accepts up to 700 addresses per call */
+exports.CACHE_API_CHUNK_SIZE = 700;
+const DEFAULT_CHAIN = 'bitcoin';
+/** UTXO snapshots newer than this are read from `/utxo`, older ones by replaying `/txs` */
+const RECENT_WINDOW_SECONDS = 30 * 60;
+/** True for built-in chains and for chains enabled through env (`<CHAIN>_EXPLORER_API` / `<CHAIN>_WHITELISTED_RPC`). */
+function isUtxoChain(chain) {
+    if (typeof chain !== 'string')
+        return false;
+    if (Object.prototype.hasOwnProperty.call(exports.CHAINS, chain))
+        return true;
+    return getEnvChainConfig(chain) !== undefined;
+}
+function parseProviderKind(value, chain) {
+    if (!value)
+        return undefined;
+    const kind = value.trim().toLowerCase();
+    if (!exports.PROVIDER_KINDS.includes(kind))
+        throw new Error(`utxo: unknown provider "${value}" for ${chain} (${chain.toUpperCase()}_EXPLORER_PROVIDER), expected one of ${exports.PROVIDER_KINDS.join(', ')}`);
+    return kind;
+}
+/**
+ * Config for a chain that is not in `CHAINS`, built from env: `<CHAIN>_EXPLORER_API`
+ * (or `<CHAIN>_WHITELISTED_RPC`) enables it, `<CHAIN>_DECIMALS` defaults to 8 and
+ * `<CHAIN>_EXPLORER_PROVIDER` picks the dialect for unrecognised hosts (default esplora).
+ */
+function getEnvChainConfig(chain) {
+    var _a;
+    if (!/^[a-z0-9_-]+$/i.test(chain))
+        return undefined;
+    const key = chain.toUpperCase();
+    const endpoints = (0, rpc_1.toEndpointList)((0, env_1.getEnvValue)(`${key}_EXPLORER_API`));
+    if (!endpoints.length && !(0, rpc_1.toEndpointList)((0, env_1.getWhitelistedRPCs)(key)).length)
+        return undefined;
+    const decimals = (0, env_1.getEnvValue)(`${key}_DECIMALS`);
+    if (decimals !== undefined && !/^\d+$/.test(decimals.trim()))
+        throw new Error(`utxo: invalid ${key}_DECIMALS "${decimals}"`);
+    return {
+        decimals: decimals === undefined ? ENV_CHAIN_DEFAULT_DECIMALS : +decimals,
+        // env endpoints are picked up by resolveEndpoints, keep defaults empty so they are not listed twice
+        endpoints: [],
+        concurrency: ENV_CHAIN_DEFAULT_CONCURRENCY,
+        provider: (_a = parseProviderKind((0, env_1.getEnvValue)(`${key}_EXPLORER_PROVIDER`), chain)) !== null && _a !== void 0 ? _a : 'esplora',
+    };
+}
+/** Resolved config for `chain`: `CHAINS[chain]` or the env-defined config. Throws for unknown chains. */
+function getChainConfig(chain) {
+    var _a;
+    const config = (_a = exports.CHAINS[chain]) !== null && _a !== void 0 ? _a : getEnvChainConfig(chain);
+    if (!config)
+        throw new Error(`utxo: unsupported chain "${chain}" (known: ${exports.utxoChains.join(', ')}; set ${String(chain).toUpperCase()}_EXPLORER_API to add it)`);
+    return config;
+}
+const getConfig = getChainConfig;
+/** Explorer base urls for `chain`: env `<CHAIN>_EXPLORER_API` wins, then `CHAINS[chain].endpoints`. */
+function getEndpoints({ chain = DEFAULT_CHAIN } = {}) {
+    const config = getConfig(chain);
+    return (0, rpc_1.getEndpoints)(chain, config.endpoints, { envKey: `${chain.toUpperCase()}_EXPLORER_API` });
+}
+function limiter(chain) {
+    return (0, rpc_1.getLimiter)(chain.toUpperCase(), getConfig(chain).concurrency);
+}
+/** Run `fn` under the chain limiter, honouring the chain's `sleepMs` pause. */
+async function throttled(chain, fn) {
+    const { sleepMs } = getConfig(chain);
+    return limiter(chain)(async () => {
+        if (sleepMs)
+            await (0, rpc_1.sleep)(sleepMs);
+        return fn();
+    });
+}
+// ---------------------------------------------------------------------------
+// pure helpers
+// ---------------------------------------------------------------------------
+const BECH32_RE = /^(bc1[ac-hj-np-z02-9]{25,87}|BC1[AC-HJ-NP-Z02-9]{25,87})$/;
+const BASE58_RE = /^[13][1-9A-HJ-NP-Za-km-z]{25,34}$/;
+/**
+ * Basic shape check for a bitcoin mainnet address: bech32 / bech32m (`bc1...`,
+ * single case) or base58 P2PKH / P2SH (`1...` / `3...`). No checksum validation.
+ */
+function isBitcoinAddress(str) {
+    if (typeof str !== 'string')
+        return false;
+    return BECH32_RE.test(str) || BASE58_RE.test(str);
+}
+/** Coerce integer-like values (decimal / bigint / integer number / integer string) to BigInt. */
+function toBigInt(value) {
+    if (value === null || value === undefined || value === '')
+        return BigInt(0);
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error(`utxo.toBigInt: not a finite number: ${value}`);
+        return BigInt(Math.trunc(value));
+    }
+    const s = String(value).trim();
+    if (/^-?\d+$/.test(s))
+        return BigInt(s);
+    if (/^-?(\d+\.?\d*|\.\d+)(e[+-]?\d+)?$/i.test(s)) {
+        const n = Number(s);
+        if (!Number.isFinite(n))
+            throw new Error(`utxo.toBigInt: cannot parse ${s}`);
+        return BigInt(Math.trunc(n));
+    }
+    throw new Error(`utxo.toBigInt: cannot parse ${s}`);
+}
+/**
+ * Whole-coin amount (`'1.5'`, `1.5`, `'2e-3'`) -> base units as a decimal string,
+ * using string arithmetic so 8-decimal values never go through float rounding.
+ * Extra fractional digits are truncated.
+ */
+function toBaseUnits(value, decimals) {
+    if (typeof value === 'bigint')
+        return (value * BigInt(10) ** BigInt(decimals)).toString();
+    let s = String(value).trim();
+    if (s === '')
+        return '0';
+    if (/e/i.test(s)) {
+        const n = Number(s);
+        if (!Number.isFinite(n))
+            throw new Error(`utxo.toBaseUnits: cannot parse ${value}`);
+        s = n.toFixed(Math.min(decimals, 100));
+    }
+    const match = /^(-)?(\d*)(?:\.(\d*))?$/.exec(s);
+    if (!match || (match[2] === '' && (match[3] === undefined || match[3] === '')))
+        throw new Error(`utxo.toBaseUnits: cannot parse ${value}`);
+    const sign = match[1] ? '-' : '';
+    const whole = match[2] || '0';
+    const fraction = (match[3] || '').slice(0, decimals).padEnd(decimals, '0');
+    const raw = BigInt(whole + fraction);
+    if (raw === BigInt(0))
+        return '0';
+    return sign + raw.toString();
+}
+/** Base units -> whole coins as a JS number (`fromBaseUnits('150000000', 8) === 1.5`). */
+function fromBaseUnits(raw, decimals) {
+    return Number(toBigInt(raw)) / 10 ** decimals;
+}
+/**
+ * Parse an esplora `/address/{addr}` response (blockstream, mempool.space,
+ * litecoinspace) into base-unit strings. `confirmed` is `chain_stats.funded - spent`,
+ * matching the adapters' getBalanceNow and the coins server getBtcBalanceSats.
+ */
+function parseBlockstreamAddressStats(json) {
+    var _a, _b, _c, _d;
+    const chainStats = json === null || json === void 0 ? void 0 : json.chain_stats;
+    if (!chainStats || chainStats.funded_txo_sum === undefined || chainStats.spent_txo_sum === undefined)
+        throw new Error('utxo: malformed esplora address response (missing chain_stats)');
+    const mempoolStats = (_a = json.mempool_stats) !== null && _a !== void 0 ? _a : {};
+    const confirmed = toBigInt(chainStats.funded_txo_sum) - toBigInt(chainStats.spent_txo_sum);
+    const unconfirmed = toBigInt((_b = mempoolStats.funded_txo_sum) !== null && _b !== void 0 ? _b : 0) - toBigInt((_c = mempoolStats.spent_txo_sum) !== null && _c !== void 0 ? _c : 0);
+    return {
+        address: json.address,
+        confirmed: confirmed.toString(),
+        unconfirmed: unconfirmed.toString(),
+        total: (confirmed + unconfirmed).toString(),
+        txCount: Number((_d = chainStats.tx_count) !== null && _d !== void 0 ? _d : 0),
+    };
+}
+/**
+ * Confirmed balance in base units from any of the supported explorer dialects.
+ * Shape detection is ordered so ambiguous `balance` fields (coins vs base units)
+ * are only reached for providers that report base units (blockbook v2, kaspa).
+ */
+function parseBalanceResponse(json, { address, decimals }) {
+    var _a, _b, _c;
+    if (json === null || json === undefined || typeof json !== 'object')
+        throw new Error('utxo: empty balance response');
+    // esplora: blockstream / mempool.space / litecoinspace
+    if (json.chain_stats)
+        return parseBlockstreamAddressStats(json).confirmed;
+    // blockcypher (`final_balance` includes unconfirmed, `balance` is confirmed only)
+    if (json.final_balance !== undefined)
+        return toBigInt((_a = json.balance) !== null && _a !== void 0 ? _a : json.final_balance).toString();
+    // insight (dash): `balance` is in coins, `balanceSat` in base units
+    if (json.balanceSat !== undefined)
+        return toBigInt(json.balanceSat).toString();
+    // whatsonchain (bsv) / mvcapi / haskoin (bitcoincash): `{ confirmed, unconfirmed }` in base units
+    if (json.confirmed !== undefined) {
+        if (typeof json.confirmed !== 'number' && typeof json.confirmed !== 'string')
+            throw new Error(`utxo: unexpected balance response for ${address}`);
+        return toBigInt(json.confirmed).toString();
+    }
+    // blockchair dashboards
+    const blockchair = (_c = (_b = json.data) === null || _b === void 0 ? void 0 : _b[address]) === null || _c === void 0 ? void 0 : _c.address;
+    if (blockchair && blockchair.balance !== undefined)
+        return toBigInt(blockchair.balance).toString();
+    if (json.data && typeof json.data === 'object' && !Array.isArray(json.data) && Object.keys(json.data).length && json.data[address] === null)
+        throw new Error(`utxo: blockchair has no data for ${address}`);
+    // tatum: `{ incoming, outgoing }` in whole coins
+    if (json.incoming !== undefined && json.outgoing !== undefined)
+        return (BigInt(toBaseUnits(json.incoming, decimals)) - BigInt(toBaseUnits(json.outgoing, decimals))).toString();
+    // blockbook v2 (string sats) / kaspa (`balance` in sompi)
+    if (json.balance !== undefined)
+        return toBigInt(json.balance).toString();
+    throw new Error(`utxo: unrecognised balance response for ${address}: ${JSON.stringify(json).slice(0, 200)}`);
+}
+const PROVIDERS = [
+    { kind: 'blockchair', match: /blockchair\.com/i, balancePath: (a) => `/dashboards/address/${a}?limit=0` },
+    { kind: 'tatum', match: /tatum\.io/i, balancePath: (a) => `/address/balance/${a}`, headers: tatumHeaders, keyEnv: 'TATUM_API_KEY' },
+    // nownodes `<coin>book.nownodes.io` hosts are blockbooks behind an `api-key` header
+    { kind: 'blockbook', match: /nownodes\.io/i, balancePath: (a) => `/address/${a}`, headers: nownodesHeaders, keyEnv: 'NOWNODES_API_KEY' },
+    { kind: 'blockcypher', match: /blockcypher\.com/i, balancePath: (a) => `/addrs/${a}/balance` },
+    { kind: 'insight', match: /insight/i, balancePath: (a) => `/addr/${a}` },
+    { kind: 'whatsonchain', match: /whatsonchain\.com/i, balancePath: (a) => `/address/${a}/balance` },
+    // haskoin store (api.haskoin.com, api.blockchain.info/haskoin-store): `{ confirmed, unconfirmed }` in base units
+    { kind: 'haskoin', match: /haskoin/i, balancePath: (a) => `/address/${a}/balance` },
+    { kind: 'kaspa', match: /kaspa/i, balancePath: (a) => `/addresses/${encodeURIComponent(a)}/balance` },
+    { kind: 'mvc', match: /mvcapi\.com/i, balancePath: (a) => `/address/${a}/balance` },
+    { kind: 'blockbook', match: /blockbook/i, balancePath: (a) => `/address/${a}` },
+    { kind: 'esplora', match: /blockstream\.info|mempool\.space|litecoinspace\.org/i, balancePath: (a) => `/address/${a}` },
+];
+function tatumHeaders() {
+    var _a;
+    const key = (_a = (0, env_1.getEnvValue)('TATUM_API_KEY')) !== null && _a !== void 0 ? _a : (0, env_1.getEnvValue)('TATUM_PUBLIC_API_KEY');
+    if (!key)
+        return undefined;
+    return { 'x-api-key': key, 'User-Agent': 'Thunder Client (https://www.thunderclient.com)' };
+}
+function nownodesHeaders() {
+    const key = (0, env_1.getEnvValue)('NOWNODES_API_KEY');
+    if (!key)
+        return undefined;
+    return { 'api-key': key };
+}
+const ESPLORA_PROVIDER = PROVIDERS[PROVIDERS.length - 1];
+/** Provider for an explicitly requested dialect; keyless entries win over keyed host-specific ones. */
+function providerByKind(kind) {
+    var _a;
+    return (_a = PROVIDERS.find(p => p.kind === kind && !p.headers)) !== null && _a !== void 0 ? _a : PROVIDERS.find(p => p.kind === kind);
+}
+/**
+ * Provider dialect for an endpoint. Known hosts match directly; otherwise
+ * `<CHAIN>_EXPLORER_PROVIDER` / `config.provider` wins, then the dialect of the
+ * chain's first default endpoint, then esplora.
+ */
+function detectProvider(endpoint, chain) {
+    var _a;
+    const found = PROVIDERS.find(p => p.match.test(endpoint));
+    if (found)
+        return found;
+    const config = getConfig(chain);
+    const kind = (_a = parseProviderKind((0, env_1.getEnvValue)(`${chain.toUpperCase()}_EXPLORER_PROVIDER`), chain)) !== null && _a !== void 0 ? _a : config.provider;
+    if (kind)
+        return providerByKind(kind);
+    const firstDefault = config.endpoints[0];
+    const fallback = firstDefault ? PROVIDERS.find(p => p.match.test(firstDefault)) : undefined;
+    return fallback !== null && fallback !== void 0 ? fallback : ESPLORA_PROVIDER;
+}
+/** Endpoints of `chain` that speak esplora (needed for utxo / tx / block calls). */
+function esploraEndpoints(chain) {
+    const list = getEndpoints({ chain }).filter(e => detectProvider(e, chain).kind === 'esplora');
+    if (!list.length)
+        throw new Error(`utxo: no esplora endpoint configured for ${chain} (set ${chain.toUpperCase()}_EXPLORER_API)`);
+    return list;
+}
+async function esploraGet(chain, path, { retries, timeout } = {}) {
+    return throttled(chain, () => (0, rpc_1.httpGet)(esploraEndpoints(chain), { path, retries, timeout }));
+}
+/**
+ * Confirmed balance of `address` in base units. Tries every configured endpoint in
+ * order (blockstream -> mempool.space -> blockbook for bitcoin) and throws only
+ * when all of them fail.
+ */
+async function getBalance({ chain = DEFAULT_CHAIN, address, retries = 2, timeout }) {
+    var _a, _b;
+    const { decimals } = getConfig(chain);
+    const endpoints = getEndpoints({ chain });
+    const errors = [];
+    for (const endpoint of endpoints) {
+        const provider = detectProvider(endpoint, chain);
+        const headers = provider.headers ? provider.headers() : undefined;
+        if (provider.headers && !headers) {
+            (0, debugLog_1.debugLog)(`[chains.utxo] ${chain}: skipping ${endpoint}, no api key configured (${(_a = provider.keyEnv) !== null && _a !== void 0 ? _a : 'api key env'})`);
+            continue;
+        }
+        try {
+            const data = await throttled(chain, () => (0, rpc_1.httpGet)(endpoint, { path: provider.balancePath(address), headers, retries, timeout }));
+            return parseBalanceResponse(data, { address, decimals });
+        }
+        catch (e) {
+            const message = String((_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : e).slice(0, 200);
+            errors.push(`${endpoint}: ${message}`);
+            (0, debugLog_1.debugLog)(`[chains.utxo] ${chain} balance error for ${address} via ${endpoint}: ${message}`);
+        }
+    }
+    throw new Error(`utxo: all explorers failed for ${chain} ${address}: ${errors.join(' | ') || 'no usable endpoint'}`);
+}
+/**
+ * Confirmed balances of many addresses as `{ [address]: baseUnits }`. Bitcoin
+ * batches through blockchain.info `multiaddr` (100 per call, 10s between chunks)
+ * and falls back to per-address explorer lookups; other chains go per address
+ * under the chain limiter.
+ */
+async function getBalances({ chain = DEFAULT_CHAIN, addresses, skipMultiaddr = false, retries, timeout }) {
+    var _a;
+    getConfig(chain);
+    const unique = uniqueAddresses(addresses);
+    if (!unique.length)
+        return {};
+    if (chain === 'bitcoin' && !skipMultiaddr && unique.length > 1) {
+        try {
+            return await getBitcoinBalancesMultiaddr({ addresses: unique });
+        }
+        catch (e) {
+            (0, debugLog_1.debugLog)(`[chains.utxo] bitcoin multiaddr failed, falling back to per-address lookups: ${String((_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e).slice(0, 200)}`);
+        }
+    }
+    const res = {};
+    await Promise.all(unique.map(async (address) => {
+        res[address] = await getBalance({ chain, address, retries, timeout });
+    }));
+    return res;
+}
+/** blockchain.info `multiaddr` base url (`BITCOIN_MULTIADDR_API` overrides). */
+function getMultiaddrEndpoints() {
+    return (0, rpc_1.getEndpoints)('bitcoin', exports.DEFAULT_MULTIADDR_API, { envKey: 'BITCOIN_MULTIADDR_API' });
+}
+/**
+ * Bitcoin balances via blockchain.info `multiaddr?active=a|b|c` in chunks of 100.
+ * `final_balance` includes unconfirmed outputs, as in the adapters helper.
+ */
+async function getBitcoinBalancesMultiaddr({ addresses, chunkSize = exports.MULTIADDR_CHUNK_SIZE, sleepMs = exports.MULTIADDR_SLEEP_MS }) {
+    const unique = uniqueAddresses(addresses);
+    const res = {};
+    const endpoints = getMultiaddrEndpoints();
+    await (0, rpc_1.runInChunks)(unique, async (chunk) => {
+        const data = await (0, rpc_1.httpGet)(endpoints, { params: { active: chunk.join('|') } });
+        if (!Array.isArray(data === null || data === void 0 ? void 0 : data.addresses))
+            throw new Error('utxo: malformed multiaddr response');
+        for (const entry of data.addresses)
+            res[entry.address] = toBigInt(entry.final_balance).toString();
+        const missing = chunk.filter(a => res[a] === undefined);
+        if (missing.length)
+            throw new Error(`utxo: multiaddr returned no balance for ${missing.length} address(es): ${missing.slice(0, 3).join(', ')}`);
+        return [];
+    }, { chunkSize, concurrency: 1, sleepTime: sleepMs });
+    return res;
+}
+/** `BITCOIN_CACHE_API` url when configured (bulk bitcoin balance cache used by the adapters). */
+function getBitcoinCacheApi() {
+    return (0, env_1.getEnvValue)('BITCOIN_CACHE_API');
+}
+/**
+ * Sum of bitcoin balances via the `BITCOIN_CACHE_API` bulk endpoint
+ * (`POST { addresses, network: 'BTC' }` -> total sats, 700 addresses per call),
+ * mirroring getCachedBitcoinBalances in the adapters. Throws when the env is not set.
+ */
+async function getCachedBitcoinTotal({ addresses, chunkSize = exports.CACHE_API_CHUNK_SIZE }) {
+    var _a, _b;
+    const cacheApi = getBitcoinCacheApi();
+    if (!cacheApi)
+        throw new Error('utxo: BITCOIN_CACHE_API is not set');
+    const unique = uniqueAddresses(addresses);
+    const chunks = (0, rpc_1.sliceIntoChunks)(unique, chunkSize);
+    (0, debugLog_1.debugLog)(`[chains.utxo] bitcoin cache api call: ${unique.length} addresses, ${chunks.length} chunk(s)`);
+    let sum = BigInt(0);
+    for (const chunk of chunks) {
+        const res = await (0, rpc_1.httpPost)(cacheApi, { addresses: chunk, network: 'BTC' }, { retries: 3 });
+        const value = typeof res === 'object' && res !== null ? ((_b = (_a = res.balance) !== null && _a !== void 0 ? _a : res.total) !== null && _b !== void 0 ? _b : res.result) : res;
+        sum += toBigInt(value);
+    }
+    return sum.toString();
+}
+/**
+ * Sum of confirmed balances in base units. For bitcoin with `BITCOIN_CACHE_API`
+ * set and more than `cacheThreshold` addresses the bulk cache is used first
+ * (the adapters' `_sumTokensBlockchain` flow), then `getBalances` is summed.
+ */
+async function getTotalBalance({ chain = DEFAULT_CHAIN, addresses, cacheThreshold = 51, forceCacheUse = false, ...rest }) {
+    var _a;
+    const unique = uniqueAddresses(addresses);
+    if (chain === 'bitcoin' && getBitcoinCacheApi() && unique.length > cacheThreshold) {
+        if (unique.length > 1000)
+            forceCacheUse = true;
+        try {
+            return await getCachedBitcoinTotal({ addresses: unique });
+        }
+        catch (e) {
+            if (forceCacheUse)
+                throw e;
+            (0, debugLog_1.debugLog)(`[chains.utxo] bitcoin cache error, falling back to explorers: ${String((_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e).slice(0, 200)}`);
+        }
+    }
+    const balances = await getBalances({ chain, addresses: unique, ...rest });
+    let sum = BigInt(0);
+    for (const value of Object.values(balances))
+        sum += toBigInt(value);
+    return sum.toString();
+}
+// ---------------------------------------------------------------------------
+// esplora: utxos, txs, historical balance
+// ---------------------------------------------------------------------------
+/**
+ * Unspent outputs of `address` (`/address/{addr}/utxo`), values as base-unit strings.
+ * Blockstream answers 400 "Too many unspent outputs" for very large utxo sets
+ * (e.g. the genesis address); use `getBalance` for those.
+ */
+async function getUtxos({ chain = DEFAULT_CHAIN, address }) {
+    const utxos = await esploraGet(chain, `/address/${address}/utxo`);
+    if (!Array.isArray(utxos))
+        throw new Error(`utxo: malformed utxo response for ${address}`);
+    return utxos.map((u) => { var _a; return ({ txid: u.txid, vout: u.vout, value: toBigInt(u.value).toString(), status: (_a = u.status) !== null && _a !== void 0 ? _a : { confirmed: false } }); });
+}
+/**
+ * One page of transactions for `address`: `/address/{addr}/txs` (up to 25 mempool
+ * + 25 confirmed) or, with `lastSeenTxid`, `/address/{addr}/txs/chain/{txid}`
+ * (next 25 confirmed). An empty array means no more pages.
+ */
+async function getAddressTxs({ chain = DEFAULT_CHAIN, address, lastSeenTxid }) {
+    const path = lastSeenTxid ? `/address/${address}/txs/chain/${lastSeenTxid}` : `/address/${address}/txs`;
+    const txs = await esploraGet(chain, path);
+    if (!Array.isArray(txs))
+        throw new Error(`utxo: malformed txs response for ${address}`);
+    return txs;
+}
+/**
+ * Bitcoin balance of `address` at `timestamp` (unix seconds) in base units, ported
+ * from the adapters' archive getBalance: for timestamps within the last 30 minutes
+ * the current utxo set is filtered by `block_time`; otherwise every confirmed tx is
+ * replayed (vout adds, vin.prevout subtracts) until the page list is exhausted.
+ * Unconfirmed txs (no `block_time`) are ignored.
+ */
+async function getBitcoinBalanceAt({ chain = DEFAULT_CHAIN, address, timestamp, maxPages }) {
+    var _a, _b, _c, _d, _e;
+    const now = Date.now() / 1e3;
+    let balance = BigInt(0);
+    if (timestamp > now - RECENT_WINDOW_SECONDS) {
+        const utxos = await getUtxos({ chain, address });
+        for (const utxo of utxos) {
+            const blockTime = (_a = utxo.status) === null || _a === void 0 ? void 0 : _a.block_time;
+            if (blockTime !== undefined && blockTime <= timestamp)
+                balance += BigInt(utxo.value);
+        }
+        return balance.toString();
+    }
+    let txs = await getAddressTxs({ chain, address });
+    let page = 0;
+    while (txs.length) {
+        for (const tx of txs) {
+            const blockTime = (_b = tx.status) === null || _b === void 0 ? void 0 : _b.block_time;
+            if (blockTime === undefined || blockTime > timestamp)
+                continue;
+            for (const vin of (_c = tx.vin) !== null && _c !== void 0 ? _c : [])
+                if (((_d = vin.prevout) === null || _d === void 0 ? void 0 : _d.scriptpubkey_address) === address)
+                    balance -= toBigInt(vin.prevout.value);
+            for (const vout of (_e = tx.vout) !== null && _e !== void 0 ? _e : [])
+                if (vout.scriptpubkey_address === address)
+                    balance += toBigInt(vout.value);
+        }
+        page++;
+        if (maxPages !== undefined && page >= maxPages) {
+            (0, debugLog_1.debugLog)(`[chains.utxo] getBitcoinBalanceAt ${address}: stopped after ${maxPages} pages`);
+            break;
+        }
+        txs = await getAddressTxs({ chain, address, lastSeenTxid: txs[txs.length - 1].txid });
+    }
+    return balance.toString();
+}
+// ---------------------------------------------------------------------------
+// esplora: blocks
+// ---------------------------------------------------------------------------
+async function getBlockByHeight(chain, height) {
+    var _a;
+    const hash = String(await esploraGet(chain, `/block-height/${height}`)).trim();
+    if (!/^[0-9a-f]{64}$/i.test(hash))
+        throw new Error(`utxo: no block hash for ${chain} height ${height}`);
+    const block = await esploraGet(chain, `/block/${hash}`);
+    return { number: Number((_a = block.height) !== null && _a !== void 0 ? _a : height), timestamp: Number(block.timestamp), hash };
+}
+/** Chain tip via `/blocks/tip/height` + `/block-height/{h}` + `/block/{hash}`. */
+async function getLatestBlock({ chain = DEFAULT_CHAIN } = {}) {
+    const height = Number(await esploraGet(chain, '/blocks/tip/height'));
+    if (!Number.isFinite(height))
+        throw new Error(`utxo: malformed tip height for ${chain}`);
+    return getBlockByHeight(chain, height);
+}
+/** Block by height (`/block-height/{h}` then `/block/{hash}`). */
+async function getBlock({ chain = DEFAULT_CHAIN, height }) {
+    return getBlockByHeight(chain, height);
+}
+/** mempool.space base urls (`BITCOIN_MEMPOOL_API` overrides; falls back to any configured mempool endpoint). */
+function getMempoolEndpoints() {
+    const configured = getEndpoints({ chain: 'bitcoin' }).filter(e => /mempool/i.test(e));
+    return (0, rpc_1.getEndpoints)('bitcoin', configured.length ? configured : exports.DEFAULT_MEMPOOL_API, { envKey: 'BITCOIN_MEMPOOL_API' });
+}
+/**
+ * Latest block mined at or before `timestamp` (unix seconds). Bitcoin asks
+ * mempool.space `/v1/mining/blocks/timestamp/{ts}` first (then walks back if the
+ * returned block is newer than `timestamp`); otherwise / on failure a binary
+ * search over `/block-height/{h}` is used.
+ */
+async function getBlockAtTimestamp({ chain = DEFAULT_CHAIN, timestamp }) {
+    var _a;
+    timestamp = Math.floor(timestamp > 1e12 ? timestamp / 1000 : timestamp);
+    if (chain === 'bitcoin') {
+        try {
+            const res = await throttled(chain, () => (0, rpc_1.httpGet)(getMempoolEndpoints(), { path: `/v1/mining/blocks/timestamp/${timestamp}` }));
+            const height = Number(res === null || res === void 0 ? void 0 : res.height);
+            if (!Number.isFinite(height))
+                throw new Error('malformed mempool response');
+            let block = await getBlockByHeight(chain, height);
+            // mempool returns the closest block, which may be just after the timestamp
+            while (block.timestamp > timestamp && block.number > 0)
+                block = await getBlockByHeight(chain, block.number - 1);
+            return block;
+        }
+        catch (e) {
+            (0, debugLog_1.debugLog)(`[chains.utxo] mempool timestamp lookup failed, falling back to binary search: ${String((_a = e === null || e === void 0 ? void 0 : e.message) !== null && _a !== void 0 ? _a : e).slice(0, 200)}`);
+        }
+    }
+    const tip = await getLatestBlock({ chain });
+    if (tip.timestamp <= timestamp)
+        return tip;
+    let lo = 0;
+    let hi = tip.number;
+    let best;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const block = await getBlockByHeight(chain, mid);
+        if (block.timestamp <= timestamp) {
+            best = block;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    if (!best)
+        throw new Error(`utxo: no ${chain} block at or before ${timestamp}`);
+    return best;
+}
+// ---------------------------------------------------------------------------
+// misc
+// ---------------------------------------------------------------------------
+function uniqueAddresses(addresses) {
+    const seen = new Set();
+    const res = [];
+    for (const address of addresses !== null && addresses !== void 0 ? addresses : []) {
+        if (typeof address !== 'string')
+            continue;
+        const trimmed = address.trim();
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        res.push(trimmed);
+    }
+    return res;
+}