If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/paritytech/substrate shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 48+ active contributors
• Distributed ownership (top contributor 8% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live paritytech/substrate repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/paritytech/substrate.

What it runs against: a local clone of paritytech/substrate — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in paritytech/substrate | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 985 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of paritytech/substrate. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/paritytech/substrate.git
#   cd substrate
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of paritytech/substrate and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "paritytech/substrate(\\.git)?\\b" \\
  && ok "origin remote is paritytech/substrate" \\
  || miss "origin remote is not paritytech/substrate (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "bin/node/cli/bin/main.rs" \\
  && ok "bin/node/cli/bin/main.rs" \\
  || miss "missing critical file: bin/node/cli/bin/main.rs"
test -f "bin/node-template/runtime/src/lib.rs" \\
  && ok "bin/node-template/runtime/src/lib.rs" \\
  || miss "missing critical file: bin/node-template/runtime/src/lib.rs"
test -f ".github/workflows" \\
  && ok ".github/workflows" \\
  || miss "missing critical file: .github/workflows"
test -f ".maintain/runtime-dep.py" \\
  && ok ".maintain/runtime-dep.py" \\
  || miss "missing critical file: .maintain/runtime-dep.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 985 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~955d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/paritytech/substrate"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Substrate is a modular blockchain framework written in Rust that enables developers to build custom blockchains by composing pluggable consensus engines (AURA, BABE, GRANDPA, BEEFY), runtime pallets (via FRAME), and client services. It abstracts away low-level blockchain complexity so teams can focus on domain-specific logic rather than reimplementing consensus, state management, and networking from scratch. Monorepo structure: bin/node/* contains the reference Substrate node (CLI, runtime, RPC, executor); client/* holds consensus (aura, babe, grandpa, beefy, pow), service layer, and CLI infrastructure; frame/* provides the runtime framework and pallets; primitives/* defines core types (sp-runtime, sp-api). Node template in bin/node-template/ is the starter scaffold for new blockchains.

Blockchain engineers and runtime developers who want to launch custom blockchains with Polkadot ecosystem compatibility; teams building parachains or standalone chains who need modular consensus and finality gadgets without forking Polkadot itself.

This repository is now archived and in transition—Parity has merged Substrate, Cumulus, and Polkadot into a single 'Polkadot SDK' repository (paritytech/polkadot-sdk). The codebase shows production maturity (18M+ lines of Rust, extensive test coverage via nextest in .config/nextest.toml, CI/CD workflows in .github/workflows/), but new work is no longer happening here. Verdict: Production-ready but deprecated—new contributions should go to polkadot-sdk.

High consolidation risk: this repo is frozen and redirects users to paritytech/polkadot-sdk, so any PRs opened here will be rejected or delayed. Large monorepo with 18M+ Rust LOC means compile times are substantial and dependency tracking complex (Cargo.lock is committed). Breaking changes between releases are common in blockchain frameworks, and FRAME/runtime APIs have evolved rapidly, so code targeting old Substrate versions will bitrot quickly.

This repo is in maintenance-only mode pending full migration to polkadot-sdk. GitHub workflows in .github/workflows/ show automated release tagging (release-tagging.yml), dependency updates (via dependabot.yml), and PR labeling (pr-custom-review.yml), but no active feature development. The README explicitly directs contributors to resubmit PRs to the new unified repository.

git clone https://github.com/paritytech/substrate.git && cd substrate && cargo build --release (note: compile time ~10–20 min on typical hardware; requires Rust 1.70+ via rustup). However, do not invest effort here—instead clone paritytech/polkadot-sdk and follow its onboarding.

Daily commands: cargo run --release --bin substrate -- --dev (starts a local dev node with PoA consensus and temporary storage). Alternatively, cargo run -p node-cli --features try-runtime for testing runtime migrations. Reference node RPC runs on localhost:9944 by default; use Polkadot.js frontend to interact.

• Cargo.toml — Root workspace manifest declaring all Substrate crates and their interdependencies; essential for understanding the modular architecture.
• bin/node/cli/bin/main.rs — Entry point for the Substrate node CLI; shows how the runtime, consensus, and networking layers initialize.
• bin/node-template/runtime/src/lib.rs — Template runtime composition demonstrating how to integrate FRAME pallets and configure on-chain execution; reference implementation for custom runtimes.
• .github/workflows — CI/CD pipeline definitions; critical for understanding build, test, and release processes.
• .maintain/runtime-dep.py — Runtime dependency analysis tooling; reveals architectural constraints and layer dependencies.
• bin/node-template/pallets/template/src/lib.rs — Minimal FRAME pallet template showing the core pattern for writing blockchain logic and storage.
• .cargo/config.toml — Cargo workspace configuration including profile settings and build optimizations for blockchain artifacts.

Add a New FRAME Pallet

1. Create a new pallet directory under bin/node-template/pallets/ with Cargo.toml declaring frame-support and frame-system dependencies (bin/node-template/pallets/template/Cargo.toml)
2. Define storage items, call extrinsics, and events in the pallet's lib.rs using #[pallet::...] macros (bin/node-template/pallets/template/src/lib.rs)
3. Integrate the pallet into the runtime by adding it to the construct_runtime! macro in bin/node-template/runtime/src/lib.rs (bin/node-template/runtime/src/lib.rs)
4. Write benchmarking code in src/benchmarking.rs to measure transaction weights (bin/node-template/pallets/template/src/benchmarking.rs)
5. Add unit tests in src/tests.rs or src/mock.rs using the mock runtime (bin/node-template/pallets/template/src/tests.rs)

Customize Runtime Configuration

1. Edit bin/node-template/runtime/src/lib.rs to import and configure pallets with their generic parameters (bin/node-template/runtime/src/lib.rs)
2. Implement required pallet Config traits (e.g., frame_system::Config) with your custom types (bin/node-template/runtime/src/lib.rs)
3. Update construct_runtime! macro to include your pallet instances and versions (bin/node-template/runtime/src/lib.rs)
4. Update runtime/Cargo.toml to add new pallet crate dependencies (bin/node-template/runtime/Cargo.toml)

Set Up a Custom Node Binary

1. Create a new node binary directory (e.g., bin/my-node/) with node/Cargo.toml, node/src/main.rs, and runtime/Cargo.toml (bin/node/cli/bin/main.rs)
2. Implement CLI parsing in node/src/cli.rs by extending StructOpt with custom chain-spec and subcommands (bin/node-template/node/src/cli.rs)
3. Define chain specifications (genesis, bootnodes) in node/src/chain_spec.rs (bin/node-template/node/src/chain_spec.rs)
4. Configure service initialization and consensus in node/src/service.rs using sc-service (bin/node-template/node/src/service.rs)
5. Reference your runtime in the node's Cargo.toml and src/main.rs (bin/node-template/node/src/main.rs)

• Rust — Memory safety, zero-cost abstractions, and performance required for blockchain consensus and state execution.
• FRAME (Pallets) — Modular runtime composition system allowing developers to mix-and-match blockchain logic without reimplementing core primitives.
• WebAssembly (WASM) — Runtime deployed as WASM allows on-chain upgrades via governance without recompiling the node binary.
• Pluggable Consensus (AURA, BABE, GRANDPA, BEEFY) — Decouples consensus algorithm from the runtime, enabling different security/performance tradeoffs per chain.
• sc-service & sc-cli — Reusable client libraries avoid reimplementing networking, RPC, transaction pool, and CLI parsing for every chain.

• Runtime as WASM instead of native binary

  • Why: Enables forkless upgrades through governance; improves decentralization by allowing non-validator node operators to participate.
  • Consequence: WASM execution is ~3-10% slower than native; requires careful optimization for heavy computations.

• Modular pallet architecture over monolithic state machine

  • Why: Reduces duplication and cognitive load; allows teams to contribute pallets independently.
  • Consequence: Increased complexity in trait bounds, generic parameters, and inter-pallet dependencies; harder to reason about global state consistency.

• Validator-centric design with finality gadgets (GRANDPA) over pure PoW

  • Why: Enables faster finality, lower orphan rates, and energy efficiency.
  • Consequence: Requires BFT consensus and stake/bond mechanisms; not suitable for permissionless networks without economic models.

• Not a full blockchain (no application layer; Substrate is the foundation).
• Does not provide a production-ready node binary out-of-the-box; requires runtime customization.
• Does not handle application-level authentication or user identity management.
• Not compatible with Ethereum or Bitcoin as-is; requires bridge pallets and custom logic.
• Not designed for privacy-preserving transactions at the core level (privacy requires pallet-specific implementation).

Cargo features are mandatory: --features try-runtime required to use TryRuntime pallet for testing state transitions. WebAssembly must be built separately: cargo build --release --target wasm32-unknown-unknown builds the runtime wasm blob, not just cargo build. Finality lag: GRANDPA/BEEFY have multi-round voting; expect 2–4 block latency before finalization on testnet. Storage trie format: StateTrieVersion is hard-coded in runtime; changing it mid-chain causes state corruption. Spec version bumps: incrementing spec_version in RuntimeVersion triggers auto-code-upgrade on-chain; mismatches cause fork. Nextest required: .config/nextest.toml assumes nextest for parallel test execution; plain cargo test may hang on some test suites.

• FRAME (Framework for Runtime Aggregation of Modularized Entities) — FRAME's macro system (pallet, construct_runtime, dispatch) is the dominant pattern in Substrate; understanding macro-generated code and pallet composition is essential to write any blockchain logic.
• Pluggable Consensus Engines (SelectChain, BlockImport, Finalizer traits) — Substrate's core innovation is swappable consensus; you must understand these traits to add custom consensus (AURA, BABE, GRANDPA are all implementations) or modify finality rules.
• State Trie (Merkle-Patricia Trie, StateTrieVersion) — Substrate uses a versioned trie for storage; trie format changes are breaking and must be coordinated with runtime spec version bumps to avoid state corruption on live chains.
• Weight and Dispatch Weight System — Extrinsics (transactions) are metered by weight (a cost abstraction covering CPU + storage I/O); miscalculating weight can cause transaction rejection or economic exploits.
• Governance Pallets (Pallet-Democracy, Pallet-Collective, Pallet-Technical-Committee) — Substrate chains are often governed on-chain; these pallets enable decentralized upgrade voting and are critical if you want decentralized chain governance rather than sudo.
• Light-Client Protocols (Grandpa Finality Proofs, Storage Proofs) — Substrate can generate compact proofs of finality and storage for light clients (mobile, browser); understanding proof generation is key for scaling.
• WebAssembly Runtime Sandboxing (wasm32-unknown-unknown target, host functions) — Runtime logic runs in WASM and talks to the host client via defined host function APIs; bugs in WASM→host calls (or missing host function implementations) cause consensus failures.

• paritytech/polkadot-sdk — The active merged repository combining Substrate, Cumulus, and Polkadot; this is where all new development happens after the consolidation.
• paritytech/cumulus — Parachain consensus and collator infrastructure; tightly integrated with Substrate for building parachains in the Polkadot ecosystem.
• paritytech/polkadot — The relay chain using Substrate primitives and FRAME; reference implementation of a Substrate-based blockchain with BABE+GRANDPA finality.
• rustwasm/wasm-bindgen — Enables Rust↔WebAssembly interop; Substrate runtimes compile to WASM and wasm-bindgen helps with FFI if custom host functions are needed.
• libp2p/rust-libp2p — Substrate's networking stack; sc-network wraps libp2p for blockchain p2p messaging, consensus gossip, and light-client protocols.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive benchmarking tests for consensus mechanisms in bin/node/bench

The repo contains multiple consensus implementations (aura, babe, grandpa, beefy, pow, manual-seal) under client/consensus/*, but bin/node/bench appears to be underutilized. New contributors could add comparative benchmarks for these consensus mechanisms to help identify performance regressions early. This is critical since Substrate is a blockchain framework where consensus performance is paramount.

• [ ] Review existing benchmarks in bin/node/bench/ to understand structure
• [ ] Create benchmark harnesses for sc-consensus-aura, sc-consensus-babe, and sc-consensus-grandpa
• [ ] Add block validation and finality latency measurements
• [ ] Integrate benchmarks into CI via .github/workflows/ (note: md-link-check.yml exists but no benchmark workflow)
• [ ] Document results in bin/node/bench/README.md

Implement missing integration tests for node-template in bin/node-template/

The node-template is the primary entry point for new Substrate developers, but there are no visible integration tests validating that the template compiles, runs, and functions correctly across different configurations. This would catch template regressions early and provide examples for contributors.

• [ ] Create bin/node-template/tests/integration_tests.rs
• [ ] Add tests for: template node compilation, basic RPC functionality, pallet instantiation, and runtime initialization
• [ ] Verify tests run against both the default and any feature-gated configurations
• [ ] Update bin/node-template/README.md with instructions for running integration tests
• [ ] Consider adding template-validation to .github/workflows/ (new workflow file)

Add missing documentation for client/rpc and client/api in frame/support and primitives/runtime

The workspace members include critical modules like client/api, client/rpc, frame/support, and sp-runtime, but there are no visible doc/ folders or ARCHITECTURE.md files explaining their interfaces and relationships. New contributors struggle to understand how RPC calls flow through the runtime. Adding structured documentation with examples would significantly lower the contribution barrier.

• [ ] Create docs/architecture/RPC_FLOW.md explaining: RPC entry points → client/rpc → frame/support → sp-runtime interaction
• [ ] Add docs/architecture/FRAME_PALLET_DEVELOPMENT.md with concrete examples from bin/node-template/pallets/template
• [ ] Document the dependency graph: which client/* modules depend on which primitives/*
• [ ] Add doc comments with examples to key types in client/api/src/lib.rs and frame/support/src/lib.rs
• [ ] Reference these docs in README.md under a new 'Architecture' section

• Add missing documentation examples to sp-runtime types (sp-runtime is 18K+ LOC with minimal code examples in doc comments); pick one type like Weight or Perbill and add a runnable example via #[doc = include_str!("examples/...")].
• Expand the node-template README with step-by-step inline comments explaining each line of runtime configuration in bin/node-template/runtime/src/lib.rs; currently it assumes readers understand macros.
• Write integration tests for client/consensus/manual-seal/ (manual block production for testing); the module has no tests/ directory and is used in testing but undocumented.

The Substrate codebase demonstrates a generally sound security foundation as a mature blockchain platform, but shows some gaps in security governance. Primary concerns include: (1) ongoing repository migration creating potential security oversight opportunities, (2) lack of formal security disclosure and vulnerability management processes, (3) insufficient documentation of supply chain security practices for the large Rust-based workspace, and (4) minimal visible security hardening in infrastructure/Docker configurations. The extensive workspace structure with 20+ interdependent crates requires robust dependency management and continuous security scanning. No obvious hardcoded credentials or critical misconfigurations detected in the provided file structure snapshot. Recommendations focus on establishing formal security policies, implementing automated security scanning in CI/CD, and completing documentation of security practices for contributors.

• Medium · Repository Migration with Potential PR Loss — README.md, repository root. The repository has been merged into a new 'Polkadot SDK' repository. This migration introduces risks of lost context, incomplete PR reviews, and potential security oversight during the transition. Contributors are asked to resubmit PRs, which could lead to duplicated or orphaned contributions. Fix: Implement a comprehensive migration checklist ensuring all open PRs are properly reviewed and transferred. Maintain audit logs of the migration process. Consider implementing automated security scanning on the new consolidated repository before accepting migrated code.
• Low · Lack of Security Configuration Documentation — .github/, repository root. No visible security policy, vulnerability disclosure, or security guidelines found in the repository structure. The .github directory contains workflow configurations but no SECURITY.md or security contact information. Fix: Create a SECURITY.md file documenting: vulnerability disclosure process, security contacts, supported versions, and security update procedures. Consider adding security scanning to GitHub workflows.
• Low · Incomplete Dependency Pinning in Workspace — Cargo.toml, Cargo.lock. The Cargo.toml shows a workspace with multiple members but only one listed dependency (aquamarine 0.3.2). Many dependencies are likely managed transitively, creating potential for supply chain vulnerabilities if transitive dependencies are compromised. Fix: Maintain an updated Cargo.lock file in version control. Regularly audit transitive dependencies using tools like cargo audit and cargo-deny. Consider implementing dependency scanning in CI/CD pipelines.
• Low · Docker Configuration Exposure — .maintain/local-docker-test-network/docker-compose.yml. Docker-related files exist (.dockerignore, docker-compose.yml) in the local development testing directory without visible security hardening guidelines or secrets management strategy documented. Fix: Ensure docker-compose configurations never include hardcoded credentials. Use Docker secrets or environment variable files (.env.example, not .env in repo). Document security best practices for Docker usage in the development guide.
• Low · Git Configuration Security — .git-blame-ignore-revs, .gitlab-ci.yml. Repository contains .git-blame-ignore-revs file which could potentially mask security-relevant commits if not properly maintained. GitLab CI configuration also present but security posture unclear. Fix: Document the purpose and maintenance of .git-blame-ignore-revs to ensure it doesn't mask security-related changes. Review and secure .gitlab-ci.yml pipeline configurations for injection vulnerabilities and credential exposure.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.