From 8828a246ab9b754d78b5c25c885e79717ed7dc13 Mon Sep 17 00:00:00 2001
From: "g. nicholas d'andrea" <nick@gnidan.org>
Date: Thu, 16 Apr 2026 03:14:44 -0400
Subject: [PATCH] format: make return.data optional

The data pointer on function return contexts was required,
forcing compilers to emit placeholder pointers at instructions
where no return value is observable. The common motivating case
is a tail-call-optimized back-edge JUMP, where the intermediate
return value is not materialized on the stack (it would have
become the next iteration's argument, which the compiler has
already folded into the new call's setup). A placeholder
pointer at such an instruction would mislabel unrelated stack
content as the return value.

Make data optional, matching the revert context's precedent
(reason and panic are both optional there for similar reasons).
A bare `return: {}` is now permitted, analogous to bare
`revert: {}`.

This also accommodates void functions (no return value to
point at) and lost-compiler-precision cases where the compiler
knows a return occurred but has dropped the value's location.

Updates:
- return.schema.yaml: drop data from required, expand
  descriptions, add a no-data example.
- context.ts: data?: Function.PointerRef and adjust guard.
- return.mdx: rewrite Field optionality section covering
  void/TCO/lost-precision cases.
- call-contexts.test.ts: use non-null assertion where the
  test asserts the compiler did emit data.
---
 .../bugc/src/evmgen/call-contexts.test.ts     |  3 +-
 packages/format/src/types/program/context.ts  |  5 +--
 .../spec/program/context/function/return.mdx  | 40 ++++++++++++++-----
 .../context/function/return.schema.yaml       | 36 ++++++++++++++---
 4 files changed, 66 insertions(+), 18 deletions(-)

diff --git a/packages/bugc/src/evmgen/call-contexts.test.ts b/packages/bugc/src/evmgen/call-contexts.test.ts
index 43f1b76cb..c05f58708 100644
--- a/packages/bugc/src/evmgen/call-contexts.test.ts
+++ b/packages/bugc/src/evmgen/call-contexts.test.ts
@@ -126,7 +126,8 @@ code {
 
     // Should have data pointer to return value at
     // TOS (stack slot 0)
-    expect(ret.data.pointer).toEqual({
+    expect(ret.data).toBeDefined();
+    expect(ret.data!.pointer).toEqual({
       location: "stack",
       slot: 0,
     });
diff --git a/packages/format/src/types/program/context.ts b/packages/format/src/types/program/context.ts
index 9388fea7b..104f27196 100644
--- a/packages/format/src/types/program/context.ts
+++ b/packages/format/src/types/program/context.ts
@@ -239,7 +239,7 @@ export namespace Context {
 
   export namespace Return {
     export interface Info extends Function.Identity {
-      data: Function.PointerRef;
+      data?: Function.PointerRef;
       success?: Function.PointerRef;
     }
 
@@ -247,8 +247,7 @@ export namespace Context {
       Function.isIdentity(value) &&
       typeof value === "object" &&
       !!value &&
-      "data" in value &&
-      Function.isPointerRef(value.data) &&
+      (!("data" in value) || Function.isPointerRef(value.data)) &&
       (!("success" in value) || Function.isPointerRef(value.success));
   }
 
diff --git a/packages/web/spec/program/context/function/return.mdx b/packages/web/spec/program/context/function/return.mdx
index e03668a1b..47279cea3 100644
--- a/packages/web/spec/program/context/function/return.mdx
+++ b/packages/web/spec/program/context/function/return.mdx
@@ -9,8 +9,8 @@ import SchemaViewer from "@site/src/components/SchemaViewer";
 A return context marks an instruction associated with a successful
 function return. It extends the
 [function identity](/spec/program/context/function) schema with
-a pointer to the return data and, for external calls, the
-success status.
+an optional pointer to the return data and, for external calls,
+the success status.
 
 <SchemaViewer
   schema={{ id: "schema:ethdebug/format/program/context/function/return" }}
@@ -18,10 +18,13 @@ success status.
 
 ## Return data
 
-The `data` field is required and contains a pointer to the value
-being returned. For internal calls this typically points to a
-stack location; for external calls it points into the
-`returndata` buffer.
+The `data` field contains a pointer to the value being returned.
+For internal calls this typically points to a stack location;
+for external calls it points into the `returndata` buffer.
+
+`data` is optional. Omit it when no return value is observable
+at this instruction—see
+[Field optionality](#field-optionality) below.
 
 ## Internal return
 
@@ -48,9 +51,28 @@ reverts at the EVM level.
 
 ## Field optionality
 
-The `data` pointer is always required—every return context must
-indicate where the return value can be found. The `success`
-field is optional and only meaningful for external calls.
+All fields on a return context are optional. A bare `return: {}`
+is permitted when the compiler knows a return occurred but has
+no further detail to record.
+
+The `data` pointer is omitted when no return value is observable
+at the marked instruction. This occurs in several legitimate
+cases:
+
+- **Void functions.** The function produces no return value, so
+  there is nothing to point at.
+- **Tail-call-optimized back-edges.** When a tail call is
+  rewritten to a back-edge JUMP, the intermediate return value
+  is not materialized—it would have become the next iteration's
+  argument, which the compiler has already folded into the new
+  call's setup. A return semantically happens, but no pointer
+  records where the value lives (it does not live anywhere).
+- **Lost compiler precision.** The compiler knows a return
+  occurred but has dropped the location tracking for the value.
+
+The `success` field is optional and only meaningful for external
+call returns, where it points to the boolean status placed on
+the stack by CALL/DELEGATECALL/STATICCALL.
 
 Function identity fields (`identifier`, `declaration`, `type`)
 are all optional. A compiler may omit them when it cannot
diff --git a/schemas/program/context/function/return.schema.yaml b/schemas/program/context/function/return.schema.yaml
index dd274f67d..4a4376048 100644
--- a/schemas/program/context/function/return.schema.yaml
+++ b/schemas/program/context/function/return.schema.yaml
@@ -5,8 +5,14 @@ title: ethdebug/format/program/context/function/return
 description: |
   This context indicates that the marked instruction is
   associated with a successful function return. Extends the
-  function identity schema with a pointer to the return data
-  and, for external calls, the success status.
+  function identity schema with an optional pointer to the
+  return data and, for external calls, the success status.
+
+  All fields are optional. A bare `return: {}` is permitted
+  when the compiler knows a return occurred but has no further
+  detail—for example, at a tail-call-optimized back-edge where
+  the intermediate return value is not materialized, or for a
+  void function with no return value.
 
 type: object
 properties:
@@ -21,6 +27,10 @@ properties:
         title: Return data
         description: |
           Pointer to the data being returned from the function.
+          Optional: may be omitted when no return value is
+          observable at this instruction (e.g., void functions,
+          tail-call-optimized returns where the intermediate
+          value is not materialized).
         properties:
           pointer:
             $ref: "schema:ethdebug/format/pointer"
@@ -39,9 +49,6 @@ properties:
         required:
           - pointer
 
-    required:
-      - data
-
     unevaluatedProperties: false
 
 required:
@@ -103,3 +110,22 @@ examples:
         pointer:
           location: stack
           slot: 0
+
+  # -----------------------------------------------------------
+  # Return without observable data: TCO back-edge
+  # -----------------------------------------------------------
+  # At a tail-call-optimized back-edge JUMP, the intermediate
+  # return value is not materialized on the stack — it would
+  # have been the argument to the next iteration, which the
+  # compiler has already folded into the new call's setup.
+  # A return semantically happens (the outer activation's
+  # iteration N is returning), but there is no pointer to
+  # record for `data`.
+  - return:
+      identifier: "fact"
+      declaration:
+        source:
+          id: 0
+        range:
+          offset: 64
+          length: 120