sect-metadata.md

title
-chap-num- Metadata

import Metadata from '/static/img/kaitai_render/metadata.svg'; import MetadataType from '/static/img/kaitai_render/metadata_type.svg'; import MetadataTypeDefinition from '/static/img/kaitai_render/metadata_type_definition.svg'; import MetadataTypeFields from '/static/img/kaitai_render/metadata_type_fields.svg'; import MetadataTypeVariants from '/static/img/kaitai_render/metadata_type_variants.svg'; import MetadataPallet from '/static/img/kaitai_render/metadata_pallet.svg'; import PalletStorage from '/static/img/kaitai_render/pallet_storage.svg'; import StorageDefinition from '/static/img/kaitai_render/storage_definition.svg'; import PalletConstant from '/static/img/kaitai_render/pallet_constant.svg'; import MetadataExtrinsic from '/static/img/kaitai_render/metadata_extrinsic.svg';

The runtime metadata structure contains all the information necessary on how to interact with the Polkadot runtime. Considering that Polkadot runtimes are upgradable and, therefore, any interfaces are subject to change, the metadata allows developers to structure any extrinsics or storage entries accordingly.

The metadata of a runtime is provided by a call to Metadata_metadata (Section -sec-num-ref-) and is returned as a scale encoded (Section -sec-num-ref-) binary blob. How to interpret and decode this data is described in this chapter.

-sec-num- Structure {#sect-rtm-structure}

The Runtime Metadata is a data structure of the following format:

$$ {\left({M},{v}{{m}},{R},{P},{t}{{e}},{v}{{e}},{E},{t}{{r}}\right)} $$ $$ {R}={\left({r}{{0}},\ldots,{r}{{n}}\right)} $$ $$ {P}={\left({p}{{0}},\ldots,{p}{{n}}\right)} $$ $$ {E}={\left({e}{{0}},\ldots,{e}{{n}}\right)} $$

where

• ${M}$ are the first four constant bytes, spelling "meta" in ASCII.

• ${v}_{{m}}$ is an unsigned 8-bit integer indicating the format version of the metadata structure (currently the value of 14).

• ${R}$ is a sequence (Definition -def-num-ref-) of type definitions ${r}_{{i}}$ (Definition -def-num-ref-).

• ${P}$ is a sequence (Definition -def-num-ref-) of pallet metadata ${p}_{{i}}$ (Section -sec-num-ref-).

• ${t}_{{e}}$ is the type Id (Definition -def-num-ref-) of the extrinsics.

• ${v}_{{e}}$ is an unsigned 8-bit integer indicating the format version of the extrinsics (implying a possible breaking change).

• ${E}$ is a sequence (Definition -def-num-ref-) of extrinsics metadata ${e}_{{i}}$ (Definition -def-num-ref-).

• ${t}_{{r}}$ is the type Id (Definition -def-num-ref-) of the runtime.

Image -img-num- Metadata {#img-metadata}

Definition -def-num- Runtime Registry Type Entry {#defn-rtm-registry-entry}

:::definition

A registry entry contains information about a type in its portable form for serialization. The entry is a data structure of the following format:

$$ {r}{{i}}={\left(\text{id}{{t}},{p},{T},{D},{c}\right)} $$ $$ {T}={\left({t}{{0}},\ldots,{t}{{n}}\right)} $$ $$ {t}_{{i}}={\left({n},{y}\right)} $$

where

• $\text{id}_{{t}}$ is a compact integer indicating the identifier of the type.

• ${p}$ is the path of the type, optional and based on the source file location. Encoded as a sequence (Definition -def-num-ref-) of strings.

• ${T}$ is a sequence (Definition -def-num-ref-) of generic parameters (empty for non-generic types).

  • ${n}$ is the name string of the generic type parameter

  • ${y}$ is a Option type containing a type Id (Definition -def-num-ref-).

• ${D}$ is the type definition (Definition -def-num-ref-).

• ${c}$ is the documentation as sequence (Definition -def-num-ref-) of strings.

Image -img-num- Metadata Type {#img-metadata-type}

::: ###### Definition -def-num- Runtime Type Id {#defn-rtm-type-id} :::definition

The runtime type Id is a compact integer representing the index of the entry (Definition -def-num-ref-) in ${R},{P}$ or ${E}$ of the runtime metadata structure (Section -sec-num-ref-), depending on context (starting at ${0}$).

:::

Definition -def-num- Type Variant {#defn-rtm-type-definition}

:::definition

The type definition ${D}$ is a varying datatype (Definition -def-num-ref-) and indicates all the possible types of encodable values a type can have.

$$ {D}={\left\lbrace\begin{matrix}{0}&\rightarrow&{C}&\text{composite type (e.g. structure or tuple)}\{1}&\rightarrow&{V}&\text{variant type}\{2}&\rightarrow&{s}_{{v}}&\text{sequence type varying length}\{3}&\rightarrow&{S}&\text{sequence with fixed length}\{4}&\rightarrow&{T}&\text{tuple type}\{5}&\rightarrow&{P}&\text{primitive type}\{6}&\rightarrow&{e}&\text{compact encoded type}\{7}&\rightarrow&{B}&\text{sequence of bits}\end{matrix}\right.} $$

where

• ${C}$ is a sequence of the following format:

  ${C}={\left({{f}{{0}},}\ldots,{f}{{n}}\right)}$

  • ${f_i}$ is a field (Definition -def-num-ref-).

• ${V}$ is a sequence of the following format:

  ${V}={\left({v}{{0}},\ldots,{v}{{n}}\right)}$

  • ${v}_{{i}}$ is a variant (Definition -def-num-ref-).

• ${s}_{{v}}$ is a type Id (Definition -def-num-ref-).

• ${S}$ is of the following format:

  ${S}={\left({l},{y}\right)}$

  • ${l}$ is an unsigned 32-bit integer indicating the length

  • ${y}$ is a type Id (Definition -def-num-ref-).

• ${T}$ is a sequence (Definition -def-num-ref-) of type Ids (Definition -def-num-ref-).

• ${P}$ is a varying datatype (Definition -def-num-ref-) of the following structure:

  $$ {P}={\left\lbrace\begin{matrix}{0}&\text{boolean}\{1}&\text{char}\{2}&\text{string}\{3}&\text{unsigned 8-bit integer}\{4}&\text{unsigned 16-bit integer}\{5}&\text{unsigned 32-bit integer}\{6}&\text{unsigned 64-bit integer}\{7}&\text{unsigned 128-bit integer}\{8}&\text{unsigned 256-bit integer}\{9}&\text{signed 8-bit integer}\{10}&\text{signed 16-bit integer}\{11}&\text{signed 32-bit integer}\{12}&\text{signed 64-bit integer}\{13}&\text{signed 128-bit integer}\{14}&\text{signed 256-bit integer}\end{matrix}\right.} $$

• ${e}$ is a type Id (Definition -def-num-ref-).

• ${B}$ is a data structure of the following format:

  ${B}={\left({s},{o}\right)}$

  • ${s}$ is a type Id (Definition -def-num-ref-) representing the bit store order (external reference)

  • ${o}$ is a type Id (Definition -def-num-ref-) the bit order type (external reference).

Image -img-num- Metadata Type Definition {#img-metadata-type-definition}

:::

Definition -def-num- Field {#defn-rtm-field}

:::definition

A field of a data structure of the following format:

$$ {{f}{{i}}=}{\left({n},{y},{y}{{n}},{C}\right)} $$

where

• ${n}$ is an Option type containing the string that indicates the field name.

• ${y}$ is a type Id (Definition -def-num-ref-).

• ${y}_{{n}}$ is an Option type containing a string that indicates the name of the type as it appears in the source code.

• ${C}$ is a sequence of varying length containing strings of documentation.

Image -img-num- Metadata Type Fields {#img-metadata-type-fields}

:::

Definition -def-num- Variant {#defn-rtm-variant}

:::definition

A struct variant of the following format:

$$ {v}_{{i}}={\left({n},{F},{k},{C}\right)} $$

where

• ${n}$ is a string representing the name of the variant.

• ${F}$ is a possible empty array of varying length containing field (Definition -def-num-ref-) elements.

• ${k}$ is an unsigned 8-bit integer indicating the index of the variant.

• ${C}$ is a sequence of strings containing the documentation.

Image -img-num- Metadata Type Variants {#img-metadata-type-variants}

::: ## -sec-num- Pallet Metadata {#sect-rtm-pallet-metadata}

All the metadata about a pallet, part of the main structure (Section -sec-num-ref-) and of the following format:

$$ {p}_{{i}}={\left({n},{S},{a},{e},{C},{e},{i}\right)} $$

where

• ${n}$ is a string representing the pallet name.

• ${S}$ is an Option type containing the pallet storage metadata (Definition -def-num-ref-).

• ${a}$ is an Option type (Definition -def-num-ref-) containing the type Id (Definition -def-num-ref-) of pallet calls.

• ${e}$ is an Option type (Definition -def-num-ref-) containing the type Id (Definition -def-num-ref-) of pallet events.

• ${C}$ is an Sequence (Definition -def-num-ref-) of all pallet constant metadata (Definition -def-num-ref-).

• ${e}$ is an Option type (Definition -def-num-ref-) containing the type Id (Definition -def-num-ref-) of the pallet error.

• ${i}$ is an unsigned 8-bit integer indicating the index of the pallet, which is used for encoding pallet events and calls.

Image -img-num- Metadata Pallet {#img-metadata-pallet}

Definition -def-num- Pallet Storage Metadata {#defn-rtm-pallet-storage-metadata}

:::definition

The metadata about pallets storage.

$$ {S}={\left({p},{E}\right)} $$ $$ {E}={\left({e}{{0}},\ldots,{e}{{n}}\right)} $$

where

• ${p}$ is the string representing the common prefix used by all storage entries.

• ${E}$ is an array of varying lengths containing elements of storage entries (Definition -def-num-ref-).

:::

Definition -def-num- Storage Entry Metadata {#defn-rtm-storage-entry-metadata}

:::definition

The metadata about a pallets storage entry.

$$ {e}{{i}}={\left({n},{m},{y},{d},{C}\right)} $$ $$ {C}={\left({c}{{0}},\ldots,{c}_{{n}}\right)} $$

where

• ${n}$ is the string representing the variable name of the storage entry.

• ${m}$ is an enum type determining the storage entry modifier (Definition -def-num-ref-).

• ${y}$ is the type of the value stored in the entry (Definition -def-num-ref-).

• ${d}$ is a byte array containing the default value.

• ${C}$ is an array of varying lengths of strings containing the documentation.

Image -img-num- Pallet Storage {#img-pallet-storage}

::: ###### Definition -def-num- Storage Entry Modifier {#defn-rtm-storage-entry-modifier} ::::definition

:::info This might be incorrect and has to be reviewed. :::

The storage entry modifier is a varying datatype (Definition -def-num-ref-) and indicates how the storage entry is returned and how it behaves if the entry is not present.

$$ {m}={\left\lbrace\begin{matrix}{0}&\text{optional}\{1}&\text{default}\end{matrix}\right.} $$

where 0 indicates that the entry returns an Option type and therefore None if the storage entry is not present. 1 indicates that the entry returns the type ${y}$ with default value ${d}$ (in Definition -def-num-ref-) if the entry is not present.

::::

Definition -def-num- Storage Entry Type {#defn-rtm-storage-entry-type}

:::definition

The type of the storage value is a varying datatype (Definition -def-num-ref-) that indicates how the entry is stored.

$$ {y}={\left\lbrace\begin{matrix}{0}&\rightarrow&{t}&\text{plain type}\{1}&\rightarrow&{\left({H},{k},{v}\right)}&\text{storage map}\end{matrix}\right.} $$

where ${t}$, ${k}$ (key) and ${v}$ (value) are all of type Ids (Definition -def-num-ref-). ${H}$ is an array of varying length containing the storage hasher (Definition -def-num-ref-).

Image -img-num- Storage Definition {#img-storage-definition}

:::

Definition -def-num- Storage Hasher {#defn-rtm-storage-hasher}

:::definition

The hashing algorithm is used by storage maps.

$$ {\left\lbrace\begin{matrix}{0}&\text{128-bit Blake2 hash}\{1}&\text{256-bit Blake2 hash}\{2}&\text{Multiple 128-bit Blake2 hashes concatenated}\{3}&\text{128-bit XX hash}\{4}&\text{256-bit XX hash}\{5}&\text{Multiple 64-bit XX hashes concatenated}\{6}&\text{Identity hashing}\end{matrix}\right.} $$

:::

Definition -def-num- Pallet Constants {#defn-rtm-pallet-constants}

:::definition

The metadata about the pallets constants.

$$ {c}_{{i}}={\left({n},{y},{v},{C}\right)} $$

where

• ${n}$ is a string representing the name of the pallet constant.

• ${y}$ is the type Id (Definition -def-num-ref-) of the pallet constant.

• ${v}$ is a byte array containing the value of the constant.

• ${C}$ is an array of varying lengths containing a string with the documentation.

Image -img-num- Pallet Constant {#img-pallet-constant}

::: ## -sec-num- Extrinsic Metadata {#sect-rtm-extrinsic-metadata}

The metadata about a pallets extrinsics, part of the main structure (Section -sec-num-ref-) and of the following format:

Definition -def-num- Signed Extension Metadata {#defn-rtm-signed-extension-metadata}

:::definition

The metadata about the additional, signed data required to execute an extrinsic.

$$ {e}_{{i}}={\left({n},{y},{a}\right)} $$

where

• ${n}$ is a string representing the unique signed extension identifier, which may be different from the type name.

• ${y}$ is a type Id (Definition -def-num-ref-) of the signed extension, with the data to be included in the extrinsic.

• ${a}$ is the type Id (Definition -def-num-ref-) of the additional signed data, with the data to be included in the signed payload.

Image -img-num- Metadata Extrinsic {#img-metadata-extrinsic}

:::