Ledger based BAL tracker by jangko · Pull Request #4269 · status-im/nimbus-eth1

jangko · 2026-05-26T13:25:40Z

As per Ben request, do not merge until all BAL missing features have been implemented.
The original BAL tracker need to be removed if we are going to merge this PR.
Revert BAL workaround of delegated target in CALL* opcodes #4257
Missing BAL test cases of contract creation collision edge cases ethereum/execution-specs#2914
Missing BAL test cases related to EIP-6780 self destruct ethereum/execution-specs#2920
Missing BAL test cases related to EIP-161 state clearing ethereum/execution-specs#2922
Benchmark vs original BAL tracker

bhartnett · 2026-06-03T12:38:32Z


 proc execPrecompile*(c: Computation, precompile: Precompiles) =
-  if c.balTrackerEnabled:
-    c.vmState.balTracker.trackAddressAccess(precompileAddrs[precompile])


If removing this, how do precompile accesses get tracked?

nimbus-eth1/execution_chain/evm/interpreter_dispatch.nim

Line 75 in 030715e

ledger.addBalance(c.msg.contractAddress, c.msg.value)

nimbus-eth1/execution_chain/evm/interpreter/op_handlers/oph_call.nim

Line 102 in 030715e

let delegateTo = parseDelegationAddress(c.getCode(codeAddress)).valueOr:

These two places ensure both top level frame and child frame record the access to precompile address.

Actually it looks like there is a missing performance optimisation here. Inside the Ledger addBalance function if delta.isZero we always load the account to check if it is empty for EIP-161 but empty accounts are no longer possible so we could skip this check at some fork boundary (at the merge if I'm not mistaken).

If we apply this optimisation then we might need to track the precompile address separately but I'm pushing for removing precompiles that don't touch the state to be removed from the BAL spec.

Even for delegate call we shouldn't need to load the code when we know the address is a precompile. This is another optimisation we can do.

Probably better we still track the precompile addresses separately until/if it gets removed from the spec so that we can apply these optimisations in our EVM to reduce the amount of state accesses.

I'm working on a few PRs to add in these optimisations.

bhartnett · 2026-06-09T16:06:46Z

    c.execCallOrCreate()
-    ledger.persist(clearEmptyAccount = true)
+    if vmState.balTrackerEnabled:
+      vmState.balLedger.writeToTxFrameAndBAL(ledger)


This means we now write to the BAL builder and check for diffs after every system call which might increase the overall work. Previously we only check if there is a diff to write into the BAL in commitCallFrame after processing all system calls. Will be interesting to see how this performs in benchmarks

Actually this could lead to an incorrect BAL in theory if one system call updated state from A -> B then another system call updates state from B -> A. Might be unlikely to happen in practice but is possible depending on what state updates the system calls do. The diff checking needs to be done once after processing all pre execution system calls and then once after processing all post execution system calls.

If the concerns is about different system call modifies the same account, the BAL builder will only record the last diff. As long as the balAccessIndex is the same, it only moves the recording process from BAL tracker to BAL builder.

The problem is that the builder doesn't handle diff tracking and the diff check runs in writeToTxFrameAndBAL which runs after every system call. So if one pre execution system call (at BAL index 0) writes the state of account 1 from A->B then a B write is added into the builder and then if another system call writes the state of account 1 from B->A then another A write is added to the builder for the account. But in this case there should be no diff because account 1 ends up with the same state as before and so the BAL should have no write included. This would cause the balHash to change.

I see, this will be a tough nut to crack in the ledger.

You might be able to move the writeToTxFrameAndBAL/persist to the point where the previous commitCallFrame was and remove it from this location.

bhartnett · 2026-06-09T16:36:11Z

For historical context the BlockAccessListTracker was loosely based on the BAL tracker in the execution specs code see here: https://github.com/ethereum/execution-specs/pull/1338/changes#diff-bf1fcde011d1f672973f27cd5a023f0921d07b186d5742e76e8d8e77c04b639e

Looks like that part is now moved here: https://github.com/ethereum/execution-specs/pull/1719/changes?mode=single#diff-743bc9d8436e6ac24492b77b87fd11f64bdc40dd8d568e4a449f21c4df198261

Other reasons for implementing the tracker separate from the ledger initially:

The ledger did not support the required pre state collection to detect what state was changed at each transaction boundary (the ledger now supports this with this change)
Pre execution and post execution system calls do not use begin save point and rollback save point pattern and so the BAL tracker was designed to check the diff in the commitCallFrame function for all system calls once for pre execution and once for post execution. With this change the diff is checked after every system call which may not be ideal for performance.
Putting the BAL tracker inside the ledger was considered but I ran into a circular dependency issue because the the tracker depends on the read only ledger to fetch the prestate.
The ledger is used in many situations where bal tracking is not required at all such as in RPC endpoints, async EVM, etc and so keeping it separate made sense.
Separation of concerns: With this change the ledger now implements some logic which is not strictly required for the ledger purpose of reading/writing to the db. It mixes in BAL tracking requirements (recording reads and holding the original accounts for the diff checking) into the ledger. The original implementation makes all this logic self contained in the separate bal tracker which was contained in the block_access_list directory.

bhartnett · 2026-06-09T16:44:55Z

The downside of using the ledger for the tracking is that the BAL must match exactly the state read and written by the ledger. Basically the state reading in the ledger and the BAL tracking are now coupled together in a way that could in theory create problems in the future if we ever run into a scenario where our state reads/writes need to deviate from what is tracked in the BAL.

jangko · 2026-06-10T01:33:04Z

You are correct about the downside, but it only affecting state reads. Ephemeral account access related to EIP-6780 will not leak to BAL. Other state writes should appear in the BAL.

Currently, there is only one place where we use state reads that is not recorded to bal: read nonce in the txpool and remove transaction with invalid nonce.

Beside the downside, there is also the upside of this design. The code can clearly detect missing test case, and I have found 2 so far, and both of them are being included in the next test release. Using a separate BAL tracker will be very difficult to know what missing test case there are.

But of course we have to benchmark both of them before we decide which one to use.

bhartnett · 2026-06-10T02:03:03Z

You are correct about the downside, but it only affecting state reads. Ephemeral account access related to EIP-6780 will not leak to BAL. Other state writes should appear in the BAL.

Currently, there is only one place where we use state reads that is not recorded to bal: read nonce in the txpool and remove transaction with invalid nonce.

Beside the downside, there is also the upside of this design. The code can clearly detect missing test case, and I have found 2 so far, and both of them are being included in the next test release. Using a separate BAL tracker will be very difficult to know what missing test case there are.

But of course we have to benchmark both of them before we decide which one to use.

Yeah good points. I support this change overall since it cleans up the EVM code somewhat.

Probably the main deciding factor should be the benchmarks.

bhartnett · 2026-06-10T03:11:40Z

+    vmState.balLedger.setBlockAccessIndex(pst.packedTxs.len() + 1)

  # Find out what to do next: accepting this tx or trying the next account
-  let rc = processTransaction(vmState, item.tx, item.sender, rollbackReads = true)


How does this function correctly without rolling back the reads? I don't see this rollbackReads functionality implemented in the new ledger bal tracking.

If I remember correctly when executing a transaction here if it fails we don't want the reads because the transaction won't be included in the block.

BAL only record the root ledger.savePoint, ledger.rollback will prevent the accessed accounts appear in the root savePoint.

And we use separate ledger for txPool and block executor. So no need for rollbackReads.

bhartnett · 2026-06-10T03:23:09Z


+  if ledger.enableBalTracker:
+    if address notin ledger.accountRead:
+      ledger.accountRead[address] = HashSet[UInt256]()


The BAL tracking here is now dependent on the caching. If the ledger.cache already contains the account then we don't track the read. If we were to change the lifetime of the ledger cache in the future the BAL tracking might break.

In my opinion it would be better if the caching does not effect the BAL tracking.

This is added to track account accessed in EVM child frame, but the account itself is removed.
Another approach is to keep the zombified accounts around and accountRead table can be removed.

I think recording the accountReads like this is fine, I just meant that perhaps the read should be tracked before checking the cache so that the read is still tracked on a cache hit.

jangko added 5 commits May 29, 2026 10:17

refactor ledger

d363a8f

preparations

98b6325

ledger based bal tracker implementation

f20158f

Skip failing tests related to EIP-7702 delegateTo of CALL* opcodes

cf8870a

Remove original bal tracker

052a073

jangko force-pushed the ledger-bal branch from a538c7f to 052a073 Compare May 29, 2026 04:35

Remove test_block_access_list_tracker

030715e

bhartnett reviewed Jun 3, 2026

View reviewed changes

jangko added 8 commits June 4, 2026 09:25

Merge branch 'master' into ledger-bal

19c2b0e

Add TxState

511ef7f

Skip bal_call_revert_insufficient_funds.json

fbb991d

Fix feeRecipient reward issue

877064f

Fix ordered list cleanup issue

b119307

Merge branch 'master' into ledger-bal

70a0b4f

Fix merge conflict

cd6ac1a

Fix checkEmptyAccount issue

c2dcbdb

bhartnett reviewed Jun 9, 2026

View reviewed changes

bhartnett reviewed Jun 10, 2026

View reviewed changes

Conversation

jangko commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhartnett commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhartnett commented Jun 9, 2026

Uh oh!

jangko commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bhartnett commented Jun 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jangko Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhartnett Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jangko commented May 26, 2026 •

edited

Loading

bhartnett commented Jun 9, 2026 •

edited

Loading

jangko commented Jun 10, 2026 •

edited

Loading

jangko Jun 11, 2026 •

edited

Loading

bhartnett Jun 10, 2026 •

edited

Loading