Skip to content

feat(archive): add state archive with historical query serving - #55

Open
bladehan1 wants to merge 222 commits into
developfrom
feature/state_archive
Open

bladehan1 wants to merge 222 commits into
developfrom
feature/state_archive

Conversation

@bladehan1

@bladehan1 bladehan1 commented Sep 20, 2026 •

Copy link
Copy Markdown
Owner

What does this PR do?

Introduces the state archive feature: append-file state archive with catalog serving, geth-style archive index, checkpoint-bound recovery, path-state snapshot pipeline, historical query RPC/VM context wiring, and related performance and metrics attribution work. Rebuilt as a fully GPG-signed (Verified) history from feature/archive_block2; content is tree-identical to that branch.

Why are these changes required?

Provides bounded historical state storage and point-query serving for archive data, with recovery semantics aligned to checkpoints.

This PR has been tested by:

  • Unit Tests
  • Manual Testing

Follow up

Extra details

174 commits, all GPG signed. Branch is based on an older develop point and shows divergence from current develop; reconcile (merge/rebase) before merge if required.


Summary by cubic

Adds an opt-in state archive that persists bounded historical state and serves exact point-in-time and range queries, enabling historical RPC and VM execution without changing current chain processing.

  • Stores append-only history body, index, and commit records with checkpoint-bound crash recovery and WAL validation, recovering truncation and restart authorities on boot.
  • Publishes immutable serving generations with an incremental exact-27 serving index and a bounded range index from committed history.
  • Acquires native LevelDB/RocksDB snapshot leases and engine identities, with request-owned historical read sessions that fail closed.
  • Rebuilds a non-consensus path-state root on startup, tracks it through blocks and reorgs, and publishes it in block headers; the rebuild is streamed, parallelized, and memory-bounded.
  • Historical VM execution rejects state-changing opcodes and unsupported precompiles via HistoricalExecutionGuard, with fail-closed fork gates, deadline-bounded pairing checks, and TRC10 balance resolution at the queried state.
  • Adds offline block replay, resumable HTTP export tools, and archive startup diagnostics.
  • Archive is default-off; existing nodes need no migration.

Review notes

  • Branch is based on an older develop point and needs a rebase before merge.

Written for commit 7b14266. Summary will update on new commits.

View guided diff Turn on auto-fix

Capture canonical block metadata and materialize reverse diffs from completed block snapshots. Classify archive state stores explicitly and project account-asset companion mutations before root merge.
Add deterministic history body and index records, ordered durable commit markers, and bounded asynchronous persistence.

Gate checkpoint advancement on committed archive history and cover crash, corruption, backpressure, and reorg behavior.
Persist reverse state history with bounded append-only body, index, and commit structures. Wire an opt-in archive writer into snapshot flush and add restart-safe account change indexing. Expose an experimental historical account balance endpoint for trace comparison.
Persist bounded restart checkpoints, truncation recovery, H/C/D/R progress authorities, and immutable serving generations. Pin committed history resources and fail closed on identity or durability drift.
Add durable engine identities and native LevelDB/RocksDB snapshot leases. Assemble exact Store generations under the SnapshotManager barrier and release partial acquisitions on authority drift.
Apply business mutations with participant progress in native sync batches. Freshly validate H/C/D authorities under the archive barrier and advance reader visibility only after exact convergence.
Unify LevelDB and RocksDB participants behind one recovery contract. Persist canonical mutation plans and bind checkpoint, participant, and reader progress to the same digest.
Collect exact ordinary and AccountAsset post-state without Store scans. Enforce target identity, bounded ownership, one-shot sealing, abort, and terminal payload release.
Drive an exact-27 capture batch through mixed native participants, inject a partial apply failure, and verify durable-plan replay, digest propagation, ownership, and restart convergence.
Apply two capture-produced targets through exact-27 participants. Verify per-target plan digests, overwrite and delete semantics, partial replay boundaries, reader publication, and restart convergence.
Prepare one target-bound Account and AccountAsset projection before snapshot merge, retain its forward payload through the revoking lifecycle, and seal it only against durable history markers.

Keep the integration default-off and preserve the existing proposal 66 physical layout.
Classify ABI as mutable auxiliary metadata outside the versioned state participant set while retaining an explicit tombstone classification.
Exercise proposal-bound projection, layer-to-flush ownership, durable marker sealing, retry and reorg boundaries, exact participant coverage, and ABI exclusion.
Expose durable marker receipt creation through direct and asynchronous history sinks, then gate forward payload sealing on the exact committed flush range.

Retain submitted frozen ranges across durability or receipt failures so retries do not resubmit history.
Verify direct and asynchronous receipt authority, disabled behavior, and retry ordering across durable wait and receipt failures without duplicate history submission.
Encode lane 22 key offsets for mixed legacy 32-byte and optimized 48-byte storage keys. Retain fixed-width old-frame decoding and exact point lookup compatibility.
Complete root-state injection and request overlays, propagate nested capability, budget and corruption failures to the entire historical request, and prevent historical persistent commits. Keep serving failures from rolling back Common and preserve original P66 materialization cleanup semantics.
Store Chainbase and PathState redo in one retained-generation checkpoint database with matching payload, baseline and current identities. Make History own the double-slot Tail and trim only uncommitted suffixes. Capture startup defaults and migrations in a maintenance layer folded into the first finalized block, restore it on carrier pop, and gate the P66 lane by archive configuration. Wire historical VM request context isolation against the shared checkpoint epochs.
Add whole-process memory diagnostics, shared RocksDB Env thread management and RocksDB-only archive admission. Stop new work below the selected 30 GiB disk redline while allowing required shutdown flushes. Overlay limits and metadata/cache tuning remain deferred.
Derive a native index asynchronously from committed History with classified retry/degradation, paired snapshot leases and segmented solo indexing for large blocks. Preserve the strict Common query contract and keep strong-baseline query changes outside this commit.
Use the snapshot head as the archive SolidityNode startup cursor without modifying persisted solid height. Record trusted solid heights inside the block session before finalization, so reverse diff, PathState and Common share the mutation and rollback restores the previous value. Archive OFF retains the upstream path.
…egration

feat(chainbase): integrate selected archive changes
@bladehan1
bladehan1 changed the base branch from develop to release_v4.8.2.2 October 16, 2026 06:25
@bladehan1
bladehan1 changed the base branch from release_v4.8.2.2 to develop October 16, 2026 06:26
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