Skip to content

Harden BASM protocol validation and Merkle path offsets - #520

Draft
sirdeggen wants to merge 18 commits into
mainfrom
codex/basm-protocol-hardening
Draft

Harden BASM protocol validation and Merkle path offsets#520
sirdeggen wants to merge 18 commits into
mainfrom
codex/basm-protocol-hardening

Conversation

@sirdeggen

@sirdeggen sirdeggen commented Sep 8, 2026

Copy link
Copy Markdown
Contributor

Overlay reliability program

This change is one slice of Make Overlays Great Again.

Do not merge until the stacked TypeScript and Go overlay branches have been proven together locally. Isolated CI green is not integration acceptance. Keep this PR draft. No npm publication, live database migration, or Mongo/BASM default activation.

C05 (verified progressive API) is parked. C02 (ts-stack#517) and C04 (ts-stack#518) both edit LookupResolver.ts and must not merge independently.

Keep this pull request in draft until local validation is complete.

Program and scope

  • Tracker or issue: Overlay reliability plan B01 TS protocol/conformance slice
  • Why this change is needed: BASM peer inputs must be bound to local canonical headers and admitted-list indices; MerklePath offsets must not wrap at 2^31.
  • Explicitly out of scope: B02 durable recovery jobs, automatic BASM sync enablement, W01 shared fixture package (full B01 still needs those)
  • Exact head SHA reviewed: 752464dff9d91ee4d0ee4abdd1ad6997a4141912

Impact

  • Public package source or manifest changed; affected packages are listed below
  • Security-sensitive boundary changed
  • Documentation or examples changed

Affected packages: @bsv/sdk (MerklePath), @bsv/overlay, @bsv/overlay-express

Verification

  • Local commands and results: MerklePath 46 passed; overlay BASM 91 passed including local Go five-method HTTP; OverlayExpress 113 passed (implementer evidence)
  • Hosted CI run: not yet (draft)
  • All applicable checks are terminal and successful on the exact head

Security and dependencies

  • No dependency or lockfile change

Release and operations

  • No npm publication was performed from a workstation or from this PR
  • enableBASMSync remains false

Validate untrusted BASM peer JSON, bind remote anchors to local canonical
headers, and independently check admitted-list block indices before
historical admission. Keep automatic BASM sync disabled and leave durable
recovery jobs for B02.

Include independent BRC-136 vector checks and localhost TS client tests
against the Go five-method read/serving surface.
Verify claimed admitted-list block indices against the compound Merkle
path even when every remote txid is already local. Check inclusion with
the chain-tracker root at the claimed height instead of MerklePath.verify,
which also enforces coinbase 100-block spendability.
Extract BASM reconcile helpers so cognitive complexity stays at or below 15,
prefer optional chaining on nullable anchors, and invert the advertised
response-length comparison.
…ardening

# Conflicts:
#	docs/reference/package-api-migrations.md
#	docs/reference/stack-facts.md
#	governance/package-release-notes.json
#	governance/repository-health/baselines.json
Jest's istanbul graph still resolved 3.15.1, which fails pnpm audit --audit-level=high.
Health requires overrideRemovalReview.retainedCount to match the live registry.
LookupResolver and evidence helpers pushed the UMD/Vite/Metro payloads
over the previous raw-size gates.
Message-box UMD, wallet Vite gzip, and Hermes bytecode now cover the
evidence/discovery helper payload growth.
@sonarqubecloud

sonarqubecloud Bot commented Sep 9, 2026

Copy link
Copy Markdown

@codecov

codecov Bot commented Sep 9, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 89.87013% with 39 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
packages/overlays/overlay/src/Engine.ts 71.55% 16 Missing and 17 partials ⚠️
packages/sdk/src/transaction/MerklePath.ts 82.85% 0 Missing and 6 partials ⚠️

📢 Thoughts on this report? Let us know!

@sirdeggen sirdeggen added the overlay-reliability Part of org overlay reliability program (project 19) label Sep 9, 2026
@sirdeggen

Copy link
Copy Markdown
Contributor Author

Linked to org project Make Overlays Great Again and tracker https://github.com/bsv-blockchain/make-overlays-great-again/issues/1.

This PR stays draft until the overlay stack is proven locally across ts-stack, go-overlay-services, and go-sdk. Do not merge to main/master to make progress.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

overlay-reliability Part of org overlay reliability program (project 19)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant