Substrate Runtime Upgrade and Storage Migration

Substrate Runtime Upgrade and Storage Migration

Substrate Runtime Upgrades: The enablement of forkless runtime upgrades is one of the defining characteristics of the Substrate framework for blockchain development

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.


substrate blockchain

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

Blockchain Certification | Blockchain Training Course | Blockchain Council

In all the market sectors, Blockchain technology has contributed to the redesign. The improvements that were once impossible have been pushed forward. Blockchain is one of the leading innovations with the ability to influence the various sectors...

5 Blockchain Applications That Have Transformed the World of Technology

The blockchain is the decentralized database of the blocks of information, which gets recorded in the chain format and linked in a secured crypto graphical manner. This technology ensures proper safety of the data due to its secure nature, and it totally changes how people carry out transactions. It also brings about a faster and secure process of validating information needed to establish reliability.

Blockchain Certification | Blockchain Training Course | Blockchain Council

Training courses for blockchains have become very popular. The software is evolving to become part of the mainstream scheme. The growing need for a safe and secure system is one of the main reasons for this. It also contributed to one of the...

Certified Blockchain Expertâ„¢ | Blockchain Certification | Blockchain Council

The entire business has been revolutionised by Blockchain. A technology that once began as the underlying Bitcoin trading platform has now become a core technology that has changed the way companies function. The media and journalism field is no...

What Is The Difference Between Blockchain And Bitcoin?

Our Blockchain Online Training will provide you to learn about Blockchain technology aspects with realty. Our Blockchain Course also includes live sessions, live Projects