Bitcoin SPV

bun add @secondlayer/stacks

import { buildTxProof, verifyBitcoinPayment } from "@secondlayer/stacks/bitcoin";

import { createPublicClient, http } from "@secondlayer/stacks";
import { mainnet } from "@secondlayer/stacks/chains";
import {
  buildTxProof,
  bitcoinRpcSource,
  esploraSource,
  fallbackProofSource,
  verifyBitcoinPayment,
} from "@secondlayer/stacks/bitcoin";

const client = createPublicClient({ chain: mainnet, transport: http() });

// Trustless by default: your own node first, hosted fallback second.
const source = fallbackProofSource([
  bitcoinRpcSource({ url: "http://127.0.0.1:8332", auth: { username: "u", password: "p" } }),
  esploraSource({ url: "https://blockstream.info/api" }),
]);

// "release only when a real BTC payment to <addr> for <amount> is proven on-chain"
const result = await verifyBitcoinPayment(client, {
  txid: "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
  source,
  vout: 0,
  contract: "SP….spv-adapter", // the reference adapter (or your own verifier contract)
  expect: { address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", amount: 5_000_000_000n },
});
// → { verified, mined, output, proof }

import { buildTxProof, esploraSource } from "@secondlayer/stacks/bitcoin";

const source = esploraSource({ url: "https://blockstream.info/api" });
const proof = await buildTxProof(source, {
  txid: "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16",
  vout: 0,
});
// proof: { rawTx, txidInternal, vout, merkle: { siblings, txIndex, txCount }, header, height }

import {
  encodeMerkleProofArgs,
  decodeTxOutput,
  parseOutputScript,
} from "@secondlayer/stacks/bitcoin";

// `(leaf, root, tx-index, tx-count, (list 24 (buff 32)))` — never reversed, never a tuple.
const args = encodeMerkleProofArgs({ leaf: proof.txidInternal, root, proof: proof.merkle });

// Decode `get-bitcoin-tx-output?`'s `{ script, amount, txid }` tuple, then read the script.
const out = decodeTxOutput(resultCV);          // { script, amount: bigint, txid }
const spk = parseOutputScript(out.script);     // { type: "p2pkh" | "p2wpkh" | "p2tr" | …, address?, data? }

;; spv-adapter -- a thin, read-only reference wrapper over the SIP-044 (Clarity 6)
;; Bitcoin SPV built-ins. The built-ins are callable only from within a Clarity
;; contract, not over RPC; this contract exposes them as read-only functions so
;; the @secondlayer/stacks `bitcoinVerifier` (and any integrator) can reach them.
;;
;; Byte order: 32-byte hashes (txids, merkle roots, siblings) are INTERNAL order
;; (raw double-SHA-256), matching the built-ins. The only display-order value is
;; the block hash from `get-burn-block-info? header-hash`, reversed before compare.

(define-constant ERR-BAD-HEADER (err u1)) ;; header not canonical at that height
(define-constant ERR-BAD-SLICE (err u2))  ;; header merkle-root slice failed

;; Reverse a 32-byte buffer (internal <-> display order).
(define-private (prepend-byte (b (buff 1)) (acc (buff 32)))
  (unwrap-panic (as-max-len? (concat b acc) u32))
)
(define-read-only (reverse-buff32 (input (buff 32)))
  (fold prepend-byte input 0x)
)

;; The merkle root committed by an 80-byte header: bytes [36, 68), internal order.
(define-read-only (header-merkle-root (header (buff 80)))
  (match (slice? header u36 u68)
    sliced (as-max-len? sliced u32)
    none)
)

;; Parse one output of a serialized BTC tx.
(define-read-only (get-tx-output (tx (buff 4096)) (vout uint))
  (get-bitcoin-tx-output? tx vout)
)

;; Prove tx inclusion under a SUPPLIED root (membership only — not chain-authenticated).
(define-read-only (verify-merkle
    (leaf (buff 32)) (root (buff 32))
    (tx-index uint) (tx-count uint) (siblings (list 24 (buff 32))))
  (verify-merkle-proof leaf root tx-index tx-count siblings)
)

;; Full check: authenticate the caller's 80-byte header against the chain's record
;; at `height` (`get-burn-block-info? header-hash`), extract its root, and prove
;; inclusion — atomically.
;;   (ok true)  header canonical AND tx included (mined)
;;   (ok false) header canonical but tx not included
;;   (err u1)   header not the canonical block at `height`
;;   (err u2)   malformed header length
;; Note: an out-of-range `height` (before the chain launched, or newer than the
;; node's last-processed burn block — a very recent tx) also yields (err u1).
;; Flash blocks (a BTC block with no Stacks block) are covered — get-burn-block-info?
;; header-hash is indexed by burn height, not a gap.
(define-read-only (was-tx-mined
    (header (buff 80)) (height uint) (leaf (buff 32))
    (tx-index uint) (tx-count uint) (siblings (list 24 (buff 32))))
  (let (
        (root (unwrap! (header-merkle-root header) ERR-BAD-SLICE))
       )
    (if (is-eq (get-burn-block-info? header-hash height)
               (some (reverse-buff32 (sha256 (sha256 header)))))
        (ok (verify-merkle-proof leaf root tx-index tx-count siblings))
        ERR-BAD-HEADER)
  )
)

import { bitcoinVerifier } from "@secondlayer/stacks/bitcoin";

const verifier = bitcoinVerifier(client, { contract: "SP….spv-adapter" });
const mined = await verifier.wasTxMined(proof);

[contracts.spv-adapter]
path = "contracts/spv-adapter.clar"
clarity_version = 6
epoch = "4.0"

import { isClarity6Active } from "@secondlayer/stacks/bitcoin";

const live = await isClarity6Active(client, { activationBurnHeight: 0 /* set post-vote */ });