Skip to content

Latest commit

 

History

History
91 lines (72 loc) · 5.35 KB

upgrades.md

File metadata and controls

91 lines (72 loc) · 5.35 KB
title
Runtime Upgrades

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 the set_code call 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 migration".

Storage Migrations

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 the OnRuntimeUpgrade trait, 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 the D1-runtime-migration label 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.

Ordering Migrations

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 example here).

FRAME storage migrations will run in this order:

  1. frame_system::on_runtime_upgrade
  2. Custom on_runtime_upgrade, as described above
  3. All on_runtime_upgrade functions defined in the pallets included in the runtime, in the order described above

Testing Migrations

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.

Learn More

  • Read more about runtime upgrades in the Executor documentation.
  • Parity Runtime Engineer Alexander Popiak maintains a Substrate Migrations repository with lots of helpful information about Substrate runtime upgrades and storage migrations.