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/Chia-Network/chia-blockchain 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 the board

• Last commit today
• 13 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

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

What it runs against: a local clone of Chia-Network/chia-blockchain — 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 Chia-Network/chia-blockchain | 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 main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Chia-Network/chia-blockchain(\\.git)?\\b" \\
  && ok "origin remote is Chia-Network/chia-blockchain" \\
  || miss "origin remote is not Chia-Network/chia-blockchain (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 main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "chia/consensus/blockchain.py" \\
  && ok "chia/consensus/blockchain.py" \\
  || miss "missing critical file: chia/consensus/blockchain.py"
test -f "chia/full_node/full_node.py" \\
  && ok "chia/full_node/full_node.py" \\
  || miss "missing critical file: chia/full_node/full_node.py"
test -f "chia/wallet/wallet.py" \\
  && ok "chia/wallet/wallet.py" \\
  || miss "missing critical file: chia/wallet/wallet.py"
test -f "chia/mempool/mempool.py" \\
  && ok "chia/mempool/mempool.py" \\
  || miss "missing critical file: chia/mempool/mempool.py"
test -f "chia/types/blockchain_format/block.py" \\
  && ok "chia/types/blockchain_format/block.py" \\
  || miss "missing critical file: chia/types/blockchain_format/block.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 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
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/Chia-Network/chia-blockchain"
  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).

Chia is a complete blockchain implementation in Python providing a Proof of Space and Time (PoST) consensus mechanism that allows farmers to earn cryptocurrency using commodity hard drive storage. It includes a full node, farmer, harvester, timelord, wallet, and ChiaLisp (a Lisp-based smart contract language) runtime, enabling efficient decentralized consensus without energy-intensive proof-of-work mining. Monolithic Python package structure with functional service separation: chia/full_node/ handles blockchain consensus and chain state, chia/farmer/ coordinates proof-of-space generation, chia/harvester/ reads plot files on disk, chia/timelord/ runs proof-of-time via VDF, chia/wallet/ manages UTXO state and transactions, and chia/types/ defines core ChiaLisp AST and block structures. Networking uses chia/server/ for peer communication; .cursor/context/ provides architectural guidance for subsystems.

Cryptocurrency farmers and node operators running commodity hardware who want to participate in Chia consensus; blockchain developers building on ChiaLisp; infrastructure engineers deploying and maintaining Chia network nodes; contributors to the open-source blockchain ecosystem.

Chia is production-ready and actively maintained with mainnet consensus since 2021. The codebase shows extensive CI/CD pipelines (.github/workflows/ with 20+ automated checks), comprehensive test coverage (.coveragerc config present), and thousands of active nodes on mainnet. Recent activity in GitHub Actions (benchmarks, installers, dependency reviews) and structured .cursor/ documentation indicates ongoing active development and community engagement.

Standard open source risks apply.

Active work on installer distribution (build-linux-installer-deb.yml, build-macos-installers.yml, build-windows-installer.yml in workflows), dependency management via Dependabot, code quality via CodeQL analysis, and test coverage tracking (.diffcover.toml). The repository maintains multiple release channels (stable, RC, beta) with automated versioning and benchmarking pipelines.

git clone https://github.com/Chia-Network/chia-blockchain.git
cd chia-blockchain
python3 -m venv venv
source venv/bin/activate  # or .\venv\Scripts\activate on Windows
pip install -e .
chia init
chia start farmer

Daily commands:

# Requires Python 3.10+ installed and virtual environment activated
chia start farmer      # Start farmer with harvester
chia start full-node   # Start full node (blockchain sync)
chia start timelord    # Start timelord for VDF computation
chia wallet show       # Check wallet balance after sync

• chia/consensus/blockchain.py — Core blockchain state machine and consensus validation logic that all contributors must understand for any changes to block validation or chain management
• chia/full_node/full_node.py — Entry point for the full node service that orchestrates peer sync, mempool, and consensus; essential for understanding node startup and message routing
• chia/wallet/wallet.py — Main wallet state machine handling coin management, transaction creation, and state synchronization; critical for any wallet or coin-related changes
• chia/mempool/mempool.py — Transaction pool management with validation logic; all transaction-related features depend on understanding this component
• chia/types/blockchain_format/block.py — Block data structure definitions and serialization; foundational for all consensus, sync, and storage code
• .cursor/context/architecture-overview.md — High-level architectural documentation that provides the mental model for how components interact across the blockchain
• pyproject.toml — Project configuration and dependency manifest; required for setting up development environment and understanding the build system

Add a new consensus rule or validation

1. Define the new validation logic or consensus check in the appropriate method within the blockchain state machine (chia/consensus/blockchain.py)
2. Update blockchain constants if new rule requires parameter tuning (chia/consensus/constants.py)
3. Add condition parsing or validation in the condition tools if it involves CLVM output (chia/consensus/condition_tools.py)
4. Write integration tests in the consensus test suite to verify rule enforcement (tests/consensus/)

Add a new transaction fee tier or mempool policy

1. Update fee calculation and prioritization logic in the mempool validator (chia/mempool/mempool.py)
2. Add mempool inclusion status handling if new rejection reasons are needed (chia/types/mempool_inclusion_status.py)
3. Update full node message handlers to propagate new fee tier information (chia/full_node/full_node.py)
4. Add mempool tests to verify fee tier enforcement (tests/mempool/)

Add a new wallet feature (e.g., new coin type or spending pattern)

1. Create or update puzzle driver for the new coin type logic (chia/wallet/puzzle_drivers.py)
2. Update wallet state manager to handle new coin type in sync and balance tracking (chia/wallet/wallet_state_manager.py)
3. Add spend bundle construction logic in the main wallet (chia/wallet/wallet.py)
4. Write wallet integration tests for the new feature (tests/wallet/)

• Python — Cross-platform compatibility, rapid prototyping of consensus logic, and extensive cryptography library ecosystem (py-ecc, clvm)
• SQLite / asyncio databases — Lightweight persistence for blockchain state without operational overhead of external database servers
• CLVM (Chialisp Virtual Machine) — Enables programmable on-chain contracts while keeping transaction validation deterministic and fast
• Proof-of-Space consensus — Energy-efficient alternative to proof-of-work while maintaining decentralization and hard-to-forge proofs
• asyncio + aiohttp — Non-blocking I/O for handling many concurrent peers without spawning multiple threads or processes

• Full node validation of all blocks instead of light client mode

  • Why: Ensures security and enables participation in consensus without trusting third parties
  • Consequence: Requires storing full blockchain state (~10GB+), higher disk and memory usage, slower initial sync

• Synchronous block validation in the consensus path

  • Why: Avoids race conditions and ensures deterministic ordering of blocks
  • Consequence: Can become a bottleneck during high-throughput periods; limits transaction throughput

• UTXO-based coin model instead of account-based

  • Why: Better privacy properties, parallelizable validation, and matches Bitcoin security model
  • Consequence: More complex wallet logic for tracking coins; larger transaction sizes

• Mempool deduplication and fee-based prioritization

  • Why: Prevents spam and DoS by requiring economic cost to flood the network
  • Consequence: Transactions may be dropped if mempool fills; users must pay higher fees during congestion

• Does not implement sharding or layer-2 scaling at the protocol level
• Does not provide light client or SPV modes built into the core node
• Does not support private transactions or confidential amounts in base layer
• Does not provide deterministic ordering across the entire network (only per-block ordering)

ChiaLisp programs are compiled to bytecode and executed in an isolated VM (clvm) — modifying program evaluation affects all contract execution. VDF computation is sequential and cannot be parallelized; timelord performance bottlenecks the entire network's time. Plot files are generated offline and immutable once created; harvester must store them accessibly or farmer cannot propose blocks. Blockchain state is consensus-critical; any change to chia/consensus/ requires careful testing and network-wide upgrade coordination. Block timestamps rely on timelord VDF output, not system clocks. Networking uses custom protocol (not HTTP); see chia/server/ for peer message format.

• Proof of Space and Time (PoST) — This is Chia's entire consensus mechanism; understanding how plots generate proofs and how timelords verify them is essential to modifying any core consensus logic
• Verifiable Delay Function (VDF) — VDFs establish network time and prevent farmers from skipping blocks; they are computed sequentially by timelords and directly impact blockchain throughput
• ChiaLisp (Lisp-based smart contract language) — Chia's contract language; learning its syntax and semantics (clvm bytecode compilation, coin spend conditions) is mandatory for modifying transaction validation
• UTXO Model (Unspent Transaction Output) — Chia's transaction model; unlike Ethereum's account model, understanding coin lifecycle (creation → spend → burn) is critical for wallet and mempool logic
• Bloom Filters (for sidecar data filtering) — Used in chia/wallet/ to efficiently filter blocks without downloading all transaction data; enables light client syncing
• BLS Aggregate Signatures — Chia combines all farmer signatures into one per block; understanding signature aggregation is important for block validation and network efficiency
• Fork Resolution and Longest Chain Rule — When two valid chains compete, Chia uses work (plot bits) and time (VDF iterations) to resolve forks; this logic in chia/consensus/ is network-critical

• Chia-Network/clvm — Implements the ChiaLisp virtual machine (clvm) that Chia uses to execute smart contracts and validate transaction logic
• Chia-Network/clvm_rs — Rust implementation of clvm for performance-critical smart contract execution, often used in production nodes
• Chia-Network/chia-setup — Official setup and configuration tooling for Chia farmers and full nodes, referenced by installer workflows
• Chia-Network/pool-reference — Reference implementation of Chia's pooling protocol allowing farmers to contribute proof-of-space to mining pools
• cosmos/cosmos-sdk — Alternative modular blockchain framework; shows different approach to consensus, state, and smart contracts versus Chia's monolithic design

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 testing guide for CLVM execution and consensus modules

The repo has context documentation (.cursor/rules/context-clvm.mdc and context-consensus.mdc) but lacks a corresponding testing guide for these critical components. CLVM execution and consensus are core to blockchain validity. Adding testing-guide-clvm.mdc and expanding testing-guide-consensus.mdc would help contributors write tests for the most security-critical paths in the codebase, reducing bugs in core protocol logic.

• [ ] Review .cursor/rules/context-clvm.mdc and .cursor/rules/context-consensus.mdc to understand scope
• [ ] Examine existing testing guides in .cursor/rules/testing-guide-*.mdc for patterns and structure
• [ ] Create .cursor/rules/testing-guide-clvm.mdc covering CLVM instruction execution, optimization, and edge cases
• [ ] Create or expand testing-guide-consensus.mdc covering block validation, difficulty adjustment, and fork resolution tests
• [ ] Include specific file paths from chia/consensus/ and chia/types/ modules in examples

Add GitHub Actions workflow for dependency security scanning with cargo-audit and pip-audit

The repo has .github/workflows/dependency-review.yml but it appears to be a basic review. For a blockchain project handling cryptographic operations and user funds, a dedicated security-focused workflow running cargo-audit (for Rust dependencies in timelord) and pip-audit (for Python dependencies) on every PR would catch vulnerable dependencies early. This is especially critical given the npm_linux config with electron-builder.

• [ ] Check if cargo-audit is already integrated in .github/workflows/test.yml or other workflows
• [ ] Check if pip-audit is already integrated for Python dependency security
• [ ] Create .github/workflows/security-audit.yml that runs on: [pull_request, schedule]
• [ ] Configure pip-audit to scan chia/ module dependencies and fail on high/critical vulnerabilities
• [ ] Configure cargo-audit for any Rust components (timelord) mentioned in BUILD_TIMELORD.md
• [ ] Add job to lint npm dependencies (electron-builder usage in .github/actions/install/) with npm-audit

Add integration tests for networking layer with protocol handshake validation

The repo has .cursor/rules/context-networking.mdc and .cursor/rules/context-routing.mdc context docs but only .cursor/rules/testing-guide-server.mdc for testing. Network security is critical for P2P blockchain systems. Missing are integration tests validating the networking handshake, peer authentication, message routing, and connection state management - vulnerabilities here could lead to eclipse attacks or network partitions.

• [ ] Review .cursor/rules/context-networking.mdc and context-routing.mdc to identify protocol stages
• [ ] Create .cursor/rules/testing-guide-networking.mdc with sections for: handshake validation, peer discovery, message routing, connection timeouts
• [ ] Add tests in chia/server/server.py test suite for: successful peer connection, invalid protocol versions, malformed handshakes
• [ ] Add tests for message routing in chia/protocols/ to verify correct peer routing under Byzantine conditions
• [ ] Reference existing patterns from testing-guide-server.mdc and use asyncio test fixtures consistently

• Add type hints to chia/mempool/mempool.py and chia/mempool/mempool_item.py to improve mypy coverage and catch potential transaction validation bugs early.
• Extend .cursor/rules/testing-guide-*.mdc documentation with 3-5 concrete integration test examples showing full_node + wallet + farmer interaction flows.
• Write snapshot tests for ChiaLisp program deserialization in chia/types/blockchain_format/ to catch bytecode format regressions before mainnet deployment.

The Chia blockchain repository shows moderate security posture. The primary concern is dependency management - specifically electron-builder as a critical build dependency that requires ongoing maintenance and monitoring. The security update policy is restrictive, supporting only the latest minor version. No obvious hardcoded secrets were detected in the file structure, but documentation on secrets management for cryptographic material could be stronger. The presence of comprehensive documentation and GitHub workflows for testing and code quality indicates a mature development process. Key recommendations: (1) Implement continuous dependency scanning and automated security updates, (2) Extend security support to N-1 version, (3) Add explicit secrets management documentation, and (4) Document networking security configurations. The blockchain's critical nature (handling consensus and transactions) makes ongoing security monitoring essential.

• Medium · Outdated electron-builder Dependency — package.json - dependencies.electron-builder. The npm package.json specifies 'electron-builder': '^26.7.0'. While this version constraint allows updates, electron-builder has had multiple security vulnerabilities in the past. The caret (^) allows minor and patch updates but may not capture all security patches if major version updates are available. Electron-builder is used for building installers on multiple platforms (Linux deb/rpm, macOS, Windows), making it a critical build dependency. Fix: 1) Regularly audit dependencies using 'npm audit' and 'npm audit fix'. 2) Consider using exact version pinning for build tools instead of version ranges. 3) Implement automated dependency scanning in CI/CD pipelines. 4) Monitor security advisories for electron-builder releases and update promptly.
• Low · Limited Security Update Support Window — SECURITY.md - Supported Versions table. SECURITY.md indicates that only version 2.1.x is currently supported with security updates, while all versions up to 2.0.x are marked as unsupported. This creates a scenario where users on slightly older versions (2.0.x) receive no security patches despite potentially being deployed in production environments. Fix: 1) Consider maintaining overlapping support windows (e.g., current and previous major version). 2) Document clear end-of-life dates for versions. 3) Provide migration guides for users on unsupported versions. 4) Consider extended support tier for critical security issues on N-1 versions.
• Low · Missing .env and Secrets Management Documentation — Repository root - missing .env.example or SECRETS.md. While no hardcoded secrets are immediately visible in the file listing, there is no evidence of documented secrets management practices or .env.example files. A blockchain implementation handling cryptographic keys and network credentials should have explicit guidance on secure credential handling. Fix: 1) Create .env.example with placeholders for all required configuration. 2) Add documentation on proper secrets management (environment variables, key files, hardware wallets). 3) Implement pre-commit hooks to prevent secrets from being committed. 4) Use tools like 'detect-secrets' in CI/CD pipeline.
• Low · No Visible Security Headers Configuration — Repository structure - networking/infrastructure configuration. No obvious security configuration files are present for the networking layer (no nginx.conf, security.conf, or CORS configuration visible). Given this is a blockchain full node with networking components, security headers and CORS policies are important. Fix: 1) Document all security headers used in network communication. 2) Implement explicit CORS policies. 3) Add rate limiting and DDoS protection documentation. 4) Include TLS/SSL configuration examples for node operators.

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.