Fluffy: Move AsyncEvmStateBackend into separate file and update documentation in comments (#3271)

* Move AsyncEvmStateBackend into separate file.

* Update documentation/comments.

* Use block header instead of state root in async evm backend.

Author: bhartnett

fluffy/evm/async_evm.nim

@@ -14,30 +14,30 @@ import
   chronicles,
   stint,
   results,
-  eth/common/[base, hashes, addresses, accounts, headers, transactions],
+  eth/common/[base, addresses, accounts, headers, transactions],
   ../../execution_chain/db/[ledger, access_list],
   ../../execution_chain/common/common,
   ../../execution_chain/transaction/call_evm,
-  ../../execution_chain/evm/[types, state, evm_errors]
+  ../../execution_chain/evm/[types, state, evm_errors],
+  ./async_evm_backend
 
-from web3/eth_api_types import TransactionArgs
-from web3/eth_api_types import Quantity
+from web3/eth_api_types import TransactionArgs, Quantity
 
 export
-  results, chronos, hashes, addresses, accounts, headers, TransactionArgs, CallResult,
+  async_evm_backend, results, chronos, headers, TransactionArgs, CallResult,
   transactions.AccessList, GasInt
 
 logScope:
   topics = "async_evm"
 
-# The Portal EVM uses the Nimbus in-memory EVM to execute transactions using the
-# portal state network state data. Currently only call is supported.
+# The Async EVM uses the Nimbus in-memory EVM to execute transactions using state
+# data fetched asyncronously from a supplied state backend.
 #
-# Rather than wire in the portal state lookups into the EVM directly, the approach
+# Rather than wire in the async state lookups into the EVM directly, the approach
 # taken here is to optimistically execute the transaction multiple times with the
 # goal of building the correct access list so that we can then lookup the accessed
-# state from the portal network, store the state in the in-memory EVM and then
-# finally execute the transaction using the correct state. The Portal EVM makes
+# state from the async state backend, store the state in the in-memory EVM and then
+# finally execute the transaction using the correct state. The Async EVM makes
 # use of data in memory during the call and therefore each piece of state is never
 # fetched more than once. We know we have found the correct access list if it
 # doesn't change after another execution of the transaction.
@@ -48,9 +48,8 @@ logScope:
 # call given that we gain the ability to fetch the state concurrently.
 #
 # There are multiple reasons for choosing this approach:
-# - Firstly updating the existing Nimbus EVM to support using a different state
-#   backend (portal state in this case) is difficult and would require making
-#   non-trivial changes to the EVM.
+# - Firstly updating the existing Nimbus EVM to support using different state
+#   backends is difficult and would require making non-trivial changes to the EVM.
 # - This new approach allows us to look up the state concurrently in the event that
 #   multiple new state keys are discovered after executing the transaction. This
 #   should in theory result in improved performance for certain scenarios. The
@@ -82,23 +81,6 @@ type
     address: Address
     codeFut: Future[Opt[seq[byte]]]
 
-  GetAccountProc* = proc(stateRoot: Hash32, address: Address): Future[Opt[Account]] {.
-    async: (raises: [CancelledError])
-  .}
-
-  GetStorageProc* = proc(
-    stateRoot: Hash32, address: Address, slotKey: UInt256
-  ): Future[Opt[UInt256]] {.async: (raises: [CancelledError]).}
-
-  GetCodeProc* = proc(stateRoot: Hash32, address: Address): Future[Opt[seq[byte]]] {.
-    async: (raises: [CancelledError])
-  .}
-
-  AsyncEvmStateBackend* = object
-    getAccount: GetAccountProc
-    getStorage: GetStorageProc
-    getCode: GetCodeProc
-
   AsyncEvm* = ref object
     com: CommonRef
     backend: AsyncEvmStateBackend
@@ -114,14 +96,6 @@ func init(
 func init(T: type CodeQuery, adr: Address, fut: Future[Opt[seq[byte]]]): T =
   T(address: adr, codeFut: fut)
 
-proc init*(
-    T: type AsyncEvmStateBackend,
-    accProc: GetAccountProc,
-    storageProc: GetStorageProc,
-    codeProc: GetCodeProc,
-): T =
-  AsyncEvmStateBackend(getAccount: accProc, getStorage: storageProc, getCode: codeProc)
-
 proc init*(
     T: type AsyncEvm, backend: AsyncEvmStateBackend, networkId: NetworkId = MainNet
 ): T =
@@ -165,7 +139,7 @@ proc callFetchingState(
     fetchedCode = initHashSet[Address]()
 
   # Set code of the 'to' address in the EVM so that we can execute the transaction
-  let code = (await evm.backend.getCode(header.stateRoot, to)).valueOr:
+  let code = (await evm.backend.getCode(header, to)).valueOr:
     return err("Unable to get code")
   vmState.ledger.setCode(to, code)
   fetchedCode.incl(to)
@@ -215,8 +189,7 @@ proc callFetchingState(
           let slotIdx = (adr, v.storageSlot)
           if slotIdx notin fetchedStorage:
             debug "Fetching storage slot", address = adr, slotKey = v.storageSlot
-            let storageFut =
-              evm.backend.getStorage(header.stateRoot, adr, v.storageSlot)
+            let storageFut = evm.backend.getStorage(header, adr, v.storageSlot)
             if not stateFetchDone:
               storageQueries.add(StorageQuery.init(adr, v.storageSlot, storageFut))
               if not optimisticStateFetch:
@@ -226,15 +199,15 @@ proc callFetchingState(
 
           if adr notin fetchedAccounts:
             debug "Fetching account", address = adr
-            let accFut = evm.backend.getAccount(header.stateRoot, adr)
+            let accFut = evm.backend.getAccount(header, adr)
             if not stateFetchDone:
               accountQueries.add(AccountQuery.init(adr, accFut))
               if not optimisticStateFetch:
                 stateFetchDone = true
 
           if v.codeTouched and adr notin fetchedCode:
             debug "Fetching code", address = adr
-            let codeFut = evm.backend.getCode(header.stateRoot, adr)
+            let codeFut = evm.backend.getCode(header, adr)
             if not stateFetchDone:
               codeQueries.add(CodeQuery.init(adr, codeFut))
               if not optimisticStateFetch:

fluffy/evm/async_evm_backend.nim

@@ -0,0 +1,38 @@
+# Fluffy
+# Copyright (c) 2025 Status Research & Development GmbH
+# Licensed and distributed under either of
+#   * MIT license (license terms in the root directory or at https://opensource.org/licenses/MIT).
+#   * Apache v2 license (license terms in the root directory or at https://www.apache.org/licenses/LICENSE-2.0).
+# at your option. This file may not be copied, modified, or distributed except according to those terms.
+
+{.push raises: [].}
+
+import chronos, stint, eth/common/[headers, addresses, accounts]
+
+export chronos, stint, headers, addresses, accounts
+
+type
+  GetAccountProc* = proc(header: Header, address: Address): Future[Opt[Account]] {.
+    async: (raises: [CancelledError])
+  .}
+
+  GetStorageProc* = proc(
+    header: Header, address: Address, slotKey: UInt256
+  ): Future[Opt[UInt256]] {.async: (raises: [CancelledError]).}
+
+  GetCodeProc* = proc(header: Header, address: Address): Future[Opt[seq[byte]]] {.
+    async: (raises: [CancelledError])
+  .}
+
+  AsyncEvmStateBackend* = ref object
+    getAccount*: GetAccountProc
+    getStorage*: GetStorageProc
+    getCode*: GetCodeProc
+
+proc init*(
+    T: type AsyncEvmStateBackend,
+    accProc: GetAccountProc,
+    storageProc: GetStorageProc,
+    codeProc: GetCodeProc,
+): T =
+  AsyncEvmStateBackend(getAccount: accProc, getStorage: storageProc, getCode: codeProc)

fluffy/evm/async_evm_portal_backend.nim

@@ -7,21 +7,21 @@
 
 {.push raises: [].}
 
-import ../network/state/state_endpoints, ./async_evm
+import ../network/state/state_endpoints, ./async_evm_backend
 
 proc toAsyncEvmStateBackend*(stateNetwork: StateNetwork): AsyncEvmStateBackend =
   let
     accProc = proc(
-        stateRoot: Hash32, address: Address
+        header: Header, address: Address
     ): Future[Opt[Account]] {.async: (raw: true, raises: [CancelledError]).} =
-      stateNetwork.getAccount(stateRoot, address)
+      stateNetwork.getAccount(header.stateRoot, address)
     storageProc = proc(
-        stateRoot: Hash32, address: Address, slotKey: UInt256
+        header: Header, address: Address, slotKey: UInt256
     ): Future[Opt[UInt256]] {.async: (raw: true, raises: [CancelledError]).} =
-      stateNetwork.getStorageAtByStateRoot(stateRoot, address, slotKey)
+      stateNetwork.getStorageAtByStateRoot(header.stateRoot, address, slotKey)
     codeProc = proc(
-        stateRoot: Hash32, address: Address
+        header: Header, address: Address
     ): Future[Opt[seq[byte]]] {.async: (raw: true, raises: [CancelledError]).} =
-      stateNetwork.getCodeByStateRoot(stateRoot, address)
+      stateNetwork.getCodeByStateRoot(header.stateRoot, address)
 
   AsyncEvmStateBackend.init(accProc, storageProc, codeProc)

fluffy/tests/evm/async_evm_test_backend.nim

@@ -7,7 +7,7 @@
 
 {.used.}
 
-import std/tables, ../../evm/async_evm
+import std/tables, ../../evm/async_evm_backend
 
 type TestEvmState* = ref object
   accounts: Table[Address, Account]
@@ -43,15 +43,15 @@ proc toAsyncEvmStateBackend*(testState: TestEvmState): AsyncEvmStateBackend =
   # State root is ignored because TestEvmState only stores a single state
   let
     accProc = proc(
-        stateRoot: Hash32, address: Address
+        header: Header, address: Address
     ): Future[Opt[Account]] {.async: (raises: [CancelledError]).} =
       Opt.some(testState.getAccount(address))
     storageProc = proc(
-        stateRoot: Hash32, address: Address, slotKey: UInt256
+        header: Header, address: Address, slotKey: UInt256
     ): Future[Opt[UInt256]] {.async: (raises: [CancelledError]).} =
       Opt.some(testState.getStorage(address, slotKey))
     codeProc = proc(
-        stateRoot: Hash32, address: Address
+        header: Header, address: Address
     ): Future[Opt[seq[byte]]] {.async: (raises: [CancelledError]).} =
       Opt.some(testState.getCode(address))