@secondlayer/verify 0.5.3 → 0.6.0

package/README.md

@@ -61,6 +61,22 @@ const keyed = new SecondlayerProofSource({ apiKey: process.env.SECONDLAYER_API_K
 await verifyBlock(9_137_005, { source: keyed, rows: true });
 ```
 
+## Bitcoin transactions
+
+`verifyBitcoinTx` proves a Bitcoin transaction is in the checkpoint's Bitcoin chain, and optionally that one output pays an address and amount. No contract call.
+
+```ts
+import { BlockVerifier, SecondlayerProofSource } from "@secondlayer/verify";
+
+const verifier = new BlockVerifier({ source: new SecondlayerProofSource() });
+const result = await verifier.verifyBitcoinTx(txid, {
+  expect: { address: "bc1q9fkjx3s9ufz90k4jzgmdkzlyt22h0tp3x92ua9", amount: 398_000n },
+});
+// result.ok, result.height, result.matched (the output index)
+```
+
+To read from your own Bitcoin node (`txindex=1`), spread `getBitcoinTxProof: (txid) => buildTxProof(bitcoinRpcSource({ url, auth }), { txid })` over the source, with both imported from `@secondlayer/stacks/bitcoin`. Any Esplora endpoint works too: the verifier re-checks every byte.
+
 ## What it proves
 
 | Proven | How |

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+/** A byte string, held as a Uint8Array. */
 type Bytes = Uint8Array;
 /** Encodes bytes as a lowercase hex string. */
 declare const hex: (b: Bytes) => string;
 /** Hex to bytes; tolerates a 0x prefix. */
 declare const unhex: (s: string) => Bytes;
+/** A Nakamoto-era Stacks block header. */
 interface NakamotoHeader {
 	/** Low 7 bits = header version; high bit = shadow block. */
 	version: number;
@@ -56,6 +58,7 @@ interface Epoch2Header {
 	blockHash: Bytes;
 	consensusHash: Bytes;
 }
+/** A Stacks block header from either era. */
 type StacksHeader = NakamotoHeader | Epoch2Header;
 /**
 * Parses the epoch 2.x block header at the start of `raw`.
@@ -86,6 +89,7 @@ declare function marfValue(value: string): Bytes;
 * header hashes to the id the trie committed. Malformed proofs yield no ids.
 */
 declare function marfProofAncestors(proof: Bytes): string[];
+/** A MARF proof with the leaf path and value it covers. */
 interface MarfProofInput {
 	/** Consensus-serialized TrieMerkleProof (`/v2/clarity/marf/<path>?proof=1`). */
 	proof: Bytes;
@@ -117,6 +121,7 @@ interface WitnessLeaf {
 	/** 32-byte value hash (first 32 bytes of the MARFValue; the tail is zero). */
 	valueHash: Bytes;
 }
+/** A recomputed trie root, its ancestor roots, and leaves. */
 interface StateWitness {
 	/** Recomputed trie root; compare to the authenticated header's state_index_root. */
 	root: Bytes;
@@ -130,6 +135,7 @@ interface StateWitness {
 * The result proves nothing until `root` equals a header's state_index_root.
 */
 declare function parseWitness(bytes: Bytes): StateWitness;
+/** The witness leaves, claimed writes, and bookkeeping keys to classify. */
 interface BlockDiffInput {
 	/** `parseWitness(bytes).leaves`, from a witness whose root was checked. */
 	leaves: WitnessLeaf[];
@@ -143,6 +149,7 @@ interface BlockDiffInput {
 interface ClassifiedLeaf extends WitnessLeaf {
 	key: string;
 }
+/** A block's witnessed leaves, split into writes, carried, and internal. */
 interface BlockDiff {
 	/** Leaves matching a claimed write (path and value). */
 	writes: ClassifiedLeaf[];
@@ -174,6 +181,7 @@ type SignerSet = Map<string, bigint>;
 * `(some (list (tuple (signer principal) (weight uint) ...)))`.
 */
 declare function decodeSignerSet(value: string | Bytes): SignerSet;
+/** Whether the signed weight meets the threshold with known signers. */
 interface SignerCheck {
 	/** Signed weight meets the threshold, and every signature is a distinct known signer. */
 	valid: boolean;
@@ -238,6 +246,7 @@ interface BlockHeader {
 	bits: number;
 	nonce: number;
 }
+/** A Bitcoin header rule a chain check can fail on. */
 type HeaderRule = "checkpoint" | "format" | "prev-link" | "bits" | "retarget" | "median-time-past" | "version" | "proof-of-work";
 /**
 * Thrown when a Bitcoin header fails a validation rule.
@@ -250,6 +259,7 @@ declare class HeaderValidationError extends Error {
 	readonly name = "HeaderValidationError";
 	constructor(height: number, rule: HeaderRule, detail: string);
 }
+/** A trusted Bitcoin header that anchors header validation. */
 interface Checkpoint {
 	height: number;
 	/** Raw 80-byte header, bytes or hex. Trusted without validation. */
@@ -261,6 +271,7 @@ interface Checkpoint {
 	*/
 	periodStartTime?: number;
 }
+/** A Bitcoin header with its height, hash, and raw bytes. */
 interface ChainEntry {
 	height: number;
 	/** Display-order hex. */
@@ -307,6 +318,7 @@ declare class HeaderChain {
 * (burn height 967,680 or later); earlier ones by hash chain from 9,055,251.
 */
 declare const MAINNET_CHECKPOINT: VerifyCheckpoint;
+/** A trusted Stacks header and signer set to start verification from. */
 interface VerifyCheckpoint {
 	stacks: {
 		/** Raw Nakamoto header (hex) of a trusted block whose state holds `signerSet`. */
@@ -319,6 +331,7 @@ interface VerifyCheckpoint {
 	/** Retarget-boundary Bitcoin header at or below the first burn block of `stacks.cycle`. */
 	bitcoin: Checkpoint;
 }
+import { SpvProof } from "@secondlayer/stacks/bitcoin";
 /** Sortition preimage behind a consensus hash. */
 interface BurnPreimage {
 	preimage: Bytes;
@@ -355,7 +368,7 @@ interface VmEventRow {
 	raw_key?: string | null;
 	raw_value?: string | null;
 }
-/** An epoch 2.x header and the consensus hash its index block hash commits to. */
+/** An epoch 2.x header and the consensus hash it commits to. */
 interface Epoch2HeaderResponse {
 	/** Consensus-serialized StacksBlockHeader. */
 	header: Bytes;
@@ -388,6 +401,11 @@ interface ProofSource {
 	getStateWrites?(height: number): Promise<StateWrite[] | null>;
 	/** Indexed vm_events write rows of the block, checked against its proven diff. */
 	getVmEvents?(height: number): Promise<VmEventRow[]>;
+	/**
+	* A Bitcoin tx, its merkle branch and block header, by display-order txid.
+	* Untrusted: `verifyBitcoinTx` re-checks every byte.
+	*/
+	getBitcoinTxProof?(txid: string): Promise<SpvProof>;
 }
 /**
 * Thrown when a proof source request fails.
@@ -404,6 +422,7 @@ declare class SourceError extends Error {
 type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
 /** The hosted API. */
 declare const DEFAULT_API_URL = "https://api.secondlayer.tools";
+/** Options for reading proofs from the Secondlayer API. */
 interface SecondlayerSourceOptions {
 	/** API origin. Defaults to {@link DEFAULT_API_URL}. */
 	baseUrl?: string;
@@ -449,8 +468,15 @@ declare class SecondlayerProofSource implements ProofSource {
 	getStateWrites: (height: number) => Promise<StateWrite[] | null>;
 	/** The indexed `vm_events` write rows of a block, from the Index API. */
 	getVmEvents: (height: number) => Promise<VmEventRow[]>;
+	/**
+	* A Bitcoin tx, its merkle branch and header, by txid.
+	*
+	* The txid is display-order hex.
+	*/
+	getBitcoinTxProof: (txid: string) => Promise<SpvProof>;
 	constructor(opts?: SecondlayerSourceOptions);
 }
+/** Options for reading proofs from a Stacks node. */
 interface NodeRpcSourceOptions {
 	/** Stacks node RPC origin, e.g. `http://localhost:20443`. */
 	nodeUrl: string;
@@ -512,6 +538,7 @@ interface StateFailure {
 	path?: string;
 	ordinal?: number;
 }
+/** A block's height, parent, and state root to check rows against. */
 interface BlockStateInput {
 	/** MARF height of the block (its Stacks chain length). */
 	height: number;
@@ -537,6 +564,7 @@ interface BlockStateInput {
 	*/
 	parentHolds?: (leaf: WitnessLeaf) => Promise<boolean>;
 }
+/** The proven diff, rows checked, notes, and failures. */
 interface BlockStateResult {
 	diff?: ProvenDiff;
 	rowsChecked: number;
@@ -553,6 +581,7 @@ interface BlockStateResult {
 * `parentLeaves`, and the remaining writes come back unnamed.
 */
 declare function verifyBlockState(input: BlockStateInput): Promise<BlockStateResult>;
+/** A transaction's id and its consensus-serialized bytes. */
 interface BlockTransaction {
 	/** sha512/256 of the transaction bytes, hex. */
 	txid: string;
@@ -583,8 +612,31 @@ declare class TransactionsError extends Error {
 * mismatch.
 */
 declare function blockTransactions(raw: Bytes, header: NakamotoHeader): BlockTransaction[] | null;
-type VerifyStep = "ancestry" | "block" | "bitcoin" | "burn" | "signer-set" | "signatures" | "txs" | "witness" | "names" | "rows";
-type VerifyFailureCode = StateFailureCode | "unavailable" | "id-mismatch" | "tx-root-mismatch" | "height-mismatch" | "invalid-header" | "preimage-mismatch" | "burn-not-in-chain" | "before-checkpoint" | "not-ancestor" | "ancestry-proof-invalid" | "anchor-not-found" | "anchor-outside-window" | "anchor-unsigned" | "set-proof-invalid" | "below-threshold" | "unknown-signer" | "duplicate-signer" | "bad-signature";
+import { SpvProof as SpvProof3 } from "@secondlayer/stacks/bitcoin";
+import { OutputScriptType } from "@secondlayer/stacks/bitcoin";
+/** One output of a proven Bitcoin transaction. */
+interface BitcoinTxOutputView {
+	vout: number;
+	/** Satoshis. */
+	amount: bigint;
+	script: Bytes;
+	type: OutputScriptType;
+	/** Mainnet address, when the script has one. */
+	address?: string;
+}
+/**
+* The output fields a proven transaction must match.
+*
+* Every field given has to be equal. `address` compares as a string, `script`
+* byte for byte, `amount` in satoshis.
+*/
+interface BitcoinTxExpect {
+	address?: string;
+	script?: Bytes;
+	amount?: bigint;
+}
+type VerifyStep = "ancestry" | "block" | "bitcoin" | "bitcoin-tx" | "burn" | "signer-set" | "signatures" | "txs" | "witness" | "names" | "rows";
+type VerifyFailureCode = StateFailureCode | "unavailable" | "id-mismatch" | "tx-root-mismatch" | "height-mismatch" | "invalid-header" | "preimage-mismatch" | "burn-not-in-chain" | "before-checkpoint" | "not-ancestor" | "ancestry-proof-invalid" | "anchor-not-found" | "anchor-outside-window" | "anchor-unsigned" | "set-proof-invalid" | "below-threshold" | "unknown-signer" | "duplicate-signer" | "bad-signature" | "tx-parse" | "txid-mismatch" | "merkle-mismatch" | "bitcoin-header-not-in-chain" | "output-not-found";
 interface VerifyFailure {
 	step: VerifyStep;
 	code: VerifyFailureCode;
@@ -609,6 +661,7 @@ interface Ancestry {
 	*/
 	via: "parents" | "marf";
 }
+/** The result of verifying a block, step by step. */
 interface BlockVerification {
 	/**
 	* Every step passed. At or above the checkpoint: header, burn binding,
@@ -649,6 +702,7 @@ interface BlockVerification {
 	/** Empty when ok. The first entry is the first broken link. */
 	failures: VerifyFailure[];
 }
+/** The proof source, checkpoint, and row checking for a block verify. */
 interface VerifyOptions {
 	source: ProofSource;
 	/** Defaults to MAINNET_CHECKPOINT. */
@@ -666,6 +720,21 @@ interface VerifyOptions {
 	*/
 	onStep?: (step: VerifyStep) => void;
 }
+/** The result of proving a Bitcoin transaction against the checkpoint's chain. */
+interface BitcoinTxVerification {
+	/** The tx is in a block of the checkpoint's Bitcoin chain, and any `expect` matched. */
+	ok: boolean;
+	/** Display-order hex. */
+	txid?: string;
+	height?: number;
+	/** Display-order hex. */
+	blockHash?: string;
+	outputs?: BitcoinTxOutputView[];
+	/** Index of the first output matching `expect`, when given. */
+	matched?: number;
+	/** Empty when ok. */
+	failures: VerifyFailure[];
+}
 /**
 * Verifies blocks from one checkpoint against one source.
 *
@@ -686,6 +755,8 @@ declare class BlockVerifier {
 	private readonly headers;
 	/** Blocks proven on the checkpoint's chain below it, by height. */
 	private readonly below;
+	/** Bitcoin block hashes proven below the checkpoint by prev-hash links, by height. */
+	private readonly bitcoinBelow;
 	private readonly burns;
 	/** Unverified source answers by consensus hash. */
 	private readonly preimages;
@@ -696,6 +767,24 @@ declare class BlockVerifier {
 	constructor(opts: VerifyOptions);
 	/** Verify one block by id (hex) or height. Never throws for bad source data. */
 	verify(ref: string | number): Promise<BlockVerification>;
+	/**
+	* Proves a Bitcoin tx is in the checkpoint's Bitcoin chain.
+	*
+	* It can also prove that one output pays `expect`. Pass an `SpvProof`, or a
+	* txid for the source's `getBitcoinTxProof` to fetch. It never throws for bad
+	* source data.
+	*/
+	verifyBitcoinTx(proof: SpvProof3 | string, opts?: {
+		expect?: BitcoinTxExpect
+	}): Promise<BitcoinTxVerification>;
+	private runBitcoinTx;
+	/**
+	* Fail unless the Bitcoin block `hash` is the checkpoint chain's block at
+	* `height`. At or above the checkpoint that is the PoW-validated chain; below
+	* it, prev-hash links back from the checkpoint header, which commits to every
+	* ancestor.
+	*/
+	private bitcoinHeaderInChain;
 	/** Report a passed link. A throwing callback must not break verification. */
 	private passed;
 	private run;
@@ -799,6 +888,7 @@ declare class BlockVerifier {
 /** One-shot: verify a block from a checkpoint (MAINNET_CHECKPOINT by default). */
 declare const verifyBlock: (ref: string | number, opts: VerifyOptions) => Promise<BlockVerification>;
 type LinkStatus = "ok" | "failed" | "skipped";
+/** One verification step with its status and what it proved. */
 interface LinkLine {
 	step: VerifyStep;
 	label: string;
@@ -827,4 +917,5 @@ declare function describeLinks(r: BlockVerification, cp: VerifyCheckpoint, opts?
 		text: string
 	}
 };
-export { Ancestry, BlockDiff, BlockDiffInput, BlockStateInput, BlockStateResult, BlockTransaction, BlockVerification, BlockVerifier, BurnPreimage, Bytes, Checkpoint, ClassifiedLeaf, DEFAULT_API_URL, DiffLeaf, DiffWrite, Epoch2Header, Epoch2HeaderResponse, HeaderChain, HeaderRule, HeaderValidationError, LINKS, LinkLine, LinkStatus, MAINNET_CHECKPOINT, MAINNET_FIRST_BURN_HEIGHT, MAINNET_PREPARE_LENGTH, MAINNET_REWARD_CYCLE_LENGTH, MarfProofInput, MarfProofResponse, NakamotoHeader, NodeRpcProofSource, NodeRpcSourceOptions, ProofSource, ProvenDiff, SIGNERS_CONTRACT, SecondlayerProofSource, SecondlayerSourceOptions, SignerCheck, SignerSet, SourceError, StacksHeader, StateFailure, StateFailureCode, StateWitness, StateWrite, TransactionsError, VerifyCheckpoint, VerifyFailure, VerifyFailureCode, VerifyOptions, VerifyStep, VmEventRow, WitnessLeaf, blockId2 as blockId, blockTransactions, classifyBlockDiff, cycleStart, dataVarKey, decodeSignerSet, describeLinks, ftBalanceKey, hex, isEpoch2Header, mapEntryKey, marfPath, marfProofAncestors, marfValue, parseEpoch2Header, parseNakamotoHeader, parseWitness, rewardCycle, signerSignatureHash, txMerkleRoot2 as txMerkleRoot, unhex, verifyBlock, verifyBlockState, verifyConsensusPreimage, verifyMarfProof, verifySignerSignatures };
+import { SpvProof as SpvProof4 } from "@secondlayer/stacks/bitcoin";
+export { Ancestry, BitcoinTxExpect, BitcoinTxOutputView, BitcoinTxVerification, BlockDiff, BlockDiffInput, BlockStateInput, BlockStateResult, BlockTransaction, BlockVerification, BlockVerifier, BurnPreimage, Bytes, Checkpoint, ClassifiedLeaf, DEFAULT_API_URL, DiffLeaf, DiffWrite, Epoch2Header, Epoch2HeaderResponse, HeaderChain, HeaderRule, HeaderValidationError, LINKS, LinkLine, LinkStatus, MAINNET_CHECKPOINT, MAINNET_FIRST_BURN_HEIGHT, MAINNET_PREPARE_LENGTH, MAINNET_REWARD_CYCLE_LENGTH, MarfProofInput, MarfProofResponse, NakamotoHeader, NodeRpcProofSource, NodeRpcSourceOptions, ProofSource, ProvenDiff, SIGNERS_CONTRACT, SecondlayerProofSource, SecondlayerSourceOptions, SignerCheck, SignerSet, SourceError, SpvProof4 as SpvProof, StacksHeader, StateFailure, StateFailureCode, StateWitness, StateWrite, TransactionsError, VerifyCheckpoint, VerifyFailure, VerifyFailureCode, VerifyOptions, VerifyStep, VmEventRow, WitnessLeaf, blockId2 as blockId, blockTransactions, classifyBlockDiff, cycleStart, dataVarKey, decodeSignerSet, describeLinks, ftBalanceKey, hex, isEpoch2Header, mapEntryKey, marfPath, marfProofAncestors, marfValue, parseEpoch2Header, parseNakamotoHeader, parseWitness, rewardCycle, signerSignatureHash, txMerkleRoot2 as txMerkleRoot, unhex, verifyBlock, verifyBlockState, verifyConsensusPreimage, verifyMarfProof, verifySignerSignatures };

package/dist/index.js

@@ -690,6 +690,9 @@ function headerHash(raw) {
   }
   return sha2562(sha2562(bytes));
 }
+function headerHashHex(raw) {
+  return bytesToHex2(reverseBytes(headerHash(raw)));
+}
 
 // src/bitcoin/pow.ts
 var POW_LIMIT = 0xffffn << 208n;
@@ -1050,6 +1053,24 @@ var toMarf = (url, j) => {
     throw new SourceError(url, 200, "MARF answer needs data and proof");
   return { data: j.data, proof: unhex(proof) };
 };
+var isHex = (v) => typeof v === "string" && /^(0x)?([0-9a-f]{2})+$/i.test(v);
+var isCount = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+var toBitcoinTxProof = (url, j) => {
+  const w = j;
+  if (!w || !isHex(w.txid) || !isHex(w.raw_tx) || !isHex(w.header) || !isCount(w.block_height) || !isCount(w.tx_index) || !isCount(w.tx_count) || !Array.isArray(w.siblings) || !w.siblings.every(isHex))
+    throw new SourceError(url, 200, "bitcoin tx proof needs txid, raw_tx, header, block_height, tx_index, tx_count and siblings");
+  return {
+    rawTx: unhex(w.raw_tx),
+    txidInternal: unhex(w.txid).reverse(),
+    header: unhex(w.header),
+    height: w.block_height,
+    merkle: {
+      siblings: w.siblings.map(unhex),
+      txIndex: w.tx_index,
+      txCount: w.tx_count
+    }
+  };
+};
 var DEFAULT_API_URL = "https://api.secondlayer.tools";
 var VM_WRITE_TYPES = [
   "var_set",
@@ -1086,6 +1107,7 @@ class SecondlayerProofSource {
   getBitcoinHeaders;
   getStateWrites;
   getVmEvents;
+  getBitcoinTxProof;
   constructor(opts = {}) {
     const base = trimSlash(opts.baseUrl ?? DEFAULT_API_URL);
     const http = {
@@ -1120,6 +1142,10 @@ class SecondlayerProofSource {
         throw new SourceError(url, 200, `headers start at ${j.from}`);
       return j.headers;
     };
+    this.getBitcoinTxProof = async (txid) => {
+      const url = `${base}/v1/proofs/bitcoin-tx/${txid}`;
+      return toBitcoinTxProof(url, required(url, await getJson(url, http)));
+    };
     this.getStateWrites = async (height) => {
       const url = `${base}/v1/proofs/writes/${height}`;
       const j = await getJson(url, http);
@@ -1437,6 +1463,8 @@ function linkDetail(step, r, cp) {
       return `${n(r.height ?? 0)}  ${r.blockId}`;
     case "bitcoin":
       return `headers ${n(cp.bitcoin.height)}..${n(r.burnHeight ?? 0)}, proof-of-work and retargets checked`;
+    case "bitcoin-tx":
+      return "";
     case "burn":
       return `height ${n(r.burnHeight ?? 0)}  ${r.bitcoinBlockHash}`;
     case "signer-set":
@@ -1522,6 +1550,86 @@ function describeLinks(r, cp, opts = {}) {
 }
 // src/verify-block.ts
 import { uintCV } from "@secondlayer/stacks/clarity";
+
+// src/bitcoin-tx.ts
+import {
+  formatBitcoinAddress,
+  parseBitcoinTx,
+  parseBlockHeader,
+  parseOutputScript,
+  reverseBytes as reverseBytes2,
+  rootFromProof,
+  stripWitness
+} from "@secondlayer/stacks/bitcoin";
+var INNER_NODE_SIZE = 64;
+function branchLength(txCount) {
+  return txCount <= 1 ? 0 : Math.ceil(Math.log2(txCount));
+}
+function checkBranch(merkle) {
+  const { txIndex, txCount, siblings } = merkle;
+  if (!Number.isSafeInteger(txCount) || txCount < 1)
+    return `tx count ${txCount} is not a positive integer`;
+  if (!Number.isSafeInteger(txIndex) || txIndex < 0 || txIndex >= txCount)
+    return `tx index ${txIndex} is outside ${txCount} txs`;
+  const want = branchLength(txCount);
+  if (siblings.length !== want)
+    return `branch has ${siblings.length} siblings, a ${txCount}-tx block needs ${want}`;
+  if (siblings.some((s) => s.length !== 32))
+    return "every sibling must be 32 bytes";
+  return;
+}
+function checkTxInclusion(proof) {
+  const bad = (code, message) => ({
+    code,
+    message
+  });
+  if (proof.header.length !== HEADER_SIZE)
+    return bad("tx-parse", `header is ${proof.header.length} bytes, not 80`);
+  let parsed;
+  let strippedSize;
+  try {
+    parsed = parseBitcoinTx(proof.rawTx);
+    strippedSize = stripWitness(proof.rawTx).length;
+  } catch (err) {
+    return bad("tx-parse", `raw tx does not parse: ${err.message}`);
+  }
+  if (strippedSize === INNER_NODE_SIZE)
+    return bad("tx-parse", "a 64-byte transaction is indistinguishable from a merkle inner node");
+  if (!bytesEqual(parsed.txidInternal, proof.txidInternal))
+    return bad("txid-mismatch", `raw tx hashes to ${hex(reverseBytes2(parsed.txidInternal))}, not ${hex(reverseBytes2(proof.txidInternal))}`);
+  const branch = checkBranch(proof.merkle);
+  if (branch)
+    return bad("merkle-mismatch", branch);
+  const root = parseBlockHeader(proof.header).merkleRoot;
+  if (!bytesEqual(rootFromProof(parsed.txidInternal, proof.merkle), root))
+    return bad("merkle-mismatch", "the branch does not fold to the header's merkle root");
+  return {
+    txid: hex(reverseBytes2(parsed.txidInternal)),
+    blockHash: headerHashHex(proof.header),
+    outputs: parsed.outputs.map((o, vout) => {
+      const script = o.scriptPubKey;
+      const parsedScript = parseOutputScript(script);
+      return {
+        vout,
+        amount: o.value,
+        script,
+        type: parsedScript.type,
+        address: formatBitcoinAddress(parsedScript, "mainnet")
+      };
+    })
+  };
+}
+function outputMatches(output, expect) {
+  if (expect.address !== undefined && output.address !== expect.address)
+    return false;
+  if (expect.script !== undefined && !bytesEqual(output.script, expect.script))
+    return false;
+  if (expect.amount !== undefined && output.amount !== expect.amount)
+    return false;
+  return true;
+}
+
+// src/verify-block.ts
 class Broken extends Error {
   failure;
   constructor(failure) {
@@ -1547,6 +1655,7 @@ async function fetchFor(step, what, call, extra = {}) {
   }
 }
 var BITCOIN_BATCH = 2016;
+var MAX_BITCOIN_WALK = 52560;
 var MAX_WALK = 16;
 async function findAnchor(low, high, window, probe, maxProbes = 32) {
   let [lo, hi] = [low, high];
@@ -1584,6 +1693,7 @@ class BlockVerifier {
   anchors = new Map;
   headers = new Map;
   below = new Map;
+  bitcoinBelow = new Map;
   burns = new Map;
   preimages = new Map;
   raws = new Map;
@@ -1612,6 +1722,114 @@ class BlockVerifier {
     out.ok = out.failures.length === 0;
     return out;
   }
+  async verifyBitcoinTx(proof, opts = {}) {
+    const out = { ok: false, failures: [] };
+    try {
+      await this.runBitcoinTx(proof, opts.expect, out);
+    } catch (err) {
+      if (!(err instanceof Broken))
+        throw err;
+      out.failures.unshift(err.failure);
+    }
+    out.ok = out.failures.length === 0;
+    return out;
+  }
+  async runBitcoinTx(input, expect, out) {
+    let proof;
+    if (typeof input === "string") {
+      const fetchProof = this.source.getBitcoinTxProof;
+      if (!fetchProof)
+        return fail({
+          step: "bitcoin-tx",
+          code: "unavailable",
+          message: "source has no getBitcoinTxProof; pass an SpvProof"
+        });
+      proof = await fetchFor("bitcoin-tx", `bitcoin tx ${input}`, () => fetchProof.call(this.source, input));
+    } else
+      proof = input;
+    const included = checkTxInclusion(proof);
+    if ("code" in included)
+      return fail({ step: "bitcoin-tx", ...included });
+    out.txid = included.txid;
+    out.height = proof.height;
+    out.blockHash = included.blockHash;
+    out.outputs = included.outputs;
+    await this.bitcoinHeaderInChain(proof.height, included.blockHash);
+    if (expect) {
+      const candidates = proof.vout === undefined ? included.outputs : included.outputs.filter((o) => o.vout === proof.vout);
+      const hit = candidates.find((o) => outputMatches(o, expect));
+      if (!hit)
+        return fail({
+          step: "bitcoin-tx",
+          code: "output-not-found",
+          message: proof.vout === undefined ? "no output of the transaction matches what was expected" : `output ${proof.vout} does not match what was expected`
+        });
+      out.matched = hit.vout;
+    }
+    this.passed("bitcoin-tx");
+  }
+  async bitcoinHeaderInChain(height, hash) {
+    const notInChain = (message) => fail({
+      step: "bitcoin-tx",
+      code: "bitcoin-header-not-in-chain",
+      message
+    });
+    const base = this.chain.checkpointHeight;
+    if (!Number.isSafeInteger(height) || height < 0)
+      return notInChain(`block height ${height} is not valid`);
+    if (height >= base) {
+      await this.syncBitcoin(height);
+      if (this.chain.headerAt(height)?.hash !== hash)
+        notInChain(`block ${hash} is not the verified Bitcoin chain's block at ${height}`);
+      return;
+    }
+    if (this.bitcoinBelow.get(height) === hash)
+      return;
+    if (base - height > MAX_BITCOIN_WALK)
+      return fail({
+        step: "bitcoin-tx",
+        code: "before-checkpoint",
+        message: `block ${height} is more than ${MAX_BITCOIN_WALK} blocks below the Bitcoin checkpoint ${base}`
+      });
+    const proven = new Map;
+    let prev;
+    for (let from = height;from < base; ) {
+      const count = Math.min(BITCOIN_BATCH, base - from);
+      const batch = await fetchFor("bitcoin-tx", `bitcoin headers ${from}`, () => this.source.getBitcoinHeaders(from, count));
+      if (batch.length !== count)
+        fail({
+          step: "bitcoin-tx",
+          code: "unavailable",
+          message: `source returned ${batch.length} Bitcoin headers from ${from}, wanted ${count}`
+        });
+      for (const [i, raw] of batch.entries()) {
+        let parsed;
+        try {
+          parsed = parseHeader(raw);
+        } catch (err) {
+          return fail({
+            step: "bitcoin-tx",
+            code: "invalid-header",
+            message: `Bitcoin header ${from + i}: ${err.message}`
+          });
+        }
+        const own = headerHashHex(raw);
+        if (prev === undefined) {
+          if (own !== hash)
+            notInChain(`header at ${height} is not block ${hash}`);
+        } else if (parsed.prevHash !== prev)
+          notInChain(`header at ${from + i} does not link to the header before it`);
+        prev = own;
+        proven.set(from + i, own);
+      }
+      from += count;
+    }
+    const anchor = this.chain.headerAt(base)?.header.prevHash;
+    if (prev === undefined || anchor !== prev)
+      notInChain(`block ${hash} does not link to the Bitcoin checkpoint at ${base}`);
+    for (const [h, v] of proven)
+      this.bitcoinBelow.set(h, v);
+  }
   passed(step) {
     try {
       this.onStep?.(step);
@@ -2220,5 +2438,5 @@ export {
   verifySignerSignatures
 };
 
-//# debugId=C611E693588430B164756E2164756E21
+//# debugId=6B4D2C6B1BB8C3A564756E2164756E21
 //# sourceMappingURL=index.js.map