Note: if you spot any missing case, feel free to get in touch!
This document describes at a high-level test scenarios for EIP-7748 (overview of the EIP).
The following are main drivers for potential bugs:
stride
allows account partial-migrations i.e., an account is not fully migrated in a single block, so proper resuming of an account migration in multiple blocks should be done.stride
quota.Note that this document describes the test cases at a medium-level of detail to not miss important things that can go wrong. The implemented fixtures might cover more ground than described here.
Rough suggestion on a plan:
execution-spec-test
tests described in this document. Allows to create fine-grained corner cases, fast to run, doesn't require coordination between EL clients or infra support.The above is just an idea. If after 1. EL clients feel confident, we jump directly to 4.
- Implemented test.
- Pending to implement
- Requires testing-framework changes.
To describe the test vectors, we use the following terminology:
FCB test cases are relevant since the EL client might have uninitialized/empty internal variables that track the conversion process. MCB are more common since most of converting blocks are MCBs. LCB situations are special since in this block the conversion process stops (e.g., what if the last account is an EIP161Account).
Here are high-level descriptions of all the cases. We might refer to block XCB in them, meaning we should run each case with XCB as the FCB or MCB. The required stride is implicit under the test-case description.
Given an XCB block, run the following scenarios which convert all mentioned accounts fully in the block:
[EOA]
[Contract]
[EOA, EOA]
[EOA, Contract]
[Contract, EOA]
[Contract, Contract]
These test cases cover situations in which at least one account in a XCB block is partially converted:
[Contract]
where finishes two storage slots before the last one.[Contract]
where finishes one storage slot before the last one.[Contract]
where finishes exactly at the last storage slot (i.e., perfect fit before account data conversion).[(EOA | Contract_A), Contract_B]
.The cases above press on the fact that the conversion for an account needs to walk the account and storage tries. The boundary where the "partial conversion" happens is the main focus of these tests.
These test cover if implementations do proper accounting of code-chunks stride overflow:
[Contract]
with number of chunks bigger than stride, must be converted in a single block.[Contract, EOA]
where the contract #code-chunks is bigger than the stride. Contract
is fully migrated in the block, and EOA
must be converted in the next block.The EIP tries to push hard on simplifying code-chunk migration, and always do it in one go. See this EIP rationale for more details.
In an XCB block:
[EIP161Account, EOA]
:
stride=1
, must skip EIP161Account
and migrate EOA
in this block.These test cases cover special situations that can happen in the last block that migrates state:
When an account is converted it could have been modified since previously executed txs forced writes for the account in the new tree.
[stale EOA]**stride ++ [EOA]
should span two blocksNote that the contract code can’t become stale.
There is a situation where a key that is converted in a block, also matches with a transaction in that same block which writes to the same key.
This is a special case of the section above, but with the tx exactly matching the block where the key is converted. Both writes happen in the same block, and it is useful to test that EL clients pending writes to be flushed at the end of the block are handeled properly.
Test cases:
An EOA can't be partially converted since it spans a single conversion unit. A contract can be in the following partially converted under the following matrix of combinations:
Not all combinations of BD*
and SS*
correspond to this EIP-7748 testing scope:
SS*
case is by by sending a tx to the contract, which means violating the BD1 constraint.This means that, for each of the following setup combinations, execute a tx which access converted & unconverted state for the contract, to verify it isn't read "from the wrong tree":
Important: Test that produce reorgs aren't currently supported without hive. The testing team is planning to add support in the near term.
The tree conversion logic should be reorg aware as any other logic within a block execution. Note that since the tree conversion keys to be migrated in a block are deterministic, a rollback will do the tree conversion for the same set of keys that was already done. The main difference is that the txs in these new blcoks might cause a different interference i.e., converted keys being stale.
To cover these situations we can run all test-vectors from Partial account migration section with a reorg happening in the process. More concretely:
Usually the test-vectors spans 2 blocks since they're trying to cover very specific scenarios, so the blow up factor wouldn't be that much. Also, we don't necessarly need to do this for all tests since we're interested in covering the rewind of internal variables that track the conversion process – but the reorg setup could be generic enough to make it easy to cover all of them if found useful.