Polkadot

Chapter 52: Polkadot/Substrate Nodes

Overview

Polkadot is a multi-chain platform where a relay chain secures and coordinates connected parachains. A single polkadot binary runs either a full/archive relay-chain node or a validator; parachain teams ship their own Substrate-based collator binaries.

---

52.1 Polkadot Basics

Feature	Value
Consensus	BABE (block production) + GRANDPA (finality)
Block Time	6 s (Polkadot), 12 s (Kusama)
Architecture	Relay Chain + Parachains
Token	DOT
Finality	GRANDPA finalizes batches of blocks with authority-set signatures

┌─────────────────────────────────────────────────────────────┐
│                  RELAY CHAIN (polkadot binary)              │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│   │ Start    │  │ Balance  │  │ ...      │  (system)        │
│   └──────────┘  └──────────┘  └──────────┘                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
        │                  │                  │
        ▼                  ▼                  ▼
  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
  │ Parachain A │   │ Parachain B │   │ Parachain C │
  │ (collators) │   │ (collators) │   │ (collators) │
  └─────────────┘   └─────────────┘   └─────────────┘

---

52.2 Node Types

Type	Description
Relay Full Node	Validates relay-chain blocks, serves RPC, no stake
Archive Node	Full historical state (RPC/explorer use case)
Validator	Runs with --validator (+ GRANDPA/BABE keys + stake) — executes blocks and validates parachains
Collator	Parachain node: collects parachain txs into candidate blocks for relay-chain validators

---

52.3 Installing Polkadot

Install (prebuilt binary — recommended)

# Download the polkadot release binary (see github.com/paritytech/polkadot/releases)
wget https://github.com/paritytech/polkadot/releases/download/v1.15.2/polkadot
chmod +x polkadot
./polkadot --version

Or build from source

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

git clone https://github.com/paritytech/polkadot.git
cd polkadot
cargo build --release          # adds the `target/release/polkadot` binary

---

52.4 Running a Node

Sync Modes

Mode	What it downloads	Use case
warp	State at last finalized block via GRANDPA authority-set proofs (default since v1.0)	Fastest; fresh node at tip in ~1 h
full	Full history execution	Historical queries / block explorers

# Full node (warp sync is default)
polkadot --name "my-node" --chain polkadot

# Explicit modes
polkadot --name "my-node" --sync warp --chain polkadot
polkadot --name "my-node" --sync full --chain polkadot

# Archive node (keeps all state — needed for deep historical RPC)
polkadot --archive --chain polkadot

Important Flags

Flag	Purpose
--chain polkadot / --chain kusama	Which network spec
--name	Display name (shows in telemetry)
--validator	Run as a validator (requires session keys + stake)
`—sync warp	full`
--pruning archive / --pruning <n>	State retention
--wasm-execution Compiled	Faster Wasm execution (default: understands native)
--rpc-port 9944	JSON-RPC port (default 9944)
--ws-port 9944	WebSocket port (default 9944)
--prometheus-port 9615	Prometheus metrics (Exporter module)
--rpc-cors all / --ws-max-connections	RPC hardening

Ports

Port	Purpose
30333	P2P (TCP, + QUIC in newer versions)
9944	JSON-RPC + WebSocket (same port)
9615	Prometheus metrics

---

52.5 Validator Basics

Becoming a validator requires session keys (BABE + GRANDPA + I’m-online) and a minimum stake:

polkadot --validator --name "my-validator" --chain polkadot \
    --rpc-port 9944 \
    --prometheus-port 9615

# Rotate/set session keys via RPC:
# curl -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"author_rotateKeys","params":[],"id":1}' http://localhost:9944
# → submit the returned keys via the staking pallet

Security note: Polkadot validators risk slashing on equivocation — run exactly one validator per key, never reuse keys across servers (Chapter 35 applies).

---

52.6 Substrate

Substrate is the framework for building parachains and standalone chains; parachain collator nodes are Substrate-based.

# Many parachains ship their own binary. For local development there is a
# prebuilt substrate node:
cargo install substrate-contract-node
# or clone substrate-node-template and build:
git clone https://github.com/substrate-developer-hub/substrate-node-template
cd substrate-node-template && cargo build --release

Substrate nodes share the same core CLI (--chain, --sync, --rpc-port, --ws-port, --prometheus-port), so the operational knowledge transfers across every parachain.

---

52.7 Monitoring & Health

# Health check
curl -s http://localhost:9944/health | jq
# → {"isSyncing":false,"peers":42,"shouldHavePeers":true}

# Prometheus (enable with --prometheus-port 9615, keep firewalled)
curl -s http://localhost:9615/metrics | grep -E "substrate_block_height|polkadot"

# Telemetry (public overview)
# https://telemetry.polkadot.io/  — filter by your --name

Alert on isSyncing staying true, block height stalling (substrate_block_height no increase), peers dropping, and disk growth — same alerting principles as Chapter 38.

---

Summary

• One polkadot binary: full node, archive node, or validator — relay chain + parachain validation
• Warp sync (GRANDPA-proof state download) is the fast path; --sync full for full history
• BABE produces, GRANDPA finalizes; validators need session keys + stake
• P2P 30333, RPC+WS 9944, Prometheus 9615
• Substrate shares the same CLI/ops model across all parachains

---

Next Chapter

In Chapter 53: Bitcoin Nodes, we’ll explore Bitcoin nodes.

---

Last Updated: 2026-09-28