feat(plugins): backfill section bloom

[317787106]

What does this PR do?

Adds an offline Toolkit command to rebuild missing historical SectionBloom indexes from retained transaction results:

java -jar Toolkit.jar db backfill-bloom

The command reads transactionRetStore and creates or updates section-bloom. see this issue: #6958. It supports:

• Inclusive start/end block numbers. Omitted or zero bounds select the earliest available non-zero transaction-result block and the latest persisted block header (latest_block_header_number in properties). Earlier starts are raised to the first available block; later ends are capped at the persisted header. Negative bounds and inverted ranges are rejected.
• Engine detection from an existing section-bloom, or from transactionRetStore when creating it. Missing engine metadata retains the legacy LevelDB default. ARM64 rejects LevelDB before opening or creating databases.
• Concurrent processing by 2,048-block sections, with each section handled by one worker. Index bits are accumulated in memory; each touched index record is read once and written at most once per section.
• Idempotent backfilling that preserves existing index bits and can be rerun after interruption. Unchanged records are not rewritten, and successful-block counts are added after the section's required writes finish.
• Parameter/database validation, a terminal progress bar, progress logs every 10,000 scanned blocks, and a final execution summary. Block and task failures produce a nonzero exit status; the summary reflects the overall result, and database write failures retain their original causes.

Usage and operational requirements are documented in plugins/README.md.

Bloom encoding is shared through BloomUtils in the existing crypto module. The node's Bloom class delegates to this utility while retaining its public API. Toolkit decodes TransactionRet directly from Protobuf, so the command needs no chainbase runtime dependency. Keccak hashing, bloom bit ordering, section keys, and the compressed database format remain compatible with the node.

Why are these changes required?

Historical blocks processed before v4.8.1 with isJsonRpcFilterEnabled disabled may lack SectionBloom indexes. Since v4.8.1, index generation is independent of this setting. This command rebuilds missing indexes from retained transaction results for address/topic filtering by eth_getLogs, without replaying the blockchain.

This PR has been tested by:

• All 19 tests in the consolidated DbBackfillBloomTest passed, with no failures or skips. Coverage includes engine selection, ARM rejection, persisted-head bounds, explicit zero bounds, validation, progress reporting, and failure summaries, including worker Error propagation and original exception causes. Additional tests verify one read/write per changed index per section, zero writes on complete reruns, and recovery after partial section read/write failures.
• Real RocksDB tests compare exact keys and compressed values with the node's SectionBloomStore, covering the 2047/2048 boundary, concurrent sections, missing target creation, existing bits, repeated runs, empty/missing transaction results, empty bloom values, and malformed Protobuf.
• Related encoder/node suites passed: BloomUtilsTest, BloomTest, SectionBloomStoreTest, LogBlockQueryTest, and LogsFilterCapsuleTest. Shared encoder tests use an independent Keccak digest and integer-based bit representation.
• Standalone RocksDB smoke tests produced identical 174-entry indexes before and after encoder extraction, including repeated runs. Runtime dependency and JAR-content checks verified that chainbase and its excluded transitive dependencies are absent.
• Root checkstyleMain checkstyleTest and git diff --check passed after the final changes. Encoder validation also included javac --release 8 for BloomUtils and the delegating Bloom class.

Automated local validation used macOS ARM64/JDK 17. The standalone command was also validated on Ubuntu x86 with real node data and -c 16, including an initially empty section-bloom database. The full repository test suite was not run locally.

Benchmark

Measured performance on Ubuntu x86 with 16 workers, using the same block range:

Initial index state	Inclusive block range	Blocks	Duration	Blocks/second	Bloom writes
Empty section-bloom database	79,775,907–86,290,757	6,514,851	257 s	25,349.61	6,516,736
Existing section-bloom indexes	79,775,907–86,290,757	6,514,851	249 s	26,164.06	0

Both runs processed 3,182 sections, found 6,508,186 blocks with logs, and completed with zero reported errors. The empty-database run wrote exactly 3,182 × 2,048 = 6,516,736 index records. With existing indexes, all required bits were already present, so no records were rewritten. These are observed results; throughput depends on the workload, hardware, and cache state.

Follow up

None.

Extra details

Stop the node and any other process accessing the database before running the command. The directory must contain properties and transactionRetStore, with at least one non-zero transaction-result block. storage.transHistory.switch must have been enabled when the target blocks were processed, and those results must still be present; the tool cannot recover missing transaction results.

The command can be rerun after interruption. Multiple backfill processes must not operate on the same database concurrently.

Known limitation: node checkpoint replay may overwrite backfilled bits in sections covered by retained checkpoints. Historical sections outside those checkpoints are unaffected. This edge case is not addressed in this PR.