Skip to content

feat(hot)!: add table for journal hashes#70

Merged
Fraser999 merged 4 commits into
mainfrom
fraser/eng-2017/journal-hashes
Jun 4, 2026
Merged

feat(hot)!: add table for journal hashes#70
Fraser999 merged 4 commits into
mainfrom
fraser/eng-2017/journal-hashes

Conversation

@Fraser999

@Fraser999 Fraser999 commented May 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a JournalHashes<BlockNumber => B256> hot table so nodes can re-seed the rolling previous-journal hash across restarts and reorgs (ENG-2017). Hot-only, opt-in per block.

Changes

  • New table JournalHashes<BlockNumber => B256> plus HotDbRead::get_journal_hash and UnsafeDbWrite::put_journal_hash.
  • ExecutedBlock.journal_hash: Option<B256> + builder setter. UnifiedStorage::append_blocks persists it in the same hot transaction as headers/bundle.
  • HistoryWrite::unwind_above deletes journal hashes alongside change-sets/headers, independent of last_block_number().
  • New STANDARD_TABLES const in signet-hot as the single source of truth for table creation and MDBX FSI cache seeding. queue_db_init and read_known_fsi both iterate it.
  • Fix: unwind_above(u64::MAX) now short-circuits via checked_add instead of overflowing block + 1 (wraps to 0 in release, panics in debug).
  • From<ExecutedBlock> for BlockData destructures explicitly so new fields trip a compile error on the cold side.

API breakages

  • ExecutedBlock::new() removed - use ExecutedBlockBuilder instead.
  • ExecutedBlock gains a new public journal_hash field. Struct-literal construction (ExecutedBlock { header, .. }) and exhaustive destructuring without .. will no longer compile.

Test plan

  • cargo t -p signet-hot -p signet-hot-mdbx -p signet-storage --all-features
  • cargo clippy --workspace --all-targets --all-features -- -D warnings
  • cargo clippy --workspace --all-targets --no-default-features -- -D warnings
  • cargo +nightly fmt -- --check
  • New tests: test_journal_hash_roundtrip (conformance), append_blocks_persists_journal_hashes / unwind_above_drops_journal_hashes (integration), unwind_above_u64_max_is_noop / unwind_above_below_u64_max_deletes_max_entry (overflow boundary). test_unwind_conformance updated to cover JournalHashes.

Notes

  • put_journal_hash has no consistent-trait wrapper; callers are responsible for pairing writes with a header. unwind_above cleans both regardless.
  • replay_to_cold silently discards journal_hash (hot-only).

PR description drafted by Claude (Opus 4.7, 1M context) via Claude Code.

Copy link
Copy Markdown
Contributor Author

This stack of pull requests is managed by Graphite. Learn more about stacking.

@Fraser999 Fraser999 changed the title add table to hot db for journal hashes feat(hot)!: add table for journal hashes May 26, 2026
@Fraser999 Fraser999 requested a review from prestwich May 26, 2026 11:45

@prestwich prestwich left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

main thing i think is

Comment thread crates/hot-mdbx/src/lib.rs Outdated
Comment thread crates/hot-mdbx/src/lib.rs Outdated
Comment thread crates/hot-mdbx/src/tx.rs Outdated
Comment thread crates/types/src/execution.rs Outdated
/// Set the journal hash (keccak256 of the wire-encoded `Journal::V1`).
/// Leave the method uncalled for block-only nodes that do not produce
/// a journal - the field defaults to `None`.
pub const fn journal_hash(mut self, hash: B256) -> Self {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

nit: usually with_journal_hash or some other verb that indicates mutating

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I prefer the with_ prefix too, but all other setters don't have it.

I'd be OK with adding it to all of them. It'd be a breaking change to the API, but this PR already has other breaking changes, so now might be a good time to make that change if we want it?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

let's go ahead and make the change :)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Done in 5d967f0.

/// [`queue_raw_create`](crate::model::HotKvWrite::queue_raw_create) so the
/// same record drives both table creation and backend-side FSI inference.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StandardTable {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

I don't mind this complexity addition

@prestwich prestwich left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

[Claude Code]

Approved. Reviewed for correctness and CLAUDE.md compliance — no bugs found and no convention violations.

Verified sound:

  • `unwind_above` `checked_add(1)` overflow guard and the `JournalHashes` range-delete ordering.
  • `queue_raw_create` flag refactor via `from_create_args`/`is_dupsort`/`is_dup_fixed` is equivalent to the prior inline behavior.
  • `append_blocks` persists journal hashes atomically in the same writer/transaction as headers/bundle.
  • `NUM_TABLES` (now `STANDARD_TABLES.len()`) — all consumers derive from the const, no drift.

One optional follow-up, not blocking: the agreed-upon `with_` prefix rename on the `ExecutedBlockBuilder` setters wasn't applied. Fraser can update the naming before merging if he wants.

Minor: the PR description still mentions the pre-upgrade FSI fallback and `open_tolerates_pre_upgrade_db` test that were removed in `ae5e263`; worth tidying the description before merge.

@Fraser999 Fraser999 merged commit 9796cc6 into main Jun 4, 2026
8 checks passed
@Fraser999 Fraser999 deleted the fraser/eng-2017/journal-hashes branch June 4, 2026 09:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants