The enablement of forkless runtime upgrades is one of the defining characteristics of the Substrate framework for blockchain development. This capability is made possible by including the definition of the state transition function, i.e. the runtime itself, as an element in the blockchain's evolving runtime state. This allows network maintainers to leverage the blockchain's capabilities for trustless, decentralized consensus to securely make enhancements to the runtime.
In the FRAME system for runtime development, the System library defines
that is used to update the definition of the runtime. The
Upgrade a Chain tutorial describes the details
of FRAME runtime upgrades and demonstrates two mechanisms for performing them. Both upgrades
demonstrated in that tutorial are strictly additive, which means that they modify the runtime by
means of extending it as opposed to updating the existing runtime state. In the event that a
runtime upgrade defines changes to existing state, it will likely be necessary to perform a "storage
Storage migrations are custom, one-time functions that allow developers to rework existing storage in order to convert it to conform to updated expectations. For instance, imagine a runtime upgrade that changes the data type used to represent user balances from an unsigned integer to a signed integer - in this case, the storage migration would read the existing value as an unsigned integer and write back an updated value that has been converted to a signed integer. Failure to perform a storage migration when needed will result in the runtime execution engine misinterpreting the storage values that represent the runtime state and lead to undefined behavior. Substrate runtime storage migrations fall into a category of storage management broadly referred to as "data migrations".
Storage Migrations with FRAME
FRAME storage migrations are implemented by way of
which specifies a single function,
on_runtime_upgrade. This function provides a hook that allows
runtime developers to specify logic that will run immediately after a runtime upgrade but before
any extrinsics or even the
on_initialize function has executed.
Preparing for a Migration
Preparing for a storage migration means understanding the changes that are defined by a runtime
upgrade. The Substrate repository uses
to designate such changes.
Writing a Migration
Each runtime migration will be different, but there are certain conventions and best practices that should be followed.
- Extract migrations into reusable functions and write tests for them.
- Include logging in migrations to assist in debugging.
- Remember that migrations are executed within the context of the upgraded runtime, which means that migration code may need to include deprecated types, as in this example.
- Use storage versions to make migrations safer by making them more declarative, as in this example.
By default, FRAME will order the execution of
on_runtime_upgrade functions according to the order
in which the pallets appear in the
construct_runtime! macro - in particular, they will run in
reverse (top-to-bottom) order. FRAME exposes a capability to inject storage migrations in a custom
order, if needed (see an
FRAME storage migrations will run in this order:
on_runtime_upgrade, as described above
on_runtime_upgradefunctions defined in the pallets included in the runtime, in the order described above
It is important to test storage migrations and a number of utilities exist to assist in this process. The Substrate Debug Kit includes a Remote Externalities tool that allows storage migration unit testing to be safely performed on live chain data. The Fork Off Substrate script makes it easy to create a chain specification that can be used to bootstrap a local test chain for testing runtime upgrades and storage migrations.