Substrate Blockchains and Runtime Modules: An Introduction

Get started developing with Substrate and runtime modules

Ross Bulat
Aug 27, 2019 · 16 min read
Image for post
Image for post

Parity’s Substrate blockchain framework has been in heavy development in recent months, coinciding with the development of the Polkadot blockchain that is being built on top of Substrate itself.

This piece aims to cover how to start building custom Substrate chains that can support your own Runtime modules:

  • We’ll run through a Substrate chain installation and setup
  • Explore Substrate chain configuration and how to browse chain state using Polkadot JS
  • Dedicate time to introduce the structure of a Runtime Module, a means of adding functionality to your chain

Developing on Substrate

Substrate and the coinciding runtime modules are developed with Rust, a statically typed language that offers speed and reliability with its memory safety features.

This is a subject often brushed aside in blockchain development, but is vitally important for adoption: how to tackle Rust. We won’t be analysing Rust code in this piece, but this will be a pre-requisitive concern for developers interested in Substrate.

How to tackle Rust for newcomers

Rust’s learning curve is on the steep side for a programming language. That can be attributed to some of the syntax conventions it adopts, with heavy reliance on features like generics, traits, lifecycles, and macros, among other considerations such as scope and mutability.

Other Substrate learning resources such as the Substrate Kitties collectibles workshop claim that Rust is quite easy to get to grips with, but this is not the case unless you have had moderate experience working with low-level languages, such as C++, having been exposed to more granular APIs that deal with system-level management.

Concretely, if you are new to Rust, be patient. Take time to understand the concepts and features the language offers, and enjoy yourself along the way. Substrate development will become a more enjoyable endeavour. The Rust book is a well-written walkthrough for both newcomers to the language and experienced users looking for a Rust refresher.

Q: Will the Rust book alone get you up to speed with the language features and concepts that Substrate adopts?

A: Yes it will, but we recommend practicing with your own demos as you read through the book to solidify your understanding. This will make coding in Substrate a lot more comfortable.

With this in mind, let’s explore some practical Substrate setup and usage, before moving into runtime modules.

Installing Substrate

Please note that this installation section is no longer up to date. Instead, installing Substrate should be done with Substrate Up.

Installing Substrate simply requires calling one bash script hosted by Parity at Substrate comes in two packages:

1. Fast installation

A faster Substrate installation that installs a pre-build Substrate development chain, along with Substrate Scripts, a command-line utility for configuring custom Substrate chains and runtime modules.

Run fast installation via the --fast flag used with the Substrate install script essentially skips the installation of some utilities that are not compulsory to run a Substrate:

curl -sSf | bash -s -- --fast

This will fetch all the dependencies Substrate requires, including Rust, OpenSSL, LLVM and more, and install them if they haven’t been already.

2. Full installation

A full Substrate installation installs all the above, as well as two other utilities:

  • Subkey: a utility that generates or restores Substrate keys (useful for managing accounts via the command line)
  • Substrate node: A pre-configured Substrate node that can connect to the Substrate test-net.

Run the following to install these tools along with Substrate Scripts and the development node:

// full Substrate installation
curl -sSf | bash

Once the install script is finished, update your cargo environment in order to call the newly installed programs:

// update env (alternatively, reboot your system)
source ~/.cargo/env

A compiled Substrate node will now be accessible via the substrate command. To verify Substrate and Subkey installed correctly, check the versioning of both programs, substrate and subkey respectively:

substrate --version
subkey --version

Note: The Polkadot JS app (which we cover further down) has implemented subkey in its account management UI — with the option to manage accounts in the browser, some users will not need subkey. This may contribute to why it is an optional utility.

All being Rust compiled binaries, the Substrate and utility tools will now be residing in the ~/.cargo/bin directory by default. Check yourself what has been installed:

// list installed cargo binariescd ~/.cargo/bin

You’ll notice that along with the substrate and subkey, we also have the substrate-node-new and substrate-module-new binaries available to us. We’ll be using these further down to generate a new custom node and module.

Note: The other newly compiled binary is substrate-ui-new, a tool for cloning the front-end React app for managing Substrate chains. This flagged an error when I attempted to run the app, therefore we will assume the Polkadot JS / Substrate UI app — another Typescript & React based app designed to configure and manage Substrate and Polkadot blockchains — is the preferred method of managing a chain.

Full Substrate installation instructions, covering instructions for a range of operating systems, can be found here.

Find more information on using subkey here.

Updating Substrate Scripts

Updating Substrate scripts (pulled from the official docs) require cloning the latest version and replacing the cargo binaries with the following command:

f=`mktemp -d` 
git clone $f
cp -a $f/substrate-* ~/.cargo/bin
cp -a $f/polkadot-* ~/.cargo/bin

We have our needed Substrate tools installed and ready to use. We can indeed run Substrate now, via the pre-built development node. This node will begin producing blocks but will be of little use for development purposes.

Note: Substrate developers use this pre-built node, accessible via the substrate path, for development purposes only, testing their latest builds and playing with configurations. For your own Substrate projects that will have their own Runtime modules and chain configurations, we’ll be compiling a custom node. This entails cloning the Substrate source code and building our custom node. We’ll cover this further down.

In any case, we can verify the Substrate dev chain is working with this command:

substrate --dev

Your node will be running in the Terminal, and blocks will start being produced. In order to see more information about your chain, such as its state for each supporting module, we will turn to the Polkadot JS app.

For a breakdown of substrate command-line options, check out the --help output:

substrate --help

Familiarising ourselves with help output is a tried and tested way of getting to know the capabilities of command-line programs. This build contains some useful flags for testing, such as pre-configured accounts for --alice, --bob, etc. The --light flag runs your node as a light client, with light client support built right into the framework.

These and other flags make it simple to toggle chain configs, mostly used for development purposes.

Note: You can even define your own command-line options with your custom Substrate node. Just remember to update the --help output! Rust has extensive tooling for the command-line and is my personal favourite language for command-line utility development.

Before endeavouring into custom builds, let’s review how we can inspect a Substrate chain. The primary means of doing so today is via the Polkadot JS app, developed with Typescript and React.

Using the Polkadot JS App

The Polkadot JS app acts as a basic chain explorer and provides APIs and interfaces to manage Substrate modules. As the name suggests, it also supports Polkadot chains. We have two options for using Polkadot JS:

Let’s clone the project and run it locally. Once installed, we can point the node endpoint to our Substrate chain, which will be another running process on your machine.

// clone and start polkadot.js appgit clone
mv apps polkadot.js
cd polkadot.js && yarn start
// start substrate dev chain in another terminal windowsubstrate --dev

Once running, go to localhost:3000 in your browser. To connect the app to your local chain, navigate to Settings in the side menu of the app and switch to your Local Node endpoint, similar to the following setup:

Image for post
Image for post
Polkadot JS: Substrate Local Node configuration

Upon hitting Save & Reload, you will notice many other side menu links now present. These links will vary depending on which features your chain supports.

Let’s take a look at something that almost all chains will support — accounts. Head over to the Accounts section of the app— you will see a list of accounts under the “My Accounts” tab. These are pre-configured accounts, with pre-configured balances. We can also send funds between accounts, delete accounts, and back up account keys. This highlights what the Polkadot JS app is for — interacting with your Substrate chain at a UI level.

Before moving on, we’ll mention a few more things the Polkadot UI can do, just to highlight some of its functionalities:

  • You can upload wasm-compiled Ink based smart contracts to use with the Contracts runtime module.

Note: I have written a dedicated article series introducing the Ink smart contract language for Substrate here.

  • As a proof-of-stake consensus blockchain, the Staking section allows you to stake funds to become a validator of transactions, with support for storing those staked funds via a “stash account”, an account that can stay offline, or store those funds in cold storage. Nominated validators, staking rewards can also be viewed — and of course, you can withdraw funds from a staked position
  • The Democracy section is designed to handle executive votes and governance of the chain
  • The entire Substrate JSON RPC (the means of contacting Substrate externally via a range of endpoints) can be tested in the Toolbox section, whereas administrative changes to the chain can be carried out in the Sudo section

You may be wondering where those pre-configured accounts from the Substrate dev chain came from, and rightfully so. These accounts, and much more, including a “blob” of compiled code for the runtime logic itself, is stored in a “Chain Specification” file, also known as the chain spec.

Chain Configuration With a Chain Spec JSON File

A chain specification is one big JSON object, generated via the substrate build-spec command. This command works by referring to your node’s imported runtime modules and looking out for exposed configurations that need to be defined. These will either be null values or have a default value provided.

In essence, runtime modules can rely on “genesis configuration”, in other words, configuration we provide when the blockchain first initialises and constructs its state. This state is initiated via the genesis block — the first produced block of the chain. The chain spec JSON file’s job is to define this initial state.

Once generated, we can open this chain specification and amend any values we deem necessary, before running the node.

Note: What if our chain writes state we no longer want? Maybe we have updated a module, or any chain config, and want to reflect the changes from the genesis block? We can purge the chain — remove the block history — effectively resetting the node.

Your node provides the purge-chain command for doing this, and is commonly used in development workflows:

# optional --dev flag to specify development chain
substrate purge-chain --dev

On top of this, there are three default chain “specs” — pre-filled configurations — that the framework provides, that define some base values based on whether we are running the node for testing or production purposes.

In fact, there are three specs provided by default: dev, local and staging:

  • The dev spec is the furthest specification away from a real-world use case, primarily configured to help you play with your chain. You’re provided with a range of accounts and configuration is provided for all of the pre-packaged runtime modules
  • The local spec is similar to the dev spec, and is used in the Private Network Substrate tutorial, hosted by Parity. It gives multiple accounts “authority”, assuming you will want to test multi-user scenarios locally
  • staging is a more conservative spec, defining a limited number of accounts, and leaving out module-specific configuration. This is the spec you’ll opt for when building your production chain.

What we can do is build a new chainspec based on one of these provided options with the substrate build-spec command, outputting the result to a separate file. If I want to copy the dev chain spec for my own chain, I can run the following command, outputting the spec in a new my-chianspec.json file in my home directory:

substrate build-spec --chain=dev > ~/my-chainspec.json

Open this file in your editor to see the configuration options available.

Note: You may wish to collapse the genesis.system.runtime block, containing a huge unreadable blob of your runtime.

The id field can be modified to your own name, along with the name field, a more human-readable name of the chain spec. Some notable common options include:

  • Telemetry endpoints: Provide endpoints for a Telemetry service via telemetryEndpoints. This will allow you to populate a UI with connected nodes, not dissimilar to the Polkadot Telemetry.
  • A list of balances to give initial accounts, in the event your node deals with a native token.
  • staking configuration in the event your chain supports the feature. Configure options such as the initial validator accounts, validator and stashing variables.

Ultimately, there will be various other variables depending on which modules your runtime includes. An advised approach to help you get familiar with the chain spec file is to refer to the main Substrate node chain spec.

Once you’re happy with your chain spec, we then process it into a raw encoded state, with the --raw flag:

substrate build-spec --chain ~/chainspec.json --raw > ~/mychain.json

And finally, to run our chain we provide substrate with this chain spec. From here we will assume that you are running a custom compiled Substrate node, where we replace <node_path> with that node’s runtime.

<node_path> --chain ~/mychain.json --validator

Note: The validator flag is required for your chain to start producing blocks.

Next let’s take a look at initialising and compiling custom Substrate nodes.

Initialising your own Substrate Node

So far we have been using a compiled Substrate node obtained via the installation script. This is great for testing a development chain, but it limits us when introducing our own runtime modules and custom configurations. For this, we need to download the Substrate source code.

We have two means of getting started with our own custom Substrate chain:

  • Downloading a readily configured node template (such as the test-net node template downloaded in the full installation from the first section, or the Substrate Kitties node that particular workshop provides).
  • Using Substrate Scripts, download the official node template, a bare-bones Substrate node script with a runtime template ready for hacking. We can do this using Substrate Scripts, which we also installed earlier.

Just about all Substrate projects will start from the official node template unless you are following a workshop or extending an existing project.

Generate a new node template with the following:

// substrate-node-new <node_name> <author>
substrate-node-new my-node "Ross Bulat"

This may take some time depending on your system — the latest Substrate source code will be fetched and compiled.

Once completed, the node’s runtime will now be editable within the runtime/src folder via the file. Also included is a template for a runtime module, with We will take a look at a runtime module next.

Building your custom node

Inside your node directory, compile your node into wasm with the included script, before compiling a binary with cargo:

# build wasm
# build binary
cargo build --release

Your node will now be compiled in your node’s ./target/release/ directory.

Where we have been using substrate to call node-specific commands, we can now refer to our newly built binary, to run commands on our custom-built chain. To purge the chain and re-run it, we’d use the binary like so:

# clear chain state
./target/release/<node_name> purge-chain --dev
# run in dev mode
./target/release/<node_name> --dev

The last subject we’ll introduce here is runtime modules. Let’s explore what they are and how to include them in a Substrate node.

Introducing Substrate Runtime Modules: Plug-in Blockchain Features

What gives Substrate practicality is a generic and modular structure that allows developers to plug functionality into their runtime, thus creating a custom blockchain that fits their requirements.

Note: Another term for the Substrate runtime is the State Transition Function, or STF. This is essentially the function that executes blocks, resulting in state changes to your blockchain.

These packages of functionality are called modules, or more specifically, Runtime Modules. These range of Runtime Modules that come pre-packaged with Substrate collectively form a catalogue of modules, called the Substrate Runtime Module Library, or SRML.

These modules are extremely useful. They add functionality for a range of features we’ve come to expect from other Blockchain frameworks, and they’re available to browse through on Github. Having these modules readily available saves developers from re-inventing the wheel and re-implementing them — and where entirely new features are implemented, they too can be developed as Runtime Modules.

The SRML modules have been maintained as Substrate has been developed, also making them reliable. Reliability is another key advantage of Runtime modules — maintaining them becomes more realistic as they gain adoption.

Here are a couple of modules available today:

  • Assets: A module providing support for fungible assets — think ERC20 tokens.
  • Balances: A module providing support for managing account balances.
  • Staking: A module providing functionality for managing funds at stake by network maintainers.

You will notice that each of these modules are formatted as a Rust crate, designed to be imported into the Substrate runtime environment.

Note: Parity has created a lot of crates to get Substrate to where it is today. Check out the index of their crates library, at This documentation is actually auto-generated, using a tool called rustdoc — more documentation on that here.

Each of the SRML modules are packaged as crates and are prefixed with srml_ before the name of the module, each of which can be found in the left menu of Parity’s crate library.

Overview of a Module Structure

Each module is defined in its own src/ file, conforming to a specific structure. Already we can see the high-level characteristics of a Substrate module:

  • A module is commonly its own crate, but does not have to be
  • A module can be defined as one file,, or more commonly if the module is a crate. A module can also have other supporting files, often all residing in a specific directory.
  • A module must conform to a particular structure, relying on Specific Substrate APIs

What does this last point actually mean? Well, it depends on what your module actually does. A module provides functionality to your blockchain — that much we already know — but this functionality can come in the form of a range of components:

Events: A module can define custom events to be called when certain criteria are met — perhaps a TokenCreated event when you mint a new non-fungible token. Events are wrapped inside a decl_event! macro:

Storage: A module can define data structures to persist on-chain, such as mappings, lists, and so on. We can actually store a range of data types, most of which are documented here. Storage items are defined within a decl_storage! macro:

Dispatchable functions: Public functions that can be executed at runtime via a JSON RPC call. All dispatchable functions include an origin argument, containing information about the origin of the call to the function, such as the public address of the caller, and other metadata.

If we look at the Assets module dispatchable functions, we can see that issue, transfer and destroy are defined for us. Dispatchable functions are called via accounts. We’ll get into managing accounts using a specific tool further down

Public or private functions: Modules can provide public functions that can be called from anywhere in your runtime environment, as well as private functions, that can only be called from within the module’s implementation. Neither of these are dispatchable functions, e.g. They cannot be reached externally via the JSON RPC protocol, and do not require the origin argument.

Structs: Modules can define structs that may be required for that module. E.g. Perhaps a ShipmentItem struct would be defined for a chain used to track global shipments:

Note that we can bring other types into the struct, as we have done with Hash and Balance in the above example.

Standard types, such as Hash, are defined in the runtime primitives library, but types are also commonly defined in other runtime modules, where we introduce the concept of dependencies for modules.

Modules can also be dependencies

As we have already discovered, modules can be crates, and therefore can act as dependencies within Cargo.toml. This ensures there will be no missing modules that others depend on.

Going back to the plug and play analogy, modules are defining pluggable (imported) features that can be played (executed) inside your runtime, giving your chain additional functionality. This pluggable aspect simply means declaring and importing your required modules into your Substrate runtime. We’ll visit this further down.

With the conceptual understanding of what a Substrate module actually is, let’s use the substrate-module-new utility to generate a bare-bones module template.

Initialising a new module

Like the substrate-node-new utility, we also have downloaded a substrate-module-new utility, that pulls the latest module template for us to work with.

Within your node runtime directory, prepare a new module with the following:

substrate-module-new <module_name>

Let’s run this with a name of my-module. The output will prompt us to add the module to our runtime/src/ file:

cd runtime/src
substrate-module-new my-module
> SRML module created as ./ and added to git.
> Ensure that you include in your ./ the line:
> mod my_module;

The resulting file, my-module, will be identical to the file that was originally included in the directory. However, running substrate-module-new is the preferred way to initiate a new runtime module in the event has been edited.

From here we can go ahead and develop the module, wrap it in its own crate, even distribute it on Github where other developers can maintain or contribute to its development. This is the inherent power of Substrate modules, and will undoubtedly aid in development efforts as module libraries are published by developers from various fields.

Read more about importing a module into your runtime on this documentation page.

Note: I will be publishing more syntax driven insights on module development in the future.


This introduction on Substrate has covered how to install the framework, along with using the included tools to aid in deploying custom nodes and modules.

We visited the Polkadot JS app to see how it works as a Substrate management utility, acting as a chain explorer and manager at the same time. The app aims to be generic and not assume anything about what your chain supports — the UI of the app will update depending on your chain spec and what modules you have defined within your runtime.

On the subject of chain specifications, we covered how a specification JSON file is generated via substrate build-spec, the contents of which will vary depending on the modules your chain’s runtime will execute. There are also three pre-configured chain-specs that fill in specifications for either a development or production node. A chain specification can be edited before compiled into a raw state and used with your runtime.

We also explored runtime modules themselves, that they are commonly one file bundled into a cargo crate. Runtime modules need to adhere to Substrate APIs, that define various components such as events, storage, and functions, all of which will become available to your runtime upon importing the module.

Better Programming

Advice for programmers.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store