First the good news - for any chain using metadata v14, specifying custom types are not needed. The metadata itself supplies all the types required. This means that when a call is defined in the metadata, the metadata itself specifies the exact type.
For older versions of the metadata, the reality was different - for each call, the metadata only supplied the type name. This meant that there needed to be a mapping to understand that something called
Balance is actually a
u128 type and should be encoded and decoded that way.
On to your question which relates to chains that have not upgraded to v14 as of yet or chains where there is a requirement to query older blocks. For these, you need to supply a mapping of the type names to the actual type it relates to, for instance in your chain you could have
Taking this example, in Substrate chains are upgradable, so at some point you could decide to change the
Balance type to a
u128 (with the required migrations). At this point, instead of injecting the
Balance -> u64 mapping, you would inject
Balance -> u128 as a type mapping. So types can and do change through the lifecycle of the runtime.
In this case we now have an issue - assuming you used
Balance -> u64 up to runtime version 100 and 101 and above used
Balance -> u128, you will have issues querying blocks before runtime 101, i.e. those will try to decode with the new types.
To get around this and define types for specific runtime version ranges, the a types bundle entry has 2 parts -
- the version range, i.e. first runtime version and last runtime version
- the actual types that needs to be applied to this version specified by the min/max range
A very good example of this is the Kusama types bundle that tracks the chain and all types from the first runtime version up to the present (where no overrides are applied due to metadata v14 being in operation)
Pulling it all together, for the
Balance example above, your types bundle would look something like the following -
// for runtime 0 to 100
minmax: [0, 100],
// runtime 101 upgrades to the new Balance
minmax: [101, 200],
// runtime 201 swapped to metadata v14, nothing needed
minmax: [201, undefined],