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/polkadot 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.

WAIT — Stale — last commit 2y ago

• 46+ active contributors
• Distributed ownership (top contributor 6% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{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/polkadot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/paritytech/polkadot.

What it runs against: a local clone of paritytech/polkadot — 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/polkadot | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.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 ≤ 934 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of paritytech/polkadot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/paritytech/polkadot.git
#   cd polkadot
#
# 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/polkadot and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.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 "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "node/core/README.md" \\
  && ok "node/core/README.md" \\
  || miss "missing critical file: node/core/README.md"
test -f "cli/src/lib.rs" \\
  && ok "cli/src/lib.rs" \\
  || miss "missing critical file: cli/src/lib.rs"
test -f "core-primitives/src/lib.rs" \\
  && ok "core-primitives/src/lib.rs" \\
  || miss "missing critical file: core-primitives/src/lib.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 934 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~904d)"
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/polkadot"
  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).

Polkadot is a Rust-based blockchain node implementation that enables parachains to connect to and validate with the Polkadot relay chain. It implements the Substrate framework and handles parachain validation, block production, and cross-chain message passing through a sophisticated overseer architecture managing multiple specialized subsystems (consensus, collation, approval voting, disputes). Monorepo structure: cli/ wraps the CLI surface, core-primitives/ defines blockchain types, node/ contains subsystems (node/core/pvf for parachain validation, node/overseer for orchestration), primitives/ holds shared types, and runtime/ contains chain logic. Multiple binaries defined in Cargo.toml: polkadot (main), polkadot-execute-worker, polkadot-prepare-worker. Workspace members span 8+ crates with feature-gated chain variants (polkadot-native, kusama-native, westend-native, rococo-native).

Blockchain protocol developers, validator operators running Polkadot nodes, and parachain teams integrating with Polkadot need this to participate in the network. Core contributors are Parity Technologies engineers maintaining consensus, PVF execution, and the relay chain runtime.

Production-ready and actively developed. The codebase is established (version 0.9.43, Rust 1.64.0+ required) with comprehensive CI workflows (.github/workflows/ contains 20+ automated checks including honggfuzz fuzzing, weight checks, and release pipelines). Recently consolidated from three separate repos (Cumulus, Substrate, Polkadot) into the Polkadot SDK, indicating major ongoing architectural evolution.

Moderate risk: the recent monorepo merge (Cumulus + Substrate + Polkadot combined) creates integration complexity and potential for incomplete migration. Heavy dependency on Substrate (git dependency on paritytech/substrate master branch) ties stability to external repo changes. PVF execution involves sandboxed worker processes (execute-worker, prepare-worker binaries) requiring careful security audits. No visible indication of single-maintainer bottleneck, but blockchain consensus code demands extremely high code quality standards.

Repository is in active transition post-merge into Polkadot SDK. Recent focus visible in workflows: extrinsic ordering verification (release-20/21), weight checking (check-weights.yml), bootnode configuration updates (check-bootnodes.yml), and Docker release automation. PVF (parachain validation function) subsystem remains a major development area (node/core/pvf/ contains execute-worker and prepare-worker). Contributors are being redirected to the new unified polkadot-sdk repo.

git clone https://github.com/paritytech/polkadot.git
cd polkadot
cargo build --release
cargo run -- --dev

Minimum Rust 1.64.0 required (set in workspace.package). Uses jemalloc allocator (tikv-jemallocator 0.5.0) for performance.

Daily commands:

# Development node (single validator, Alice account)
cargo run -- --dev

# Connect to live Polkadot network
cargo run -- --chain polkadot

# Kusama testnet
cargo run -- --chain kusama

# Rococo testnet
cargo run -- --chain rococo-dev

Binary name is 'polkadot' (set as default-run in Cargo.toml). Worker processes spawn automatically.

• Cargo.toml — Root workspace configuration defining all dependencies, workspace members, and the polkadot binary entry point—essential for understanding the entire project's structure and build system.
• src/main.rs — Main entry point for the polkadot node executable; defines the CLI interface and orchestrates core subsystems.
• node/core/README.md — Documents the architecture and responsibilities of core node subsystems (approval-voting, av-store, backing), critical for understanding the validator/parachain consensus layer.
• cli/src/lib.rs — CLI library initialization and command routing; defines how the node starts and processes configuration.
• core-primitives/src/lib.rs — Core data structures and type definitions used throughout the Polkadot node; foundational to all other modules.
• node/collation-generation/src/lib.rs — Parachain collation generation logic; critical for understanding how collators produce candidate blocks.
• erasure-coding/src/lib.rs — Erasure coding implementation for availability distribution; fundamental to the data availability layer.

Add a new validator subsystem

1. Create new subsystem crate under node/core/{name}/ with Cargo.toml (node/core/{name}/Cargo.toml)
2. Implement the main library with standard subsystem trait and message handling (node/core/{name}/src/lib.rs)
3. Define subsystem messages and errors following existing patterns (see backing/av-store) (node/core/{name}/src/error.rs)
4. Add subsystem spawn logic and registration in cli/src/command.rs (cli/src/command.rs)
5. Update workspace Cargo.toml to include the new member (Cargo.toml)

Add metrics to a subsystem

1. Define metrics struct following the pattern in existing subsystems (node/core/{subsystem}/src/metrics.rs)
2. Import and instantiate metrics in the main subsystem loop (node/core/{subsystem}/src/lib.rs)
3. Record metric points at key operations (e.g., candidate validation, approval checks) (node/core/{subsystem}/src/lib.rs)

Add erasure coding test or benchmark

1. Create test or fuzzing crate with test vectors and expected results (erasure-coding/benches/scaling_with_validators.rs)
2. Call library functions from erasure-coding/src/lib.rs with test data (erasure-coding/src/lib.rs)
3. Run with cargo test or cargo bench to validate correctness and performance (erasure-coding/Cargo.toml)

Modify CLI startup behavior

1. Add new CLI flag or option in cli/src/cli.rs (cli/src/cli.rs)
2. Parse and handle the option in cli/src/command.rs (cli/src/command.rs)
3. Pass configuration to relevant subsystems during initialization in main command handler (cli/src/command.rs)

• Rust + Substrate Framework — Type-safe, zero-cost abstractions, and memory safety enable secure validator consensus code; Substrate provides blockchain primitives and networking
• Tokio async runtime — Efficient handling of thousands of concurrent subsystem message channels and network I/O on a single validator
• Erasure coding (Reed-Solomon) — Distributed data availability without requiring all validators to store all parachain data; reduces bandwidth and storage
• Separate worker processes (execute-worker, prepare-worker) — Isolates untrusted parachain code execution and PVF preparation; prevents malicious code from crashing the validator node
• SQLite/RocksDB persistence (approval database) — Durability of validator state (approvals, judgments) across restarts; efficient key-value queries for approval voting

• Worker process isolation via separate binaries

  • Why: Security: prevents untrusted parachain execution from compromising the validator
  • Consequence: Higher complexity and IPC overhead; slower parachain execution compared to in-process

• Distributed erasure-coded data availability

  • Why: Scalability: allows many parachains without full replication on every validator
  • Consequence: Requires reconstruction logic; adds latency for validators that miss chunks

• Async subsystem architecture with message-based communication

  • Why: Decoupling and testability: subsystems can be developed/tested independently
  • Consequence: Message ordering and race condition complexity; debugging distributed state is harder than monolithic code

• Approval voting as a separate subsystem

  • Why: Finality security: allows validators to vote on candidates after backing dispute window
  • Consequence: Two-phase validation adds latency and complexity for parachain block finality

• Does not implement parachain runtime execution—only validates and distributes parachain candidate blocks (workers handle execution)
• Does not manage smart contract state or consensus for parachains themselves—relay chain only
• Not a blockchain indexer or query engine; does not expose high-level state APIs for applications
• Not a light client implementation; full validator nodes required for this codebase
• Does not handle inter-parachain communication directly (XCM routing is in parachains/Substrate)
• Cross-platform GUI or wallet—CLI-only node operator interface

PVF worker processes (execute-worker, prepare-worker) require careful configuration: they spawn as separate binaries and may fail silently if not in PATH. Feature flag combinations matter: enabling multiple chain natives (polkadot-native, kusama-native) together causes build conflicts—use only one per binary. Rust 1.64.0 is a hard minimum (workspace.package); older toolchains will fail. Git dependencies on paritytech/substrate master branch mean breaking changes can propagate without warning. Jemalloc allocator (default) requires glibc; musl targets need fallback. Worker process stdio is redirected; debugging requires enabling RUST_LOG=debug and checking polkadot logs, not worker stderr.

• Parachain Validation Function (PVF) — Core to Polkadot's security model; you need to understand how node/core/pvf/ sandboxes and executes parachain code to prevent malicious validators from crashing the relay chain
• Overseer Pattern (Message-Driven Subsystem Orchestration) — The entire node is built on the overseer's message-passing architecture (node/overseer/); understanding how subsystems communicate is essential for contributing to consensus or networking logic
• BABE (Blind Assignment for Blockchain Extension) — Polkadot's block production consensus; you need to know how slot leaders are assigned and validated to understand node/core/babe or modify block authoring logic
• GRANDPA (GHOST-based Recursive Ancestor Deriving Prefix Agreement) — Finality gadget used alongside BABE; critical for understanding how blocks are finalized and how forks are resolved in the relay chain
• Approval Voting Protocol — Secondary validator approval mechanism ensuring parachain candidates are checked; complexity is in node/core/approval-voting; understand this to modify validator security policies
• Dispute Resolution & Slashing — Handles Byzantine validator detection; node/core/disputes manages slash evidence and challenge mechanisms that keep Polkadot's economic security functioning
• Substrate Runtime FRAME (Framework for Runtime Aggregation of Modularized Entities) — The runtime/ crates use FRAME pallets (modules) to define chain logic; understanding pallet composition is required to modify Polkadot's on-chain rules

• paritytech/polkadot-sdk — The new unified monorepo officially replacing this repo; consolidates Polkadot, Substrate, and Cumulus into one codebase (this repo is now archived/deprecated)
• paritytech/substrate — Core blockchain framework that Polkadot node is built on; defines the runtime, RPC, and consensus primitives
• paritytech/cumulus — Parachain consensus and collation framework; used by parachains connecting to Polkadot relay chain (now merged into polkadot-sdk)
• w3f/polkadot-spec — Official Polkadot protocol specification; required reading for understanding consensus, validation, and message formats implemented here
• paritytech/ink — Smart contract language for parachains on Polkadot; developers building contracts need to understand how this node validates them via PVF

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 integration tests for polkadot-execute-worker and polkadot-prepare-worker binaries

The repo defines three binaries (polkadot, polkadot-execute-worker, polkadot-prepare-worker) but the file structure shows dev-dependencies with test tools (assert_cmd, tempfile, tokio) that aren't being fully utilized for binary integration testing. The worker binaries are critical PVF (Parachain Validation Function) components with no visible integration tests in the current structure. Adding tests would catch regressions in worker lifecycle, IPC communication, and process isolation.

• [ ] Create tests/execute_worker_integration_tests.rs with assert_cmd tests for polkadot-execute-worker binary startup, argument parsing, and signal handling
• [ ] Create tests/prepare_worker_integration_tests.rs with similar coverage for polkadot-prepare-worker
• [ ] Add test fixtures in tests/fixtures/ for sample PVF artifacts and test payloads
• [ ] Reference node/core/pvf/execute-worker and node/core/pvf/prepare-worker to understand expected behavior
• [ ] Document test execution in doc/testing.md with sections for worker binary tests

Add GitHub Actions workflow for checking PVF (Parachain Validation Function) security properties

The repo has extensive CI workflows (.github/workflows/) for labels, weights, licenses, and honggfuzz, but no dedicated security or correctness checks for the PVF subsystem despite it being a critical attack surface. The erasure-coding/ directory already has fuzzing infrastructure, and node/core/pvf/ is a core component. A new workflow could run fuzzing, check memory safety properties, and validate prepare/execute worker isolation.

• [ ] Create .github/workflows/pvf-security-checks.yml that runs on PRs affecting node/core/pvf/*
• [ ] Integrate erasure-coding/fuzzer/src/reconstruct.rs and round_trip.rs fuzzing targets into the workflow
• [ ] Add checks for unsafe code blocks in PVF paths using cargo-audit and cargo-geiger
• [ ] Run polkadot-node-core-pvf integration tests with sanitizers (miri/asan) enabled
• [ ] Reference SECURITY.md for context on PVF threat model and add security check documentation there

Refactor overseer initialization logic from cli/src/command.rs into dedicated module

Based on the file structure, cli/src/command.rs likely contains overseer instantiation code mixed with other CLI logic. The polkadot-overseer crate exists at node/overseer/ but is imported as a dependency. Extracting overseer initialization into cli/src/overseer/ would reduce command.rs complexity, improve testability of overseer configuration, and make feature flag handling (polkadot-native, kusama-native, westend-native, rococo-native) more maintainable.

• [ ] Create cli/src/overseer/mod.rs and cli/src/overseer/builder.rs to encapsulate OverseerBuilder and chain-specific configuration
• [ ] Move network, collation, approval, and validation subsystem initialization from cli/src/command.rs into the new module
• [ ] Extract chain-specific overseer configurations (kusama vs polkadot vs rococo) into separate functions in cli/src/overseer/chain_config.rs
• [ ] Add unit tests in cli/src/overseer/tests.rs covering subsystem initialization with different feature flag combinations
• [ ] Update cli/Cargo.toml if needed to reflect new module organization

• Add integration tests for CLI command parsing in cli/src/cli.rs. Currently only command.rs is tested; verify that all flag combinations for --chain, --validator, --pruning work correctly across Polkadot/Kusama/Rococo runtimes.: medium
• Document the overseer message-passing protocol in node/overseer/src/lib.rs with code examples. The subsystem orchestration is underdocumented; add rustdoc comments showing how a new subsystem (e.g., custom consensus) would integrate.: low
• Add benchmarking suite for PVF execution latency in node/core/pvf/. Currently no performance regression tests visible; create micro-benchmarks for execute-worker and prepare-worker stages using criterion or similar.: hard

The Polkadot codebase demonstrates a reasonable security posture with an established vulnerability disclosure process. However, there are notable concerns regarding dependency management practices: reliance on master branches instead of pinned versions, and potentially loose version constraints that could allow uncontrolled updates. The incomplete workspace configuration and outdated Rust version requirement warrant attention. Critical recommendation: migrate Substrate dependencies from 'master' branch to specific commits/tags, implement automated dependency security scanning in CI/CD, and update the MSRV. The project's consolidation into Polkadot SDK suggests active maintenance, which is a positive security indicator.

• Medium · Workspace Dependency on Master Branch — Cargo.toml - [dev-dependencies] and [build-dependencies]. Multiple dependencies are pinned to the 'master' branch of paritytech/substrate rather than stable versions. This introduces risk of unexpected breaking changes and unvetted code entering the build. Examples include substrate-build-script-utils and substrate-rpc-client dependencies. Fix: Pin dependencies to specific tagged versions or commits. Use rev instead of branch = "master" to ensure reproducible builds. Example: git = "https://github.com/paritytech/substrate", rev = "abc123def456"
• Medium · Missing Dependency Version Pinning — Cargo.toml - [dependencies]. Several dependencies use loose version constraints (e.g., color-eyre = "0.6.1", tikv-jemallocator = "0.5.0") which may allow patch version updates that could introduce vulnerabilities. The nix dependency uses features but lacks version specification in workspace config. Fix: Use exact versions (e.g., =0.6.1) for critical dependencies, or maintain a Cargo.lock file and audit transitive dependencies regularly with cargo audit.
• Low · Incomplete File Structure in Cargo.toml — Cargo.toml - [workspace] members. The workspace members list in Cargo.toml appears truncated ("runtime/comm" is incomplete), which could indicate incomplete configuration or version control issues. Fix: Complete the workspace members list and verify all intended workspace members are included. Run cargo metadata to validate workspace structure.
• Low · No Explicit Security Policy in Repository Root — .github/workflows/. While SECURITY.md exists with vulnerability disclosure guidelines, there is no explicit mention of security scanning in CI/CD workflows visible in the provided file list. The repository would benefit from automated security checks. Fix: Add automated security scanning to CI/CD pipeline using tools like cargo audit, cargo-deny, and dependabot (already present) to catch vulnerabilities early.
• Low · Rust Version Compatibility — Cargo.toml - [package]. The project specifies rust-version = "1.64.0" which is relatively old (from December 2022). Using outdated Rust versions may miss important security patches and compiler improvements. Fix: Update the minimum supported Rust version (MSRV) to a more recent stable version (1.70+) and document any compatibility reasons for the current MSRV. Regularly review and update this constraint.

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.