Skip to content

Pluggable BDK WASM script-verification backend (@bsv/verifast)#186

Merged
sirdeggen merged 18 commits into
mainfrom
feat/bdk
Jun 16, 2026
Merged

Pluggable BDK WASM script-verification backend (@bsv/verifast)#186
sirdeggen merged 18 commits into
mainfrom
feat/bdk

Conversation

@sirdeggen

@sirdeggen sirdeggen commented Jun 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Adds an optional, pluggable C++/WASM (BSV BDK) backend for transaction script verification, with the pure-TS interpreter as default + sole fallback.
  • Strict: when a backend is configured, its verdict is authoritative; failures throw (no silent JS fallback).
  • Ships an equivalence + benchmark harness to prove the speedup once a real wasm is supplied.

Changes

Core @bsv/sdk:

  • New BdkVerifierInterface (whole-tx verifyScripts).
  • Transaction.verify(chainTracker, feeModel, memoryLimit, verifier?) — optional 4th arg. When present, the per-input Spend loop is bypassed and the whole tx goes to the backend once. Spend untouched; default path byte-for-byte unchanged.
  • UTXO mined-height fallback 943816 (post-Chronicle) when unobtainable.

New package @bsv/verifast:

  • BdkVerifier adapter: marshals tx.toEF() + per-input UTXO heights + flag bitfield into BDK's embind VerifyScript, frees vectors.
  • flags.ts: TS string flags → BDK uint32 bitfield.
  • Mock-wasm unit tests; deterministic P2PKH corpus; JS-vs-BDK equivalence test (auto-skips without a real wasm); inputs/sec benchmark.
  • Supply-your-own-wasm (upstream prebuilt is an unvalidated stub); README documents the build + assumptions to confirm.

Docs: design spec + implementation plan under docs/superpowers/.

Notes

  • Monorepo pins published @bsv/sdk 2.1.3 for siblings, so verifast tests/bench map @bsv/sdk → local source (jest/tsx) to see the new signature; build/typecheck via tsc. See spec "Monorepo linkage constraint".
  • Real comparative benchmark numbers require a real bdk-core.wasm build (emsdk+boost+openssl) — out of scope here.

Test plan

  • SDK: seam tests (routing, true/false passthrough, throw propagation, 943816 fallback) + full src/transaction/ suite green (963 pass, no regressions).
  • verifast: flags + BdkVerifier mock-wasm tests green (10 pass, 1 equivalence skipped w/o wasm); build + typecheck clean.
  • Benchmark runs (pure-JS baseline ~1k inputs/s; BDK path skips cleanly w/o wasm).
  • Reviewer: confirm BDK API assumptions (EF format, flag bit values, success code) against a real build.

🤖 Generated with Claude Code

sirdeggen and others added 12 commits June 8, 2026 17:09
@sirdeggen @claude
docs: design for pluggable BDK wasm script-verification backend (@bsv…
d81335c 
…/verifast)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
docs: rename ScriptVerificationBackend -> BdkVerifierInterface
1d45aab 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
docs: add verifast implementation plan + monorepo linkage addendum
bb74549 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
feat(sdk): add BdkVerifierInterface for pluggable script verification
35d9813 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
feat(sdk): optional verifier backend in Transaction.verify, bypasses …
4d5c49f 
…Spend

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
chore(verifast): scaffold @bsv/verifast package
6c3e96d 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
feat(verifast): flag string -> BDK uint32 bitfield mapping
132f845 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
feat(verifast): BdkVerifier adapter marshalling tx.toEF + heights + f…
85cbd7e 
…lags

Uses a local structural copy of BdkVerifierInterface since the monorepo pins
published @bsv/sdk 2.1.3. Build via tsconfig.build.json; full typecheck incl
tests via tsconfig.json. Drops ts-standard (TS6-beta project-resolution issue,
matches sibling packages with no lint script); type safety covered by tsc.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
test(verifast): deterministic P2PKH transaction corpus for bench/equi…
4079fb3 
…valence

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
test(verifast): JS-vs-BDK equivalence corpus (skips without real wasm)
d4b0d4c 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
test(verifast): inputs/sec benchmark harness, JS vs BDK
7415562 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
docs(verifast): usage, supply-your-own-wasm, and caveats
1515ae3 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen sirdeggen changed the title Design: pluggable BDK wasm script-verification backend (@bsv/verifast) Pluggable BDK WASM script-verification backend (@bsv/verifast) Jun 8, 2026
@codecov

codecov Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.66667% with 1 line in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
packages/sdk/src/transaction/Transaction.ts 91.66% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

sirdeggen and others added 2 commits June 16, 2026 13:01
@sirdeggen @claude
docs(superpowers): add required frontmatter to verifast BDK plan/spec
b58369c 
Docs Site Validation requires schema frontmatter on every docs/*.md.
These two new files were missing it, failing the docs-validate job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen @claude
fix(verifast): resolve sonar issues and close codecov gaps on PR 186
e4899e0 
- flags.ts: replace `1 << 0` with `1` (S7767)
- BdkVerifier.ts: use `??=` for lazy module load (S6606)
- flags.test.ts: drop redundant `undefined` arg (S4623)
- benchmark.ts: top-level await instead of promise chain (S7785)
- Transaction.ts: drop unreachable merklePath height lookup in the
  verifier block (mined txs short-circuit earlier, so it was always the
  fallback) — removes the uncovered branch flagged by codecov
- align verifier test with the fallback-only height

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen sirdeggen requested a review from ty-everett as a code owner June 16, 2026 21:48
sirdeggen and others added 2 commits June 16, 2026 17:11
@sirdeggen @claude
fix(ci): regenerate pnpm-lockfile to repair badly-merged peer entries
420701c 
Frozen install failed on Linux CI (ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY)
while passing on macOS. A prior merge left eslint-plugin-es / eslint-utils
snapshots pinned to eslint@8.57.1 instead of eslint@10.4.0, leaving the
lockfile internally inconsistent for clean Linux resolution. Regenerated
with pnpm@10.33.2 inside node:24; verified `pnpm install --frozen-lockfile`
passes in that container.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@sirdeggen
Merge remote-tracking branch 'origin/main' into feat/bdk
412d8cb 
# Conflicts:
#	pnpm-lock.yaml
@sonarqubecloud

sonarqubecloud Bot commented Jun 16, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

@sirdeggen sirdeggen merged commit f2b2054 into main Jun 16, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@BraydenLangley BraydenLangley Awaiting requested review from BraydenLangley BraydenLangley is a code owner

@tonesnotes tonesnotes Awaiting requested review from tonesnotes tonesnotes is a code owner

@ty-everett ty-everett Awaiting requested review from ty-everett ty-everett is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@sirdeggen