Besu Documentation

The ParallelStoredMerklePatriciaTrie is designed to speed up batch updates to a Merkle Patricia Trie by processing independent branches across multiple CPU cores. Instead of updating keys one-by-one, it uses a three-phase approach:

1. Accumulation Phase: Collects all updates without applying them.
2. Parallel Processing Phase: Recursively applies updates, splitting work into parallel tasks when beneficial.
3. Persistence Phase: Writes all modified nodes to storage in a single batch.

Parallelization is achieved by grouping updates by their next hex nibble at branch nodes. If a group contains multiple updates and the branch has multiple active groups, the work is dispatched to a thread pool. Otherwise, it is processed sequentially to avoid task creation overhead.

Key architectural principles include:

• Immutability: Nodes are never modified in place; every update creates a new node instance, allowing safe concurrent reads.
• Independence: Updates to different children of a branch node (e.g., child[A] vs child[F]) are data-independent and can run in parallel.
• Deferred Persistence: A CommitCache (a thread-safe map) collects nodes during parallel processing to allow a single, batched I/O flush at the end.

The Besu Engine API (engine_* JSON-RPC methods) uses a strict versioning pattern based on sealed class hierarchies. This ensures that each new version of a method (e.g., engine_forkchoiceUpdatedV2) extends the previous version (e.g., engine_forkchoiceUpdatedV1) and only overrides the specific hooks required by the specification change.

Key Architectural Components

• Sealed Class Hierarchies: Method series (like EngineNewPayloadV*) are implemented as sealed classes where version $N$ extends $N-1$. The latest version is marked final.
• Base Class: All versions extend ExecutionEngineJsonRpcMethod, which handles fork-window validation using minSupportedFork and firstUnsupportedFork.
• Constructor Pattern: Migrated series use a single ExecutionEngineJsonRpcMethod.ConstructorArguments record (built via ConstructorArgumentsBuilder) instead of positional arguments. This allows the VersionScheduler to manage versioning through a shared factory shape.
• Data Structures: Request parameters (in ..internal.parameters) and results (in ..internal.results) also follow sealed hierarchy patterns to mirror specification versions.
• Hooks: Version classes override protected hooks (e.g., createResponse, validateParameters) rather than re-implementing the entire request flow.

When bonsaiCrossBlockCacheEnabled is enabled, Besu uses a versioned cross-block cache to manage accounts and storage slots. This design allows a single shared cache to remain correct across reorgs, snapshots, and head reads by using a global monotonic version instead of block numbers.

Key Concepts

• Global Monotonic Version: Managed by VersionedCacheManager, this version increments on every successful world-state commit (via CachedUpdater.commit()). It is independent of block height; even if a reorg causes a block height to repeat, the cache version continues to move forward, ensuring different histories do not incorrectly reuse cache generations.
• Pinned Versions:
  • Head Storage: The cacheVersion is updated to match the globalVersion after every commit.
  • Snapshot Storage: When a snapshot is created (BonsaiSnapshotWorldStateKeyValueStorage), it captures the current cacheVersion and keeps it immutable. This pins the snapshot to a specific logical cache epoch.
• Cache Entry Lifecycle: The cache maps a key to a VersionedValue. If a write occurs at version V and the existing entry is older (existing.version < V), the old entry is replaced. The cache does not retain multiple versions of the same key simultaneously.

Read Path Logic

For a read request getFromCacheOrStorage(segment, key, version, storageGetter):

1. Cache Hit: Occurs if an entry exists and cachedEntry.version <= readerVersion. The reader can see cached data as long as it is not newer than their pinned epoch.
2. Cache Miss: If no valid entry is found, the value is loaded from storage via storageGetter.
3. Cache Population: A miss only populates the cache if readerVersion == globalVersion. This ensures the moving head can warm the cache, while stale snapshots (where readerVersion < globalVersion) read from storage without overwriting the head's cache state with potentially stale data.

Cached Segments

The VersionedCacheManager only caches the following segments:

• ACCOUNT_INFO_STATE
• ACCOUNT_STORAGE_STORAGE