feat(fw): add max_stack_increase to EOF Section.Code (#1446)

The `max_stack_increase` is complementary but preferred to
`max_stack_height`. Both cannot be set at the same time.

Author: chfast

src/ethereum_test_types/eof/v1/__init__.py

@@ -133,7 +133,11 @@ class Section(CopyValidateModel):
     Data stack items produced by or expected at the end of this code section
     (function)
     """
-    max_stack_height: int = 0
+    max_stack_increase: int | None = None
+    """
+    Maximum operand stack height increase above the code section inputs.
+    """
+    max_stack_height: int | None = None
     """
     Maximum height data stack reaches during execution of code section.
     """
@@ -180,9 +184,10 @@ def type_definition(self) -> bytes:
         if self.kind != SectionKind.CODE and not self.force_type_listing:
             return bytes()
 
-        code_inputs, code_outputs, max_stack_height = (
+        code_inputs, code_outputs, max_stack_increase, max_stack_height = (
             self.code_inputs,
             self.code_outputs,
+            self.max_stack_increase,
             self.max_stack_height,
         )
         if self.auto_max_stack_height or self.auto_code_inputs_outputs:
@@ -191,15 +196,20 @@ def type_definition(self) -> bytes:
                 auto_code_outputs,
                 auto_max_height,
             ) = compute_code_stack_values(self.data)
-            if self.auto_max_stack_height:
-                max_stack_height = auto_max_height
             if self.auto_code_inputs_outputs:
                 code_inputs, code_outputs = (
                     auto_code_inputs,
                     auto_code_outputs,
                 )
+            if self.auto_max_stack_height:
+                max_stack_increase = auto_max_height - code_inputs
 
-        max_stack_increase = max_stack_height - code_inputs
+        if max_stack_increase is not None:
+            assert max_stack_height is None
+        elif max_stack_height is not None:
+            max_stack_increase = max_stack_height - code_inputs
+        else:
+            max_stack_increase = 0
         assert max_stack_increase >= 0, "incorrect max stack height value"
         return (
             code_inputs.to_bytes(length=TYPES_INPUTS_BYTE_LENGTH, byteorder="big")
@@ -269,8 +279,13 @@ def Code(  # noqa: N802
         if code is None:
             code = Bytecode()
         kwargs.pop("kind", None)
-        if "max_stack_height" not in kwargs and isinstance(code, Bytecode):
-            kwargs["max_stack_height"] = code.max_stack_height
+        if (
+            "max_stack_height" not in kwargs
+            and "max_stack_increase" not in kwargs
+            and isinstance(code, Bytecode)
+        ):
+            # If not specified, take the max_stack_increase from the Bytecode.
+            kwargs["max_stack_increase"] = code.max_stack_height - kwargs.get("code_inputs", 0)
         return cls(kind=SectionKind.CODE, data=code, **kwargs)
 
     @classmethod

tests/osaka/eip7692_eof_v1/eip3540_eof_v1/test_eof_example.py

@@ -25,28 +25,28 @@ def test_eof_example(eof_test: EOFTestFiller):
             Section.Code(
                 code=Op.CALLF[1](Op.PUSH0) + Op.STOP,  # bytecode to be deployed in the body
                 # Code: call section 1 with a single zero as input, then stop.
-                max_stack_height=1,  # define code header (in body) stack size
+                max_stack_increase=1,  # define code header (in body) stack size
             ),
             # There can be multiple code sections
             Section.Code(
                 # Remove input and call section 2 with no inputs, then remove output and return
                 code=Op.POP + Op.CALLF[2]() + Op.POP + Op.RETF,
                 code_inputs=1,
                 code_outputs=0,
-                max_stack_height=1,
+                max_stack_increase=0,
             ),
             Section.Code(
                 # Call section 3 with two inputs (address twice), return
                 code=Op.CALLF[3](Op.DUP1, Op.ADDRESS) + Op.POP + Op.POP + Op.RETF,
                 code_outputs=1,
-                max_stack_height=3,
+                max_stack_increase=3,
             ),
             Section.Code(
                 # Duplicate one input and return
                 code=Op.DUP1 + Op.RETF,
                 code_inputs=2,
                 code_outputs=3,
-                max_stack_height=3,
+                max_stack_increase=1,
             ),
             # DATA section
             Section.Data("0xef"),

tests/osaka/eip7692_eof_v1/eip4750_functions/test_code_validation.py

@@ -787,6 +787,7 @@ def test_callf_stack_overflow_variable_stack_3(eof_test: EOFTestFiller, stack_he
             ),
         ],
     )
+    assert container.sections[0].max_stack_height is not None
     stack_overflow = (
         container.sections[0].max_stack_height + stack_height > MAX_RUNTIME_OPERAND_STACK_HEIGHT
     )
@@ -925,6 +926,7 @@ def test_callf_with_inputs_stack_overflow(
             code_section,
         ],
     )
+    assert code_section.max_stack_height is not None
     exception = None
     if (
         push_stack + code_section.max_stack_height - code_section.code_inputs
@@ -1055,6 +1057,7 @@ def test_callf_with_inputs_stack_overflow_variable_stack(
         ],
     )
     initial_stack = 3  # Initial items in the scak
+    assert code_section.max_stack_height is not None
     exception = None
     if (
         push_stack + initial_stack + code_section.max_stack_height - code_section.code_inputs