crypto-aio 0.0.3 → 0.2.0

package/dist/adapters/utxo/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../../src/adapters/utxo/driver.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The UTXO driver factory: validated network config, endpoint probes on both transports,\n * and the ports. Loaded only by the manifest's `load()`, with bitcoinjs-lib.\n */\nimport type { ChainDriver, DriverContext, DriverFactory } from '../../core/driver/types';\nimport { ConfigError } from '../../core/errors/error';\nimport type { EndpointCall, HealthProbes } from '../../core/transport/types';\nimport { utxoBroadcaster, utxoBuilder, utxoReplacement } from './builder';\nimport { networkOf } from './codec';\nimport { READ, parseWalletOptions, signingScheme, type UtxoContext } from './context';\nimport { EsploraClient, parseHash, parseHeight } from './esplora';\nimport { utxoNetworkConfig } from './network';\nimport { blockSource, proofSource } from './proofs';\nimport { addressCodec, addressHistory, chainReader, listUnspent } from './reader';\nimport { bitcoin, useNobleEcc } from './sdk';\nimport { coinSelectionPreview } from './preview';\nimport { MAX_OUTPUTS } from './spend';\nimport type { UtxoExt } from './types';\n\nexport interface UtxoNativeClient {\n  /** The bitcoinjs-lib module, with this library's `@noble/curves` ECC backend installed. */\n  readonly bitcoin: typeof bitcoin;\n  /** A fresh copy of this network's bitcoinjs parameters. */\n  readonly network: ReturnType<typeof networkOf>;\n  /** A GET to the handle's Esplora (`rpc`) endpoints, through the policy-wrapped transport. */\n  esplora<T = unknown>(path: string, responseType?: 'json' | 'text'): Promise<T>;\n}\n\nfunction probes(expectedIdentity: string): HealthProbes {\n  const text = (call: EndpointCall, path: string, route: string) =>\n    call.http<string>({ method: 'GET', path, route, responseType: 'text' });\n  return {\n    identity: async (call) =>\n      parseHash(await text(call, '/block-height/0', '/block-height/:height')),\n    expectedIdentity,\n    height: async (call) =>\n      parseHeight(await text(call, '/blocks/tip/height', '/blocks/tip/height')),\n  };\n}\n\nexport const utxoDriverFactory: DriverFactory = {\n  async create(ctx: DriverContext): Promise<ChainDriver> {\n    const config = utxoNetworkConfig(ctx.chain, ctx.network, ctx.options);\n    if (!ctx.indexer) {\n      throw new ConfigError(\n        'CONFIG_INVALID',\n        'the UTXO driver requires an indexer provider',\n      );\n    }\n    // Both transports, before any traffic: the genesis-hash probe keeps an endpoint of\n    // another network out of the `rpc` reads and the `indexer` reads alike.\n    ctx.transport.setProbes(probes(config.genesisHash));\n    ctx.indexer.setProbes(probes(config.genesisHash));\n    const esplora = new EsploraClient(ctx.transport, ctx.indexer);\n    const utxo: UtxoContext = {\n      esplora,\n      chain: ctx.chain,\n      network: ctx.network,\n      config,\n      log: ctx.log,\n    };\n    const network = networkOf(config.address);\n    const builder = utxoBuilder(utxo, network);\n    return {\n      ordering: 'inputs',\n      capabilities: config.capabilities,\n      address: addressCodec(utxo),\n      reader: chainReader(utxo),\n      builder,\n      broadcaster: utxoBroadcaster(utxo),\n      proofs: proofSource(utxo),\n      replacement: utxoReplacement(utxo, network),\n      blocks: blockSource(utxo),\n      history: addressHistory(utxo),\n      ext: {\n        utxo: {\n          listUnspent: (address: string) => listUnspent(utxo, address),\n          coinSelection: (request: Parameters<UtxoExt['utxo']['coinSelection']>[0]) =>\n            coinSelectionPreview(utxo, request),\n        },\n      } satisfies UtxoExt,\n      limits: () => ({ maxOutputs: MAX_OUTPUTS }),\n      // One scheme per address type, so a p2tr wallet's ECDSA-only signer (a KMS key) is\n      // refused when the wallet resolves, not at signing.\n      signingSchemes: (wallet) => [\n        signingScheme(parseWalletOptions(wallet, config).addressType),\n      ],\n      createNativeClient: () => {\n        // The doc's promise: taproot works on this module (and a swapped backend is undone).\n        useNobleEcc();\n        const client: UtxoNativeClient = {\n          bitcoin,\n          network: { ...network, bip32: { ...network.bip32 } },\n          esplora: <T>(path: string, responseType: 'json' | 'text' = 'json') =>\n            ctx.transport.http<T>(\n              { method: 'GET', path, route: '/native', responseType },\n              READ,\n            ),\n        };\n        return { client };\n      },\n    };\n  },\n};\n"]}

package/dist/adapters/utxo/ecc.d.ts

@@ -0,0 +1,9 @@
+import { isXOnlyPoint } from './address';
+export interface XOnlyTweakResult {
+    readonly parity: 0 | 1;
+    readonly xOnlyPubkey: Uint8Array;
+}
+export declare const nobleEcc: Readonly<{
+    isXOnlyPoint: typeof isXOnlyPoint;
+    xOnlyPointAddTweak(point: Uint8Array, tweak: Uint8Array): XOnlyTweakResult | null;
+}>;

package/dist/adapters/utxo/ecc.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nobleEcc = void 0;
+/**
+ * bitcoinjs-lib's ECC interface (`isXOnlyPoint`, `xOnlyPointAddTweak`) over
+ * `@noble/curves`. SDK-free: bitcoinjs checks it against its own vectors when
+ * `initEccLib` installs it.
+ */
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const address_1 = require("./address");
+exports.nobleEcc = Object.freeze({
+    isXOnlyPoint: address_1.isXOnlyPoint,
+    xOnlyPointAddTweak(point, tweak) {
+        if (!(0, address_1.isXOnlyPoint)(point) || tweak.length !== 32)
+            return null;
+        const t = secp256k1_1.schnorr.utils.bytesToNumberBE(tweak);
+        if (t >= secp256k1_1.secp256k1.CURVE.n)
+            return null;
+        const P = secp256k1_1.schnorr.utils.lift_x(secp256k1_1.schnorr.utils.bytesToNumberBE(point));
+        const Q = t === 0n ? P : P.add(secp256k1_1.secp256k1.ProjectivePoint.BASE.multiply(t));
+        if (Q.equals(secp256k1_1.secp256k1.ProjectivePoint.ZERO))
+            return null;
+        return { parity: Q.hasEvenY() ? 0 : 1, xOnlyPubkey: Q.toRawBytes(true).slice(1) };
+    },
+});
+//# sourceMappingURL=ecc.js.map

package/dist/adapters/utxo/ecc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ecc.js","sourceRoot":"","sources":["../../../src/adapters/utxo/ecc.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,uDAA6D;AAC7D,uCAAyC;AAO5B,QAAA,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,YAAY,EAAZ,sBAAY;IACZ,kBAAkB,CAAC,KAAiB,EAAE,KAAiB;QACrD,IAAI,CAAC,IAAA,sBAAY,EAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,IAAI,CAAC;QAC7D,MAAM,CAAC,GAAG,mBAAO,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI,qBAAS,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,IAAI,CAAC;QACxC,MAAM,CAAC,GAAG,mBAAO,CAAC,KAAK,CAAC,MAAM,CAAC,mBAAO,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,qBAAS,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3E,IAAI,CAAC,CAAC,MAAM,CAAC,qBAAS,CAAC,eAAe,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAC;QAC1D,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,CAAC;CACF,CAAC,CAAC","sourcesContent":["/**\n * bitcoinjs-lib's ECC interface (`isXOnlyPoint`, `xOnlyPointAddTweak`) over\n * `@noble/curves`. SDK-free: bitcoinjs checks it against its own vectors when\n * `initEccLib` installs it.\n */\nimport { schnorr, secp256k1 } from '@noble/curves/secp256k1';\nimport { isXOnlyPoint } from './address';\n\nexport interface XOnlyTweakResult {\n  readonly parity: 0 | 1;\n  readonly xOnlyPubkey: Uint8Array;\n}\n\nexport const nobleEcc = Object.freeze({\n  isXOnlyPoint,\n  xOnlyPointAddTweak(point: Uint8Array, tweak: Uint8Array): XOnlyTweakResult | null {\n    if (!isXOnlyPoint(point) || tweak.length !== 32) return null;\n    const t = schnorr.utils.bytesToNumberBE(tweak);\n    if (t >= secp256k1.CURVE.n) return null;\n    const P = schnorr.utils.lift_x(schnorr.utils.bytesToNumberBE(point));\n    const Q = t === 0n ? P : P.add(secp256k1.ProjectivePoint.BASE.multiply(t));\n    if (Q.equals(secp256k1.ProjectivePoint.ZERO)) return null;\n    return { parity: Q.hasEvenY() ? 0 : 1, xOnlyPubkey: Q.toRawBytes(true).slice(1) };\n  },\n});\n"]}

package/dist/adapters/utxo/errors.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Broadcast classification (pure). Esplora forwards bitcoind's `sendrawtransaction` error as
+ * an HTTP 400 body, in one of two formats:
+ * - Blockstream electrs: `sendrawtransaction RPC error -26: min relay fee not met, 100 < 141`
+ * - mempool/electrs: `sendrawtransaction RPC error: {"code":-26,"message":"min relay fee …"}`
+ *
+ * `rejected` only for exact, anchored reject reasons that make these
+ * bytes invalid by consensus on every node (bitcoind's `CheckTransaction` and consensus
+ * script checks, and an undecodable transaction); everything that depends on state, policy
+ * or node configuration is `refused`, which is also the default for unknown texts. A
+ * `rejected` reason counts only under the code bitcoind answers it with, so a text outside
+ * bitcoind's structured answer never ends an Attempt. Reasons are fixed literals: bitcoind's
+ * texts carry txids, amounts and fee rates, which a stored reason must never hold.
+ *
+ * A node's rejection is a claim. `nodeClaim` only parses what the node
+ * claims, and a claimed consensus failure is `invalid`, a kind no `Broadcaster` may return.
+ * `classifyOwnBroadcast`, the only classifier, keeps a `rejected` only when the claimed reason
+ * holds for the bytes that were sent, checked here, and makes every other one `refused`
+ * (non-terminal). No export takes the node at its word.
+ */
+import type { BroadcastResult } from '../../core/driver/types';
+export interface NodeError {
+    readonly code?: number;
+    readonly message: string;
+}
+/**
+ * The bitcoind error inside an Esplora 400 body, or the body's head when it is neither
+ * format.
+ */
+export declare function parseNodeError(body: string): NodeError;
+/**
+ * What bitcoind's answer claims, parsed: it decides nothing. A claimed consensus failure is
+ * `invalid`, which is no `BroadcastResult`: only `classifyOwnBroadcast` turns it into a
+ * `rejected` verdict, and only for bytes its reason holds for.
+ */
+export type NodeClaim = Extract<BroadcastResult, {
+    readonly kind: 'already-known' | 'refused';
+}> | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+};
+export declare function nodeClaim(error: NodeError): NodeClaim;
+/**
+ * The node's answer to the hex this driver sent. A terminal `rejected` frees the
+ * Attempt's inputs for a caller's retry, and if a lying or buggy endpoint relayed the bytes
+ * before it claimed them invalid, the retry and the original can both confirm: a double
+ * payment. So a rejection stands only when its claimed reason holds for those bytes, decoded
+ * here (whether they decode is always this module's own finding): an undecodable
+ * hex for `TX decode failed`, a byte rule for a `CheckTransaction` reason. Anything else is
+ * `refused`.
+ */
+export declare function classifyOwnBroadcast(error: NodeError, sentHex: string): BroadcastResult;

package/dist/adapters/utxo/errors.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseNodeError = parseNodeError;
+exports.nodeClaim = nodeClaim;
+exports.classifyOwnBroadcast = classifyOwnBroadcast;
+const rawtx_1 = require("./rawtx");
+/**
+ * Only a body's head is read. bitcoind's code and reject reason come first and its
+ * texts are far shorter; unbounded, the mempool/electrs pattern is quadratic in the length.
+ */
+const MAX_BODY = 1_024;
+/**
+ * The bitcoind error inside an Esplora 400 body, or the body's head when it is neither
+ * format.
+ */
+function parseNodeError(body) {
+    const text = body.slice(0, MAX_BODY).trim();
+    const json = /RPC error: (\{.*\})$/s.exec(text);
+    if (json) {
+        try {
+            const parsed = JSON.parse(json[1]);
+            if (typeof parsed.message === 'string') {
+                return {
+                    ...(typeof parsed.code === 'number' ? { code: parsed.code } : {}),
+                    message: parsed.message,
+                };
+            }
+        }
+        catch {
+            // Fall through: not the mempool/electrs format after all.
+        }
+    }
+    // The transport keeps only the first 300 characters of a 400 body (`details.body`), which
+    // leaves the JSON of a long message unterminated: its code and the head of its message
+    // classify it as the Blockstream format of the same answer does.
+    const cut = /RPC error: \{"code":(-?\d+),"message":"(.*)$/s.exec(text);
+    if (cut)
+        return { code: Number(cut[1]), message: cut[2] };
+    const plain = /RPC error (-?\d+): (.*)$/s.exec(text);
+    if (plain)
+        return { code: Number(plain[1]), message: plain[2] };
+    return { message: text };
+}
+/** A reject reason at the start of the message, followed by nothing, `,`, `.` or a space. */
+const reason = (...names) => new RegExp(`^(?:${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})(?:$|,| \\(|\\.| )`);
+const ALREADY_KNOWN = reason('txn-already-in-mempool', 'txn-already-known', 'txn-same-nonwitness-data-in-mempool', 'Transaction outputs already in utxo set', 'Transaction already in block chain');
+/** bitcoind's -22 (`RPC_DESERIALIZATION_ERROR`) reason: the hex does not decode. */
+const DECODE_FAILED = 'TX decode failed';
+/**
+ * Consensus failures of these exact bytes (bitcoind `CheckTransaction`, consensus scripts),
+ * each under the code bitcoind answers it with: -26 (`RPC_VERIFY_REJECTED`, a mempool
+ * rejection) or -22 (`RPC_DESERIALIZATION_ERROR`, undecodable hex).
+ */
+const REJECTED = [
+    [
+        -26,
+        [
+            'bad-txns-vin-empty',
+            'bad-txns-vout-empty',
+            'bad-txns-oversize',
+            'bad-txns-vout-negative',
+            'bad-txns-vout-toolarge',
+            'bad-txns-txouttotal-toolarge',
+            'bad-txns-inputs-duplicate',
+            'bad-txns-prevout-null',
+            'bad-txns-in-belowout',
+            'bad-txns-inputvalues-outofrange',
+            'bad-txns-fee-outofrange',
+            'coinbase',
+        ],
+        'invalid by consensus rules',
+    ],
+    [
+        -26,
+        ['mandatory-script-verify-flag-failed', 'block-script-verify-flag-failed'],
+        'script verification failed',
+    ],
+    [-22, [DECODE_FAILED], 'the transaction does not decode'],
+];
+/** Each rejected reason's own anchored pattern, with the code and the verdict text. */
+const CLAIMS = REJECTED.flatMap(([code, names, text]) => names.map((name) => [code, name, reason(name), text]));
+/** The rejected reason bitcoind's answer claims, or `undefined` when it claims none. */
+function claimedReason(error, message) {
+    return CLAIMS.find(([code, , pattern]) => error.code === code && pattern.test(message));
+}
+const FEE_TOO_LOW = reason('min relay fee not met', 'mempool min fee not met', 'insufficient fee');
+const SPENT = reason('bad-txns-inputs-missingorspent', 'Missing inputs', 'Inputs missing or spent', 'txn-mempool-conflict', 'bad-txns-spends-conflicting-tx');
+function nodeClaim(error) {
+    const message = error.message.trim();
+    if (ALREADY_KNOWN.test(message) || error.code === -27)
+        return { kind: 'already-known' };
+    const claim = claimedReason(error, message);
+    if (claim)
+        return { kind: 'invalid', reason: claim[3] };
+    if (FEE_TOO_LOW.test(message)) {
+        return { kind: 'refused', code: 'FEE_TOO_LOW', reason: 'fee too low for the node' };
+    }
+    if (SPENT.test(message)) {
+        return {
+            kind: 'refused',
+            code: 'TX_REFUSED',
+            reason: 'inputs missing or already spent',
+        };
+    }
+    return {
+        kind: 'refused',
+        code: 'TX_REFUSED',
+        reason: 'the node refused the transaction',
+    };
+}
+/** Bitcoin Core's `MAX_MONEY` and `MAX_BLOCK_WEIGHT`. */
+const MAX_MONEY = 2100000000000000n;
+const MAX_BLOCK_WEIGHT = 4_000_000;
+const NULL_TXID = '0'.repeat(64);
+const isNull = (input) => input.txid === NULL_TXID && input.vout === 0xffffffff;
+const isCoinbase = (tx) => tx.inputs.length === 1 && isNull(tx.inputs[0]);
+/**
+ * bitcoind's reasons the bytes alone decide (`CheckTransaction`, and ATMP's `coinbase`), each
+ * as bitcoind tests it. The others (`bad-txns-in-belowout`, `-inputvalues-outofrange`,
+ * `-fee-outofrange` and every script check) depend on the spent outputs, and have no rule: the
+ * builder spends only outputs whose value and script their previous transaction authenticates
+ * (every input, every wallet type, whatever `nonWitnessUtxo` says), and the core
+ * verifies every signature, so they cannot hold for our own bytes, and a node that claims one
+ * is not believed.
+ */
+const BYTE_RULES = {
+    'bad-txns-vin-empty': (tx) => tx.inputs.length === 0,
+    'bad-txns-vout-empty': (tx) => tx.values.length === 0,
+    'bad-txns-oversize': (tx) => tx.strippedSize * 4 > MAX_BLOCK_WEIGHT,
+    'bad-txns-vout-negative': (tx) => tx.values.some((value) => value < 0n),
+    'bad-txns-vout-toolarge': (tx) => tx.values.some((value) => value > MAX_MONEY),
+    // bitcoind's loop: each output in order, stopping at the first that fails.
+    'bad-txns-txouttotal-toolarge': (tx) => {
+        let total = 0n;
+        for (const value of tx.values) {
+            if (value < 0n || value > MAX_MONEY)
+                return false; // `vout-negative`, `-toolarge`
+            total += value;
+            if (total > MAX_MONEY)
+                return true;
+        }
+        return false;
+    },
+    'bad-txns-inputs-duplicate': (tx) => new Set(tx.inputs.map((input) => `${input.txid}:${input.vout}`)).size <
+        tx.inputs.length,
+    'bad-txns-prevout-null': (tx) => !isCoinbase(tx) && tx.inputs.some(isNull),
+    coinbase: isCoinbase,
+};
+/** A rejection this driver cannot confirm for the bytes it sent: observed, never terminal. */
+const UNCONFIRMED = {
+    kind: 'refused',
+    code: 'TX_REFUSED',
+    reason: 'the node claimed the transaction is invalid',
+};
+/**
+ * The hex that was sent, decoded as `sendrawtransaction` decodes it (`rawtx.ts` follows
+ * bitcoind's format, with no cap below the broadcaster's own), or `undefined` when bitcoind
+ * cannot decode it either.
+ */
+function bytesOf(sentHex) {
+    const tx = (0, rawtx_1.readTxHex)(sentHex, { maxStripped: rawtx_1.MAX_TX_BYTES });
+    if (!tx)
+        return undefined;
+    return {
+        inputs: tx.inputs.map((input) => ({ txid: input.txid, vout: input.vout })),
+        values: tx.outputs.map((output) => output.value),
+        strippedSize: tx.strippedSize,
+    };
+}
+/**
+ * The node's answer to the hex this driver sent. A terminal `rejected` frees the
+ * Attempt's inputs for a caller's retry, and if a lying or buggy endpoint relayed the bytes
+ * before it claimed them invalid, the retry and the original can both confirm: a double
+ * payment. So a rejection stands only when its claimed reason holds for those bytes, decoded
+ * here (whether they decode is always this module's own finding): an undecodable
+ * hex for `TX decode failed`, a byte rule for a `CheckTransaction` reason. Anything else is
+ * `refused`.
+ */
+function classifyOwnBroadcast(error, sentHex) {
+    const claim = nodeClaim(error);
+    if (claim.kind !== 'invalid')
+        return claim;
+    const bytes = bytesOf(sentHex);
+    const rejected = { kind: 'rejected', reason: claim.reason };
+    const name = claimedReason(error, error.message.trim())?.[1];
+    if (name === DECODE_FAILED)
+        return bytes === undefined ? rejected : UNCONFIRMED;
+    const rule = name !== undefined && Object.hasOwn(BYTE_RULES, name) ? BYTE_RULES[name] : undefined;
+    return bytes !== undefined && rule?.(bytes) ? rejected : UNCONFIRMED;
+}
+//# sourceMappingURL=errors.js.map

package/dist/adapters/utxo/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/adapters/utxo/errors.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Broadcast classification (pure). Esplora forwards bitcoind's `sendrawtransaction` error as\n * an HTTP 400 body, in one of two formats:\n * - Blockstream electrs: `sendrawtransaction RPC error -26: min relay fee not met, 100 < 141`\n * - mempool/electrs: `sendrawtransaction RPC error: {\"code\":-26,\"message\":\"min relay fee …\"}`\n *\n * `rejected` only for exact, anchored reject reasons that make these\n * bytes invalid by consensus on every node (bitcoind's `CheckTransaction` and consensus\n * script checks, and an undecodable transaction); everything that depends on state, policy\n * or node configuration is `refused`, which is also the default for unknown texts. A\n * `rejected` reason counts only under the code bitcoind answers it with, so a text outside\n * bitcoind's structured answer never ends an Attempt. Reasons are fixed literals: bitcoind's\n * texts carry txids, amounts and fee rates, which a stored reason must never hold.\n *\n * A node's rejection is a claim. `nodeClaim` only parses what the node\n * claims, and a claimed consensus failure is `invalid`, a kind no `Broadcaster` may return.\n * `classifyOwnBroadcast`, the only classifier, keeps a `rejected` only when the claimed reason\n * holds for the bytes that were sent, checked here, and makes every other one `refused`\n * (non-terminal). No export takes the node at its word.\n */\nimport type { BroadcastResult } from '../../core/driver/types';\nimport { MAX_TX_BYTES, readTxHex } from './rawtx';\n\nexport interface NodeError {\n  readonly code?: number;\n  readonly message: string;\n}\n\n/**\n * Only a body's head is read. bitcoind's code and reject reason come first and its\n * texts are far shorter; unbounded, the mempool/electrs pattern is quadratic in the length.\n */\nconst MAX_BODY = 1_024;\n\n/**\n * The bitcoind error inside an Esplora 400 body, or the body's head when it is neither\n * format.\n */\nexport function parseNodeError(body: string): NodeError {\n  const text = body.slice(0, MAX_BODY).trim();\n  const json = /RPC error: (\\{.*\\})$/s.exec(text);\n  if (json) {\n    try {\n      const parsed = JSON.parse(json[1] as string) as {\n        code?: unknown;\n        message?: unknown;\n      };\n      if (typeof parsed.message === 'string') {\n        return {\n          ...(typeof parsed.code === 'number' ? { code: parsed.code } : {}),\n          message: parsed.message,\n        };\n      }\n    } catch {\n      // Fall through: not the mempool/electrs format after all.\n    }\n  }\n  // The transport keeps only the first 300 characters of a 400 body (`details.body`), which\n  // leaves the JSON of a long message unterminated: its code and the head of its message\n  // classify it as the Blockstream format of the same answer does.\n  const cut = /RPC error: \\{\"code\":(-?\\d+),\"message\":\"(.*)$/s.exec(text);\n  if (cut) return { code: Number(cut[1]), message: cut[2] as string };\n  const plain = /RPC error (-?\\d+): (.*)$/s.exec(text);\n  if (plain) return { code: Number(plain[1]), message: plain[2] as string };\n  return { message: text };\n}\n\n/** A reject reason at the start of the message, followed by nothing, `,`, `.` or a space. */\nconst reason = (...names: readonly string[]): RegExp =>\n  new RegExp(\n    `^(?:${names.map((n) => n.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')).join('|')})(?:$|,| \\\\(|\\\\.| )`,\n  );\n\nconst ALREADY_KNOWN = reason(\n  'txn-already-in-mempool',\n  'txn-already-known',\n  'txn-same-nonwitness-data-in-mempool',\n  'Transaction outputs already in utxo set',\n  'Transaction already in block chain',\n);\n\n/** bitcoind's -22 (`RPC_DESERIALIZATION_ERROR`) reason: the hex does not decode. */\nconst DECODE_FAILED = 'TX decode failed';\n\n/**\n * Consensus failures of these exact bytes (bitcoind `CheckTransaction`, consensus scripts),\n * each under the code bitcoind answers it with: -26 (`RPC_VERIFY_REJECTED`, a mempool\n * rejection) or -22 (`RPC_DESERIALIZATION_ERROR`, undecodable hex).\n */\nconst REJECTED: readonly (readonly [number, readonly string[], string])[] = [\n  [\n    -26,\n    [\n      'bad-txns-vin-empty',\n      'bad-txns-vout-empty',\n      'bad-txns-oversize',\n      'bad-txns-vout-negative',\n      'bad-txns-vout-toolarge',\n      'bad-txns-txouttotal-toolarge',\n      'bad-txns-inputs-duplicate',\n      'bad-txns-prevout-null',\n      'bad-txns-in-belowout',\n      'bad-txns-inputvalues-outofrange',\n      'bad-txns-fee-outofrange',\n      'coinbase',\n    ],\n    'invalid by consensus rules',\n  ],\n  [\n    -26,\n    ['mandatory-script-verify-flag-failed', 'block-script-verify-flag-failed'],\n    'script verification failed',\n  ],\n  [-22, [DECODE_FAILED], 'the transaction does not decode'],\n];\n\n/** Each rejected reason's own anchored pattern, with the code and the verdict text. */\nconst CLAIMS: readonly (readonly [number, string, RegExp, string])[] = REJECTED.flatMap(\n  ([code, names, text]) => names.map((name) => [code, name, reason(name), text] as const),\n);\n\n/** The rejected reason bitcoind's answer claims, or `undefined` when it claims none. */\nfunction claimedReason(error: NodeError, message: string) {\n  return CLAIMS.find(([code, , pattern]) => error.code === code && pattern.test(message));\n}\n\nconst FEE_TOO_LOW = reason(\n  'min relay fee not met',\n  'mempool min fee not met',\n  'insufficient fee',\n);\nconst SPENT = reason(\n  'bad-txns-inputs-missingorspent',\n  'Missing inputs',\n  'Inputs missing or spent',\n  'txn-mempool-conflict',\n  'bad-txns-spends-conflicting-tx',\n);\n\n/**\n * What bitcoind's answer claims, parsed: it decides nothing. A claimed consensus failure is\n * `invalid`, which is no `BroadcastResult`: only `classifyOwnBroadcast` turns it into a\n * `rejected` verdict, and only for bytes its reason holds for.\n */\nexport type NodeClaim =\n  | Extract<BroadcastResult, { readonly kind: 'already-known' | 'refused' }>\n  | { readonly kind: 'invalid'; readonly reason: string };\n\nexport function nodeClaim(error: NodeError): NodeClaim {\n  const message = error.message.trim();\n  if (ALREADY_KNOWN.test(message) || error.code === -27) return { kind: 'already-known' };\n  const claim = claimedReason(error, message);\n  if (claim) return { kind: 'invalid', reason: claim[3] };\n  if (FEE_TOO_LOW.test(message)) {\n    return { kind: 'refused', code: 'FEE_TOO_LOW', reason: 'fee too low for the node' };\n  }\n  if (SPENT.test(message)) {\n    return {\n      kind: 'refused',\n      code: 'TX_REFUSED',\n      reason: 'inputs missing or already spent',\n    };\n  }\n  return {\n    kind: 'refused',\n    code: 'TX_REFUSED',\n    reason: 'the node refused the transaction',\n  };\n}\n\n/**\n * A transaction's bytes as bitcoind's byte-only checks read them, decoded here\n * from the hex that was sent: its outpoints, its output values as signed 64-bit integers, and\n * its size without witness data.\n */\ninterface TxBytes {\n  readonly inputs: readonly { readonly txid: string; readonly vout: number }[];\n  readonly values: readonly bigint[];\n  readonly strippedSize: number;\n}\n\n/** Bitcoin Core's `MAX_MONEY` and `MAX_BLOCK_WEIGHT`. */\nconst MAX_MONEY = 2_100_000_000_000_000n;\nconst MAX_BLOCK_WEIGHT = 4_000_000;\nconst NULL_TXID = '0'.repeat(64);\n\nconst isNull = (input: TxBytes['inputs'][number]): boolean =>\n  input.txid === NULL_TXID && input.vout === 0xffffffff;\nconst isCoinbase = (tx: TxBytes): boolean =>\n  tx.inputs.length === 1 && isNull(tx.inputs[0] as TxBytes['inputs'][number]);\n\n/**\n * bitcoind's reasons the bytes alone decide (`CheckTransaction`, and ATMP's `coinbase`), each\n * as bitcoind tests it. The others (`bad-txns-in-belowout`, `-inputvalues-outofrange`,\n * `-fee-outofrange` and every script check) depend on the spent outputs, and have no rule: the\n * builder spends only outputs whose value and script their previous transaction authenticates\n * (every input, every wallet type, whatever `nonWitnessUtxo` says), and the core\n * verifies every signature, so they cannot hold for our own bytes, and a node that claims one\n * is not believed.\n */\nconst BYTE_RULES: Readonly<Record<string, (tx: TxBytes) => boolean>> = {\n  'bad-txns-vin-empty': (tx) => tx.inputs.length === 0,\n  'bad-txns-vout-empty': (tx) => tx.values.length === 0,\n  'bad-txns-oversize': (tx) => tx.strippedSize * 4 > MAX_BLOCK_WEIGHT,\n  'bad-txns-vout-negative': (tx) => tx.values.some((value) => value < 0n),\n  'bad-txns-vout-toolarge': (tx) => tx.values.some((value) => value > MAX_MONEY),\n  // bitcoind's loop: each output in order, stopping at the first that fails.\n  'bad-txns-txouttotal-toolarge': (tx) => {\n    let total = 0n;\n    for (const value of tx.values) {\n      if (value < 0n || value > MAX_MONEY) return false; // `vout-negative`, `-toolarge`\n      total += value;\n      if (total > MAX_MONEY) return true;\n    }\n    return false;\n  },\n  'bad-txns-inputs-duplicate': (tx) =>\n    new Set(tx.inputs.map((input) => `${input.txid}:${input.vout}`)).size <\n    tx.inputs.length,\n  'bad-txns-prevout-null': (tx) => !isCoinbase(tx) && tx.inputs.some(isNull),\n  coinbase: isCoinbase,\n};\n\n/** A rejection this driver cannot confirm for the bytes it sent: observed, never terminal. */\nconst UNCONFIRMED: BroadcastResult = {\n  kind: 'refused',\n  code: 'TX_REFUSED',\n  reason: 'the node claimed the transaction is invalid',\n};\n\n/**\n * The hex that was sent, decoded as `sendrawtransaction` decodes it (`rawtx.ts` follows\n * bitcoind's format, with no cap below the broadcaster's own), or `undefined` when bitcoind\n * cannot decode it either.\n */\nfunction bytesOf(sentHex: string): TxBytes | undefined {\n  const tx = readTxHex(sentHex, { maxStripped: MAX_TX_BYTES });\n  if (!tx) return undefined;\n  return {\n    inputs: tx.inputs.map((input) => ({ txid: input.txid, vout: input.vout })),\n    values: tx.outputs.map((output) => output.value),\n    strippedSize: tx.strippedSize,\n  };\n}\n\n/**\n * The node's answer to the hex this driver sent. A terminal `rejected` frees the\n * Attempt's inputs for a caller's retry, and if a lying or buggy endpoint relayed the bytes\n * before it claimed them invalid, the retry and the original can both confirm: a double\n * payment. So a rejection stands only when its claimed reason holds for those bytes, decoded\n * here (whether they decode is always this module's own finding): an undecodable\n * hex for `TX decode failed`, a byte rule for a `CheckTransaction` reason. Anything else is\n * `refused`.\n */\nexport function classifyOwnBroadcast(error: NodeError, sentHex: string): BroadcastResult {\n  const claim = nodeClaim(error);\n  if (claim.kind !== 'invalid') return claim;\n  const bytes = bytesOf(sentHex);\n  const rejected: BroadcastResult = { kind: 'rejected', reason: claim.reason };\n  const name = claimedReason(error, error.message.trim())?.[1];\n  if (name === DECODE_FAILED) return bytes === undefined ? rejected : UNCONFIRMED;\n  const rule =\n    name !== undefined && Object.hasOwn(BYTE_RULES, name) ? BYTE_RULES[name] : undefined;\n  return bytes !== undefined && rule?.(bytes) ? rejected : UNCONFIRMED;\n}\n"]}

package/dist/adapters/utxo/esplora.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The Esplora REST API, sent directly over the core transport. Every call carries the
+ * calling driver method's tags and a `route` template with no identifiers in it, which
+ * events and logs show instead of the path. Answers are validated strictly: a malformed
+ * one is a retryable `ProviderError('PROVIDER_UNAVAILABLE')`, a missing or ill-typed
+ * field is malformed and never a default, an answer for another id than the one asked for is
+ * refused, and a 404 is `null`. Chain data is read as the chain allows it, never bounded by
+ * what this library builds (lenient readers). Chain reads use the `rpc` transport; address
+ * reads use the `indexer`. Only raw transactions and blocks are decoded, by the strict
+ * linear readers (`rawtx.ts`, `rawblock.ts`), to bind them to their txid or block hash.
+ */
+import { ProviderError } from '../../core/errors/error';
+import type { Transport } from '../../core/transport/types';
+import { type PreviousTx } from './codec';
+import { type RawBlock } from './rawblock';
+import type { EsploraAddressStats, EsploraBlock, EsploraOutspend, EsploraStatus, EsploraTx, EsploraUtxo, UtxoCallTags } from './types';
+/**
+ * The previous transactions one client keeps, by count and by bytes without the
+ * witness (a larger one is not kept). A typical one is a few hundred bytes.
+ */
+export declare const PREVIOUS_TX_CACHE: Readonly<{
+    entries: 1000;
+    bytes: 8000000;
+}>;
+/** Bitcoin Core's `MAX_MONEY`: no output, and no balance, is larger. */
+export declare const MAX_MONEY = 2100000000000000n;
+export declare function malformed(what: string): ProviderError;
+/** A definitive 404 (not an ambiguous or retried failure): the resource is not there. */
+export declare function isNotFound(error: unknown): boolean;
+export declare function parseHeight(text: unknown): bigint;
+export declare function parseHash(text: unknown): string;
+export declare function parseStatus(value: unknown): EsploraStatus;
+export declare function parseTx(value: unknown): EsploraTx;
+export declare function parseOutspend(value: unknown): EsploraOutspend;
+/** Esplora's `/fee-estimates`: confirmation target (blocks) → sat/vB (a float). */
+export declare function parseFeeEstimates(value: unknown): ReadonlyMap<number, number>;
+/** Whether a caller's id is a txid or block hash (64 lowercase hex characters). */
+export declare const isHash: (value: unknown) => value is string;
+/** An output as a transaction's bytes hold it: its value, signed as bitcoind reads it. */
+export interface TxOutput {
+    readonly value: bigint;
+    readonly script: Uint8Array;
+}
+/** One Esplora endpoint family (the `rpc` transport) and its address index (`indexer`). */
+export declare class EsploraClient {
+    #private;
+    private readonly chain;
+    private readonly indexer;
+    private readonly cache;
+    constructor(chain: Transport, indexer: Transport, cache?: {
+        readonly entries: number;
+        readonly bytes: number;
+    });
+    tipHeight(tags: UtxoCallTags): Promise<bigint>;
+    /** The hash of the block at `height` on this endpoint's best chain, or `null` above its tip. */
+    blockHashAt(height: bigint, tags: UtxoCallTags): Promise<string | null>;
+    block(blockHash: string, tags: UtxoCallTags): Promise<EsploraBlock | null>;
+    /**
+     * `/block/:hash/raw`, the block's own bytes, read strictly once (`rawblock.ts`) and bound to
+     * `blockHash`: bytes that do not decode are malformed, and bytes whose header hashes to
+     * another block, or whose transactions are not the ones that header commits to, are a
+     * retryable `PROVIDER_INCONSISTENT`. So no endpoint can add, drop or alter a transaction of
+     * a block whose hash is right. A 404 (a backend that does not have the block) is `null`.
+     */
+    rawBlock(blockHash: string, tags: UtxoCallTags): Promise<RawBlock | null>;
+    blockTxids(blockHash: string, tags: UtxoCallTags): Promise<string[]>;
+    /** Up to 25 transactions of a block from `start` (a multiple of 25). */
+    blockTxs(blockHash: string, start: number, tags: UtxoCallTags): Promise<EsploraTx[]>;
+    tx(txid: string, tags: UtxoCallTags): Promise<EsploraTx | null>;
+    /** The raw transaction, as hex, bound to `txid` (see `#rawTx`). */
+    txHex(txid: string, tags: UtxoCallTags): Promise<string | null>;
+    /**
+     * An input's previous transaction, decoded once and bound to `txid` (see
+     * `#rawTx`). Its bytes authenticate themselves, so it is kept per txid, whatever endpoint
+     * served it, in a bounded cache: a replacement's inputs are read once per client.
+     */
+    previousTx(txid: string, tags: UtxoCallTags): Promise<PreviousTx | null>;
+    /**
+     * The outputs of transaction `txid`, from its bytes, bound to `txid` (see `#rawTx`), or
+     * `null` when the endpoint does not have it: what an input naming `txid:vout` spends. A
+     * previous transaction this client keeps answers without a read; one read here is not kept,
+     * since a block scan reads thousands, which would evict a build's.
+     */
+    outputsOf(txid: string, tags: UtxoCallTags): Promise<readonly TxOutput[] | null>;
+    /**
+     * A transaction this client sent for an Attempt and a node took. Its bytes are
+     * known here, so its outputs are not an indexer's word even before a block holds it, and
+     * under `minInputConfirmations: 0` they may be spent unconfirmed. Kept like the cache.
+     */
+    rememberOwn(tx: PreviousTx): void;
+    isOwn(txid: string): boolean;
+    outspend(txid: string, vout: number, tags: UtxoCallTags): Promise<EsploraOutspend>;
+    feeEstimates(tags: UtxoCallTags): Promise<ReadonlyMap<number, number>>;
+    /** `POST /tx`: the node's txid on success; a node refusal is the transport's `RPC_ERROR`. */
+    broadcast(hex: string, tags: UtxoCallTags): Promise<string>;
+    addressUtxos(address: string, tags: UtxoCallTags): Promise<EsploraUtxo[]>;
+    addressStats(address: string, tags: UtxoCallTags): Promise<EsploraAddressStats>;
+    /** Confirmed history, newest first, 25 per page, after `lastSeen` when given. */
+    addressTxs(address: string, lastSeen: string | undefined, tags: UtxoCallTags): Promise<EsploraTx[]>;
+}