Define ethdebug/format/info schema

packages/web/spec/info/_category_.json

@@ -0,0 +1,5 @@
+{
+  "label": "ethdebug/format/info",
+  "position": 5,
+  "link": null
+}

packages/web/spec/info/info.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 4
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/info" }}
+  />

packages/web/spec/info/overview.mdx

@@ -0,0 +1,55 @@
+---
+sidebar_position: 1
+---
+
+# Overview
+
+:::tip[Summary]
+
+**ethdebug/format/info** is a JSON Schema and namespace containing the
+**ethdebug/format/info/resources** JSON Schema. These schemas provide a means
+for representing the debugging data pertaining to a particular compilation.
+
+These two schemas serve to address two distinct purposes:
+1. **ethdebug/format/info** provides a means for representing a complete,
+   standalone, and language-agnostic representation of all necessary debugging
+   data. Objects in this schema contain all information specified by
+   **ethdebug/format/info/resources** plus additional metadata.
+2. **ethdebug/format/info/resources** provides a means for compilers to specify
+   compilation-related debug information without also specifying compilation
+   metadata that may already be found elsewhere in compiler output.
+
+Due to the common practice that EVM language compilers already provide their
+own structured JSON output formats, it is expected that compilers will
+primarily produce objects in the **ethdebug/format/info/resources** schema, and
+that language-specific tooling will serve to convert these objects plus other
+compiler JSON output into the more standalone **ethdebug/format/info**.
+
+This format recommends that compilers **should** ensure there
+exists tooling support for the creation of **ethdebug/format/info** objects,
+either via custom compilation modes or through the distribution of first- or
+third-party tools.
+
+:::
+
+This format defines the primary **ethdebug/format/info** schema.
+
+JSON values adhering to this schema contain debugging information about a
+single invocation of a compiler.
+
+
+## Reading this schema
+
+The **ethdebug/format/info** schema is a standalone schema and does not define
+a corresponding namespace.
+
+This schema (like all schemas in this format) are specified as
+[JSON Schema](https://json-schema.org), draft 2020-12.
+
+Please refer to one or more of the following resources in this section, or
+see the navigation bar for complete contents:
+
+- [Schema](/spec/info) (**ethdebug/format/info** schema listing)
+
+- [Resources schema](/spec/info/resources)
+  (**ethdebug/format/info/resources** schema listing)

packages/web/spec/info/resources.mdx

@@ -0,0 +1,11 @@
+---
+sidebar_position: 5
+---
+
+import SchemaViewer from "@site/src/components/SchemaViewer";
+
+# Resources lookup schema
+
+<SchemaViewer
+  schema={{ id: "schema:ethdebug/format/info/resources" }}
+  />

packages/web/src/schemas.ts

@@ -194,6 +194,11 @@ const materialsSchemaIndex: SchemaIndex = {
     title: "Source range schema",
     href: "/spec/materials/source-range"
   },
+
+  "schema:ethdebug/format/info": {
+    title: "ethdebug/format/info",
+    href: "/spec/info"
+  },
 };
 
 const programSchemaIndex: SchemaIndex = {
@@ -216,7 +221,15 @@ const programSchemaIndex: SchemaIndex = {
       }
     })).reduce((a, b) => ({ ...a, ...b }), {})
   ),
+};
 
+const infoSchemaIndex: SchemaIndex = {
+  "schema:ethdebug/format/info": {
+    href: "/spec/info"
+  },
+  "schema:ethdebug/format/info/resources": {
+    href: "/spec/info/resources"
+  },
 };
 
 export const schemaIndex: SchemaIndex = {
@@ -225,4 +238,5 @@ export const schemaIndex: SchemaIndex = {
   ...dataSchemaIndex,
   ...materialsSchemaIndex,
   ...programSchemaIndex,
+  ...infoSchemaIndex,
 };

schemas/info.schema.yaml

@@ -0,0 +1,184 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/info"
+
+title: ethdebug/format/info
+description: |
+  Debugging information about a single compilation
+
+type: object
+
+$ref: "schema:ethdebug/format/info/resources"
+
+properties:
+  programs:
+    type: array
+    items:
+      $ref: "schema:ethdebug/format/program"
+    additionalItems:
+      false
+
+  compilation:
+    $ref: "schema:ethdebug/format/materials/compilation"
+
+
+required:
+  - compilation
+  - programs
+
+examples:
+  - compilation:
+      id: __301f3b6d85831638
+      compiler:
+        name: egc
+        version: 0.2.3+commit.8b37fa7a
+      settings:
+        turbo: true
+      sources:
+        - id: 1
+          path: "Escrow.eg"
+          language: examplelang
+          contents: |
+            import { Asset } from std::asset::fungible;
+
+            type State = !slots[
+              ready: bool,
+              complete: bool,
+
+              beneficiary: address,
+
+              asset: Asset,
+              amount: uint256,
+
+              canRemit: () -> bool,
+            ]
+
+            @create
+            func setup(
+              beneficiary: address,
+              asset: Asset,
+              canRemit: () -> bool,
+            ) -> State:
+              return {
+                ready = False,
+                complete = False,
+                beneficiary,
+                asset,
+                amount = 0,
+                canRemit,
+              }
+
+            @abi
+            @state(self: State)
+            @account(self)
+            func deposit(depositor: address, amount: uint256):
+              require(!self.ready)
+              require(!self.complete)
+
+              # expects an existing allowance (also known as "approval")
+              self.asset.transferFrom(depositor, self, amount)
+
+              self.amount = amount
+              self.ready = True
+
+            @abi
+            @state(self: State)
+            func remit():
+              require(self.ready)
+              require(!self.complete)
+
+              require(self.canRemit())
+
+              asset.transfer(self.beneficiary, self.amount)
+
+              self.complete = True
+
+    types:
+      # Define the State type structure
+      State:
+        kind: "struct"
+        contains:
+          - name: "ready"
+            type:
+              kind: "bool"
+          - name: "complete"
+            type:
+              kind: "bool"
+          - name: "beneficiary"
+            type:
+              kind: "address"
+          - name: "asset"
+            type:
+              kind: "struct"
+              contains:
+                - name: "address"
+                  type:
+                    kind: "address"
+          - name: "amount"
+            type:
+              kind: "uint"
+              bits: 256
+          - name: "canRemit"
+            type:
+              kind: "function"
+              internal: true
+              contains:
+                parameters:
+                  type:
+                    kind: "tuple"
+                    contains: []
+                returns:
+                  type:
+                    kind: "bool"
+
+    pointers:
+      # Define storage layout for the State struct
+      State_storage:
+        expect: ["slot"]
+        for:
+          group:
+            - name: "ready"
+              location: "storage"
+              slot: "slot"
+              offset: 0
+              length: 1
+            - name: "complete"
+              location: "storage"
+              slot: "slot"
+              offset: 1
+              length: 1
+            - name: "beneficiary"
+              location: "storage"
+              slot: { "$sum": ["slot", 1] }
+            - name: "asset"
+              location: "storage"
+              slot: { "$sum": ["slot", 2] }
+            - name: "amount"
+              location: "storage"
+              slot: { "$sum": ["slot", 3] }
+            - name: "canRemit"
+              location: "storage"
+              slot: { "$sum": ["slot", 4] }
+
+    programs:
+      - contract:
+          name: "Escrow"
+          definition:
+            source:
+              id: 1
+            range:
+              offset: 0
+              length: 891
+        environment: "create"
+        instructions:
+          - offset: 0
+            operation:
+              mnemonic: "PUSH1"
+              arguments: ["0x80"]
+            context:
+              code:
+                source:
+                  id: 1
+                range:
+                  offset: 891
+                  length: 20
+

schemas/info/resources.schema.yaml

@@ -0,0 +1,75 @@
+$schema: "https://json-schema.org/draft/2020-12/schema"
+$id: "schema:ethdebug/format/info/resources"
+
+title: ethdebug/format/info/resources
+description: |
+  An object containing lookup tables for finding debugging resources by name.
+
+type: object
+
+properties:
+  types:
+    title: Types by name
+    description: |
+      A collection of types by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/type"
+
+  pointers:
+    title: Pointer templates by name
+    description: |
+      A collection of pointer templates by name identifier.
+    type: object
+    additionalProperties:
+      $ref: "schema:ethdebug/format/pointer/template"
+
+  compilation:
+    $ref: "schema:ethdebug/format/materials/compilation"
+
+
+required:
+  - types
+  - pointers
+
+examples:
+  - types:
+      "struct__Coordinate":
+        kind: struct
+        contains:
+          - name: x
+            type:
+              kind: uint
+              bits: 128
+          - name: y
+            type:
+              kind: uint
+              bits: 128
+        definition:
+          name: Coordinate
+          location:
+            source:
+              id: 5
+            range:
+              offset: 18
+              length: 55
+
+    pointers:
+      "struct__Coordinate__storage":
+        expect:
+          - contract_variable_slot__struct__Coordinate__storage
+        for:
+          group:
+            - name: member__x__struct__Coordinate__storage
+              location: storage
+              slot: contract_variable_slot__struct__Coordinate__storage
+              offset: 0
+              length: 128
+            - name: member__y__struct__Coordinate__storage
+              location: storage
+              slot: contract_variable_slot__struct__Coordinate__storage
+              offset:
+                $sum:
+                  - .offset: member__x__struct__Coordinate__storage
+                  - .length: member__x__struct__Coordinate__storage
+              length: 128

schemas/materials/compilation.schema.yaml

@@ -11,7 +11,7 @@ properties:
     description: |
       Compilation ID. Optional, but **should** be specified.
 
-      This value **should** be globally-unique and generated only from the
+      This value **must** be globally-unique and generated only from the
       compiler inputs (settings, sources, etc.); the same compiler inputs/
       settings **should** produce the same identifier.