@secondlayer/stacks 6.2.2 → 6.3.0

package/dist/shared/{stacks-esm-nt5hf8ht.js → stacks-esm-z0rq3ejt.js}

@@ -73,6 +73,14 @@ function rootFromProof2(leafInternal, proof) {
 }
 
 // src/bitcoin/proof.ts
+class BitcoinSourceError2 extends Error {
+  code;
+  name = "BitcoinSourceError";
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
 function normalizeTxid(txid) {
   return without0x2(txid).toLowerCase();
 }
@@ -149,22 +157,32 @@ function bitcoinRpcSource2(config) {
       const basic = typeof config.auth === "string" ? config.auth : btoa(`${config.auth.username}:${config.auth.password}`);
       headers.authorization = `Basic ${basic}`;
     }
-    const res = await doFetch(config.url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        jsonrpc: "1.0",
-        id: "secondlayer",
-        method,
-        params: rpcParams
-      })
-    });
-    if (!res.ok) {
-      throw new Error(`bitcoin rpc ${method} failed: HTTP ${res.status}`);
+    let res;
+    try {
+      res = await doFetch(config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "1.0",
+          id: "secondlayer",
+          method,
+          params: rpcParams
+        })
+      });
+    } catch (error) {
+      throw new BitcoinSourceError2("unavailable", `bitcoin rpc ${method} failed: ${error instanceof Error ? error.message : "network error"}`);
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new BitcoinSourceError2("unavailable", `bitcoin rpc ${method} failed: HTTP ${res.status}`);
     }
-    const json = await res.json();
     if (json.error) {
-      throw new Error(`bitcoin rpc ${method} error: ${json.error.message}`);
+      throw new BitcoinSourceError2(json.error.code === -5 ? "not-found" : "unavailable", `bitcoin rpc ${method} error: ${json.error.message}`);
+    }
+    if (!res.ok) {
+      throw new BitcoinSourceError2("unavailable", `bitcoin rpc ${method} failed: HTTP ${res.status}`);
     }
     return json.result;
   }
@@ -178,7 +196,7 @@ function bitcoinRpcSource2(config) {
         true
       ]);
       if (!tx.blockhash) {
-        throw new Error(`tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`);
+        throw new BitcoinSourceError2("unconfirmed", `tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`);
       }
       const block = await rpc("getblock", [
         tx.blockhash,
@@ -199,9 +217,14 @@ function esploraSource2(config) {
   const doFetch = config.fetch ?? fetch;
   const base = config.url.replace(/\/+$/, "");
   async function get(path) {
-    const res = await doFetch(`${base}${path}`);
+    let res;
+    try {
+      res = await doFetch(`${base}${path}`);
+    } catch (error) {
+      throw new BitcoinSourceError2("unavailable", `esplora GET ${path} failed: ${error instanceof Error ? error.message : "network error"}`);
+    }
     if (!res.ok) {
-      throw new Error(`esplora GET ${path} failed: HTTP ${res.status}`);
+      throw new BitcoinSourceError2(res.status === 404 ? "not-found" : "unavailable", `esplora GET ${path} failed: HTTP ${res.status}`);
     }
     return res;
   }
@@ -212,7 +235,7 @@ function esploraSource2(config) {
     async getBlockForTx(txid) {
       const status = await (await get(`/tx/${txid}`)).json();
       if (!status.status.confirmed) {
-        throw new Error(`tx ${txid} is unconfirmed`);
+        throw new BitcoinSourceError2("unconfirmed", `tx ${txid} is unconfirmed`);
       }
       const blockHashHex = status.status.block_hash;
       const header = (await (await get(`/block/${blockHashHex}/header`)).text()).trim();
@@ -231,7 +254,7 @@ function esploraSource2(config) {
 // src/epochs.ts
 var EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET2 = 960230;
 
-export { merkleRoot2, buildMerkleProof2, rootFromProof2, buildTxProof2, fallbackProofSource2, bitcoinRpcSource2, esploraSource2, EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET2 };
+export { merkleRoot2, buildMerkleProof2, rootFromProof2, BitcoinSourceError2, buildTxProof2, fallbackProofSource2, bitcoinRpcSource2, esploraSource2, EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET2 };
 
-//# debugId=058A5CB7C5A2CAEE64756E2164756E21
-//# sourceMappingURL=stacks-esm-nt5hf8ht.js.map
+//# debugId=4CD23767D82ECDDE64756E2164756E21
+//# sourceMappingURL=stacks-esm-z0rq3ejt.js.map

package/dist/shared/stacks-esm-z0rq3ejt.js.map

@@ -0,0 +1,12 @@
+{
+  "version": 3,
+  "sources": ["../src/bitcoin/merkle.ts", "../src/bitcoin/proof.ts", "../src/epochs.ts"],
+  "sourcesContent": [
+    "import { concatBytes } from \"../utils/encoding.ts\";\nimport { doubleSha256 } from \"./serialize.ts\";\n\n/**\n * A Bitcoin merkle inclusion proof, shaped for the SIP-044 `verify-merkle-proof`\n * built-in: `(leaf-hash, root-hash, tx-index, tx-count, sibling-hashes)`.\n *\n * - `siblings` are the sibling node hashes from the leaf up to (excluding) the\n *   root, in *internal* byte order — never reversed.\n * - `txCount` (not tree-depth) pins the canonical tree shape; the built-in\n *   rejects any proof whose length differs from `ceil(log2(tx-count))`.\n */\nexport interface MerkleProof {\n\tsiblings: Uint8Array[];\n\ttxIndex: number;\n\ttxCount: number;\n}\n\n/** Combine an ordered pair of nodes into their parent hash. */\nfunction hashPair(left: Uint8Array, right: Uint8Array): Uint8Array {\n\treturn doubleSha256(concatBytes(left, right));\n}\n\n/** Collapse one merkle level into the next, duplicating the last node if odd. */\nfunction nextLevel(level: Uint8Array[]): Uint8Array[] {\n\tconst next: Uint8Array[] = [];\n\tfor (let i = 0; i < level.length; i += 2) {\n\t\tconst left = level[i];\n\t\tif (left === undefined) throw new Error(\"merkle: missing left node\");\n\t\t// Bitcoin duplicates the final node when a level has an odd count.\n\t\tconst right = level[i + 1] ?? left;\n\t\tnext.push(hashPair(left, right));\n\t}\n\treturn next;\n}\n\n/**\n * Compute the merkle root over txids in *internal* byte order. The result is\n * also internal order — it matches the `merkle-root` field read straight out of\n * an 80-byte block header, so it can be cross-checked against the header before\n * a proof is trusted.\n */\nexport function merkleRoot(txidsInternal: Uint8Array[]): Uint8Array {\n\tif (txidsInternal.length === 0) {\n\t\tthrow new Error(\"merkleRoot: empty tx list\");\n\t}\n\tlet level = txidsInternal.slice();\n\twhile (level.length > 1) {\n\t\tlevel = nextLevel(level);\n\t}\n\tconst root = level[0];\n\tif (root === undefined) throw new Error(\"merkleRoot: no root\");\n\treturn root;\n}\n\n/**\n * Build the merkle inclusion proof for the tx at `txIndex`. Sibling count is\n * exactly `ceil(log2(txCount))`, as the SIP-044 built-in requires.\n */\nexport function buildMerkleProof(\n\ttxidsInternal: Uint8Array[],\n\ttxIndex: number,\n): MerkleProof {\n\tconst txCount = txidsInternal.length;\n\tif (txCount === 0) {\n\t\tthrow new Error(\"buildMerkleProof: empty tx list\");\n\t}\n\tif (txIndex < 0 || txIndex >= txCount) {\n\t\tthrow new Error(\n\t\t\t`buildMerkleProof: txIndex ${txIndex} out of range for ${txCount} txs`,\n\t\t);\n\t}\n\n\tconst siblings: Uint8Array[] = [];\n\tlet index = txIndex;\n\tlet level = txidsInternal.slice();\n\twhile (level.length > 1) {\n\t\tconst isRight = index % 2 === 1;\n\t\tconst siblingIndex = isRight ? index - 1 : index + 1;\n\t\tconst self = level[index];\n\t\tif (self === undefined) throw new Error(\"buildMerkleProof: missing node\");\n\t\t// When the node is the last of an odd level, it is paired with itself.\n\t\tsiblings.push(level[siblingIndex] ?? self);\n\t\tlevel = nextLevel(level);\n\t\tindex = Math.floor(index / 2);\n\t}\n\n\treturn { siblings, txIndex, txCount };\n}\n\n/**\n * Recompute the merkle root from a leaf + its proof — the same fold the on-chain\n * `verify-merkle-proof` performs. Use it off-chain to self-check a constructed\n * proof against the header's merkle root before submitting a contract call.\n */\nexport function rootFromProof(\n\tleafInternal: Uint8Array,\n\tproof: MerkleProof,\n): Uint8Array {\n\tlet hash = leafInternal;\n\tlet index = proof.txIndex;\n\tfor (const sibling of proof.siblings) {\n\t\thash = index % 2 === 1 ? hashPair(sibling, hash) : hashPair(hash, sibling);\n\t\tindex = Math.floor(index / 2);\n\t}\n\treturn hash;\n}\n",
+    "import { bytesToHex, hexToBytes, without0x } from \"../utils/encoding.ts\";\nimport { type MerkleProof, buildMerkleProof, rootFromProof } from \"./merkle.ts\";\nimport { parseBitcoinTx, parseBlockHeader, reverseBytes } from \"./serialize.ts\";\n\n/**\n * A self-contained Bitcoin SPV proof: everything the SIP-044 built-ins need to\n * prove a tx (and one of its outputs) is committed in a confirmed block. Hashes\n * are internal byte order throughout.\n */\nexport interface SpvProof {\n\trawTx: Uint8Array;\n\t/** The tx's txid, internal order — the merkle leaf. */\n\ttxidInternal: Uint8Array;\n\t/** Output index of interest, if the proof targets a specific output. */\n\tvout?: number;\n\tmerkle: MerkleProof;\n\t/** The 80-byte block header that commits the tx. */\n\theader: Uint8Array;\n\t/** Bitcoin block height. */\n\theight: number;\n}\n\n/** The block context a `ProofSource` resolves for a confirmed tx. */\nexport interface BlockForTx {\n\t/** 80-byte block header. */\n\theader: Uint8Array;\n\theight: number;\n\t/** All of the block's txids, internal order, in block order. */\n\ttxidsInternal: Uint8Array[];\n\t/** Index of the target tx within the block. */\n\ttxIndex: number;\n}\n\n/**\n * Where proof inputs come from. The default is the integrator's own Bitcoin node\n * (`bitcoinRpcSource`) — trustless; a hosted Esplora-compatible endpoint\n * (`esploraSource`) is the fallback. `buildTxProof` independently re-checks\n * whatever a source returns, so a wrong or hostile source fails loudly rather\n * than producing a bad proof.\n */\nexport interface ProofSource {\n\t/** Raw (serialized) tx bytes for a txid (display-order hex). */\n\tgetRawTx(txid: string): Promise<Uint8Array>;\n\t/** The confirming block's header, height, and txid set for a txid. */\n\tgetBlockForTx(txid: string): Promise<BlockForTx>;\n}\n\n/** Why a source could not produce a proof input. */\nexport type BitcoinSourceErrorCode =\n\t| \"not-found\"\n\t| \"unconfirmed\"\n\t| \"unavailable\";\n\n/**\n * Thrown by `bitcoinRpcSource` / `esploraSource` when the source itself cannot\n * answer: the tx is unknown, not yet in a block, or the source is unreachable.\n * Inconsistent data from a source is a plain `Error` (the source lied).\n */\nexport class BitcoinSourceError extends Error {\n\toverride readonly name = \"BitcoinSourceError\";\n\tconstructor(\n\t\treadonly code: BitcoinSourceErrorCode,\n\t\tmessage: string,\n\t) {\n\t\tsuper(message);\n\t}\n}\n\nfunction normalizeTxid(txid: string): string {\n\treturn without0x(txid).toLowerCase();\n}\n\n/**\n * Locate `txid` in a block's txid set and assemble its `BlockForTx`. Owns the\n * display→internal byte-order reversal (`reverseBytes`) so the ProofSources\n * can't drift on the one operation a silent merkle-root mismatch would hide.\n * `txidsDisplay` are display-order hex txids as returned by Core / Esplora.\n */\nfunction assembleBlockForTx(args: {\n\ttxid: string;\n\tblockId: string;\n\theaderHex: string;\n\theight: number;\n\ttxidsDisplay: string[];\n}): BlockForTx {\n\tconst txIndex = args.txidsDisplay.indexOf(normalizeTxid(args.txid));\n\tif (txIndex < 0) {\n\t\tthrow new Error(`tx ${args.txid} not found in block ${args.blockId}`);\n\t}\n\treturn {\n\t\theader: hexToBytes(args.headerHex),\n\t\theight: args.height,\n\t\ttxidsInternal: args.txidsDisplay.map((t) => reverseBytes(hexToBytes(t))),\n\t\ttxIndex,\n\t};\n}\n\n/**\n * Assemble an `SpvProof` for a txid from a `ProofSource`, validating every claim\n * the source makes:\n *  - the returned raw tx actually hashes to the requested txid,\n *  - the claimed `txIndex` points at that txid in the block, and\n *  - the resulting merkle proof folds back to the block header's merkle root.\n * Any mismatch throws — the proof is never returned half-trusted.\n */\nexport async function buildTxProof(\n\tsource: ProofSource,\n\tparams: { txid: string; vout?: number },\n): Promise<SpvProof> {\n\tconst { txid, vout } = params;\n\tconst want = normalizeTxid(txid);\n\n\tconst [rawTx, block] = await Promise.all([\n\t\tsource.getRawTx(txid),\n\t\tsource.getBlockForTx(txid),\n\t]);\n\n\tconst parsed = parseBitcoinTx(rawTx);\n\tconst gotDisplay = bytesToHex(reverseBytes(parsed.txidInternal));\n\tif (gotDisplay !== want) {\n\t\tthrow new Error(\n\t\t\t`source returned a tx whose id ${gotDisplay} does not match requested ${want}`,\n\t\t);\n\t}\n\n\tconst atIndex = block.txidsInternal[block.txIndex];\n\tif (!atIndex || bytesToHex(atIndex) !== bytesToHex(parsed.txidInternal)) {\n\t\tthrow new Error(\n\t\t\t`source txIndex ${block.txIndex} does not point at tx ${want}`,\n\t\t);\n\t}\n\n\tconst merkle = buildMerkleProof(block.txidsInternal, block.txIndex);\n\n\tconst headerRoot = parseBlockHeader(block.header).merkleRoot;\n\tconst computed = rootFromProof(parsed.txidInternal, merkle);\n\tif (bytesToHex(computed) !== bytesToHex(headerRoot)) {\n\t\tthrow new Error(\n\t\t\t\"constructed merkle proof does not reconcile with the block header merkle root\",\n\t\t);\n\t}\n\n\treturn {\n\t\trawTx,\n\t\ttxidInternal: parsed.txidInternal,\n\t\tvout,\n\t\tmerkle,\n\t\theader: block.header,\n\t\theight: block.height,\n\t};\n}\n\n/**\n * Compose sources into an ordered fallback chain: each call tries them in turn\n * and returns the first success, throwing the last error if all fail. Put the\n * trustless integrator node first and a hosted endpoint last.\n */\nexport function fallbackProofSource(sources: ProofSource[]): ProofSource {\n\tif (sources.length === 0) {\n\t\tthrow new Error(\"fallbackProofSource: at least one source is required\");\n\t}\n\tasync function firstSuccess<T>(\n\t\tfn: (s: ProofSource) => Promise<T>,\n\t): Promise<T> {\n\t\tlet lastError: unknown;\n\t\tfor (const source of sources) {\n\t\t\ttry {\n\t\t\t\treturn await fn(source);\n\t\t\t} catch (error) {\n\t\t\t\tlastError = error;\n\t\t\t}\n\t\t}\n\t\tthrow lastError;\n\t}\n\treturn {\n\t\tgetRawTx: (txid) => firstSuccess((s) => s.getRawTx(txid)),\n\t\tgetBlockForTx: (txid) => firstSuccess((s) => s.getBlockForTx(txid)),\n\t};\n}\n\nexport interface BitcoinRpcConfig {\n\t/** Bitcoin Core JSON-RPC endpoint URL. */\n\turl: string;\n\t/** Basic auth — `{ username, password }` or a pre-encoded base64 string. */\n\tauth?: { username: string; password: string } | string;\n\t/** Override the fetch implementation (testing / custom agents). */\n\tfetch?: typeof fetch;\n}\n\n/**\n * A `ProofSource` backed by the integrator's own Bitcoin Core node over\n * JSON-RPC. This is the trustless default. The node must run with `-txindex`\n * (or the tx must be in the mempool's block view) so `getrawtransaction` can\n * resolve the confirming block.\n */\nexport function bitcoinRpcSource(config: BitcoinRpcConfig): ProofSource {\n\tconst doFetch = config.fetch ?? fetch;\n\n\tasync function rpc<T>(method: string, rpcParams: unknown[]): Promise<T> {\n\t\tconst headers: Record<string, string> = {\n\t\t\t\"content-type\": \"application/json\",\n\t\t};\n\t\tif (config.auth) {\n\t\t\tconst basic =\n\t\t\t\ttypeof config.auth === \"string\"\n\t\t\t\t\t? config.auth\n\t\t\t\t\t: btoa(`${config.auth.username}:${config.auth.password}`);\n\t\t\theaders.authorization = `Basic ${basic}`;\n\t\t}\n\t\tlet res: Response;\n\t\ttry {\n\t\t\tres = await doFetch(config.url, {\n\t\t\t\tmethod: \"POST\",\n\t\t\t\theaders,\n\t\t\t\tbody: JSON.stringify({\n\t\t\t\t\tjsonrpc: \"1.0\",\n\t\t\t\t\tid: \"secondlayer\",\n\t\t\t\t\tmethod,\n\t\t\t\t\tparams: rpcParams,\n\t\t\t\t}),\n\t\t\t});\n\t\t} catch (error) {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\"unavailable\",\n\t\t\t\t`bitcoin rpc ${method} failed: ${error instanceof Error ? error.message : \"network error\"}`,\n\t\t\t);\n\t\t}\n\t\t// Core answers RPC errors with HTTP 500 and the error in the JSON body.\n\t\tlet json: { result: T; error: { code?: number; message: string } | null };\n\t\ttry {\n\t\t\tjson = (await res.json()) as typeof json;\n\t\t} catch {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\"unavailable\",\n\t\t\t\t`bitcoin rpc ${method} failed: HTTP ${res.status}`,\n\t\t\t);\n\t\t}\n\t\tif (json.error) {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\tjson.error.code === -5 ? \"not-found\" : \"unavailable\",\n\t\t\t\t`bitcoin rpc ${method} error: ${json.error.message}`,\n\t\t\t);\n\t\t}\n\t\tif (!res.ok) {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\"unavailable\",\n\t\t\t\t`bitcoin rpc ${method} failed: HTTP ${res.status}`,\n\t\t\t);\n\t\t}\n\t\treturn json.result;\n\t}\n\n\treturn {\n\t\tasync getRawTx(txid) {\n\t\t\treturn hexToBytes(await rpc<string>(\"getrawtransaction\", [txid, false]));\n\t\t},\n\t\tasync getBlockForTx(txid) {\n\t\t\tconst tx = await rpc<{ blockhash?: string }>(\"getrawtransaction\", [\n\t\t\t\ttxid,\n\t\t\t\ttrue,\n\t\t\t]);\n\t\t\tif (!tx.blockhash) {\n\t\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\t\"unconfirmed\",\n\t\t\t\t\t`tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst block = await rpc<{ tx: string[]; height: number }>(\"getblock\", [\n\t\t\t\ttx.blockhash,\n\t\t\t\t1,\n\t\t\t]);\n\t\t\tconst header = await rpc<string>(\"getblockheader\", [tx.blockhash, false]);\n\t\t\treturn assembleBlockForTx({\n\t\t\t\ttxid,\n\t\t\t\tblockId: tx.blockhash,\n\t\t\t\theaderHex: header,\n\t\t\t\theight: block.height,\n\t\t\t\ttxidsDisplay: block.tx,\n\t\t\t});\n\t\t},\n\t};\n}\n\nexport interface EsploraConfig {\n\t/** Esplora REST base URL, e.g. `https://blockstream.info/api` or a self-hosted instance. */\n\turl: string;\n\t/** Override the fetch implementation. */\n\tfetch?: typeof fetch;\n}\n\n/**\n * A `ProofSource` backed by an Esplora REST API (self-hosted, or a hosted\n * provider as a fallback). Provider-agnostic: any Esplora-compatible endpoint\n * works. Use as the hosted fallback behind `bitcoinRpcSource`.\n */\nexport function esploraSource(config: EsploraConfig): ProofSource {\n\tconst doFetch = config.fetch ?? fetch;\n\tconst base = config.url.replace(/\\/+$/, \"\");\n\n\tasync function get(path: string): Promise<Response> {\n\t\tlet res: Response;\n\t\ttry {\n\t\t\tres = await doFetch(`${base}${path}`);\n\t\t} catch (error) {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\"unavailable\",\n\t\t\t\t`esplora GET ${path} failed: ${error instanceof Error ? error.message : \"network error\"}`,\n\t\t\t);\n\t\t}\n\t\tif (!res.ok) {\n\t\t\tthrow new BitcoinSourceError(\n\t\t\t\tres.status === 404 ? \"not-found\" : \"unavailable\",\n\t\t\t\t`esplora GET ${path} failed: HTTP ${res.status}`,\n\t\t\t);\n\t\t}\n\t\treturn res;\n\t}\n\n\treturn {\n\t\tasync getRawTx(txid) {\n\t\t\treturn hexToBytes((await (await get(`/tx/${txid}/hex`)).text()).trim());\n\t\t},\n\t\tasync getBlockForTx(txid) {\n\t\t\tconst status = (await (await get(`/tx/${txid}`)).json()) as {\n\t\t\t\tstatus: {\n\t\t\t\t\tconfirmed: boolean;\n\t\t\t\t\tblock_height: number;\n\t\t\t\t\tblock_hash: string;\n\t\t\t\t};\n\t\t\t};\n\t\t\tif (!status.status.confirmed) {\n\t\t\t\tthrow new BitcoinSourceError(\n\t\t\t\t\t\"unconfirmed\",\n\t\t\t\t\t`tx ${txid} is unconfirmed`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst blockHashHex = status.status.block_hash;\n\t\t\tconst header = (\n\t\t\t\tawait (await get(`/block/${blockHashHex}/header`)).text()\n\t\t\t).trim();\n\t\t\tconst txids = (await (\n\t\t\t\tawait get(`/block/${blockHashHex}/txids`)\n\t\t\t).json()) as string[];\n\t\t\treturn assembleBlockForTx({\n\t\t\t\ttxid,\n\t\t\t\tblockId: blockHashHex,\n\t\t\t\theaderHex: header,\n\t\t\t\theight: status.status.block_height,\n\t\t\t\ttxidsDisplay: txids,\n\t\t\t});\n\t\t},\n\t};\n}\n",
+    "/**\n * Stacks hard-fork epoch activation heights, as Bitcoin burn block heights.\n *\n * Epoch 4.0 carries both SIP-044 (the native Bitcoin SPV built-ins / Clarity 6)\n * and SIP-045 (`pox-5` Bitcoin Staking) — one fork, one height. Keep it here so\n * the two modules can never disagree.\n */\n\n/**\n * Epoch 4.0 activation height on mainnet — Bitcoin block 960,230 (~2026-07-30\n * AM UTC, per the stacks-core 4.0.1 release notes).\n *\n * Only mainnet has a fixed height. On other networks, read it from the node\n * (`getPox5Activation` for pox-5) or pass it explicitly.\n */\nexport const EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET = 960_230;\n"
+  ],
+  "mappings": "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",
+  "debugId": "4CD23767D82ECDDE64756E2164756E21",
+  "names": []
+}

package/dist/src/bitcoin/index.cjs

@@ -66,6 +66,7 @@ var __export = (target, all) => {
 // src/bitcoin/index.ts
 var exports_bitcoin = {};
 __export(exports_bitcoin, {
+  BitcoinSourceError: () => BitcoinSourceError,
   BtcReader: () => BtcReader,
   EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET: () => EPOCH_4_ACTIVATION_BURN_HEIGHT_MAINNET,
   SPV_ADAPTER_ABI: () => SPV_ADAPTER_ABI,
@@ -452,6 +453,14 @@ function rootFromProof(leafInternal, proof) {
 }
 
 // src/bitcoin/proof.ts
+class BitcoinSourceError extends Error {
+  code;
+  name = "BitcoinSourceError";
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
 function normalizeTxid(txid) {
   return without0x(txid).toLowerCase();
 }
@@ -528,22 +537,32 @@ function bitcoinRpcSource(config) {
       const basic = typeof config.auth === "string" ? config.auth : btoa(`${config.auth.username}:${config.auth.password}`);
       headers.authorization = `Basic ${basic}`;
     }
-    const res = await doFetch(config.url, {
-      method: "POST",
-      headers,
-      body: JSON.stringify({
-        jsonrpc: "1.0",
-        id: "secondlayer",
-        method,
-        params: rpcParams
-      })
-    });
-    if (!res.ok) {
-      throw new Error(`bitcoin rpc ${method} failed: HTTP ${res.status}`);
+    let res;
+    try {
+      res = await doFetch(config.url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          jsonrpc: "1.0",
+          id: "secondlayer",
+          method,
+          params: rpcParams
+        })
+      });
+    } catch (error) {
+      throw new BitcoinSourceError("unavailable", `bitcoin rpc ${method} failed: ${error instanceof Error ? error.message : "network error"}`);
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new BitcoinSourceError("unavailable", `bitcoin rpc ${method} failed: HTTP ${res.status}`);
     }
-    const json = await res.json();
     if (json.error) {
-      throw new Error(`bitcoin rpc ${method} error: ${json.error.message}`);
+      throw new BitcoinSourceError(json.error.code === -5 ? "not-found" : "unavailable", `bitcoin rpc ${method} error: ${json.error.message}`);
+    }
+    if (!res.ok) {
+      throw new BitcoinSourceError("unavailable", `bitcoin rpc ${method} failed: HTTP ${res.status}`);
     }
     return json.result;
   }
@@ -557,7 +576,7 @@ function bitcoinRpcSource(config) {
         true
       ]);
       if (!tx.blockhash) {
-        throw new Error(`tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`);
+        throw new BitcoinSourceError("unconfirmed", `tx ${txid} is not in a block (node needs -txindex, or the tx is unconfirmed)`);
       }
       const block = await rpc("getblock", [
         tx.blockhash,
@@ -578,9 +597,14 @@ function esploraSource(config) {
   const doFetch = config.fetch ?? fetch;
   const base = config.url.replace(/\/+$/, "");
   async function get(path) {
-    const res = await doFetch(`${base}${path}`);
+    let res;
+    try {
+      res = await doFetch(`${base}${path}`);
+    } catch (error) {
+      throw new BitcoinSourceError("unavailable", `esplora GET ${path} failed: ${error instanceof Error ? error.message : "network error"}`);
+    }
     if (!res.ok) {
-      throw new Error(`esplora GET ${path} failed: HTTP ${res.status}`);
+      throw new BitcoinSourceError(res.status === 404 ? "not-found" : "unavailable", `esplora GET ${path} failed: HTTP ${res.status}`);
     }
     return res;
   }
@@ -591,7 +615,7 @@ function esploraSource(config) {
     async getBlockForTx(txid) {
       const status = await (await get(`/tx/${txid}`)).json();
       if (!status.status.confirmed) {
-        throw new Error(`tx ${txid} is unconfirmed`);
+        throw new BitcoinSourceError("unconfirmed", `tx ${txid} is unconfirmed`);
       }
       const blockHashHex = status.status.block_hash;
       const header = (await (await get(`/block/${blockHashHex}/header`)).text()).trim();
@@ -2798,5 +2822,5 @@ async function verifyBitcoinPayment(client, params) {
   return { verified, mined, output, proof };
 }
 
-//# debugId=A75A612053B8AE0464756E2164756E21
+//# debugId=0A88BBD4FA62DB1264756E2164756E21
 //# sourceMappingURL=index.cjs.map