Data Structure

The draft envelope format and field semantics of a Sigil.

Draft

This page specifies the draft Sigil envelope: the fields every Sigil shares, their types and the rules for encoding them.

Envelope

envelope.json

Draft Example — Not Finalized

JSON

{
  "p": "saelis",
  "v": 0,
  "std": "elc-20",
  "meta": {
    "name": "Example",
    "description": "Optional human-readable text.",
    "uri": "ipfs://bafy…",
    "hash": "0x…"
  },
  "refs": [
    { "rel": "part-of", "id": "0x7a…c2" }
  ],
  "body": {}
}

Field reference

Field	Type	Required	Description
`p`	string	Yes	Protocol identifier. Must equal `saelis`.
`v`	integer	Yes	Envelope version. The current draft is `0`.
`std`	string or null	No	Lowercase identifier of the standard that interprets the body, such as `elc-20`.
`meta`	object	No	Descriptive metadata. Never affects standard interpretation.
`refs`	array	No	References to earlier Sigils. Defaults to an empty array.
`body`	object	No	Standard-specific content. Defaults to an empty object.

Metadata fields

Field	Type	Description
`name`	string	Short display name.
`description`	string	Longer description.
`uri`	string	Optional pointer to external content.
`hash`	hex string	Optional keccak256 digest of the external content, for integrity checks.

Reference fields

Field	Type	Description
`rel`	string	Relation type, such as `part-of`, `follows` or `derived-from`.
`id`	hex string	Sigil ID of the target. The target must exist at an earlier position.

Encoding

The draft encoding is a fixed ASCII marker followed by UTF-8 JSON:

Text

data:application/vnd.saelis+json,{"p":"saelis","v":0,"body":{}}

The marker lets indexers discard non-Sigil data with a prefix comparison before attempting to parse JSON.

Parsing rules

A conforming parser must reject the record, rather than repair it, if any of the following hold:

The marker is missing or differs in any byte.
The payload is not valid UTF-8 or not valid JSON.
The top-level value is not an object, or contains duplicate keys.
p is not exactly saelis, or v is not a supported version.
A field has the wrong type.

Unknown top-level fields are ignored in version 0, so that future versions can add fields without invalidating earlier parsers.

Type definitions

The draft envelope expressed as TypeScript types, for use in experimental tooling:

TypeScript

export type Hex = `0x${string}`

export interface SigilReference {
  rel: string
  id: Hex
}

export interface SigilEnvelope<Body = Record<string, unknown>> {
  p: 'saelis'
  v: 0
  std?: string | null
  meta?: {
    name?: string
    description?: string
    uri?: string
    hash?: Hex
  }
  refs?: SigilReference[]
  body?: Body
}

Open questions

Maximum envelope size, which will depend on the transport and Elysium's calldata pricing.
Whether to require canonical JSON (such as RFC 8785) so that identical content always produces identical bytes.
Whether to support a compact binary encoding in a later version.