feat(archive): add state archive with historical query serving by bladehan1 · Pull Request #55 · bladehan1/java-tron

bladehan1 · 2026-09-20T07:17:22Z

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 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 99658a3. Summary will update on new commits.}

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.

Exempt the deliberately cache-less account-asset snapshot participant from the second-cache check and attach the lane in the exact-27 startup scenario the way Manager.init does.

The format-v2 expectation was pinned before the commitment codec was deliberately reverted to format v1 for compatibility; restore the v1 root the code has always produced.

The v3 serving-index builder held the coordinator monitor across plan and RocksDB append I/O every 10-block batch, so query threads blocked for seconds in pinIndexed and 9.1% of historical-query requests spiked to 2.3-4.0s. Apply the P04 read-side pattern to the build side: the monitor only swaps the pending range into an in-flight capture and publishes the immutable generation, while plan/append I/O runs lock-free; MutableIndex pin captures its lease on volatile state and a request-owned snapshot. A concurrent close fails an in-flight flush closed instead of blocking.

cubic-dev-ai · 2026-09-20T11:39:46Z