infrablockchain-docs
en
en
  • InfraBlockchain
    • Learn
      • Architecture
        • Architecture
        • Network Participants
        • Parachain
          • System Parachains
      • Protocol
        • System Token
        • Transaction Fee
        • Proof of Transaction
      • Substrate
        • Learn
          • Basic
            • Cryptography
            • Blockchain Basics
            • Consensus
            • Networks and Nodes
            • Blockchain Transaction
            • Transaction Life Cycle
            • Offchain Operations
            • Light Client
            • Rust for Substrate
            • Introduction to Library
            • Architecture and Rust Libraries
            • File Architecture
            • Accounts, Addresses, and Keys
            • Transaction Format
            • Blockchain Randomness
          • FRAME
            • FRAME Pallets
            • FRAME Macros
            • Custom Pallets
            • Pallet Coupling
            • Origin
            • Events and Erros
            • Runtime Storage
            • State Transitions and Storage
            • SCALE Encoding
            • Weight and Fee
            • Runtime API
            • Runtime Development
          • Account
          • Address Format
          • Glossary
          • CLI
            • Archive
            • Memory Profiler
            • Node Template
            • sidecar
            • srtool
            • Subkey
            • subxt
            • try-runtime
            • tx-wrapper
          • Runtime Development
            • Basics
              • Configure Genesis State
              • Configure Runtime Constants
              • Customize a Chain Spec
              • Import a Pallet
              • Use Helper Function
            • Consensus Model
              • PoW
              • Create a Hybrid Node
            • Offchain Worker
              • Request Offchain HTTP
              • Offchain Indexing
              • Offchain Local Storage
            • Pallet Design
              • Create a Storage Structure
              • Implement Lockable Currency
              • Incorporate Randomness
              • Loose Coupling
              • Tight Coupling
            • Parachain Development
              • Add HRMP Channel
              • Add Paranodes
              • Connect to a Local Relay Chain
              • Convert a Solo Chain
              • Prepare to Launch
              • Select Collator
              • Upgrade a Parachain
            • Storage Migration
              • Basics
              • Trigger Migration
            • Test
              • Basics
              • Test a Transfer Transaction
            • Tools
              • Create a TxWrapper
              • Use Sidecar
              • try-runtime
              • Verify WASM
            • Weigths
              • Benchmark
              • Calculate Fees
              • Use Conditional Weights
              • Use Custom Weights
        • Build
          • Decide What to Build
          • Build Process
          • Determinisitc Runtime
          • Chain Spec
          • Genesis Configuration
          • Application Development
          • RPC
          • Troubleshoot Your Code
        • Tutorials
          • Install
            • Developer Tools
            • Linux
            • macOS
            • Rust Toolchain
            • Issues
            • Windows
          • Quick Start
            • Explore the Code
            • Modify Runtime
            • Start a Node
            • Substrate Basics
          • Build a Blockchain
            • Add Trusted Nodes
            • Authorize Specific Nodes
            • Build a Local Blockchain
            • Simulate Network
            • Upgrade a Running Network
          • Build Application Logic
            • Add a Pallet
            • Add Offchasin Workers
            • Publish Custom Pallets
            • Specify Origin for a Call
            • Use Macros in a Custom Pallet
          • Integrate with Tools
            • Access EVM Accounts
            • EVM Integration
            • Explore Sidecar Endpoints
            • Integrate a Light Client Node
          • Smart Contracts
            • Strategy
            • Build a Token Contract
            • Develop a Smart Contract
            • Prepare Your First Contract
            • Troubleshoot Smart Contracts
            • Use Maps for Storing Values
      • XCM
        • XCM
        • XCM Format
    • Service Chains
      • InfraDID
      • InfraEVM
      • URAuth(Universal Resource Auth)
    • DevOps
      • Build
      • Deploy
      • Monitoring
      • Runtime Upgrade
    • Tutorials
      • Basic
        • How to Interact with System Token
        • How To Pay Transaction Fee
        • How To Vote with TaaV
        • Hot to Get Validator Reward
      • Build
        • Build InfraRelayChain
        • Build Parachain
        • Open Message Passing Channels
        • Transfer Assets with XCM
      • Test
        • Benchmark
        • Check Runtime
        • Debug
        • Simulate Parachains
        • Unit Testing
      • Service Chains
        • Play with InfraDID
          • Build
          • Add Keys
          • Add Service Endpoint
          • Create InfraDID
        • Play with InfraEVM
          • Build
          • Deposit and Withdraw Token
          • Deploy ERC20 Contract
          • Deploy ERC721 Contract
          • Deploy ERC1155 Contract
  • Newnal Data Market
Powered by GitBook
On this page
  • Before you begin
  • Tutorial objectives
  • Authorize an upgrade with Sudo
  • Add the Utility pallet to the runtime
  • Execute a runtime upgrade
  • Where to go next
  1. InfraBlockchain
  2. Learn
  3. Substrate
  4. Tutorials
  5. Build a Blockchain

Upgrade a Running Network

Illustrates ways you can update a running node.

PreviousSimulate NetworkNextBuild Application Logic

Last updated 1 year ago

Unlike many blockchains, the Substrate development framework supports forkless upgrades to the runtime that is the core of the blockchain. Most blockchain projects require a of the code base to support ongoing development of new features or enhancements to existing features. With Substrate, you can deploy enhanced runtime capabilities—including breaking changes—without a hard fork. Because the definition of the runtime is itself an element in the state of a Substrate-based chain, network participants can update this value by calling the function in a transaction. Because updates to the runtime state are validated using the blockchain's consensus mechanisms and cryptographic guarantees, network participants can use the blockchain itself to distribute updated or extended runtime logic without needing to fork the chain or release a new blockchain client.

This tutorial illustrates how to upgrade the runtime without creating a fork of the code base or stopping the progress of the chain. In this tutorial, you'll make the following changes to a Substrate runtime on a running network node:

  • Increase the spec_version of the runtime.

  • Add the Utility pallet to the runtime.

  • Increase the minimum balance for network accounts.

Before you begin

Before you begin, verify the following:

  • You have configured your environment for Substrate development by installing .

  • You have completed and have the Substrate node template installed locally.

  • You have reviewed for an introduction to adding a new pallet to the runtime.

Tutorial objectives

By completing this tutorial, you will accomplish the following objectives:

  • Use the Sudo pallet to simulate governance for a chain upgrade.

  • Upgrade the runtime for a running node to include a new pallet.

  • Submit a transaction to upload the modified runtime onto a running node.

Authorize an upgrade with Sudo

Typically, runtime upgrades are managed through governance with community members voting to approve or reject upgrade proposals. In place of governance, this tutorial uses the Sudo pallet and the Root origin to identify the runtime administrator with permission to upgrade the runtime. Only this root-level administrator can update the runtime by calling the set_code function. The Sudo pallet enables you to invoke the set_code function using the Root origin by specifying the account that has root-level administrative permissions.

By default, the chain specification file for the node template specifies that the alice development account is the owner of the Sudo administrative account. Therefore, this tutorial uses the alice account to perform runtime upgrades.

Resource accounting for runtime upgrades

The weight annotation for the set_code function also specifies that the function is in the Operational class because it provides network capabilities. Function calls that are identified as operational:

  • Can consume the entire weight limit of a block.

  • Are given maximum priority.

  • Are exempt from paying transaction fees.

Managing resource accounting

Add the Utility pallet to the runtime

Start the local node

This tutorial illustrates how to update a running node, so the first step is to start the local node with the current runtime.

To start the node with the current runtime:

  1. Open a terminal shell on your computer.

  2. Change to the root directory where you compiled the Substrate node template.

  3. Start the previously-compiled local node in development mode by running the following command:

    cargo run --release -- --dev

    Leave this node running. You can edit and re-compile to upgrade the runtime without stopping or restarting the running node.

  4. Click the left-most dropdown menu to select the network.

  5. Under Development, select Local Node, then click Switch.

    In the upper left, notice the node template version is the default version 100.

Add the Utility pallet to the runtime dependencies

To update the dependencies for the runtime to include the Utility pallet:

  1. Open a second terminal shell window or tab.

  2. Change to the root directory where you compiled the Substrate node template.

  3. Open the runtime/Cargo.toml file in a text editor.

  4. Locate the [dependencies] section.

    For example:

    [dependencies]
    codec = { package = "parity-scale-codec", version = "3.0.0", default-features = false, features = ["derive"] }
    scale-info = { version = "2.1.1", default-features = false, features = ["derive"] }
    
    pallet-aura = { version = "4.0.0-dev", default-features = false, git = "https://github.com/paritytech/polkadot-sdk.git", branch = "polkadot-v1.0.0" }
  5. Add the Utility pallet as a dependency.

    For example, add a single line with the following fields:

    pallet-utility = {
       version = "4.0.0-dev",
       default-features = false,
       git = "https://github.com/paritytech/polkadot-sdk.git",
       branch = "polkadot-v1.0.0"
    }
  6. Locate the [features] section and the list of the default features for the standard binary.

    For example:

    [features]
    default = ["std"]
    std = [
       "frame-try-runtime?/std",
       "frame-system-benchmarking?/std",
       "frame-benchmarking?/std",
       "codec/std",
       "scale-info/std",
  7. Add the Utility pallet to the list.

    "pallet-utility/std",
  8. Save your changes and close the Cargo.toml file.

Add the Utility pallet configuration

To add the Utility types and configuration trait:

  1. Open the runtime/src/lib.rs file in a text editor.

  2. Add the implementation for the Config trait for the Utility pallet.

    impl pallet_utility::Config for Runtime {
       type RuntimeEvent = RuntimeEvent;
       type RuntimeCall = RuntimeCall;
       type PalletsOrigin = OriginCaller;
       type WeightInfo = pallet_utility::weights::SubstrateWeight<Runtime>;
    }
  3. Locate the construct_runtime! macro.

    construct_runtime!(
      pub struct Runtime
      where
         Block = Block,
         NodeBlock = opaque::Block,
         UncheckedExtrinsic = UncheckedExtrinsic
      {
             System: frame_system,
             RandomnessCollectiveFlip: pallet_randomness_collective_flip,
             Timestamp: pallet_timestamp,
             Aura: pallet_aura,
  4. Add the Utility pallet inside the construct_runtime! macro.

    Utility: pallet_utility,
  5. Locate the runtime_version macro.

    #[sp_version::runtime_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: 100,
         impl_version: 1,
         apis: RUNTIME_API_VERSIONS,
         transaction_version: 1,
         state_version: 1,
    };
  6. Update the value for the EXISTENTIAL_DEPOSIT for the Balances pallet.

    pub const EXISTENTIAL_DEPOSIT: u128 = 1000 // Update this value.
  7. spec_version: 101,  // Change the spec_version from 100 to 101

    The fields for the runtime_version specify the following information:

    • spec_name specifies the name of the runtime.

    • impl_name specifies the name of the outer node client.

    • spec_version specifies the version of the runtime.

    • impl_version specifies the version of the outer node client.

    • apis specifies the list of supported APIs.

    • state_version specifies the version of the key-value trie data structure that the runtime uses.

  8. Save your changes and close the runtime/src/lib.rs file.

Recompile and connect to the local node

  1. Verify that the local node continues to run in the first terminal.

  2. In the second terminal where you updated the runtime Cargo.toml and lib.rs files, recompile the runtime by running the following command

    cargo build --release --package node-template-runtime

    The --release command-line option requires a longer compile time. However, it generates a smaller build artifact that is better suited for submitting to the blockchain network. Storage optimization is critical for any blockchain. With this command, the build artifacts are output to the target/release directory. The WebAssembly build artifacts are in the target/release/wbuild/node-template-runtime directory. For example, you should see the following WebAssembly artifacts:

    node_template_runtime.compact.compressed.wasm
    node_template_runtime.compact.wasm
    node_template_runtime.wasm

Execute a runtime upgrade

You now have a WebAssembly artifact that describes the modified runtime logic. However, the running node isn't using the upgraded runtime yet. To complete the upgrade, you need to submit a transaction that updates the node to use the upgraded runtime.

To update the network with the upgraded runtime:

  1. Click Developer and select Extrinsics to submit a transaction for the runtime to use the new build artifact.

  2. Select the administrative Alice account.

  3. Select the sudo pallet and the sudoUncheckedWeight(call, weight) function.

  4. Select system and setCode(code) as the call to make using the Alice account.

  5. Click file upload, then select or drag and drop the compact and compressed WebAssembly file—node_template_runtime.compact.compressed.wasm—that you generated for the updated runtime.

    For example, navigate to the target/release/wbuild/node-template-runtime directory and select node_template_runtime.compact.compressed.wasm as the file to upload.

  6. Leave both of the weight parameters set to the default value of 0.

  7. Click Submit Transaction.

  8. Review the authorization, then click Sign and Submit.

  9. Click Network and select Explorer to see that there has been a successful sudo.Sudid event.

    After the transaction is included in a block, the node template version number indicates that the runtime version is now 101. For example:

    If your local node is producing blocks in the terminal that match what is displayed in the browser, you have completed a successful runtime upgrade.

  10. Click Developer and select Extrinsics. Click on submit the following extrinsic and scroll to the bottom of the list. You will see utility as an option.

    • Click Developer and select Chain state.

    • Click Constants.

    • Select the balances pallet.

    • Select existentialDeposit as the constant value as the value to query.

Where to go next

Function calls that are dispatched to the Substrate runtime are always associated with a to account for resource usage. The FRAME System module sets boundaries on the block length and block weight that these transactions can use. However, the set_code function is intentionally designed to consume the maximum weight that can fit in a block. Forcing a runtime upgrade to consume an entire block prevents transactions in the same block from executing on different versions of a runtime.

In this tutorial, the function is used to invoke the set_code function for the runtime upgrade. The sudo_unchecked_weight function is the same as the sudo function except that it supports an additional parameter to specify the weight to use for the call. This parameter enables you to work around resource accounting safeguards to specify a weight of zero for the call that dispatches the set_code function. This setting allows for a block to take an indefinite time to compute to ensure that the runtime upgrade does not fail, no matter how complex the operation is. It can take all the time it needs to succeed or fail.

By default, the node template doesn't include the in its runtime. To illustrate a runtime upgrade, you can add the Utility pallet to a running node.

Open the in a browser and connect to the local node.

Select network

This change increases the minimum balance an account is required to have on deposit to be viewed as a valid active account. This change doesn't remove any accounts with balances between 500 and 1000. Removing accounts would require a storage migration. For information about upgrading data storage, see

Increment the to specify the new runtime version.

authoring_version specifies the version for .

transaction_version specifies the version of the interface.

To upgrade the runtime, you must increase the spec_version. For more information, see the module and the can_set_code method.

Open the in a browser and connect to the local node.

Verify the constant value by querying the chain state in the .

Verify the constant value change

hard fork
set_code
Rust and the Rust toolchain
Build a local blockchain
Add a pallet to the runtime
weight
sudo_unchecked_weight
Utility pallet
Polkadot/Substrate Portal
storage migration
spec_version
block authors
dispatchable function
FRAME System
Polkadot/Substrate Portal
Polkadot/Substrate Portal
Runtime version 101
Runtime version 102
Storage migrations
Select network
Runtime upgrade settings
Successful sudo event
Updated runtime version is 101