Skip to main content

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:

(M,vm,R,P,te,ve,E,tr){\left({M},{v}_{{m}},{R},{P},{t}_{{e}},{v}_{{e}},{E},{t}_{{r}}\right)}
R=(r0,,rn){R}={\left({r}_{{0}},\ldots,{r}_{{n}}\right)}
P=(p0,,pn){P}={\left({p}_{{0}},\ldots,{p}_{{n}}\right)}
E=(e0,,en){E}={\left({e}_{{0}},\ldots,{e}_{{n}}\right)}

where

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

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

  • R{R} is a sequence (Definition 192) of type definitions ri{r}_{{i}} (Definition 159).

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

  • te{t}_{{e}} is the type Id (Definition 160) of the extrinsics.

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

  • E{E} is a sequence (Definition 192) of extrinsics metadata ei{e}_{{i}} (Definition 170).

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

Image 8. Metadata
cluster__metadataMetadatametadata__seqpossizetypeid04magic41u1metadata_version5...Scale::CompactIntnum_types......MetadataTypetypesrepeat num_types.value times......Scale::CompactIntnum_pallets......MetadataPalletpalletsrepeat num_pallets.value times......Scale::CompactIntextrinsic_type...1u1extrinsic_version......Scale::CompactIntnum_extrinsics......MetadataExtrinsicextrinsicsrepeat num_extrinsics.value times......Scale::CompactIntruntime_typemetadata_type__seqMetadataTypemetadata__seq:types_type->metadata_type__seqmetadata_pallet__seqMetadataPalletmetadata__seq:pallets_type->metadata_pallet__seqmetadata_extrinsic__seqMetadataExtrinsicmetadata__seq:extrinsics_type->metadata_extrinsic__seq
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:

ri=(idt,p,T,D,c){r}_{{i}}={\left(\text{id}_{{t}},{p},{T},{D},{c}\right)}
T=(t0,,tn){T}={\left({t}_{{0}},\ldots,{t}_{{n}}\right)}
ti=(n,y){t}_{{i}}={\left({n},{y}\right)}

where

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

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

  • T{T} is a sequence (Definition 192) of generic parameters (empty for non-generic types).

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

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

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

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

Image 9. Metadata Type
cluster__metadata_typeMetadataTypecluster__paramMetadataType::Parammetadata_type__seqpossizetypeid0...Scale::CompactIntid......Scale::StringListpath......Scale::CompactIntnum_params......Paramparamsrepeat num_params.value times......MetadataTypeDefinitiondefinition......Scale::StringListdocsparam__seqpossizetypeid0...Scale::Stringname......Scale::MaybeCompactInttypemetadata_type__seq:params_type->param__seqmetadata_type_definition__seqMetadataTypeDefinitionmetadata_type__seq:definition_type->metadata_type_definition__seq
Definition 160. Runtime Type Id

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

Definition 161. Type Variant

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

D={0Ccomposite type (e.g. structure or tuple)1Vvariant type2svsequence type varying length3Ssequence with fixed length4Ttuple type5Pprimitive type6ecompact encoded type7Bsequence of bits{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{C} is a sequence of the following format:

    C=(f0,,fn){C}={\left({{f}_{{0}},}\ldots,{f}_{{n}}\right)}

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

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

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

  • S{S} is of the following format:

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

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

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

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

  • P{P} is a varying datatype (Definition 188) of the following structure:

    P={0boolean1char2string3unsigned 8-bit integer4unsigned 16-bit integer5unsigned 32-bit integer6unsigned 64-bit integer7unsigned 128-bit integer8unsigned 256-bit integer9signed 8-bit integer10signed 16-bit integer11signed 32-bit integer12signed 64-bit integer13signed 128-bit integer14signed 256-bit integer{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{e} is a type Id (Definition 160).

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

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

Image 10. Metadata Type Definition
cluster__metadata_type_definitionMetadataTypeDefinitioncluster__arrayMetadataTypeDefinition::Arraycluster__sequenceMetadataTypeDefinition::Sequencecluster__primitiveMetadataTypeDefinition::Primitivecluster__tupleMetadataTypeDefinition::Tuplecluster__bitsMetadataTypeDefinition::Bitscluster__compactMetadataTypeDefinition::Compactmetadata_type_definition__seqpossizetypeid01u1→Typetype1...switch (type)detailsmetadata_type_definition__seq:type_type->metadata_type_definition__seq:details_typemetadata_type_definition__seq_details_switchcasetype:type_compositeMetadataTypeFields:type_bitsBits:type_arrayArray:type_sequenceSequence:type_primitivePrimitive:type_compactCompact:type_variantMetadataTypeVariants:type_tupleTuplemetadata_type_definition__seq:details_type->metadata_type_definition__seq_details_switcharray__seqpossizetypeid04u4lelength4...Scale::CompactInttypemetadata_type_definition__seq_details_switch:case2->array__seqsequence__seqpossizetypeid0...Scale::CompactInttypemetadata_type_definition__seq_details_switch:case3->sequence__seqprimitive__seqpossizetypeid01u1→Pididmetadata_type_definition__seq_details_switch:case4->primitive__seqtuple__seqpossizetypeid0...Scale::CompactIntnum_types......Scale::CompactInttypesrepeat num_types.value timesmetadata_type_definition__seq_details_switch:case7->tuple__seqbits__seqpossizetypeid0...Scale::CompactInttype......Scale::CompactIntordermetadata_type_definition__seq_details_switch:case1->bits__seqcompact__seqpossizetypeid0...Scale::CompactInttypemetadata_type_definition__seq_details_switch:case5->compact__seqmetadata_type_fields__seqMetadataTypeFieldsmetadata_type_definition__seq_details_switch:case0->metadata_type_fields__seqmetadata_type_variants__seqMetadataTypeVariantsmetadata_type_definition__seq_details_switch:case6->metadata_type_variants__seq
Definition 162. Field

A field of a datastructure of the following format:

fi=(n,y,yn,C){{f}_{{i}}=}{\left({n},{y},{y}_{{n}},{C}\right)}

where

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

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

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

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

Image 11. Metadata Type Fields
cluster__metadata_type_fieldsMetadataTypeFieldscluster__fieldMetadataTypeFields::Fieldmetadata_type_fields__seqpossizetypeid0...Scale::CompactIntnum_fields......Fieldfieldsrepeat num_fields.value timesfield__seqpossizetypeid0...Scale::MaybeStringname......Scale::CompactInttype......Scale::MaybeStringtypename......Scale::StringListdocsmetadata_type_fields__seq:fields_type->field__seq
Definition 163. Variant

A struct variant of the following format:

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

where

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

  • F{F} is a possible empty array of varying length containing field (Definition 162) elements.

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

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

Image 12. Metadata Type Variants
cluster__metadata_type_variantsMetadataTypeVariantscluster__variantMetadataTypeVariants::Variantmetadata_type_variants__seqpossizetypeid0...Scale::CompactIntnum_variants......Variantvariantsrepeat num_variants.value timesvariant__seqpossizetypeid0...Scale::Stringname......MetadataTypeFieldscomposite...1u1index......Scale::StringListdocsmetadata_type_variants__seq:variants_type->variant__seqmetadata_type_fields__seqMetadataTypeFieldsvariant__seq:composite_type->metadata_type_fields__seq

12.2. Pallet Metadata

All the metadata about a pallet, part of the main structure (Section 12.1.) and of the following format:

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

where

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

  • S{S} is an Option type containing the pallet storage metadata (Definition 164).

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

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

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

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

  • i{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
cluster__metadata_palletMetadataPalletcluster__callsMetadataPallet::Callscluster__eventsMetadataPallet::Eventscluster__errorsMetadataPallet::Errorsmetadata_pallet__seqpossizetypeid0...Scale::Stringname...1u1has_storage......PalletStoragestorage...1u1has_calls......Callscalls...1u1has_events......Eventsevents......Scale::CompactIntnum_constants......PalletConstantconstantsrepeat num_constants.value times...1u1has_errors......Errorserrors...1u1indexcalls__seqpossizetypeid0...Scale::CompactInttypemetadata_pallet__seq:calls_type->calls__seqevents__seqpossizetypeid0...Scale::CompactInttypemetadata_pallet__seq:events_type->events__seqerrors__seqpossizetypeid0...Scale::CompactInttypemetadata_pallet__seq:errors_type->errors__seqpallet_storage__seqPalletStoragemetadata_pallet__seq:storage_type->pallet_storage__seqpallet_constant__seqPalletConstantmetadata_pallet__seq:constants_type->pallet_constant__seq
Definition 164. Pallet Storage Metadata

The metadata about a pallets storage.

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

where

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

  • E{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.

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

where

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

  • m{m} is an enum type determining the storage entry modifier (Definition 166).

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

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

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

Image 14. Pallet Storage
cluster__pallet_storagePalletStoragecluster__itemPalletStorage::Itempallet_storage__seqpossizetypeid0...Scale::Stringprefix......Scale::CompactIntnum_items......Itemitemsrepeat num_items.value timesitem__seqpossizetypeid0...Scale::Stringname...1u1→StorageModifiermodifier......StorageDefinitiondefinition......Scale::Bytesfallback......Scale::StringListdocspallet_storage__seq:items_type->item__seqstorage_definition__seqStorageDefinitionitem__seq:definition_type->storage_definition__seq
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={0optional1default{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{y} with default value d{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={0tplain type1(H,k,v)storage map{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{t}, k{k} (key) and v{v} (value) are all of type Ids (Definition 160). H{H} is an array of varying length containing the storage hasher (Definition 168).

Image 15. Storage Definition
cluster__storage_definitionStorageDefinitioncluster__plainStorageDefinition::Plaincluster__mapStorageDefinition::Mapstorage_definition__seqpossizetypeid01u1→StorageTypetype1...switch (type)detailsstorage_definition__seq:type_type->storage_definition__seq:details_typestorage_definition__seq_details_switchcasetype:storage_type_plainPlain:storage_type_mapMapstorage_definition__seq:details_type->storage_definition__seq_details_switchplain__seqpossizetypeid0...Scale::CompactInttypestorage_definition__seq_details_switch:case0->plain__seqmap__seqpossizetypeid0...Scale::CompactIntnum_hasher...1u1→HasherTypehasherrepeat num_hasher.value times......Scale::CompactIntkey......Scale::CompactIntvaluestorage_definition__seq_details_switch:case1->map__seq
Definition 168. Storage Hasher

The hashing algorithm used by storage maps.

{0128-bit Blake2 hash1256-bit Blake2 hash2Multiple 128-bit Blake2 hashes concatenated3128-bit XX hash4256-bit XX hash5Multiple 64-bit XX hashes concatenated6Identity hashing{\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.

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

where

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

  • y{y} is the type Id (Definition 160) of the pallet constant.

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

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

Image 16. Pallet Constant
cluster__pallet_constantPalletConstantpallet_constant__seqpossizetypeid0...Scale::Stringname......Scale::CompactInttype......Scale::Bytesvalue......Scale::StringListdocs

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.

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

where

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

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

  • a{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
cluster__metadata_extrinsicMetadataExtrinsicmetadata_extrinsic__seqpossizetypeid0...Scale::Stringname......Scale::CompactInttype......Scale::CompactIntadditional