How Block Access Lists are implemented in ethrex

2026-05-23T00:00:00+00:00

A Block Access List</a> is a structured, per-block record of every account and storage slot touched during execution, with the post-execution values. The top-level shape is List[AccountChanges]</code>, one entry per touched address. It lives in two places: a new block_access_list_hash</code> field in the block header (keccak256(rlp.encode(bal))</code>), and the BAL itself transmitted alongside the block via the Engine API.</p>

A BAL exists because of what it lets a validator do: prefetch state without speculating, execute transactions in parallel with disjoint per-tx views, and merkleize the post-state root concurrently with the EVM. All three are possible because the BAL declares up front what the block will touch and what each touch will produce. This post is the anatomy of how ethrex implements both sides: producing a BAL while executing a block, and consuming a BAL to validate one in parallel.</p>

Most of the code referenced below is in crates/common/types/block_access_list.rs</code></a> and crates/common/validation.rs</code></a>, with the parallel execution wiring in crates/vm/backends/levm/mod.rs</code></a>.</p>

Pinned to ethrex main</code> at commit c0995b947</code> and bal-devnet-7. The EIP and ethrex are both in active development.</p>

The data structures</h2>
Reading the types top-down is the fastest way in. The top of the tree is BlockAccessList</code>, just a vector of per-address entries:</p>
pub struct</span> BlockAccessList</span> {</span></span>
    inner</span>:</span> Vec</span><</span>AccountChanges</span>>,</span></span>
}</span></span></code></pre>
Each AccountChanges</code> is an address plus five vectors, one per kind of touch:</p>
pub struct</span> AccountChanges</span> {</span></span>
    pub</span> address</span>:</span> Address</span>,</span></span>
    pub</span> storage_changes</span>:</span> Vec</span><</span>SlotChange</span>>,</span></span>
    pub</span> storage_reads</span>:</span> Vec</span><</span>U256</span>>,</span></span>
    pub</span> balance_changes</span>:</span> Vec</span><</span>BalanceChange</span>>,</span></span>
    pub</span> nonce_changes</span>:</span> Vec</span><</span>NonceChange</span>>,</span></span>
    pub</span> code_changes</span>:</span> Vec</span><</span>CodeChange</span>>,</span></span>
}</span></span></code></pre>
The split between storage_changes</code> and storage_reads</code> matters: a read is a slot that was loaded but not written, a change is a slot that was written. Same for everything else, except reads only exist for storage. Touching an address with no state change still puts the address in the BAL with empty vectors.</p>
The leaf types are all "block access index + post-state value" pairs:</p>
pub struct</span> StorageChange</span> {</span></span>
    pub</span> block_access_index</span>:</span> u32</span>,</span></span>
    pub</span> post_value</span>:</span> U256</span>,</span></span>
}</span></span>
</span>
pub struct</span> BalanceChange</span> {</span></span>
    pub</span> block_access_index</span>:</span> u32</span>,</span></span>
    pub</span> post_balance</span>:</span> U256</span>,</span></span>
}</span></span>
</span>
pub struct</span> NonceChange</span> {</span></span>
    pub</span> block_access_index</span>:</span> u32</span>,</span></span>
    pub</span> post_nonce</span>:</span> u64</span>,</span></span>
}</span></span>
</span>
pub struct</span> CodeChange</span> {</span></span>
    pub</span> block_access_index</span>:</span> u32</span>,</span></span>
    pub</span> new_code</span>:</span> Bytes</span>,</span></span>
}</span></span></code></pre>
SlotChange</code> groups changes by slot:</p>
pub struct</span> SlotChange</span> {</span></span>
    pub</span> slot</span>:</span> U256</span>,</span></span>
    pub</span> slot_changes</span>:</span> Vec</span><</span>StorageChange</span>>,</span></span>
}</span></span></code></pre>
The recurring rule across all of them: post-state only. The EIP is explicit: "If a storage slot's value is changed but its post-transaction value is equal to its pre-transaction value, the slot MUST NOT be recorded as modified." That rule sounds simple. It isn't.</p>
The recorder</h2>
The BAL is not built incrementally by executing the EVM and appending. It's built by feeding execution events into a BlockAccessListRecorder</code>, which accumulates everything, and consuming it at the end of the block:</p>
pub struct</span> BlockAccessListRecorder</span> {</span></span>
    current_index</span>:</span> u32</span>,</span></span>
    touched_addresses</span>:</span> IndexSet</span><</span>Address</span>>,</span></span>
    storage_reads</span>:</span> IndexMap</span><</span>Address</span>,</span> IndexSet</span><</span>U256</span>>>,</span></span>
    storage_writes</span>:</span> BTreeMap</span><</span>Address</span>,</span> BTreeMap</span><</span>U256</span>,</span> Vec</span><(</span>u32</span>,</span> U256</span>)>>>,</span></span>
    initial_balances</span>:</span> IndexMap</span><</span>Address</span>,</span> U256</span>>,</span></span>
    tx_initial_storage</span>:</span> BTreeMap</span><(</span>Address</span>,</span> U256</span>),</span> U256</span>>,</span></span>
    tx_initial_code</span>:</span> BTreeMap</span><</span>Address</span>,</span> Bytes</span>>,</span></span>
    balance_changes</span>:</span> BTreeMap</span><</span>Address</span>,</span> Vec</span><(</span>u32</span>,</span> U256</span>)>>,</span></span>
    nonce_changes</span>:</span> BTreeMap</span><</span>Address</span>,</span> Vec</span><(</span>u32</span>,</span> u64</span>)>>,</span></span>
    code_changes</span>:</span> BTreeMap</span><</span>Address</span>,</span> Vec</span><(</span>u32</span>,</span> Bytes</span>)>>,</span></span>
    addresses_with_initial_code</span>:</span> IndexSet</span><</span>Address</span>>,</span></span>
    reads_promoted_to_writes</span>:</span> BTreeMap</span><</span>Address</span>,</span> Vec</span><</span>U256</span>>>,</span></span>
    in_system_call</span>:</span> bool</span>,</span></span>
}</span></span></code></pre>
The choice of IndexSet</code> and IndexMap</code> over BTreeMap</code> for some fields isn't aesthetic. It's for the revert mechanism below: those types let us snapshot a length and truncate back to it, instead of cloning the whole structure per call frame.</p>
The lifecycle looks like this:</p>

new()</code> at the start of the block.</li>
set_block_access_index(0)</code> for the pre-execution system contracts (EIP-2935 history, EIP-4788 beacon root, etc.).</li>
For each transaction i</code> (1-indexed), set_block_access_index(i)</code>, then execute the tx, with the EVM calling record_storage_read</code>, record_storage_write</code>, record_balance_change</code>, etc.</li>
set_block_access_index(n+1)</code> for post-execution (withdrawals).</li>
Consume the recorder into the final BlockAccessList</code>.</li>
</ol>
The EVM doesn't care about BAL. It just emits access events. The recorder is the only thing that knows about block access indices, ordering, or filtering.</p>
Revert semantics and checkpoints</h2>
The EIP says: "State changes from reverted calls are discarded, but all accessed addresses must be included." This sounds like a footnote and is actually the most annoying part of the implementation.</p>
The distinction is: touches</em> persist across reverts, state changes</em> don't. If a CALL</code> revert undoes a write, the slot still needs to appear in the BAL (because the SLOAD happened), but as a read, not a write. The recorder needs to be able to roll back exactly the state-change parts while keeping touched addresses and read sets intact.</p>
ethrex uses two checkpoint types. The first is for inner-call reverts:</p>
pub struct</span> BlockAccessListCheckpoint</span> {</span></span>
    reads_promoted_len</span>:</span> BTreeMap</span><</span>Address</span>,</span> usize</span>>,</span></span>
    storage_writes_len</span>:</span> BTreeMap</span><</span>Address</span>,</span> BTreeMap</span><</span>U256</span>,</span> usize</span>>>,</span></span>
    balance_changes_len</span>:</span> BTreeMap</span><</span>Address</span>,</span> usize</span>>,</span></span>
    nonce_changes_len</span>:</span> BTreeMap</span><</span>Address</span>,</span> usize</span>>,</span></span>
    code_changes_len</span>:</span> BTreeMap</span><</span>Address</span>,</span> usize</span>>,</span></span>
}</span></span></code></pre>
Notice what's missing: there's no touched_addresses_len</code> here, and no storage_reads</code>. Both persist across the revert. The checkpoint only captures lengths</em>, and restoring it truncates each vector back to its captured size. No cloning of the recorder, no copying of state. Take a checkpoint before a CALL</code>, restore it on revert.</p>
The second checkpoint is for a different case: a transaction during block building that fails validation entirely (gas underpriced after re-execution, etc.) and needs to be fully erased from the recorder:</p>
pub struct</span> TxCheckpoint</span> {</span></span>
    inner</span>:</span> BlockAccessListCheckpoint</span>,</span></span>
    current_index</span>:</span> u32</span>,</span></span>
    touched_addresses_len</span>:</span> usize</span>,</span></span>
    storage_reads_lens</span>:</span> IndexMap</span><</span>Address</span>,</span> usize</span>>,</span></span>
    initial_balances_len</span>:</span> usize</span>,</span></span>
    addresses_with_initial_code_len</span>:</span> usize</span>,</span></span>
}</span></span></code></pre>
This one does</em> capture touched addresses and read lengths, because for a fully-rejected tx, those touches shouldn't exist either. Same trick: lengths only, restore is truncate()</code> and Vec::resize()</code>.</p>
The reason both are length-based and not copy-based: a tx can have hundreds of call frames. Cloning the recorder per frame would tip a state-heavy block into OOM. Lengths are O(addresses_changed) per checkpoint, restore is O(items_to_drop).</p>
Net-zero filtering</h2>
Back to the EIP rule: "If a storage slot's value is changed but its post-transaction value is equal to its pre-transaction value, the slot MUST NOT be recorded as modified."</p>
This is a per-transaction rule, not per-call. You can write slot[k] = 5</code> then slot[k] = 0</code> (its original value) within the same tx and the BAL should show no storage change. You also can't just suppress the write at write-time, because you don't know the final value until the tx is done.</p>
The recorder solves this with tx_initial_storage</code>: a BTreeMap<(Address, U256), U256></code> capturing the pre-tx value of every slot first written during the current tx. When set_block_access_index</code> is called to move to the next transaction, filter_net_zero_storage</code> runs:</p>
fn</span> filter_net_zero_storage</span>(</span>&</span>mut</span> self</span>) {</span></span>
    let</span> current_idx</span> =</span> self</span>.</span>current_index;</span></span>
    let mut</span> slots_to_convert</span>:</span> Vec</span><(</span>Address</span>,</span> U256</span>)></span> =</span> Vec</span>::</span>new</span>();</span></span>
</span>
    for</span> ((addr, slot), pre_value)</span> in</span> &</span>self</span>.</span>tx_initial_storage {</span></span>
        if let</span> Some</span>(slots)</span> =</span> self</span>.</span>storage_writes</span>.</span>get</span>(addr)</span></span>
            &&</span> let</span> Some</span>(changes)</span> =</span> slots</span>.</span>get</span>(slot)</span></span>
        {</span></span>
            let</span> final_value</span> =</span> changes</span></span>
                .</span>iter</span>()</span></span>
                .</span>filter</span>(</span>|</span>(idx, _)</span>| *</span>idx</span> ==</span> current_idx)</span></span>
                .</span>next_back</span>()</span></span>
                .</span>map</span>(</span>|</span>(_, val)</span>| *</span>val);</span></span>
</span>
            if let</span> Some</span>(final_val)</span> =</span> final_value</span></span>
                &&</span> final_val</span> == *</span>pre_value</span></span>
            {</span></span>
                slots_to_convert</span>.</span>push</span>((</span>*</span>addr,</span> *</span>slot));</span></span>
            }</span></span>
        }</span></span>
    }</span></span>
</span>
    for</span> (addr, slot)</span> in</span> slots_to_convert {</span></span>
        // remove the write entries, undo any read-to-write promotion,</span></span>
        // and re-insert as a read</span></span>
        // ...</span></span>
        self</span>.</span>storage_reads</span>.</span>entry</span>(addr)</span>.</span>or_default</span>()</span>.</span>insert</span>(slot);</span></span>
    }</span></span>
}</span></span></code></pre>
The subtle part is the last step: a net-zero write doesn't disappear, it downgrades</em> to a read. The slot was still touched. If the slot was already a read that got promoted to a write earlier in the tx (because of an SSTORE), we have to undo the promotion too. There's a parallel filter_net_zero_code</code> doing the same dance for code changes (delegate then reset in one tx should produce no code change).</p>
This is one of those rules that is easy to read in the EIP and then takes three review rounds to get right in code.</p>
Block access index semantics</h2>
Every change in the BAL has an index. The indices are not just transaction numbers; they encode the execution phase:</p>

Edgar Luque - performance

How Block Access Lists are implemented in ethrex

`Block access index semantics</h2> Every change in the BAL has an index. The indices are not just transaction numbers; they encode the execution phase:</p>`