Schema

Explore

Loading ....

View source

YAML

ethdebug/format/pointer

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

title: ethdebug/format/pointer
description: |
  A schema for representing a pointer to a data position or a range of data
  positions in the EVM.

  An **ethdebug/format/pointer** is either a single region or a structured
  collection of other pointers.

type: object

if:
  required: [location]
then:
  $ref: "schema:ethdebug/format/pointer/region"
else:
  $ref: "schema:ethdebug/format/pointer/collection"

examples:
  - # example: a single particular storage slot
    location: storage
    slot: 2

  - # example `uint256[] memory` allocation pointer
    # this pointer composes an ordered list of other pointers
    group:
      # declare the first sub-pointer to be the "array-start" region of data
      # corresponding to the first item in the stack (at time of observation)
      - name: "array-start"
        location: stack
        slot: 0

      # declare the "array-count" region to be at the offset indicated by
      # the value at "array-start"
      - name: "array-count"
        location: memory
        offset:
          $read: "array-start"
        length: $wordsize

      # thirdly, declare a sub-pointer that is a dynamic list whose size is
      # indicated by the value at "array-count", where each "item-index"
      # corresponds to a discrete "array-item" region
      - list:
          count:
            $read: "array-count"
          each: "item-index"
          is:
            name: "array-item"
            location: "memory"
            offset:
              # array items are positioned so that the item with index 0
              # immediately follows "array-count", and each subsequent item
              # immediately follows the previous.
              $sum:
                - .offset: "array-count"
                - .length: "array-count"
                - $product:
                    - "item-index"
                    - .length: "array-item"
            length: $wordsize

  - # example `struct Record { uint128 x; uint128 y }` in memory
    group:
      - name: "struct-start"
        location: stack
        slot: 0

      - name: "struct-member-0"
        location: memory
        # the first struct member begins at the offset indicated by the value
        # at "struct-start"
        offset:
          $read: "struct-start"
        length: $wordsize

      - name: "struct-member-1"
        location: memory
        # the second struct member immediately follows the first
        offset:
          $sum:
            - .offset: "struct-member-0"
            - .length: "struct-member-0"
        length: $wordsize

  - # example `(struct Record { uint256 x; uint256 y; })[] memory`
    group:
      # declare the first sub-pointer to be the "array-start" region of data
      # corresponding to the first item in the stack (at time of observation)
      - name: "array-start"
        location: stack
        slot: 0

      # declares the "array-count" region in memory at the offset indicated
      # by "array-start" and of length equal to word size
      - name: "array-count"
        location: memory
        offset:
          $read: "array-start"
        length: $wordsize

      # declare this to include a list of pointers of size indicated by the
      # value at "array-count", where each "item-index" corresponds to a
      # group of pointers
      - list:
          count:
            $read: "array-count"
          each: "item-index"
          is:
            group:
              # each element in the list includes a "struct-pointer" region
              # in memory (laid out sequentially in a block as the raw
              # array data)
              - name: "struct-pointer"
                location: memory
                offset:
                  $sum:
                    - .offset: "array-count"
                    - .length: "array-count"
                    - $product:
                      - "item-index"
                      - .length: "struct-pointer"
                length: $wordsize

              # following that pointer leads to the region corresponding to
              # the first member of the struct
              - name: "struct-member-0"
                location: memory
                offset:
                  $read: "struct-pointer"
                length: $wordsize

              # the second struct member immediately follows the first
              - name: "struct-member-1"
                location: memory
                offset:
                  $sum:
                    - .offset: "struct-member-0"
                    - .length: "struct-member-0"
                length: $wordsize

  - # example `string storage` allocation
    define:
      "contract-variable-slot": 0
    in:
      group:
        # for short strings, the length is stored as 2n in the last byte of slot
        - name: "length-flag"
          location: storage
          slot: contract-variable-slot
          offset:
            $difference: [$wordsize, 1]
          length: 1

        # long strings may use full word to describe length as 2n+1
        - name: "long-string-length-data"
          location: storage
          slot: contract-variable-slot
          offset: 0
          length: $wordsize

        # define the region representing the string data itself conditionally
        # based on odd or even length data
        - if:
            $remainder:
              - $sum:
                  - $read: "length-flag"
                  - 1
              - 2

          # short string case (flag is even)
          then:
            define:
              "string-length":
                $quotient: [{ $read: "length-flag" }, 2]
            in:
              name: "string"
              location: storage
              slot: "contract-variable-slot"
              offset: 0
              length: "string-length"

          # long string case (flag is odd)
          else:
            define:
              "string-length":
                $quotient:
                  - $difference:
                    - $read: "long-string-length-data"
                    - 1
                  - 2

              "start-slot":
                $keccak256:
                  - $wordsized: "contract-variable-slot"

              "total-slots":
                # account for both zero and nonzero slot remainders by adding
                # $wordsize-1 to the length before dividing
                $quotient:
                  - $sum: ["string-length", { $difference: [$wordsize, 1] }]
                  - $wordsize
            in:
              list:
                count: "total-slots"
                each: "i"
                is:
                  define:
                    "current-slot":
                      $sum: ["start-slot", "i"]
                    "previous-length":
                      $product: ["i", $wordsize]
                  in:
                    # conditional based on whether this is the last slot:
                    # is the string length longer than the previous length
                    # plus this whole slot?
                    if:
                      $difference:
                        - "string-length"
                        - $sum: ["previous-length", "$wordsize"]
                    then:
                      # include the whole slot
                      name: "string"
                      location: storage
                      slot: "current-slot"
                    else:
                      # include only what's left in the string
                      name: "string"
                      location: storage
                      slot: "current-slot"
                      offset: 0
                      length:
                        $difference: ["string-length", "previous-length"]

JSON

ethdebug/format/pointer

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "schema:ethdebug/format/pointer",
  "title": "ethdebug/format/pointer",
  "description": "A schema for representing a pointer to a data position or a range of data\npositions in the EVM.\n\nAn **ethdebug/format/pointer** is either a single region or a structured\ncollection of other pointers.\n",
  "type": "object",
  "if": {
    "required": [
      "location"
    ]
  },
  "then": {
    "$ref": "schema:ethdebug/format/pointer/region"
  },
  "else": {
    "$ref": "schema:ethdebug/format/pointer/collection"
  },
  "examples": [
    {
      "location": "storage",
      "slot": 2
    },
    {
      "group": [
        {
          "name": "array-start",
          "location": "stack",
          "slot": 0
        },
        {
          "name": "array-count",
          "location": "memory",
          "offset": {
            "$read": "array-start"
          },
          "length": "$wordsize"
        },
        {
          "list": {
            "count": {
              "$read": "array-count"
            },
            "each": "item-index",
            "is": {
              "name": "array-item",
              "location": "memory",
              "offset": {
                "$sum": [
                  {
                    ".offset": "array-count"
                  },
                  {
                    ".length": "array-count"
                  },
                  {
                    "$product": [
                      "item-index",
                      {
                        ".length": "array-item"
                      }
                    ]
                  }
                ]
              },
              "length": "$wordsize"
            }
          }
        }
      ]
    },
    {
      "group": [
        {
          "name": "struct-start",
          "location": "stack",
          "slot": 0
        },
        {
          "name": "struct-member-0",
          "location": "memory",
          "offset": {
            "$read": "struct-start"
          },
          "length": "$wordsize"
        },
        {
          "name": "struct-member-1",
          "location": "memory",
          "offset": {
            "$sum": [
              {
                ".offset": "struct-member-0"
              },
              {
                ".length": "struct-member-0"
              }
            ]
          },
          "length": "$wordsize"
        }
      ]
    },
    {
      "group": [
        {
          "name": "array-start",
          "location": "stack",
          "slot": 0
        },
        {
          "name": "array-count",
          "location": "memory",
          "offset": {
            "$read": "array-start"
          },
          "length": "$wordsize"
        },
        {
          "list": {
            "count": {
              "$read": "array-count"
            },
            "each": "item-index",
            "is": {
              "group": [
                {
                  "name": "struct-pointer",
                  "location": "memory",
                  "offset": {
                    "$sum": [
                      {
                        ".offset": "array-count"
                      },
                      {
                        ".length": "array-count"
                      },
                      {
                        "$product": [
                          "item-index",
                          {
                            ".length": "struct-pointer"
                          }
                        ]
                      }
                    ]
                  },
                  "length": "$wordsize"
                },
                {
                  "name": "struct-member-0",
                  "location": "memory",
                  "offset": {
                    "$read": "struct-pointer"
                  },
                  "length": "$wordsize"
                },
                {
                  "name": "struct-member-1",
                  "location": "memory",
                  "offset": {
                    "$sum": [
                      {
                        ".offset": "struct-member-0"
                      },
                      {
                        ".length": "struct-member-0"
                      }
                    ]
                  },
                  "length": "$wordsize"
                }
              ]
            }
          }
        }
      ]
    },
    {
      "define": {
        "contract-variable-slot": 0
      },
      "in": {
        "group": [
          {
            "name": "length-flag",
            "location": "storage",
            "slot": "contract-variable-slot",
            "offset": {
              "$difference": [
                "$wordsize",
                1
              ]
            },
            "length": 1
          },
          {
            "name": "long-string-length-data",
            "location": "storage",
            "slot": "contract-variable-slot",
            "offset": 0,
            "length": "$wordsize"
          },
          {
            "if": {
              "$remainder": [
                {
                  "$sum": [
                    {
                      "$read": "length-flag"
                    },
                    1
                  ]
                },
                2
              ]
            },
            "then": {
              "define": {
                "string-length": {
                  "$quotient": [
                    {
                      "$read": "length-flag"
                    },
                    2
                  ]
                }
              },
              "in": {
                "name": "string",
                "location": "storage",
                "slot": "contract-variable-slot",
                "offset": 0,
                "length": "string-length"
              }
            },
            "else": {
              "define": {
                "string-length": {
                  "$quotient": [
                    {
                      "$difference": [
                        {
                          "$read": "long-string-length-data"
                        },
                        1
                      ]
                    },
                    2
                  ]
                },
                "start-slot": {
                  "$keccak256": [
                    {
                      "$wordsized": "contract-variable-slot"
                    }
                  ]
                },
                "total-slots": {
                  "$quotient": [
                    {
                      "$sum": [
                        "string-length",
                        {
                          "$difference": [
                            "$wordsize",
                            1
                          ]
                        }
                      ]
                    },
                    "$wordsize"
                  ]
                }
              },
              "in": {
                "list": {
                  "count": "total-slots",
                  "each": "i",
                  "is": {
                    "define": {
                      "current-slot": {
                        "$sum": [
                          "start-slot",
                          "i"
                        ]
                      },
                      "previous-length": {
                        "$product": [
                          "i",
                          "$wordsize"
                        ]
                      }
                    },
                    "in": {
                      "if": {
                        "$difference": [
                          "string-length",
                          {
                            "$sum": [
                              "previous-length",
                              "$wordsize"
                            ]
                          }
                        ]
                      },
                      "then": {
                        "name": "string",
                        "location": "storage",
                        "slot": "current-slot"
                      },
                      "else": {
                        "name": "string",
                        "location": "storage",
                        "slot": "current-slot",
                        "offset": 0,
                        "length": {
                          "$difference": [
                            "string-length",
                            "previous-length"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      }
    }
  ]
}

Playground

Loading...