Skip to content

docs(model/block): document BlockIDs[0] == GenesisBlockID invariant#974

Merged
oskarszoon merged 1 commit into
bsv-blockchain:mainfrom
oskarszoon:fix/teranode-967
May 28, 2026
Merged

docs(model/block): document BlockIDs[0] == GenesisBlockID invariant#974
oskarszoon merged 1 commit into
bsv-blockchain:mainfrom
oskarszoon:fix/teranode-967

Conversation

@oskarszoon

@oskarszoon oskarszoon commented May 28, 2026

Copy link
Copy Markdown
Contributor

Closes #967.

Spells out the invariant that keeps the BlockIDs[0] == GenesisBlockID access in checkParentExistsOnChain fork-safe:

  • The restore path appends GenesisBlockID first.
  • Real confirmations get appended after.
  • Genesis cannot be in a fork, so BlockIDs[0] == GenesisBlockID uniquely identifies a restored tx.

The site looks identical at a glance to the index-[0] bugs surfaced in #963, but is safe by construction. The comment expansion stops a future reader from "fixing" it.

No behavioural change.

@oskarszoon
docs(model/block): document BlockIDs[0] == GenesisBlockID invariant (b…
0ab4a37 
…sv-blockchain#967)

Spell out why the [0] access in checkParentExistsOnChain is fork-safe:
the restore path appends GenesisBlockID first, and genesis cannot fork.
Looks identical at a glance to the index-[0] bugs surfaced in bsv-blockchain#963, but
this site is safe by construction.
@github-actions

github-actions Bot commented May 28, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🤖 Claude Code Review

Status: Complete

Current Review:
No issues found. This is a documentation-only change that accurately clarifies a fork-safe invariant.

Analysis:
The PR expands a comment to document why BlockIDs[0] == GenesisBlockID is safe to check without a main-chain filter. The documentation claim is verified correct:

  1. Restore path confirmed: cmd/seeder/seeder.go:557 creates transactions with WithMinedBlockInfo(utxo.MinedBlockInfo{BlockID: 0, ...}) where 0 is GenesisBlockID
  2. First-position guarantee: The store implementation (stores/utxo/sql/sql.go:836-852) preserves MinedBlockInfo order, so GenesisBlockID appears at index [0]
  3. Fork-safety: Genesis cannot be in a fork, so BlockIDs[0] == GenesisBlockID uniquely identifies restored transactions
  4. Addresses audit transaction-block-array indexing for fork safety #963: This was identified as a potential index-[0] bug but is safe by construction

The expanded comment prevents future maintainers from incorrectly "fixing" this intentional pattern.

@oskarszoon oskarszoon self-assigned this May 28, 2026
@oskarszoon oskarszoon enabled auto-merge (squash) May 28, 2026 13:15
@sonarqubecloud

sonarqubecloud Bot commented May 28, 2026

Copy link
Copy Markdown

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

ordishs
ordishs approved these changes May 28, 2026
View reviewed changes

@ordishs ordishs left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Targeted docs change; verified against cmd/seeder/seeder.go:557 (restore path appends BlockID: 0 first). Comment accurately captures the sentinel invariant that makes the BlockIDs[0] access fork-safe at this call site.

@oskarszoon oskarszoon merged commit 6922f38 into bsv-blockchain:main May 28, 2026
27 of 28 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@ordishs ordishs ordishs approved these changes

@icellan icellan icellan approved these changes

@freemans13 freemans13 Awaiting requested review from freemans13

Assignees

@oskarszoon oskarszoon

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

model/Block: document why BlockIDs[0] == GenesisBlockID check is fork-safe

3 participants

@oskarszoon @ordishs @icellan