Initiate a Forkless Runtime Upgrade

Introduction

One of the defining features of the Substrate blockchain development framework is its support for forkless runtime upgrades. Forkless upgrades are a means of enhancing a blockchain runtime in a way that is supported and protected by the capabilities of the blockchain itself. A blockchain's runtime defines the state the blockchain can hold and also defines the logic for effecting changes to that state.

Substrate makes it possible to deploy enhanced runtime capabilities (including breaking changes(!)) without a hard fork. Because the definition of the runtime is itself an element in a Substrate chain's state, network participants may update this value by way of an extrinsic, specifically the set_code function. Since updates to runtime state are bound by the blockchain's consensus mechanisms and cryptographic guarantees, network participants can use the blockchain itself to trustlessly distribute updated or extended runtime logic without needing to fork the chain or even release a new blockchain client.

This tutorial will use the Substrate Developer Hub node template to explore two mechanisms for forkless upgrades of FRAME-based runtimes. First, the sudo_unchecked_weight function from the Sudo pallet will be used to perform an upgrade that adds the Scheduler pallet. Then, the schedule function from the Scheduler pallet will be used to perform an upgrade that increases the existential (minimum) balance for network accounts.

If you have problems with this tutorial, the Substrate community is full of helpful resources! We actively monitor the Substrate Stack Exchange.

What You Will Be Doing

Before we even get started, let's layout what we are going to do over the course of this tutorial. We will:

Learning outcomes

• Understand some basic governance features in Substrate chains
• Gain experience with how a Substrate chain can upgrade it's runtime
• Learn how to use the scheduler pallet in your runtime

Sudo Upgrade

This part of the tutorial will step you through launching a Substrate chain and initiating a simple runtime upgrade using the Sudo pallet.

Start the Template Node

Since forkless runtime upgrades do not require network participants to restart their blockchain clients, the first step of this tutorial is to start the template node as-is. Build and start the unmodified node template.

cargo run --release -- --dev

By default, the well-known Alice account is configured as the holder of the Sudo pallet's key in the development_config function of the template node's chain specification file - this is the configuration that is used when the node is launched with the --dev flag. This means that Alice's account will be the one used to perform runtime upgrades throughout this tutorial.

Runtime Upgrade Resource Accounting

Dispatchable calls in Substrate are always associated with a weight, which is used for resource accounting. FRAME's System module bounds extrinsics to a block BlockLength and BlockWeights limit. The set_code function in the System module is intentionally designed to consume the maximum weight that may fit in a block.

The set_code function's weight annotation also specifies that the extrinsic call is in the Operational class of dispatchable function, which identifies it as relating to network operations and impacts the accounting of its resources, such as by exempting it from the TransactionByteFee.

Use sudo to dispatch

As the name of the Sudo pallet implies, it provides capabilities related to the management of a single sudo ("superuser do") administrator. In FRAME, the Root Origin is used to identify the runtime administrator; some of FRAME's features, including the ability to update the runtime by way of the set_code function, are only accessible to this administrator. The Sudo pallet maintains a single storage item: the ID of the account that has access to the pallet's dispatchable functions. The Sudo pallet's sudo function allows the holder of this account to invoke a dispatchable as the Root origin.

The following pseudo-code demonstrates how this is achieved, refer to the Sudo pallet's source code to learn more.

fn sudo(origin, call) -> Result {
    // Ensure caller is the account identified by the administrator key
    let sender = ensure_signed(origin)?;
    ensure!(sender == Self::key(), Error::RequireSudo);

    // Dispatch the specified call as the Root origin
    let res = call.dispatch(Origin::Root);
    Ok()
}

sudo to Override Resource Accounting

In order to work around resource accounting within FRAME's safeguards, the Sudo pallet provides the sudo_unchecked_weight function, which provides the same capability as the sudo function, but accepts an additional parameter that is used to specify the (possibly zero) weight to use for the call. The sudo_unchecked_weight function is what will be used to invoke the runtime upgrade in this section of this tutorial; in the next section, the Scheduler pallet will be used to manage the resources consumed by the set_code function.

Here we allow for a block that may take an indefinite time to compute intentionally. This ensures that our runtime upgrade does not fail, no matter how complex the operation is. It could take all the time it needs to succeed or fail.

Prepare an Upgraded Runtime

Add the Scheduler Pallet

Because the template node doesn't come with the Scheduler pallet included in its runtime, the first runtime upgrade performed in this tutorial will add that pallet. First, add the Scheduler pallet as a dependency in the template node's runtime Cargo file.

runtime/Cargo.toml

pallet-scheduler = { default-features = false, git = "https://github.com/paritytech/substrate.git", branch = "polkadot-v0.9.17" }

#--snip--

[features]
default = ['std']
std = [
    #--snip--
    'pallet-scheduler/std',
    #--snip--
]

Next, add the pallet to the runtime:

runtime/src/lib.rs

// Define the types required by the Scheduler pallet.
parameter_types! {
    pub MaximumSchedulerWeight: Weight = 10_000_000;
    pub const MaxScheduledPerBlock: u32 = 50;
}

// Configure the runtime's implementation of the Scheduler pallet.
impl pallet_scheduler::Config for Runtime {
    type Event = Event;
    type Origin = Origin;
    type PalletsOrigin = OriginCaller;
    type Call = Call;
    type MaximumWeight = MaximumSchedulerWeight;
    type ScheduleOrigin = frame_system::EnsureRoot<AccountId>;
    type MaxScheduledPerBlock = MaxScheduledPerBlock;
    type WeightInfo = ();
    type OriginPrivilegeCmp = EqualPrivilegeOnly;
}

// Add the Scheduler pallet inside the construct_runtime! macro.
construct_runtime!(
    pub enum Runtime where
        Block = Block,
        NodeBlock = opaque::Block,
        UncheckedExtrinsic = UncheckedExtrinsic
    {
        /*** snip ***/
        Scheduler: pallet_scheduler,
    }
);

Add the following trait dependency at the top of the file:

pub use frame_support::traits::EqualPrivilegeOnly;

The final step to preparing an upgraded FRAME runtime is to increment its spec_version, which is a member of the RuntimeVersion struct:

runtime/src/lib.rs

pub const VERSION: RuntimeVersion = RuntimeVersion {
    spec_name: create_runtime_str!("node-template"),
    impl_name: create_runtime_str!("node-template"),
    authoring_version: 1,
    spec_version: 101,  // *Increment* this value, the template uses 100 as a base
    impl_version: 1,
    apis: RUNTIME_API_VERSIONS,
    transaction_version: 1,
};

Take a moment to review the components of the RuntimeVersion struct:

• spec_name: The name of the runtime/chain, e.g. Ethereum.
• impl_name: The name of the client, e.g. OpenEthereum.
• authoring_version: The authorship version for block authors.
• spec_version: The version of the runtime/chain.
• impl_version: The version of the client.
• apis: The list of supported APIs.
• transaction_version: The version of the dispatchable function interface.

In order to upgrade the runtime it is required to increase the spec_version; refer to the implementation of the FRAME System module and in particular the can_set_code function to to see how this requirement and others are enforced by runtime logic.

Build the Upgraded Runtime

# Here we *only* build the runtime, the node has not been changed.
cargo build --release -p node-template-runtime

Here the --release flag will result in a longer compile time, but also generate a smaller build artifact that is better suited for submitting to the blockchain network: storage minimization and optimizations are critical for any blockchain.

As we are only building the runtime, Cargo looks in runtime cargo.toml file for requirements and only executes these. Notice the runtime/build.rs file that cargo looks for builds the Wasm of your runtime that is specified in runtime/src/lib.rs.

When the --release flag is specified, build artifacts are output to the target/release directory; when the flag is omitted they will be sent to target/debug. Refer to the official documentation to learn more about building Rust code with Cargo.

Upgrade the Runtime

Use this link to open the Polkadot JS Apps UI and automatically configure the UI to connect to the local node.

Use Alice's account to invoke the sudoUncheckedWeight function and use the setCode function from the system pallet as its parameter. In order to supply the build artifact that was generated by the previous build step, toggle the "file upload" switch on the right-hand side of the "code" input field for the parameter to the setCode function. Click the "code" input field, and select the Wasm binary that defines the upgraded runtime: target/release/wbuild/node-template-runtime/node_template_runtime.compact.wasm. Leave the value for the _weight parameter at the default of 0. Click "Submit Transaction" and then "Sign and Submit".

After the transaction has been included in a block, the version number in the upper-left-hand corner of Polkadot JS Apps UI should reflect that the runtime version is now 101.

If you still see your node producing blocks in the terminal it's running and reported on the UI, you have performed a successful forkless runtime upgrade! Congrats!!!

Next up, we will:

1. Upgrade your runtime version
2. Use the Scheduler pallet to schedule your runtime upgrade on your running chain

Schedule an Upgrade

Now that the node template has been upgraded to include the Scheduler pallet, the schedule function can be used to perform the next runtime upgrade. In the previous part, the sudo_unchecked_weight function was used to override the weight associated with the set_code function; in this section, the runtime upgrade will be scheduled so that it can be processed as the only extrinsic in a block.

Prepare an Upgraded Runtime

This upgrade is more straightforward than the previous one and only requires updating a single value in runtime/src/lib.rs aside from the runtime's spec_version.

pub const VERSION: RuntimeVersion = RuntimeVersion {
    spec_name: create_runtime_str!("node-template"),
    impl_name: create_runtime_str!("node-template"),
    authoring_version: 1,
    spec_version: 102,  // *Increment* this value.
    impl_version: 1,
    apis: RUNTIME_API_VERSIONS,
    transaction_version: 1,
};

/*** snip ***/

parameter_types! {
    pub const ExistentialDeposit: u128 = 1000;  // Update this value.
    pub const MaxLocks: u32 = 50;
}

/*** snip ***/

This change increases the value of the Balances pallet's ExistentialDeposit - the minimum balance needed to keep an account alive from the point-of-view of the Balances pallet.

Build the Upgraded Runtime

cargo build --release -p node-template-runtime

This will override any previous build artifacts! So if you want to have a copy on hand of your last runtime Wasm build files, be sure to copy them somewhere else."

Upgrade the Runtime

In the previous section, the Scheduler pallet was configured with the Root origin as its ScheduleOrigin, which means that the sudo function (not sudo_unchecked_weight) can be used to invoke the schedule function. Use this link to open the Polkadot JS Apps UI's Sudo tab: https://polkadot.js.org/apps/#/sudo?rpc=ws://127.0.0.1:9944.

Wait until all the other fields have been filled in before providing the when parameter. Leave the maybe_periodic parameter empty and the priority parameter at its default value of 0. Select the System pallet's set_code function as the call parameter and provide the Wasm binary as before. Leave the "with weight override" option deactivated. Once all the other fields have been filled in, use a block number about 10 blocks (1 minute) in the future to fill in the when parameter and quickly submit the transaction.

You can use the template node's command line output or the Polkadot JS Apps UI block explorer to watch as this scheduled call takes place.

After the target block has been included in the chain, the version number in the upper-left-hand corner of Polkadot JS Apps UI should reflect that the runtime version is now 102.

You can then observe the specific changes that were made in the upgrade by using the Polkadot JS Apps UI Chain State app to query the existentialDeposit constant value from the Balances pallet.

Next Steps

• Learn about storage migrations and attempt one alongside a runtime upgrade.
• Explore the how-to guides section on storage migrations.