feat: implement placeholder for bytecode

Author: LouisTsai-Csie

packages/testing/src/execution_testing/__init__.py

@@ -107,6 +107,7 @@
     Opcode,
     OpcodeCallArg,
     Opcodes,
+    Placeholder,
     call_return_code,
 )
 
@@ -170,6 +171,7 @@
     "OpcodeCallArg",
     "Opcodes",
     "ParameterSet",
+    "Placeholder",
     "ReferenceSpec",
     "ReferenceSpecTypes",
     "Removable",

packages/testing/src/execution_testing/vm/__init__.py

@@ -5,7 +5,7 @@
     OpcodeBase,
     OpcodeGasCalculator,
 )
-from .bytecode import Bytecode
+from .bytecode import Bytecode, Placeholder
 from .helpers import MemoryVariable, call_return_code
 from .opcodes import (
     Macro,
@@ -30,5 +30,6 @@
     "OpcodeCallArg",
     "OpcodeGasCalculator",
     "Opcodes",
+    "Placeholder",
     "call_return_code",
 )

packages/testing/src/execution_testing/vm/bytecode.py

@@ -1,6 +1,6 @@
 """Ethereum Virtual Machine bytecode primitives and utilities."""
 
-from typing import Any, List, Self, SupportsBytes, Type
+from typing import Any, Dict, List, Self, SupportsBytes, Type
 
 from pydantic import GetCoreSchemaHandler
 from pydantic_core.core_schema import (
@@ -14,6 +14,49 @@
 from .bases import ForkOpcodeInterface, OpcodeBase
 
 
+class Placeholder:
+    """
+    Placeholder for a value to be filled in later.
+
+    Used to break circular dependencies where a value (like gas cost)
+    needs to be embedded in bytecode, but the bytecode structure is
+    needed to calculate that value.
+
+    Since PUSH1-PUSH32 all have the same gas cost (G_VERY_LOW = 3),
+    the placeholder can be used in gas calculations before being filled.
+
+    Example:
+        >>> loop_cost = Placeholder(width=2)
+        >>> code = Op.JUMPI(Op.GT(Op.GAS, loop_cost), 0)
+        >>> actual_cost = code.gas_cost(fork)
+        >>> final_code = code.fill(loop_cost, actual_cost)
+
+    """
+
+    _counter: int = 0
+
+    def __init__(self, width: int = 2):
+        """
+        Create a placeholder with a specific byte width.
+
+        Args:
+            width: Number of bytes (1-32). Determines max value:
+                   - width=1: max 255 (PUSH1)
+                   - width=2: max 65535 (PUSH2)
+                   - width=3: max 16777215 (PUSH3)
+
+        """
+        if not 1 <= width <= 32:
+            raise ValueError("width must be between 1 and 32")
+        self.width = width
+        self._id = Placeholder._counter
+        Placeholder._counter += 1
+
+    def __repr__(self) -> str:
+        """Return string representation of the placeholder."""
+        return f"Placeholder(width={self.width}, id={self._id})"
+
+
 class Bytecode:
     """
     Base class to represent EVM bytecode.
@@ -41,6 +84,7 @@ class Bytecode:
 
     terminating: bool
     opcode_list: List[OpcodeBase]
+    _placeholders: Dict[Placeholder, int]
 
     def __new__(
         cls,
@@ -67,6 +111,7 @@ def __new__(
             instance.terminating = False
             instance._name_ = name
             instance.opcode_list = opcode_list
+            instance._placeholders = {}
             return instance
 
         if isinstance(bytes_or_byte_code_base, Bytecode):
@@ -81,6 +126,7 @@ def __new__(
             obj.terminating = bytes_or_byte_code_base.terminating
             obj.opcode_list = bytes_or_byte_code_base.opcode_list[:]
             obj._name_ = bytes_or_byte_code_base._name_
+            obj._placeholders = bytes_or_byte_code_base._placeholders.copy()
             return obj
 
         if isinstance(bytes_or_byte_code_base, bytes):
@@ -103,6 +149,7 @@ def __new__(
             obj.terminating = terminating
             obj.opcode_list = opcode_list
             obj._name_ = name
+            obj._placeholders = {}
             return obj
 
         raise TypeError(
@@ -217,7 +264,7 @@ def __add__(self, other: "Bytecode | bytes | int | None") -> "Bytecode":
             c_min + a_max - a_min, c_min - a_pop + a_push + b_max - b_min
         )
 
-        return Bytecode(
+        c = Bytecode(
             bytes(self) + bytes(other),
             popped_stack_items=c_pop,
             pushed_stack_items=c_push,
@@ -226,6 +273,11 @@ def __add__(self, other: "Bytecode | bytes | int | None") -> "Bytecode":
             terminating=other.terminating,
             opcode_list=self.opcode_list + other.opcode_list,
         )
+        # Merge placeholders, adjusting offsets for 'other'
+        c._placeholders = self._placeholders.copy()
+        for placeholder, offset in other._placeholders.items():
+            c._placeholders[placeholder] = offset + len(self)
+        return c
 
     def __radd__(self, other: "Bytecode | int | None") -> "Bytecode":
         """
@@ -295,6 +347,60 @@ def refund(
             total_refund += opcode_refund_calculator(opcode)
         return total_refund
 
+    def fill(self, placeholder: Placeholder, value: int) -> "Bytecode":
+        """
+        Replace a placeholder with an actual value.
+
+        Args:
+            placeholder: The placeholder to fill
+            value: The value to insert (must fit in placeholder's width)
+
+        Returns:
+            New Bytecode with the placeholder replaced
+
+        Raises:
+            ValueError: If value doesn't fit in placeholder's width
+            KeyError: If placeholder not found in this bytecode
+
+        """
+        if placeholder not in self._placeholders:
+            raise KeyError(f"Placeholder {placeholder} not found in bytecode")
+
+        max_value = (1 << (placeholder.width * 8)) - 1
+        if value < 0 or value > max_value:
+            raise ValueError(
+                f"Value {value} doesn't fit in {placeholder.width} bytes "
+                f"(max {max_value})"
+            )
+
+        offset = self._placeholders[placeholder]
+        value_bytes = value.to_bytes(placeholder.width, "big")
+
+        # Replace the placeholder bytes with the actual value
+        new_bytes = (
+            self._bytes_[:offset]
+            + value_bytes
+            + self._bytes_[offset + placeholder.width :]
+        )
+
+        # Create new Bytecode with updated bytes
+        result = Bytecode(
+            new_bytes,
+            popped_stack_items=self.popped_stack_items,
+            pushed_stack_items=self.pushed_stack_items,
+            max_stack_height=self.max_stack_height,
+            min_stack_height=self.min_stack_height,
+            terminating=self.terminating,
+            opcode_list=self.opcode_list[:],
+        )
+
+        # Copy placeholders except the one we just filled
+        result._placeholders = {
+            p: o for p, o in self._placeholders.items() if p is not placeholder
+        }
+
+        return result
+
     @classmethod
     def __get_pydantic_core_schema__(
         cls, source_type: Any, handler: GetCoreSchemaHandler

packages/testing/src/execution_testing/vm/opcodes.py

@@ -24,7 +24,7 @@
 from execution_testing.base_types import to_bytes
 
 from .bases import OpcodeBase
-from .bytecode import Bytecode
+from .bytecode import Bytecode, Placeholder
 
 
 def _get_int_size(n: int) -> int:
@@ -45,13 +45,29 @@ def _get_int_size(n: int) -> int:
 
 def _stack_argument_to_bytecode(
     arg: (
-        "int | bytes | SupportsBytes | str | Opcode | Bytecode | Iterable[int]"
+        "int | bytes | SupportsBytes | str | Opcode"
+        " | Bytecode | Iterable[int] | Placeholder"
     ),
 ) -> Bytecode:
     """Convert stack argument in an opcode or macro to bytecode."""
     if isinstance(arg, Bytecode):
         return arg
 
+    # Handle Placeholder - create appropriate PUSH with zeros
+    if isinstance(arg, Placeholder):
+        # PUSH1 is 0x60, PUSH2 is 0x61, ..., PUSH32 is 0x7f
+        push_opcode = 0x5F + arg.width
+        bytecode_bytes = bytes([push_opcode]) + bytes(arg.width)
+        bytecode = Bytecode(
+            bytecode_bytes,
+            popped_stack_items=0,
+            pushed_stack_items=1,
+            min_stack_height=0,
+            max_stack_height=1,
+        )
+        bytecode._placeholders = {arg: 1}
+        return bytecode
+
     # We are going to push a constant to the stack.
     data_size = 0
     if isinstance(arg, int):
@@ -329,7 +345,10 @@ def with_metadata(self, **metadata: Any) -> "Opcode":
 
     def __call__(
         self,
-        *args_t: "int | bytes | str | Opcode | Bytecode | Iterable[int]",
+        *args_t: (
+            "int | bytes | str | Opcode"
+            " | Bytecode | Iterable[int] | Placeholder"
+        ),
         unchecked: bool = False,
         **kwargs: "int | bytes | str | Opcode | Bytecode",
     ) -> "Bytecode | Opcode":
@@ -362,9 +381,10 @@ def __call__(
 
         Hex-strings will be automatically converted to bytes.
         """
-        args: List["int | bytes | str | Opcode | Bytecode | Iterable[int]"] = (
-            list(args_t)
-        )
+        args: List[
+            "int | bytes | str | Opcode"
+            " | Bytecode | Iterable[int] | Placeholder"
+        ] = list(args_t)
         opcode = self
 
         # handle metadata first
@@ -386,6 +406,7 @@ def __call__(
             assert type(opcode) is Opcode
             get_item_arg = args.pop()
             assert not isinstance(get_item_arg, Bytecode)
+            assert not isinstance(get_item_arg, Placeholder)
             return opcode[get_item_arg](*args)
 
         if opcode.kwargs is not None and len(kwargs) > 0: