diff --git a/packages/web/spec/materials/_category_.json b/packages/web/spec/materials/_category_.json new file mode 100644 index 00000000..3c917bfa --- /dev/null +++ b/packages/web/spec/materials/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "ethdebug/format/materials", + "position": 5, + "link": { + "type": "generated-index", + "description": "Work-in-progress formal schema for ethdebug format" + } +} diff --git a/packages/web/spec/materials/compilation.mdx b/packages/web/spec/materials/compilation.mdx new file mode 100644 index 00000000..a597d03a --- /dev/null +++ b/packages/web/spec/materials/compilation.mdx @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +import SchemaViewer from "@site/src/components/SchemaViewer"; + +# Compilation schema + + diff --git a/packages/web/spec/materials/id.mdx b/packages/web/spec/materials/id.mdx new file mode 100644 index 00000000..9a7afd5b --- /dev/null +++ b/packages/web/spec/materials/id.mdx @@ -0,0 +1,23 @@ +--- +sidebar_position: 2 +--- + +import SchemaViewer from "@site/src/components/SchemaViewer"; + +# Identifiers and references + +## Identifier schema + +This format defines a very loosely specified schema for external IDs. + + + +## Reference schema + +This format defines a schema for referencing external resources by ID. + + diff --git a/packages/web/spec/materials/overview.mdx b/packages/web/spec/materials/overview.mdx new file mode 100644 index 00000000..ff017eb4 --- /dev/null +++ b/packages/web/spec/materials/overview.mdx @@ -0,0 +1,37 @@ +--- +sidebar_position: 1 +--- + +# Overview + +:::tip + +**ethdebug/format/materials** is a namespace for schemas about external +resources, including schemas for representing full compiler invocation details, +schemas for individual sources, particular source ranges, and so on. + +Schemas in this namespace exist so that the rest of **ethdebug/format** has +a consistent way of representing these external resources. These schemas also +serve to define something of a data model: one aggregation aggregates multiple +sources, e.g. + +::: + +This format defines a namespace of schemas for representing external resources +relevant to smart contract debugging. + +## Reading these schemas + +The **ethdebug/format/materials** namespace is not a schema itself, but rather +a collection of closely-related schemas. + +These schemas (like all schemas in this format) are specified as +[JSON Schema](https://json-schema.org), draft 2020-12. + +Please refer to the following resources in this section, or see the navigation +bar for complete contents. + +- [Identifiers and references](/spec/materials/id) +- [Compilation schema](/spec/materials/compilation) +- [Source schema](/spec/materials/source) +- [Source range schema](/spec/materials/source-range) diff --git a/packages/web/spec/materials/source-range.mdx b/packages/web/spec/materials/source-range.mdx new file mode 100644 index 00000000..e7128d2b --- /dev/null +++ b/packages/web/spec/materials/source-range.mdx @@ -0,0 +1,11 @@ +--- +sidebar_position: 4 +--- + +import SchemaViewer from "@site/src/components/SchemaViewer"; + +# Source range schema + + diff --git a/packages/web/spec/materials/source.mdx b/packages/web/spec/materials/source.mdx new file mode 100644 index 00000000..fcea7942 --- /dev/null +++ b/packages/web/spec/materials/source.mdx @@ -0,0 +1,11 @@ +--- +sidebar_position: 3 +--- + +import SchemaViewer from "@site/src/components/SchemaViewer"; + +# Source schema + + diff --git a/packages/web/src/schemas.ts b/packages/web/src/schemas.ts index 0216b3fc..4beee819 100644 --- a/packages/web/src/schemas.ts +++ b/packages/web/src/schemas.ts @@ -150,4 +150,24 @@ export const schemaIndex: SchemaIndex = { title: "Region reference", href: "/spec/pointer/expression#region-references" }, + + "schema:ethdebug/format/materials/id": { + title: "Identifier schema", + href: "/spec/materials/id#identifier-schema" + }, + + "schema:ethdebug/format/materials/reference": { + title: "Identifier schema", + href: "/spec/materials/id#reference-schema" + }, + + "schema:ethdebug/format/materials/compilation": { + title: "Compilation schema", + href: "/spec/materials/compilation" + }, + + "schema:ethdebug/format/materials/source": { + title: "Source schema", + href: "/spec/materials/source" + }, }; diff --git a/schemas/materials/compilation.schema.yaml b/schemas/materials/compilation.schema.yaml new file mode 100644 index 00000000..d685d83e --- /dev/null +++ b/schemas/materials/compilation.schema.yaml @@ -0,0 +1,86 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/materials/compilation" + +title: ethdebug/format/materials/compilation +description: | + An object representing a single invocation of a compiler. + +type: object +properties: + id: + description: | + Compilation ID. Optional, but **should** be specified. + + This value **should** be globally-unique and generated only from the + compiler inputs (settings, sources, etc.); the same compiler inputs/ + settings **should** produce the same identifier. + + $ref: "schema:ethdebug/format/materials/id" + + compiler: + type: object + title: Compiler name and version + properties: + name: + type: string + description: Compiler name + + version: + type: string + description: | + Compiler version. + + This value **should** be specified using the most detailed version + representation available, i.e., including source control hash and + compiler build information whenever possible. + + required: + - name + - version + + examples: + - name: lllc + version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++ + + settings: + description: | + Compiler settings in a format native to the compiler. + + For compilers whose settings includes full source representations, this + field **should** be specified in such a way that avoids large data + redundancies (e.g. if compiler settings contain full source + representations, then this field would significantly duplicate the + information represented by the `sources` field in this object). + + In situations where settings information duplicates information + represented elsewhere in **ethdebug/format**, compilers **may** adopt + any reasonable strategy, e.g.: + - omit duplications partially (leaving the rest of the settings + intact) + - omit this field entirely + - specify this field as a hash of the full settings + representation (with the expectation that users of this format will + have access to the full representation by some other means) + + allOf: + - true + + sources: + type: array + items: + $ref: "schema:ethdebug/format/materials/source" + +required: + - compiler + - sources + +examples: + - compiler: + name: lllc + version: 0.4.12-develop.2017.6.27+commit.b83f77e0.Linux.g++ + sources: + - id: 0 + path: stdin + contents: | + (add 1 (mul 2 (add 3 4))) + language: LLL diff --git a/schemas/materials/id.schema.yaml b/schemas/materials/id.schema.yaml new file mode 100644 index 00000000..98468e97 --- /dev/null +++ b/schemas/materials/id.schema.yaml @@ -0,0 +1,13 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/materials/id" + +title: ethdebug/format/materials/id +description: An opaque external ID (likely generated by compiler) + +type: + - number + - string + +examples: + - 5 + - "five" diff --git a/schemas/materials/reference.schema.yaml b/schemas/materials/reference.schema.yaml new file mode 100644 index 00000000..0c1eccb3 --- /dev/null +++ b/schemas/materials/reference.schema.yaml @@ -0,0 +1,22 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/materials/reference" + +title: ethdebug/format/materials/reference +description: A reference to an external resource by ID + +type: object +properties: + id: + $ref: "schema:ethdebug/format/materials/id" + + type: + enum: + - compilation + - source + +required: [id] + +unevaluatedProperties: false + +examples: + - id: 1 diff --git a/schemas/materials/source-range.schema.yaml b/schemas/materials/source-range.schema.yaml new file mode 100644 index 00000000..bccf805c --- /dev/null +++ b/schemas/materials/source-range.schema.yaml @@ -0,0 +1,56 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/materials/source-range" + +title: ethdebug/format/materials/source-range +description: | + A range of bytes in a particular source. + + Note that this refers to the bytes range in the original character encoding + for the source, not the character encoding used for strings in this JSON + format (UTF-8). For compilers that support input sources in encodings other + than this format's transmission encoding, compilers **must** address source + ranges in this original encoding, and debuggers **must** re-encode source + contents obtained from this format _before_ performing any range addressing. + + (Compilers that only accept UTF-8 or ASCII are naturally exempt from this + concern.) + +type: object +properties: + compilation: + title: Compilation reference by ID + $ref: "schema:ethdebug/format/materials/reference" + + source: + title: Source reference by ID + $ref: "schema:ethdebug/format/materials/reference" + + range: + type: object + properties: + offset: + description: Byte offset at beginning of range + type: number + + length: + description: Number of bytes contained in range + type: number + + unevaluatedProperties: false + + required: + - offset + - length + +unevaluatedProperties: false + +required: + - source + - range + +examples: + - source: + id: 5 + range: + offset: 20 + length: 100 diff --git a/schemas/materials/source.schema.yaml b/schemas/materials/source.schema.yaml new file mode 100644 index 00000000..c00a276c --- /dev/null +++ b/schemas/materials/source.schema.yaml @@ -0,0 +1,99 @@ +$schema: "https://json-schema.org/draft/2020-12/schema" +$id: "schema:ethdebug/format/materials/source" + +title: ethdebug/format/materials/source +description: | + An object representing one unit of compiler input, the raw text contents and + identifying metadata (such as file path) that were given to the compiler as + part of a compilation. + +type: object +properties: + id: + description: | + Source identifier. This field **must** be unique for all sources + within a single compiler invocation (compilation). + $ref: "schema:ethdebug/format/materials/id" + + path: + type: string + description: | + Hierarchical file-system-like path to this source. This value may + be an absolute path, a path relative to some root directory, a path + to some resource within a package, etc. + + This value does not need to correspond to any file on disk (either + physical or virtual), and might instead refer to a path identifier + for a source that was generated by a compiler or other development tool. + + This format makes no specific restrictions on how paths should be + specified (e.g., no restriction on path separators, etc.), other than + that values for this field should match what users observe elsewhere for + the inputs/outputs of this particular compiler invocation. + + If no path information is available for a particular source, e.g. if the + source was provided to the compiler via shell standard input, this field + should indicate that somehow (e.g., specifying `"path": "stdin"` or + similar). + + This field's value **should** be unique across all sources within the + same compilation. + + contents: + description: | + The full contents of the source, possibly re-encoded as UTF-8 to + match parent JSON encoding. + + In cases where input source used a different encoding, this object + **must** also specify an `encoding` property to indicate the + encoding originally used. Where relevant, debuggers **must** also + convert these `contents` back to the specified original encoding so + as to match code author expectations. + + type: string + + encoding: + description: | + Character encoding of original source `contents`. This property + is **required** if this encoding does not match the JSON transmission + encoding (UTF-8), since the value of the `contents` property will + represent the text of the source of this JSON encoding. + + This property **must not** appear in objects that do not specify + a `contents` property. + + type: string + + language: + description: | + The high-level language that the source contents are written in. + + type: string + +required: + - id + - path + - contents + - language + +examples: + - id: 5 + path: ./contracts/SimpleStorage.sol + contents: | + // SPDX-License-Identifier: GPL-3.0 + pragma solidity >=0.4.16 <0.9.0; + + contract SimpleStorage { + uint storedData; + + function set(uint x) public { + storedData = x; + } + + function get() public view returns (uint) { + return storedData; + } + } + + language: + Solidity diff --git a/schemas/type/definition.schema.yaml b/schemas/type/definition.schema.yaml index a4974bf6..05e38de2 100644 --- a/schemas/type/definition.schema.yaml +++ b/schemas/type/definition.schema.yaml @@ -13,33 +13,20 @@ properties: name: type: string - source: - type: object - properties: - id: - type: - - string - - number - range: - type: object - properties: - offset: - type: number - length: - type: number + location: + $ref: "schema:ethdebug/format/materials/source-range" anyOf: - title: Required `name` - required: - - name - - title: Required `source` - required: - - source + required: [name] + - title: Required `location` + required: [location] examples: - name: Ballot - source: - id: 5 + location: + source: + id: 5 range: offset: 10 length: 56