feat: pass StateOracle as a parameter to `state_transition` #1371

kevaundray · 2025-08-17T17:36:29Z

What was wrong?

Not mergable in current state

Related to #1209

How was it fixed?

This initial PR is made to start discussion on implementing this. Something like this would be useful for both:

zkEVMs that need to create merkle proofs based on state that has been read
Block level access lists that need to keep track of state changes across the block

The idea being that an oracle/state object can be wrapped to record whenever state has been accessed/modified.

Notes

The original issue defined a quite minimal interface, this PR tries to reduce the diff by first introducing the idea of an Oracle and making all of the previous state management functions become methods.

To get what the original PR described, I believe we would move most of the methods into something like an EVMOracle structure that depends on a MerkleOracle

This PR does not modify the monkey patching that happens with the optimized impl for State

kevaundray · 2025-08-17T17:37:38Z

src/ethereum/osaka/fork.py

+def state_transition(chain: BlockChain, block: Block, oracle=None) -> None:
    """


main TLDR; the object that is used to fetch state is now an explicit parameter to the state transition function instead of it being implicit

kevaundray · 2025-08-17T17:38:50Z

src/ethereum/osaka/fork.py

-    sender_account = get_account(block_env.state, sender)
+    sender_account = block_env.oracle.get_account(sender)


Most changes look like this:

Before:

func(state, params)

After:

oracle.func(params)

kevaundray · 2025-08-17T17:40:08Z

src/ethereum/state_oracle/interface.py

+# Use generic types for compatibility across forks
+Account = Any
+Address = Bytes20


I initially thought that this interface would fork agnostic, but perhaps it makes sense to have one per fork?

kevaundray · 2025-08-17T17:40:23Z

src/ethereum/state_oracle/interface.py

+        This is required for SSTORE gas calculations per EIP-2200.
+        The implementation should use state snapshots/checkpoints to track
+        pre-transaction values.
+        TODO: The oracle does not have a `begin_transaction` method, so it kind of breaks here.


kevaundray · 2025-08-17T17:40:40Z

src/ethereum/state_oracle/memory_oracle.py

+from ethereum_types.bytes import Bytes20, Bytes32
+from ethereum_types.numeric import Uint
+
+# TODO: This file is current Osaka specific -- we could move state.py into here to mitigate this.


kevaundray · 2025-08-17T17:49:36Z

cc @SamWilsn @gurukamath since you were tagged in that issue -- would be good to know if this is directionally what you were thinking first, since there is likely some cleanup required

kevaundray · 2025-08-17T19:05:33Z

src/ethereum/state_oracle/interface.py

+    def get_storage(
+        self, address: Address, key: Bytes32  # noqa: U100
+    ) -> Bytes32:  # noqa: U100
+        """Get storage value at `key` for the given `address`."""


noqa: U100 was needed for tox lint

kevaundray · 2025-08-17T19:08:28Z

src/ethereum/state_oracle/interface.py

+    def account_has_code_or_nonce(
+        self, address: Address  # noqa: U100
+    ) -> bool:  # noqa: U100
+        """
+        Check if account has non-zero code or nonce.
+
+        Used during contract creation to check if address is available.
+        """
+
+    def account_has_storage(self, address: Address) -> bool:  # noqa: U100
+        """
+        Check if account has any storage slots.
+
+        Used during contract creation to check if address is available.
+        """


As noted in the PR description; methods like these can be moved into something like an "EVMOracle", since they can be implemented using get_account plus a few extra LOC to check if there is code/nonce/storage.

The user would then only implement MerkleOracle, which then gets wrapped in an EVMOracle so that the EVM can use the relevant methods

This is the motivation behind the minimal state interface in #1209. Everything that isn't off the shelf that can be done in the specs should be done there, even if the performance is terrible.

kevaundray · 2025-08-17T19:10:59Z

src/ethereum/osaka/vm/instructions/environment.py

@@ -19,7 +19,6 @@
 from ethereum.utils.numeric import ceil32



blockhash was not modified, but that should also likely be a part of "state" since 2935 has been implemented

kevaundray · 2025-08-17T19:37:20Z

src/ethereum_spec_tools/evm_tools/t8n/__init__.py

+        # TODO: Hack imo
+        if self.fork.is_after_fork("ethereum.osaka"):
+            from ethereum.state_oracle import MemoryMerkleOracle
+
+            oracle = MemoryMerkleOracle(self.alloc.state)
+            state_or_oracle = {"oracle": oracle}
+        else:
+            state_or_oracle = {"state": self.alloc.state}


Since the change currently only applies to Osaka

There are quite a few places in the ethereum_spec_tools directory that rely on accessing the state parameter explicitly, so I'll wait to see if this is directionally correct before modifying those

SamWilsn · 2025-08-18T19:39:57Z

Our primary concern is readability, and I fear feeding the state oracle through everything will hurt that. Would an approach like our trace implementation work?

Otherwise I think this looks pretty good!

kevaundray · 2025-08-18T20:11:00Z

Our primary concern is readability, and I fear feeding the state oracle through everything will hurt that. Would an approach like our trace implementation work?

Otherwise I think this looks pretty good!

I have no strong opinion on how its implemented :) -- when you say feeding the state oracle through everything, do you mean places outside of BlockEnv? Since in most places we are replacing block_env.state with block_env.oracle

kevaundray · 2025-08-18T20:36:53Z

@SamWilsn have added a commit to an approach that is closer to evm_trace; with a global oracle -- was this what you had in mind?

kevaundray · 2025-08-18T21:02:11Z

src/ethereum_spec_tools/evm_tools/t8n/__init__.py

+            # TODO: Remove this, since its not being used.
            "state": self.alloc.state,


Need to remove state from BlockEnvironment to finish this

SamWilsn · 2025-08-19T23:28:23Z

src/ethereum/state_oracle/__init__.py

+    return old
+
+
+def get_state_oracle() -> MerkleOracle:


You're still returning an object here. We want this to be as flat as possible. For each function on the MerkleOracle, create a function in this file exposing it.

SamWilsn · 2025-08-19T23:29:51Z

src/ethereum/state_oracle/__init__.py

+    if _state_oracle is None:
+        raise RuntimeError(
+            "No global state oracle set. Call set_state_oracle() first."
+        )


There should always be a default. That way the reader can easily trace the implementation of the unmodified spec. The average reader isn't going to be going through the whole codebase (instead just reading a function or implementing an EIP), so locality is very important.

I think this implies that the state_oracl folder will be copied between forks, unless we have a fork agnostic default

I also think that we would need some state to create the default oracle with

SamWilsn · 2025-08-19T23:37:03Z

src/ethereum/state_oracle/interface.py

+Address = Bytes20
+
+
+class MerkleOracle(Protocol):


Hm, so we have a vague rule that if something changes between forks, it must be placed into the fork's folder. For example, keccak256 is used in every fork and isn't likely to disappear, so it lives in ethereum.crypto, where as Address might get bumped to 32 bytes in the future, so it's defined per fork.

If the MPT is going to get replaced (or is fairly likely), it might be best to define it per fork.

related to #1371 (comment)

SamWilsn · 2025-08-19T23:37:35Z

src/ethereum/state_oracle/interface.py

+        self, address: Address  # noqa: U100
+    ) -> Account:  # noqa: U100


I think if you raise NotImplementedError it mutes the linter, but I'm not 100% sure on that.

SamWilsn · 2025-08-19T23:39:56Z

src/ethereum/state_oracle/interface.py

+Address = Bytes20
+
+
+class MerkleOracle(Protocol):


"Oracle" is a bit of a foreign term for non-cryptography folks. The base protocol could just be State.

That said, we've managed to keep protocols and most OOP out of the spec so far, so we might want to rethink how we organize this.

SamWilsn · 2025-08-19T23:45:17Z

src/ethereum/state_oracle/interface.py

+    def account_has_code_or_nonce(
+        self, address: Address  # noqa: U100
+    ) -> bool:  # noqa: U100
+        """
+        Check if account has non-zero code or nonce.
+
+        Used during contract creation to check if address is available.
+        """
+
+    def account_has_storage(self, address: Address) -> bool:  # noqa: U100
+        """
+        Check if account has any storage slots.
+
+        Used during contract creation to check if address is available.
+        """


This is the motivation behind the minimal state interface in #1209. Everything that isn't off the shelf that can be done in the specs should be done there, even if the performance is terrible.

kevaundray · 2025-08-21T11:26:28Z

Discussed with @SamWilsn offline and this may not be strictly better than what is already on main wrt the design constraints for the execution specs. Putting this back in draft.

The main change I'm looking to add is state tracking, which this should have made easier. If not, we can close it and make a separate PR for state tracking

add code

974cbcf

kevaundray commented Aug 17, 2025

View reviewed changes

kevaundray added 2 commits August 17, 2025 18:42

revert format

c214f9f

remove write

4db099e

kevaundray added 5 commits August 17, 2025 18:56

format

3112a1c

formatting

a340007

python format

ed85d8f

python lint

ad9dd18

python lint

d12c5d4

kevaundray commented Aug 17, 2025

View reviewed changes

temp: hack

72df534

kevaundray commented Aug 17, 2025

View reviewed changes

evm_tracer like approach

c07b175

kevaundray force-pushed the kw/state-oracle branch from 6604ee8 to c07b175 Compare August 18, 2025 20:35

tox

4a46cb5

kevaundray commented Aug 18, 2025

View reviewed changes

kevaundray mentioned this pull request Aug 19, 2025

Add Specs: EIP-7928: Block-level Access Lists #1338

Closed

SamWilsn reviewed Aug 19, 2025

View reviewed changes

kevaundray marked this pull request as draft August 21, 2025 11:26

spencer-tb mentioned this pull request Aug 28, 2025

feat(fill): add a plugin for optional execution witness generation ethereum/execution-spec-tests#2066

Merged

5 tasks

fselmo mentioned this pull request Aug 30, 2025

feat(fork,bal): Adds basic Amsterdam fork setup and Block Access List support #1381

Open

		def state_transition(chain: BlockChain, block: Block, oracle=None) -> None:
		"""

		sender_account = get_account(block_env.state, sender)
		sender_account = block_env.oracle.get_account(sender)

		# TODO: Remove this, since its not being used.
		"state": self.alloc.state,

		self, address: Address # noqa: U100
		) -> Account: # noqa: U100

feat: pass StateOracle as a parameter to state_transition #1371

Are you sure you want to change the base?

feat: pass StateOracle as a parameter to state_transition #1371

Uh oh!

Conversation

kevaundray commented Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was wrong?

How was it fixed?

Notes

Uh oh!

kevaundray Aug 17, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kevaundray commented Aug 17, 2025 • 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!

SamWilsn commented Aug 18, 2025

Uh oh!

kevaundray commented Aug 18, 2025

Uh oh!

kevaundray commented Aug 18, 2025

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!

kevaundray Aug 20, 2025 • 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!

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!

kevaundray commented Aug 21, 2025

Uh oh!

Uh oh!

feat: pass StateOracle as a parameter to `state_transition` #1371

feat: pass StateOracle as a parameter to `state_transition` #1371

kevaundray commented Aug 17, 2025 •

edited

Loading

kevaundray Aug 17, 2025 •

edited

Loading

kevaundray commented Aug 17, 2025 •

edited

Loading

kevaundray Aug 20, 2025 •

edited

Loading