pointer.schema.yaml

$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

oneOf:
  - $ref: "schema:ethdebug/format/pointer/region"
  - $ref: "schema:ethdebug/format/pointer/collection"

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

  - # example `uint256[] memory` allocation pointer
    define:
      "uint256-array-memory-pointer-slot": 0
    in:
      # 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: "uint256-array-memory-pointer-slot"

        # 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: $this
              length: $wordsize

  - # example `struct Record { uint8 x; uint8 y; bytes4 salt; }` in storage
    #
    # this example defines the "packed-field" template inline and demonstrates
    # how templates can be reused with `yields` to rename regions.
    # each field is placed by packing right-to-left from the previous offset.
    templates:
      packed-field:
        expect:
          - "struct-storage-contract-variable-slot"
          - "previous"
          - "size"
        for:
          name: "field"
          location: storage
          slot: "struct-storage-contract-variable-slot"
          offset:
            $difference: ["previous", "size"]
          length: "size"
    in:
      define:
        "struct-storage-contract-variable-slot": 0
      in:
        group:
          # sentinel region marking where packing begins (end of word)
          - name: "packing-begin"
            location: storage
            slot: "struct-storage-contract-variable-slot"
            offset: $wordsize
            length: 0

          - define: { previous: { .offset: "packing-begin" }, size: 1 }
            in:
              template: "packed-field"
              yields: { "field": "x" }

          - define: { previous: { .offset: "x" }, size: 1 }
            in:
              template: "packed-field"
              yields: { "field": "y" }

          - define: { previous: { .offset: "y" }, size: 4 }
            in:
              template: "packed-field"
              yields: { "field": "salt" }

  - # 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:
      "string-storage-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: "string-storage-contract-variable-slot"
          offset:
            $difference: [$wordsize, 1]
          length: 1

        # 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: "string-storage-contract-variable-slot"
              offset: 0
              length: "string-length"

          # long string case (flag is odd)
          else:
            group:
              # long strings may use full word to describe length as 2n+1
              - name: "long-string-length-data"
                location: storage
                slot: "string-storage-contract-variable-slot"
                offset: 0
                length: $wordsize

              - define:
                  "string-length":
                    $quotient:
                      - $difference:
                          - $read: "long-string-length-data"
                          - 1
                      - 2

                  "start-slot":
                    $keccak256:
                      - $wordsized: "string-storage-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"]