From 37e10e35eab6fda6693539ea6f3f66b1dcae0d93 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Thu, 29 May 2025 15:41:48 +0100 Subject: [PATCH 1/4] Draft function call context schemas --- schemas/program/context.schema.yaml | 12 + schemas/program/context/invoke.schema.yaml | 250 +++++++++++++++++++++ schemas/program/context/return.schema.yaml | 69 ++++++ schemas/program/context/revert.schema.yaml | 58 +++++ 4 files changed, 389 insertions(+) create mode 100644 schemas/program/context/invoke.schema.yaml create mode 100644 schemas/program/context/return.schema.yaml create mode 100644 schemas/program/context/revert.schema.yaml diff --git a/schemas/program/context.schema.yaml b/schemas/program/context.schema.yaml index 5739ff40..eefd82cc 100644 --- a/schemas/program/context.schema.yaml +++ b/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 diff --git a/schemas/program/context/invoke.schema.yaml b/schemas/program/context/invoke.schema.yaml new file mode 100644 index 00000000..820c55f9 --- /dev/null +++ b/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 being called. + properties: + pointer: + $ref: "schema:ethdebug/format/pointer" + required: + - pointer + additionalProperties: false + + internal: + type: boolean + description: | + Indicates this is an internal function call (JUMP/JUMPI). + + external: + type: boolean + description: | + Indicates this is an external contract call (CALL/DELEGATECALL/etc). + + 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 + + gas: + type: object + title: Gas allocation + description: | + Pointer to the gas allocated for an external call. + Only valid for external calls. + 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. + Only valid for external calls. + 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 + + 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 + + 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: + - target + + oneOf: + - properties: + internal: + const: true + required: + - internal + - properties: + external: + const: true + required: + - external + +required: + - invoke + +additionalProperties: false + +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 diff --git a/schemas/program/context/return.schema.yaml b/schemas/program/context/return.schema.yaml new file mode 100644 index 00000000..09189313 --- /dev/null +++ b/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 diff --git a/schemas/program/context/revert.schema.yaml b/schemas/program/context/revert.schema.yaml new file mode 100644 index 00000000..032b10c1 --- /dev/null +++ b/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 From 85f9b999f25ad62014a0ca31a3112edbb7bc1fe6 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Sat, 31 May 2025 14:19:56 +0100 Subject: [PATCH 2/4] Organize schema a bit --- schemas/program/context/invoke.schema.yaml | 74 +++++++++++----------- 1 file changed, 37 insertions(+), 37 deletions(-) diff --git a/schemas/program/context/invoke.schema.yaml b/schemas/program/context/invoke.schema.yaml index 820c55f9..70c703d7 100644 --- a/schemas/program/context/invoke.schema.yaml +++ b/schemas/program/context/invoke.schema.yaml @@ -33,7 +33,7 @@ properties: 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 being called. + to the address and/or selector being called. properties: pointer: $ref: "schema:ethdebug/format/pointer" @@ -41,15 +41,26 @@ properties: - pointer additionalProperties: false + oneOf: + - $ref: "#/$defs/InternalFunctionInvocation" + - $ref: "#/$defs/ExternalFunctionInvocation" + + required: + - target + +required: + - invoke + +additionalProperties: false + +$defs: + InternalFunctionInvocation: + type: object + properties: internal: - type: boolean description: | Indicates this is an internal function call (JUMP/JUMPI). - - external: - type: boolean - description: | - Indicates this is an external contract call (CALL/DELEGATECALL/etc). + const: true arguments: type: object @@ -63,13 +74,21 @@ properties: 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. - Only valid for external calls. + Pointer to the gas allocated for an external call properties: pointer: $ref: "schema:ethdebug/format/pointer" @@ -82,7 +101,6 @@ properties: title: ETH value description: | Pointer to the amount of ETH being sent with an external call. - Only valid for external calls. properties: pointer: $ref: "schema:ethdebug/format/pointer" @@ -90,12 +108,12 @@ properties: - pointer additionalProperties: false - input: + salt: type: object - title: Call input data + title: CREATE2 salt description: | - Pointer to the input data for an external call. - Only valid for external calls. + Pointer to the salt value for CREATE2. + Only valid when create2 is true. properties: pointer: $ref: "schema:ethdebug/format/pointer" @@ -103,12 +121,12 @@ properties: - pointer additionalProperties: false - salt: + input: type: object - title: CREATE2 salt + title: Call input data description: | - Pointer to the salt value for CREATE2. - Only valid when create2 is true. + Pointer to the input data for an external call. + Only valid for external calls. properties: pointer: $ref: "schema:ethdebug/format/pointer" @@ -140,25 +158,7 @@ properties: Indicates this external call creates a new contract (CREATE2). Only valid when external is true. - required: - - target - - oneOf: - - properties: - internal: - const: true - required: - - internal - - properties: - external: - const: true - required: - - external - -required: - - invoke - -additionalProperties: false + required: [external] examples: - invoke: From c1c32e95fc08c98f4fdd4aaab7a760a543aba0a8 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Sat, 31 May 2025 15:00:35 +0100 Subject: [PATCH 3/4] Disable unevaluated properties --- schemas/program/context/invoke.schema.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/schemas/program/context/invoke.schema.yaml b/schemas/program/context/invoke.schema.yaml index 70c703d7..31d8060c 100644 --- a/schemas/program/context/invoke.schema.yaml +++ b/schemas/program/context/invoke.schema.yaml @@ -45,6 +45,8 @@ properties: - $ref: "#/$defs/InternalFunctionInvocation" - $ref: "#/$defs/ExternalFunctionInvocation" + unevaluatedProperties: false + required: - target From bbba565c8b07fdb10ede9a2cde5e2ad624008ac7 Mon Sep 17 00:00:00 2001 From: "g. nicholas d'andrea" Date: Sat, 31 May 2025 15:00:58 +0100 Subject: [PATCH 4/4] Allow additionalProperties at top-level --- schemas/program/context/invoke.schema.yaml | 2 -- 1 file changed, 2 deletions(-) diff --git a/schemas/program/context/invoke.schema.yaml b/schemas/program/context/invoke.schema.yaml index 31d8060c..e0ca257c 100644 --- a/schemas/program/context/invoke.schema.yaml +++ b/schemas/program/context/invoke.schema.yaml @@ -53,8 +53,6 @@ properties: required: - invoke -additionalProperties: false - $defs: InternalFunctionInvocation: type: object