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 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 202) of type definitions ${r}_{{i}}$ (Definition 169).

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

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

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

Image 8. Metadata

Definition 169. Runtime Registry Type Entry

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 202) of strings.

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

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

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

Image 9. Metadata Type

Definition 170. Runtime Type Id

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

Definition 171. Type Variant

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

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

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

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

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

• ${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 170).

• ${T}$ is a sequence (Definition 202) of type Ids (Definition 170).

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

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

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

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

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

Image 10. Metadata Type Definition

Definition 172. Field

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

• ${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 173. 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 172) 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 174).

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

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

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

• ${e}$ is an Option type (Definition 200) containing the type Id (Definition 170) 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 13. Metadata Pallet

Definition 174. Pallet Storage Metadata

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

Definition 175. 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 176).

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

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

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

Image 14. Pallet Storage

Definition 176. Storage Entry Modifier

info

This might be incorrect and has to be reviewed.

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

Definition 177. Storage Entry Type

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

Image 15. Storage Definition

Definition 178. Storage Hasher

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

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

Image 17. Metadata Extrinsic