Schema

Explore

Loading ....

View source

YAML

ethdebug/format/program

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "schema:ethdebug/format/program"

title: ethdebug/format/program
description: |
  Debugging information about a particular bytecode in a compilation.

type: object

properties:
  ethdebug:
    title: Stamp
    description: |
      Names this schema and the specification version. A program
      emitted outside an info document should carry this field. A
      program inside an info document (in `programs`) should not; the
      stamp of the info document covers it.
    allOf:
      - $ref: "schema:ethdebug/format/data/stamp"
      # note: whitespace chars are \255 (nbsp)
      - title: '{ "schema": "ethdebug/format/program" }'
        properties:
          schema:
            const: "ethdebug/format/program"

  compilation:
    title: Compilation reference by ID
    description: |
      A reference to the compilation as an `{ "id": ... }` object.
    $ref: "schema:ethdebug/format/materials/reference"

  contract:
    type: object
    properties:
      name:
        type: string

      definition:
        $ref: "schema:ethdebug/format/materials/source-range"
    required:
      - definition

  environment:
    title: Bytecode execution environment
    description: |
      Whether this bytecode is for contract creation or runtime calls.
    type: string
    enum:
      - call
      - create

  context:
    description: |
      The context that holds prior to the execution of the first
      instruction in the bytecode. This is the base case of the context
      chain — the precondition to the first instruction — from which each
      instruction's own `context` follows as a postcondition (see
      **ethdebug/format/program/instruction**).

      This field is **optional**. Omitting it is equivalent to specifying the
      empty context value (`{}`).
    $ref: "schema:ethdebug/format/program/context"
    default: {}

  instructions:
    type: array
    description: |
      The full array of instructions for the bytecode.
    items:
      $ref: "schema:ethdebug/format/program/instruction"

required:
  - contract
  - environment
  - instructions

unevaluatedProperties: false

examples:
  - # Incrementing a storage counter
    #
    # This example represents the call bytecode for the following pseudo-code:
    # ```
    # contract Incrementer;
    #
    # storage {
    #   [0] storedValue: uint256;
    # };
    #
    # code {
    #   let localValue = storedValue;
    #   storedValue += 1;
    # };
    # ```
    ethdebug:
      schema: "ethdebug/format/program"
      version: "0.1.0-draft.1"
    contract:
      name: "Incrementer"
      definition:
        source:
          id: 0
    environment: call
    context:
      variables:
        - &stored-value
          identifier: storedValue
          type:
            kind: uint
            bits: 256
          pointer:
            location: storage
            slot: 0
    instructions:
      - offset: 0
        operation:
          mnemonic: PUSH0
        context:
          variables:
            - *stored-value
      - offset: 1
        operation:
          mnemonic: SLOAD
        context:
          variables:
            - *stored-value
            - &local-value
              identifier: localValue
              type:
                kind: uint
                bits: 256
              pointer:
                location: stack
                slot: 0
      - offset: 2
        operation:
          mnemonic: PUSH1
          arguments: ["0x01"]
        context:
          variables:
            - *stored-value
            - <<: *local-value
              pointer:
                location: stack
                slot: 1

      - offset: 4
        operation:
          mnemonic: ADD
        # ADD consumes localValue, leaving storedValue + 1 on the stack,
        # so localValue is no longer observable from this point on.
        context:
          variables:
            - *stored-value
      - offset: 5
        operation:
          mnemonic: PUSH0
        context:
          variables:
            - *stored-value

      - offset: 6
        operation:
          mnemonic: SSTORE
        context:
          variables:
            - *stored-value

JSON

ethdebug/format/program

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/program",
  "title": "ethdebug/format/program",
  "description": "Debugging information about a particular bytecode in a compilation.\n",
  "type": "object",
  "properties": {
    "ethdebug": {
      "title": "Stamp",
      "description": "Names this schema and the specification version. A program\nemitted outside an info document should carry this field. A\nprogram inside an info document (in `programs`) should not; the\nstamp of the info document covers it.\n",
      "allOf": [
        {
          "$ref": "schema:ethdebug/format/data/stamp"
        },
        {
          "title": "{ \"schema\": \"ethdebug/format/program\" }",
          "properties": {
            "schema": {
              "const": "ethdebug/format/program"
            }
          }
        }
      ]
    },
    "compilation": {
      "title": "Compilation reference by ID",
      "description": "A reference to the compilation as an `{ \"id\": ... }` object.\n",
      "$ref": "schema:ethdebug/format/materials/reference"
    },
    "contract": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "definition": {
          "$ref": "schema:ethdebug/format/materials/source-range"
        }
      },
      "required": [
        "definition"
      ]
    },
    "environment": {
      "title": "Bytecode execution environment",
      "description": "Whether this bytecode is for contract creation or runtime calls.\n",
      "type": "string",
      "enum": [
        "call",
        "create"
      ]
    },
    "context": {
      "description": "The context that holds prior to the execution of the first\ninstruction in the bytecode. This is the base case of the context\nchain — the precondition to the first instruction — from which each\ninstruction's own `context` follows as a postcondition (see\n**ethdebug/format/program/instruction**).\n\nThis field is **optional**. Omitting it is equivalent to specifying the\nempty context value (`{}`).\n",
      "$ref": "schema:ethdebug/format/program/context",
      "default": {}
    },
    "instructions": {
      "type": "array",
      "description": "The full array of instructions for the bytecode.\n",
      "items": {
        "$ref": "schema:ethdebug/format/program/instruction"
      }
    }
  },
  "required": [
    "contract",
    "environment",
    "instructions"
  ],
  "unevaluatedProperties": false,
  "examples": [
    {
      "ethdebug": {
        "schema": "ethdebug/format/program",
        "version": "0.1.0-draft.1"
      },
      "contract": {
        "name": "Incrementer",
        "definition": {
          "source": {
            "id": 0
          }
        }
      },
      "environment": "call",
      "context": {
        "variables": [
          {
            "identifier": "storedValue",
            "type": {
              "kind": "uint",
              "bits": 256
            },
            "pointer": {
              "location": "storage",
              "slot": 0
            }
          }
        ]
      },
      "instructions": [
        {
          "offset": 0,
          "operation": {
            "mnemonic": "PUSH0"
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              }
            ]
          }
        },
        {
          "offset": 1,
          "operation": {
            "mnemonic": "SLOAD"
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              },
              {
                "identifier": "localValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "stack",
                  "slot": 0
                }
              }
            ]
          }
        },
        {
          "offset": 2,
          "operation": {
            "mnemonic": "PUSH1",
            "arguments": [
              "0x01"
            ]
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              },
              {
                "identifier": "localValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "stack",
                  "slot": 1
                }
              }
            ]
          }
        },
        {
          "offset": 4,
          "operation": {
            "mnemonic": "ADD"
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              }
            ]
          }
        },
        {
          "offset": 5,
          "operation": {
            "mnemonic": "PUSH0"
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              }
            ]
          }
        },
        {
          "offset": 6,
          "operation": {
            "mnemonic": "SSTORE"
          },
          "context": {
            "variables": [
              {
                "identifier": "storedValue",
                "type": {
                  "kind": "uint",
                  "bits": 256
                },
                "pointer": {
                  "location": "storage",
                  "slot": 0
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Playground

Loading playground...

Stamp

A program emitted outside an info document should carry a stamp in its ethdebug field. A program inside an info document should not. See Stamp.