Schema

Explore

Loading ....

View source

YAML

ethdebug/format/program/context

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

title: ethdebug/format/program/context
description: |
  An **ethdebug/format/program/context** object represents compile-time
  information about the high-level runtime execution state at a specific point
  in a program's bytecode.

  This schema provides a formal specification for this format's model of what
  information can be known at compile-time about the high-level runtime. This
  includes data such as a particular machine instruction's source mapping or
  what variables exist in runtime state following some instruction.

  The context object supports dynamic context combination and selection through
  the use of `gather`, and `pick` properties. This allows for flexible
  composition and extraction of context information.

  Contexts serve as a bridge between low-level EVM execution and high-level
  language constructs. Debuggers can use these compile-time guarantees to
  maintain a coherent view of the high-level language runtime throughout
  program execution. This enables debugging tools to map execution points to
  source code, reconstruct variable states, provide meaningful stack traces,
  and offer insights into control flow and data structures.

type: object

allOf:
  - if:
      required: ["code"]
    then:
      description: |
        The context's corresponding source code range.
      $ref: "schema:ethdebug/format/program/context/code"
  - if:
      required: ["variables"]
    then:
      description: |
        Variable definitions, types, allocations known to exist in the context.
      $ref: "schema:ethdebug/format/program/context/variables"
  - if:
      required: ["remark"]
    then:
      description: |
        Human-readable context annotation. Not intended for compiler use.
      $ref: "schema:ethdebug/format/program/context/remark"
  - if:
      required: ["pick"]
    then:
      description: |
        Alternation between several possible contexts.
      $ref: "schema:ethdebug/format/program/context/pick"
  - if:
      required: ["gather"]
    then:
      description: |
        Collection of multiple known, separate contexts.
      $ref: "schema:ethdebug/format/program/context/gather"
  - if:
      required: ["frame"]
    then:
      description: |
        For use by compilers with multiple pipeline outputs (e.g., use of an
        intermediary representation) to associate a
        context with a particular compiler step.
      $ref: "schema:ethdebug/format/program/context/frame"

unevaluatedProperties: false

examples:
  - variables:
      - identifier: x
        declaration:
          source:
            id: 5
          range:
            offset: 10
            length: 56
        type:
          kind: string
        pointer:
          location: storage
          slot: 0
    code:
      source:
        id: 5
      range:
        offset: 68
        length: 16

JSON

ethdebug/format/program/context

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/program/context",
  "title": "ethdebug/format/program/context",
  "description": "An **ethdebug/format/program/context** object represents compile-time\ninformation about the high-level runtime execution state at a specific point\nin a program's bytecode.\n\nThis schema provides a formal specification for this format's model of what\ninformation can be known at compile-time about the high-level runtime. This\nincludes data such as a particular machine instruction's source mapping or\nwhat variables exist in runtime state following some instruction.\n\nThe context object supports dynamic context combination and selection through\nthe use of `gather`, and `pick` properties. This allows for flexible\ncomposition and extraction of context information.\n\nContexts serve as a bridge between low-level EVM execution and high-level\nlanguage constructs. Debuggers can use these compile-time guarantees to\nmaintain a coherent view of the high-level language runtime throughout\nprogram execution. This enables debugging tools to map execution points to\nsource code, reconstruct variable states, provide meaningful stack traces,\nand offer insights into control flow and data structures.\n",
  "type": "object",
  "allOf": [
    {
      "if": {
        "required": [
          "code"
        ]
      },
      "then": {
        "description": "The context's corresponding source code range.\n",
        "$ref": "schema:ethdebug/format/program/context/code"
      }
    },
    {
      "if": {
        "required": [
          "variables"
        ]
      },
      "then": {
        "description": "Variable definitions, types, allocations known to exist in the context.\n",
        "$ref": "schema:ethdebug/format/program/context/variables"
      }
    },
    {
      "if": {
        "required": [
          "remark"
        ]
      },
      "then": {
        "description": "Human-readable context annotation. Not intended for compiler use.\n",
        "$ref": "schema:ethdebug/format/program/context/remark"
      }
    },
    {
      "if": {
        "required": [
          "pick"
        ]
      },
      "then": {
        "description": "Alternation between several possible contexts.\n",
        "$ref": "schema:ethdebug/format/program/context/pick"
      }
    },
    {
      "if": {
        "required": [
          "gather"
        ]
      },
      "then": {
        "description": "Collection of multiple known, separate contexts.\n",
        "$ref": "schema:ethdebug/format/program/context/gather"
      }
    },
    {
      "if": {
        "required": [
          "frame"
        ]
      },
      "then": {
        "description": "For use by compilers with multiple pipeline outputs (e.g., use of an\nintermediary representation) to associate a\ncontext with a particular compiler step.\n",
        "$ref": "schema:ethdebug/format/program/context/frame"
      }
    }
  ],
  "unevaluatedProperties": false,
  "examples": [
    {
      "variables": [
        {
          "identifier": "x",
          "declaration": {
            "source": {
              "id": 5
            },
            "range": {
              "offset": 10,
              "length": 56
            }
          },
          "type": {
            "kind": "string"
          },
          "pointer": {
            "location": "storage",
            "slot": 0
          }
        }
      ],
      "code": {
        "source": {
          "id": 5
        },
        "range": {
          "offset": 68,
          "length": 16
        }
      }
    }
  ]
}

Playground

Loading...