[codex] Implement BRC-136 BASM overlay sync#170
Open
ty-everett wants to merge 9 commits into
Open
Conversation
Contributor
Author
|
cc @sirdeggen for BRC-136 review context. GitHub rejected my formal reviewer request from the fork account, so tagging here explicitly. cc @siggioskarsson as co-author context. |
Contributor
Author
|
Correction: GitHub now shows @sirdeggen in the review requests. Keeping this explicit cc here as well for BRC-136 review context. cc @siggioskarsson. |
Per BRC-136, the cumulative TAC must advance on every block so a peer can authoritatively confirm a block contained no transactions for a topic. Previously the chain only recomputed touched heights, which could reset across empty blocks and leave gaps from out-of-order proofs. Engine: rebuild contiguous anchor slices over [fromHeight, toHeight], filling missing heights with empty anchors (zero basmRoot, zero admittedCount) chained off the prior TAC. Add advanceTopicAnchorChains() to extend every topic's chain forward to the current tip, halting cleanly when a block hash cannot be resolved and capping work per pass at DEFAULT_BASM_RANGE_LIMIT. OverlayExpress: extend anchor chains to the tip on startup and poll periodically (basmBlockPollIntervalMs, default 10m; 0 disables) so chains follow new blocks. Add configureBASMBlockPollInterval(). Add BASMChain.test.ts covering TAC continuity across empty blocks. Signed-off-by: Deggen <d.kellenschwiler@bsvassociation.org>
Document the BRC-136 admitted-set vs lookup-set separation (admin/janitor removal cannot rewrite anchors/TAC) and add the approved design spec for reorg handling that reuses the chaintracks subscribeReorgs mechanism. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Primary reorg trigger is go-chaintracks /v2/reorg/stream (ReorgEvent: orphanedHashes, commonAncestor, newTip, depth), consumed via an SSE client. In-process subscribeReorgs becomes a secondary adapter; poll sweep covers event-less trackers and SSE reconnect catch-up (no Last-Event-ID replay). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add Engine.handleReorg (demote orphaned-block admissions to unproven, rebuild affected topic anchor chains over canonical hashes) and revalidateRecentAnchors (root-revalidation sweep for the fallback + SSE reconnect catch-up). Add forceResolve to anchor rebuild so stale block hashes are re-resolved, plus the storage methods findProvenAppliedTransactionsByBlockHash / ...InRange / demoteAppliedTransactionToUnproven (interface + Knex). Tested in BASMChain.test.ts. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add ReorgStream (parseReorgEvent + extractSseFrames + ReorgSseAdapter) to consume go-chaintracks/Arcade /v2/reorg/stream, mapping each ReorgEvent to Engine.handleReorg. Wire into the BASM lifecycle: configureReorgStream sets the URL + scan depth; the block poll also runs revalidateRecentAnchors as a fallback and the SSE adapter runs it as reconnect catch-up. Pure helpers unit-tested. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a Reorg handling section to BRC-136-BASM.md: go-chaintracks/Arcade /v2/reorg/stream as the reorg authority + ReorgEvent shape, the demote-and-rebuild flow, the revalidation sweep fallback + reconnect catch-up, interaction with admin/janitor removal, config, and operator verification steps. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Hoist H101_NEW, the post-reorg header resolver, and seedTwoBlockChain to module scope so the reorg-handling and revalidation-sweep suites share one copy, clearing SonarCloud new-code duplication. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
docs-site validate walks docs/** and requires schema frontmatter; the spec lacked it. Dates quoted so YAML keeps them as strings. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
@bsv/overlay:computeBasmRoot,computeTac, anchor/raw-tx wire types, and a lightweight BASM peer remote.startBASMSyncandevictUnprovenroutes.@bsv/gaspwithout changing existing GASP behavior.Review Notes
BRC-136 Author Context
Requested @sirdeggen for review. Deggen authored BRC-136 with Siggi, so also tagging @siggioskarsson for visibility.
Validation
corepack pnpm --filter @bsv/overlay run buildcorepack pnpm --filter @bsv/overlay-express run buildcorepack pnpm --filter @bsv/gasp run buildcorepack pnpm --filter @bsv/overlay exec jest --runInBandcorepack pnpm --filter @bsv/overlay-express exec jest --runInBandcorepack pnpm conformanceLint Note
Package-wide
lint:cicurrently reports pre-existing unrelated issues inOverlayGASPStorage.tsandOverlayExpress.test.ts; this PR does not include those cleanup changes.