Skip to content

00-introduction.md

Latest commit

 

History

History
158 lines (120 loc) · 10.9 KB

00-introduction.md

File metadata and controls

158 lines (120 loc) · 10.9 KB
Raw

Introduction

Building a Substrate chain, step by step — a tutorial in eight commits, each one a deliberate design decision.

This tutorial shows how to build a Substrate blockchain node by extending a minimal one, step by step — improving it one piece of functionality at a time. We start from a bare, barely-useful AURA + GRANDPA node and end with a full-featured, self-governed chain that speaks Ethereum: NPoS validator economics, on-chain governance, a treasury, an institutional-accounts layer, an H160 account model, and a complete Frontier EVM.

What we're building

The finished chain (substrate-tutorial) is a Substrate solochain with:

  • BABE + GRANDPA consensus — VRF-based block production with explicit, provable finality.
  • NPoS validator economics — validators bond stake, nominators back them, an on-chain Phragmén election picks the active set each era, and misbehavior is slashed.
  • OpenGov (Gov2) — track-based referenda with conviction voting, so the chain governs itself with no sudo key.
  • A sovereign treasury — fed by transaction fees, tips, slashes, and forfeited deposits, and spent through governance.
  • Accounts as institutions — identity, utility (batching), multisig, and proxy pallets.
  • An H160-native account model — 20-byte Ethereum addresses and secp256k1/ECDSA signatures, so an account's address matches its MetaMask address and Ethereum wallets can sign the chain's EVM transactions.
  • A full Frontier EVM — pallet-evm + pallet-ethereum with the complete eth_* JSON-RPC surface, so Solidity contracts deploy and run unchanged.

Each of those capabilities is introduced in its own lesson, layered on top of what came before.

Why build it this way

Most tutorials hand you a finished template and explain it top-down. This one does the opposite: it grows the chain so you can see each decision in isolation — what problem it solves, what it costs, and what alternatives exist at that branch point.

The AURA + GRANDPA node we start with is deliberately minimal and not very useful: a fixed set of authorities take turns producing blocks, with no economic security, no way to change the rules, and no smart contracts. That is exactly the point — every later lesson takes one concrete weakness of the current chain and fixes it, and you get to understand why each pallet is there rather than just that it is. The goal is teaching you the design space, not just the resulting code.

How the tutorial is structured

The tutorial is built around an actual git history. After this introduction and the prerequisites, each lesson maps to exactly one commit, and each commit is a single, self-contained step. Every lesson explains:

  1. What we're building — what the chain gains at this step.
  2. The decision we made — and why this path.
  3. Other paths we could have taken — alternatives at this branch point, honestly evaluated.
  4. What's next — the decision the next lesson takes on.

Reading order

Sequential — each lesson assumes you read the previous one, as concepts and vocabulary build up.

# Lesson Commit
— Prerequisites. What to know before you start. —
1 A solochain that breathes: AURA + GRANDPA. A working node with the simplest possible consensus. 6 pallets, no sudo. f2fecbb
2 From AURA to BABE: randomness in the slot lottery. Replace deterministic block production with VRF-based selection. Add pallet-session, pallet-authorship, Babe + Grandpa RPC. 3a0a139
3 Validator economics: NPoS, slashing, and ImOnline. Add pallet-staking, pallet-offences, pallet-im-online, real equivocation reporting. The chain now has economic security. c246a27
4 OpenGov: making the chain governable. Add pallet-referenda, pallet-conviction-voting, pallet-scheduler, pallet-preimage, custom origins pallet, 5 tracks. The chain can now decide. 5232539
5 Treasury: a public-funds layer. Add pallet-treasury, route slashes / reward dust / 20% of fees / 100% of tips / forfeited referendum deposits to a sovereign account. Two new spend tracks (Treasurer, BigSpender). The chain can now spend. 6e253cd
6 Accounts as institutions. Add pallet-identity, pallet-utility, pallet-multisig, pallet-proxy. Human-readable accounts, atomic batching, M-of-N multisigs, delegated keys with scoped permissions. Six ProxyType variants. c39096f
7 H160: Ethereum-flavored account model. Swap AccountId32 + MultiSignature for AccountId20 + EthereumSignature. Ethereum-identical addresses; native extrinsics signed via the Ethereum crypto path (MetaMask signs EVM txs, added next lesson). Add substrate-tutorial-keyring crate with the six Moonbeam test accounts. 2931bdb
8 Frontier EVM. Add pallet-ethereum + pallet-evm + base-fee + dynamic-fee + chain-id + 6 precompiles. Wire fp_self_contained::UncheckedExtrinsic for Ethereum tx dispatch. Full eth_* / net_* / web3_* / debug_* / eth_filter_* / eth_pubsub_* JSON-RPC. BabeConsensusDataProvider for pending-block simulation. Chain id 1337. 7f1a9bc
— Where to go from here. Smart contracts, assets, XCM, custom pallets, production hardening. The branches we haven't built. —

How to follow along

Each lesson is readable standalone. If you also want to see the code at any step:

git clone <repo> substrate-tutorial && cd substrate-tutorial
git checkout <commit>            # e.g., git checkout f2fecbb for lesson 1
cargo build --release
./target/release/substrate-tutorial --dev    # if the commit's build succeeds

Following the evolution. Because each lesson is exactly one commit, git diff between two lesson hashes shows precisely what that step changed — the cleanest way to see how the chain grew:

git diff f2fecbb 3a0a139               # everything lesson 2 (BABE) added over lesson 1
git show 5232539                       # lesson 4 (OpenGov) as one reviewable patch
git show 6e253cd -- runtime/          # just lesson 5's runtime changes
git log --oneline --reverse            # the whole lesson sequence at a glance

Prefer the browser? GitHub renders the same diffs — each lesson's header links its commit (which on GitHub is that lesson's diff against the previous one), and you can compare any two lessons directly:

Diffing consecutive lesson hashes — locally or on GitHub — lets you read the tutorial as a story of small, self-contained changes.

The post-Frontier-EVM state is the working version with Ethereum compatibility enabled end to end.

What this tutorial covers

  • Block production: AURA, BABE, alternatives
  • Finality: GRANDPA, alternatives, why decoupled-from-production matters
  • Session machinery and key rotation
  • Validator economics: NPoS, on-chain elections, reward curves
  • Slashing: equivocation, liveness, the offence pipeline
  • Governance: OpenGov tracks, conviction voting, custom origins pallet, scheduler+preimage infrastructure
  • Treasury: revenue sinks, fee splitting, spend tracks, the legacy-Currency-vs-fungibles wiring quirk
  • Accounts as institutions: identity, utility batching, multisig, proxy types and InstanceFilter
  • Account models: AccountId32 vs H160, Ethereum-flavored signatures, and what a wallet like MetaMask can (EVM txs) and can't (native extrinsics) sign
  • Frontier EVM: pallet-ethereum, pallet-evm, base-fee, precompiles, self-contained extrinsics, pending-block simulation
  • Runtime API surface and how the node consumes it
  • JSON-RPC integration (Babe + Grandpa, full eth_/net_/web3_/debug_ namespaces)

What this tutorial doesn't cover (yet)

  • Bounties and tips — multi-stage paid work, tipper-collective payouts
  • Wasm contracts — pallet-revive, pallet-contracts (Frontier-flavored EVM is covered in lesson 8)
  • Cross-chain — XCM, bridges, parachain conversion
  • Custom pallet authorship — the actual reason most chains exist
  • Production hardening — chain specs, validator ops, monitoring, audits

The where-to-next page lays out roadmap pointers for each.

Design choices the tutorial took

A few choices that pervade everything:

  • No sudo. Most tutorials include pallet-sudo as "convenience for dev." We don't. This forces the governance conversation to happen for real, instead of "we'll deal with it later."
  • Real reference comparison. Each lesson references the equivalent code in polkadot-sdk/substrate/bin/node — the canonical full node implementation — so you can see how Polkadot does it and where Substrate Tutorial simplifies.
  • Honest alternatives. Each lesson's "Other paths" section evaluates alternatives we didn't take, including why we didn't. PoW is mentioned. BEEFY is mentioned. The PoA-forever path is mentioned. We don't pretend our path is the only viable one.
  • No tests, no benchmarks (yet). Both are real concerns, but they're orthogonal to the design teaching. The where-to-next page covers them.

Conventions

  • "polkadot-sdk" means the upstream monorepo at paritytech/polkadot-sdk.
  • Code references are at branch stable2603 unless otherwise stated.
  • Code citations use path/file.rs:LINE format. They are stable for the duration of stable2603's life; chase HEAD if you read this in the future.
  • "Substrate" and "polkadot-sdk" are used interchangeably — historically the Substrate monorepo merged into polkadot-sdk in 2023.

Feedback

This tutorial is a work in progress. If a lesson is unclear, an "Other paths" claim is wrong, or you'd like a topic from the where-to-next page expanded into a real lesson — open an issue or PR.

Start with the Prerequisites, or jump straight to Lesson 1 — AURA + GRANDPA if you're impatient.