eest-static-layout

EEST Static Layout Lessons

Moved out of AGENTS.md to keep the agent guide compact. Load this when:

• changing stateless_guest, block_state_root, BAL replay, or EEST harness memory layout;
• changing static .data arenas used by EEST codegen programs;
• adding harness filters or cap checks for EEST stateless runs.

Protocol Limits First

Do not pick static arena sizes from the failing fixture alone. Check the local execution-specs and execution-spec-tests submodules first, then size or gate from the protocol/test limit that actually constrains the data.

For BAL replay, Amsterdam does not use a fixed account-row cap. The rule is gas-derived:

bal_items <= block_gas_limit / 2000
bal_items = account addresses + unique storage keys

The source of truth is execution-specs/src/ethereum/forks/amsterdam/block_access_lists.py plus execution-specs/src/ethereum/forks/amsterdam/vm/gas.py.

This means a complete static layout is complete only relative to a declared maximum supported actual BAL item count, not merely a declared block gas limit. For the execution-specs default block gas limit of 120,000,000, the BAL item budget is 60,000. The current emitted static replay arenas are sized for 100,000 BAL items (the 200M target); the older 500,000-item/1G layout is historical. A layout with a declared capacity must cover both extreme shapes:

• many account rows, which stress basr_* account-record arrays and the top-level bsr_* state-change arrays;
• one/few accounts with many storage keys, which stress per-account storage replay arrays such as baap_storage_desc, baap_storage_paths, baap_storage_delete_paths, and baap_storage_values. The baap_storage_delete_paths child is historical/probe-only in the current guest; the emitted RegionMap.dataUnionChildren has no such symbol.

Do not resize only the first array that failed. Follow every index that derives from the same count and resize the matching backing storage together.