feat(types): Add traceable exceptions

Author: marioevz

Diff for: src/ethereum_test_tools/common/__init__.py

@@ -1,6 +1,7 @@
 """
 Common definitions and types.
 """
+
 from .base_types import (
     Address,
     Bloom,
@@ -41,6 +42,7 @@
     JSONEncoder,
     Removable,
     Storage,
+    TraceableException,
     Transaction,
     Withdrawal,
     alloc_to_accounts,
@@ -75,6 +77,7 @@
     "TestParameterGroup",
     "TestPrivateKey",
     "TestPrivateKey2",
+    "TraceableException",
     "Transaction",
     "Withdrawal",
     "ZeroPaddedHexNumber",

Diff for: src/ethereum_test_tools/common/types.py

@@ -28,6 +28,7 @@
 from trie import HexaryTrie
 
 from ethereum_test_forks import Fork
+from evm_transition_tool import EVMTransactionTrace
 
 from ..exceptions import ExceptionList, TransactionException
 from .base_types import Address, Bytes, Hash, HexNumber, Number, ZeroPaddedHexNumber
@@ -63,6 +64,55 @@ def __repr__(self) -> str:
         return "auto"
 
 
+class TraceableException(Exception):
+    """
+    Exception that can use a trace to provide more information.
+    """
+
+    traces: List[List[EVMTransactionTrace]] | None
+
+    def set_traces(self, traces: List[List[EVMTransactionTrace]]):
+        """
+        Set the traces for the exception.
+        """
+        self.traces = traces
+
+    def get_trace_context(
+        self,
+        *,
+        context_address: Optional[Address] = None,
+        opcode_name: Optional[str] = None,
+        stack_item_0: Optional[int] = None,
+        previous_lines: int = 0,
+    ) -> List[str]:
+        """
+        Returns a list of strings with the context of the exception.
+        """
+        lines = []
+        if self.traces:
+            for execution_trace in self.traces:
+                for tx_trace in execution_trace:
+                    for i, trace in enumerate(tx_trace.trace_lines()):
+                        if (
+                            (context_address is None or trace.context_address == context_address)
+                            and (opcode_name is None or trace.opcode_name == opcode_name)
+                            and (
+                                stack_item_0 is None
+                                or (len(trace.stack) > 0 and trace.stack[-1] == stack_item_0)
+                            )
+                        ):
+                            lines += [
+                                *[
+                                    f"    {dict(trace)}"
+                                    for trace in tx_trace.trace_lines()[
+                                        max(0, i - previous_lines) : i
+                                    ]
+                                ],
+                                f"  {dict(trace)}",
+                            ]
+        return lines
+
+
 MAX_STORAGE_KEY_VALUE = 2**256 - 1
 MIN_STORAGE_KEY_VALUE = -(2**255)
 
@@ -148,23 +198,31 @@ def __str__(self):
             """
 
     @dataclass(kw_only=True)
-    class MissingKey(Exception):
+    class MissingKey(TraceableException):
         """
         Test expected to find a storage key set but key was missing.
         """
 
+        address: Address
         key: int
 
-        def __init__(self, key: int, *args):
+        def __init__(self, address: Address, key: int, *args):
             super().__init__(args)
+            self.address = address
             self.key = key
 
         def __str__(self):
-            """Print exception string"""
-            return "key {0} not found in storage".format(Storage.key_value_to_string(self.key))
+            """Print exception string lines"""
+            lines = [
+                f"key {Storage.key_value_to_string(self.key)} not found in"
+                + f"storage of {self.address}"
+            ]
+            if self.traces:
+                pass
+            return "\n".join(lines)
 
     @dataclass(kw_only=True)
-    class KeyValueMismatch(Exception):
+    class KeyValueMismatch(TraceableException):
         """
         Test expected a certain value in a storage key but value found
         was different.
@@ -183,13 +241,23 @@ def __init__(self, address: Address, key: int, want: int, got: int, *args):
             self.got = got
 
         def __str__(self):
-            """Print exception string"""
-            return (
+            """Print exception string lines"""
+            lines = [
                 f"incorrect value in address {self.address} for "
-                + f"key {Storage.key_value_to_string(self.key)}:"
-                + f" want {Storage.key_value_to_string(self.want)} (dec:{self.want}),"
-                + f" got {Storage.key_value_to_string(self.got)} (dec:{self.got})"
-            )
+                + f"key {Storage.key_value_to_string(self.key)}:",
+                f"want: {Storage.key_value_to_string(self.want)} (dec:{self.want})",
+                f"got {Storage.key_value_to_string(self.got)} (dec:{self.got})",
+            ]
+            if self.traces:
+                lines += ["", "Relevant EVM traces:"]
+                lines += self.get_trace_context(
+                    context_address=self.address,
+                    opcode_name="SSTORE",
+                    stack_item_0=self.key,
+                    previous_lines=2,
+                )
+
+            return "\n".join(lines)
 
     @staticmethod
     def parse_key_value(input: str | int | bytes | SupportsBytes) -> int:
@@ -309,7 +377,7 @@ def must_contain(self, address: Address, other: "Storage"):
             if key not in self:
                 # storage[key]==0 is equal to missing storage
                 if other[key] != 0:
-                    raise Storage.MissingKey(key=key)
+                    raise Storage.MissingKey(address=address, key=key)
             elif self[key] != other[key]:
                 raise Storage.KeyValueMismatch(
                     address=address, key=key, want=self[key], got=other[key]

Diff for: src/ethereum_test_tools/spec/blockchain/blockchain_test.py

@@ -20,6 +20,7 @@
     Hash,
     HeaderNonce,
     Number,
+    TraceableException,
     Transaction,
     ZeroPaddedHexNumber,
     alloc_to_accounts,
@@ -303,12 +304,15 @@ def network_info(self, fork: Fork, eips: Optional[List[int]] = None):
             else fork.blockchain_test_network_name()
         )
 
-    def verify_post_state(self, alloc, traces):
+    def verify_post_state(self, alloc, traces: Optional[List[List[EVMTransactionTrace]]] = None):
         """
         Verifies the post alloc after all block/s or payload/s are generated.
         """
         try:
             verify_post_alloc(self.post, alloc)
+        except TraceableException as e:
+            e.set_traces(traces)
+            raise e
         except Exception as e:
             print_traces(traces)
             raise e
@@ -455,7 +459,7 @@ def make_hive_fixture(
             # Most clients require the header to start the sync process, so we create an empty
             # block on top of the last block of the test to send it as new payload and trigger the
             # sync process.
-            sync_header, _, _, _, _ = self.generate_block_data(
+            sync_header, _, _, _, _, _ = self.generate_block_data(
                 t8n=t8n,
                 fork=fork,
                 block=Block(),

Diff for: src/ethereum_test_tools/spec/state/state_test.py

@@ -9,7 +9,7 @@
 from ethereum_test_forks import Fork
 from evm_transition_tool import FixtureFormats, TransitionTool
 
-from ...common import Address, Alloc, Environment, Number, Transaction
+from ...common import Address, Alloc, Environment, Number, TraceableException, Transaction
 from ...common.constants import EngineAPIError
 from ...common.json import to_json
 from ..base.base_test import BaseFixture, BaseTest, verify_post_alloc
@@ -156,6 +156,9 @@ def make_state_test_fixture(
 
         try:
             verify_post_alloc(self.post, next_alloc)
+        except TraceableException as e:
+            e.set_traces([traces])
+            raise e
         except Exception as e:
             print_traces([traces] if traces is not None else None)
             raise e