Draft function call context schemas

schemas/program/context.schema.yaml

@@ -50,6 +50,18 @@ allOf:
       required: ["frame"]
     then:
       $ref: "schema:ethdebug/format/program/context/frame"
+  - if:
+      required: ["invoke"]
+    then:
+      $ref: "schema:ethdebug/format/program/context/invoke"
+  - if:
+      required: ["return"]
+    then:
+      $ref: "schema:ethdebug/format/program/context/return"
+  - if:
+      required: ["revert"]
+    then:
+      $ref: "schema:ethdebug/format/program/context/revert"
 
 unevaluatedProperties: false
 

schemas/program/context/invoke.schema.yaml

@@ -0,0 +1,250 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/invoke"
+
+title: ethdebug/format/program/context/invoke
+description: |
+  Schema for representing function invocation context at a specific point in
+  program execution.
+
+  This context captures information about function calls, including both
+  internal function calls (via JUMP) and external contract calls (via CALL,
+  DELEGATECALL, STATICCALL, etc.). The schema distinguishes between these
+  different invocation types through the use of `internal` and `external`
+  boolean properties.
+
+type: object
+properties:
+  invoke:
+    type: object
+    title: Function invocation
+    description: |
+      Represents a function invocation, either internal (via JUMP) or external
+      (via CALL opcodes). The schema enforces that exactly one of `internal`
+      or `external` must be true.
+
+      For internal calls, only `target` and `arguments` are valid.
+      For external calls, `gas`, `value`, `input`, `salt`, `delegate`,
+      `static`, `create`, and `create2` may be used as appropriate.
+
+    properties:
+      target:
+        type: object
+        title: Invocation target
+        description: |
+          Pointer to the target of the invocation. For internal calls, this
+          typically points to a code location. For external calls, this points
+          to the address and/or selector being called.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+
+    oneOf:
+      - $ref: "#/$defs/InternalFunctionInvocation"
+      - $ref: "#/$defs/ExternalFunctionInvocation"
+
+    unevaluatedProperties: false
+
+    required:
+      - target
+
+required:
+  - invoke
+
+$defs:
+  InternalFunctionInvocation:
+    type: object
+    properties:
+      internal:
+        description: |
+          Indicates this is an internal function call (JUMP/JUMPI).
+        const: true
+
+      arguments:
+        type: object
+        title: Function arguments
+        description: |
+          Pointer to the arguments for an internal function call.
+          Only valid for internal calls.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+    required: [internal]
+
+  ExternalFunctionInvocation:
+    type: object
+    properties:
+      external:
+        description: |
+          Indicates this is an external contract call (CALL/DELEGATECALL/etc).
+        const: true
+
+      gas:
+        type: object
+        title: Gas allocation
+        description: |
+          Pointer to the gas allocated for an external call
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+
+      value:
+        type: object
+        title: ETH value
+        description: |
+          Pointer to the amount of ETH being sent with an external call.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+
+      salt:
+        type: object
+        title: CREATE2 salt
+        description: |
+          Pointer to the salt value for CREATE2.
+          Only valid when create2 is true.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+
+      input:
+        type: object
+        title: Call input data
+        description: |
+          Pointer to the input data for an external call.
+          Only valid for external calls.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+        additionalProperties: false
+
+      delegate:
+        type: boolean
+        description: |
+          Indicates this external call is a DELEGATECALL.
+          Only valid when external is true.
+
+      static:
+        type: boolean
+        description: |
+          Indicates this external call is a STATICCALL.
+          Only valid when external is true.
+
+      create:
+        type: boolean
+        description: |
+          Indicates this external call creates a new contract (CREATE).
+          Only valid when external is true.
+
+      create2:
+        type: boolean
+        description: |
+          Indicates this external call creates a new contract (CREATE2).
+          Only valid when external is true.
+
+    required: [external]
+
+examples:
+  - invoke:
+      target:
+        pointer:
+          location: code
+          offset: 291
+          length: 2
+      internal: true
+      arguments:
+        pointer:
+          location: stack
+          slot: 0
+          length: 3
+
+  - invoke:
+      target:
+        pointer:
+          location: stack
+          slot: 0
+      external: true
+      value:
+        pointer:
+          location: stack
+          slot: 1
+      gas:
+        pointer:
+          location: stack
+          slot: 2
+      input:
+        pointer:
+          location: memory
+          offset: 128
+          length: 68
+
+  - invoke:
+      target:
+        pointer:
+          location: stack
+          slot: 0
+      external: true
+      delegate: true
+      gas:
+        pointer:
+          location: stack
+          slot: 1
+      input:
+        pointer:
+          location: calldata
+          offset: 4
+          length: 68
+
+  - invoke:
+      target:
+        pointer:
+          location: stack
+          slot: 0
+      external: true
+      create2: true
+      salt:
+        pointer:
+          location: stack
+          slot: 1
+      value:
+        pointer:
+          location: stack
+          slot: 2
+      input:
+        pointer:
+          location: memory
+          offset: 0
+          length: 200
+
+  - invoke:
+      target:
+        pointer:
+          location: stack
+          slot: 0
+      external: true
+      static: true
+      gas:
+        pointer:
+          location: stack
+          slot: 1
+      input:
+        pointer:
+          location: calldata
+          offset: 4
+          length: 36

schemas/program/context/return.schema.yaml

@@ -0,0 +1,69 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/return"
+
+title: ethdebug/format/program/context/return
+description: |
+  Schema for representing function return context at a specific point in
+  program execution.
+
+  This context captures information about successful function returns,
+  including the return data and, for external calls, the success status.
+
+type: object
+properties:
+  return:
+    type: object
+    properties:
+      data:
+        type: object
+        title: Return data
+        description: |
+          Pointer to the data being returned from the function.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+
+      success:
+        type: object
+        title: Call success status
+        description: |
+          Pointer to the success status of an external call.
+          Typically points to a boolean value on the stack.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+
+required:
+  - return
+
+additionalProperties: false
+
+examples:
+  - return:
+      data:
+        pointer:
+          location: memory
+          offset: 0x40
+          length: 0x20
+
+  - return:
+      data:
+        pointer:
+          location: memory
+          offset: 0x40
+          length: 0x20
+      success:
+        pointer:
+          location: stack
+          slot: 0
+
+  - return:
+      data:
+        pointer:
+          location: returndata
+          offset: 0
+          length: 32

schemas/program/context/revert.schema.yaml

@@ -0,0 +1,58 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/program/context/revert"
+
+title: ethdebug/format/program/context/revert
+description: |
+  Schema for representing function revert context at a specific point in
+  program execution.
+
+  This context captures information about function reverts, including
+  revert reason data or panic codes.
+
+type: object
+properties:
+  revert:
+    type: object
+    properties:
+      reason:
+        type: object
+        title: Revert reason
+        description: |
+          Pointer to the revert reason data. This typically contains an
+          ABI-encoded error message or custom error data.
+        properties:
+          pointer:
+            $ref: "schema:ethdebug/format/pointer"
+        required:
+          - pointer
+
+      panic:
+        type: integer
+        title: Panic code
+        description: |
+          Numeric panic code for built-in assertion failures.
+          Languages may define their own panic code conventions
+          (e.g., Solidity uses codes like 0x11 for arithmetic overflow).
+
+required:
+  - revert
+
+additionalProperties: false
+
+examples:
+  - revert:
+      reason:
+        pointer:
+          location: memory
+          offset: 0x40
+          length: 0x60
+
+  - revert:
+      panic: 0x11
+
+  - revert:
+      reason:
+        pointer:
+          location: returndata
+          offset: 0
+          length: 100