From 0b42c024c4703d4aa799b711e96fa955e6800051 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Thu, 2 Apr 2026 07:58:37 -0400 Subject: [PATCH 1/3] format: fix invoke schema pointer semantics and examples Align invoke context examples with the "following execution" semantics defined by instruction.schema.yaml. The internal call example previously referenced pre-JUMP stack state (destination at slot 0, arguments at slots 2-3), but JUMP consumes its destination operand. Fix the example to mark the callee's entry JUMPDEST with the correct post-JUMP stack layout: return label at slot 0, arguments at slots 1-2, and target as a code pointer to the function's entry offset. Also fix the CREATE2 example: salt was incorrectly shown at stack slot 1 instead of slot 3 (the EVM pops value, offset, length, salt in that order). Add clarifying text to the schema description and spec page explaining when internal call contexts use callee JUMPDEST placement vs. external call/create contexts on the instruction itself, and how stack-based pointers reference pre-execution state for instructions that consume their operands. --- .../spec/program/context/function/invoke.mdx | 27 +++++- .../context/function/invoke.schema.yaml | 83 ++++++++++++------- 2 files changed, 78 insertions(+), 32 deletions(-) diff --git a/packages/web/spec/program/context/function/invoke.mdx b/packages/web/spec/program/context/function/invoke.mdx index d017c2cc0..4775037a8 100644 --- a/packages/web/spec/program/context/function/invoke.mdx +++ b/packages/web/spec/program/context/function/invoke.mdx @@ -19,15 +19,36 @@ gas, value, and input data as applicable. See worked examples showing how debuggers use invoke and return contexts to reconstruct call stacks. +## Pointer evaluation and instruction placement + +Pointer values within an invoke context reference the machine +state as it exists at the marked instruction's trace step. + +For **internal calls**, this context is typically placed on the +callee's entry JUMPDEST rather than the caller's JUMP. Because +JUMP consumes its destination operand from the stack, placing +the context on the JUMP would require pointers to reference a +stack layout that no longer exists after execution. At the entry +JUMPDEST, the remaining stack (return address followed by +arguments) is stable and directly addressable. + +For **external calls** and **contract creations**, this context +marks the CALL/DELEGATECALL/STATICCALL/CREATE/CREATE2 +instruction itself. These instructions consume all of their +stack operands, so stack-based pointers reference the +pre-execution state visible in the trace step. + ## Internal call -An internal call represents a function call within the same contract -via JUMP/JUMPI. The target points to a code location and arguments -are passed on the stack. +An internal call represents a function call within the same contract. +This context is typically placed on the callee's entry JUMPDEST; the +caller's JUMP has already consumed the destination from the stack, so +pointer slot values reflect the post-JUMP layout. The target points +to a code location and arguments are passed on the stack. Date: Thu, 2 Apr 2026 08:06:36 -0400 Subject: [PATCH 2/3] =?UTF-8?q?format:=20clarify=20context=20semantics=20?= =?UTF-8?q?=E2=80=94=20facts=20vs=20pointer=20state?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Resolve the tension between "following execution" semantics and pointer evaluation. The instruction schema's "following execution" describes when a context's semantic facts hold (e.g., "a function was invoked"), not the machine state that pointers reference. Pointers reference the state at the instruction's trace step — the state a debugger observes when it encounters the instruction. Update instruction.schema.yaml to make this two-level model explicit. Simplify the invoke schema description and spec page to present this cleanly rather than restating the contradiction. --- .../spec/program/context/function/invoke.mdx | 19 ++++++++++--------- .../context/function/invoke.schema.yaml | 12 ++++++------ schemas/program/instruction.schema.yaml | 5 +++++ 3 files changed, 21 insertions(+), 15 deletions(-) diff --git a/packages/web/spec/program/context/function/invoke.mdx b/packages/web/spec/program/context/function/invoke.mdx index 4775037a8..dea5ba527 100644 --- a/packages/web/spec/program/context/function/invoke.mdx +++ b/packages/web/spec/program/context/function/invoke.mdx @@ -21,22 +21,23 @@ contexts to reconstruct call stacks. ## Pointer evaluation and instruction placement -Pointer values within an invoke context reference the machine -state as it exists at the marked instruction's trace step. +An instruction's context describes what is known *following* +that instruction's execution: the fact that a function was +invoked holds from that point forward. Pointers within the +context reference the machine state at the instruction's trace +step — the state a debugger observes when it encounters the +instruction. For **internal calls**, this context is typically placed on the -callee's entry JUMPDEST rather than the caller's JUMP. Because -JUMP consumes its destination operand from the stack, placing -the context on the JUMP would require pointers to reference a -stack layout that no longer exists after execution. At the entry +callee's entry JUMPDEST rather than the caller's JUMP. JUMP +consumes its destination operand from the stack; at the entry JUMPDEST, the remaining stack (return address followed by arguments) is stable and directly addressable. For **external calls** and **contract creations**, this context marks the CALL/DELEGATECALL/STATICCALL/CREATE/CREATE2 -instruction itself. These instructions consume all of their -stack operands, so stack-based pointers reference the -pre-execution state visible in the trace step. +instruction itself, where the call parameters are visible on +the stack. Date: Thu, 2 Apr 2026 08:11:20 -0400 Subject: [PATCH 3/3] chore: fix formatting --- packages/web/spec/program/context/function/invoke.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/web/spec/program/context/function/invoke.mdx b/packages/web/spec/program/context/function/invoke.mdx index dea5ba527..b249a1a0a 100644 --- a/packages/web/spec/program/context/function/invoke.mdx +++ b/packages/web/spec/program/context/function/invoke.mdx @@ -21,7 +21,7 @@ contexts to reconstruct call stacks. ## Pointer evaluation and instruction placement -An instruction's context describes what is known *following* +An instruction's context describes what is known _following_ that instruction's execution: the fact that a function was invoked holds from that point forward. Pointers within the context reference the machine state at the instruction's trace