crypto-aio 0.0.3 → 0.1.0

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,79 @@
+/**
+ * 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 transaction hex is decoded, by the strict linear
+ * reader (`rawtx.ts`), to bind it to its txid.
+ */
+import { ProviderError } from '../../core/errors/error';
+import type { Transport } from '../../core/transport/types';
+import { type PreviousTx } from './codec';
+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;
+/** 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>;
+    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>;
+    /**
+     * 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[]>;
+}