12. Metadata

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 C.5.1.) and is returned as a scale encoded (Section A.2.2.) binary blob. How to interpret and decode this data is described in this chapter.

12.1. Structure

The Runtime Metadata is a datastructure 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 192) of type definitions ${r}_{{i}}$ (Definition 159).

• ${P}$ is a sequence (Definition 192) of pallet metadata ${p}_{{i}}$ (Section 12.2.).

• ${t}_{{e}}$ is the type Id (Definition 160) 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 192) of extrinsics metadata ${e}_{{i}}$ (Definition 170).

• ${t}_{{r}}$ is the type Id (Definition 160) of the runtime.

Image 8. Metadata

Definition 159. Runtime Registry Type Entry

A registry entry contains information about a type in its portable form for serialization. The entry is a datastructure 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 source file location. Encoded as a sequence (Definition 192) of strings.

• ${T}$ is a sequence (Definition 192) 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 160).

• ${D}$ is the type definition (Definition 161).

• ${c}$ is the documentation as sequence (Definition 192) of strings.

Image 9. Metadata Type

Definition 160. Runtime Type Id

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

Definition 161. Type Variant

The type definition ${D}$ is a varying datatype (Definition 188) 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 162).

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

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

  • ${v}_{{i}}$ is a variant (Definition 163).

• ${s}_{{v}}$ is a type Id (Definition 160).

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

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

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

  • ${y}$ is a type Id (Definition 160).

• ${T}$ is a sequence (Definition 192) of type Ids (Definition 160).

• ${P}$ is a varying datatype (Definition 188) 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 160).

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

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

  • ${s}$ is a type Id (Definition 160) representing the bit store order (external reference)

  • ${o}$ is a type Id (Definition 160) the bit order type (external reference).

Image 10. Metadata Type Definition

Definition 162. Field

A field of a datastructure 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 160).

• ${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 11. Metadata Type Fields

Definition 163. Variant

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 162) elements.

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

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

Image 12. Metadata Type Variants

12.2. Pallet Metadata

All the metadata about a pallet, part of the main structure (Section 12.1.) 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 164).

• ${a}$ is an Option type (Definition 190) containing the type Id (Definition 160) of pallet calls.

• ${e}$ is an Option type (Definition 190) containing the type Id (Definition 160) of pallet events.

• ${C}$ is an Sequence (Definition 192) of all pallet constant metadata (Definition 169).

• ${e}$ is an Option type (Definition 190) containing the type Id (Definition 160) of the pallet error.

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

Image 13. Metadata Pallet

Definition 164. Pallet Storage Metadata

The metadata about a 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 length containing elements of storage entries (Definition 165).

Definition 165. Storage Entry Metadata

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 166).

• ${y}$ is the type of the value stored in the entry (Definition 167).

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

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

Image 14. Pallet Storage

Definition 166. Storage Entry Modifier

info

This might be incorrect and has to be reviewed.

The storage entry modifier is a varying datatype (Definition 188) 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 165) if the entry is not present.

Definition 167. Storage Entry Type

The type of the storage value is a varying datatype (Definition 188) 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 160). ${H}$ is an array of varying length containing the storage hasher (Definition 168).

Image 15. Storage Definition

Definition 168. Storage Hasher

The hashing algorithm 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 169. Pallet Constants

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 160) of the pallet constant.

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

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

Image 16. Pallet Constant

12.3. Extrinsic Metadata

The metadata about a pallets extrinsics, part of the main structure (Section 12.1.) and of the following format:

Definition 170. Signed Extension Metadata

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 160) of the signed extension, with the data to be included in the extrinsic.

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

Image 17. Metadata Extrinsic