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/btcsuite/btcd 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 1d ago
• 13 active contributors
• Distributed ownership (top contributor 37% of recent commits)
• ISC 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 btcsuite/btcd repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/btcsuite/btcd.

What it runs against: a local clone of btcsuite/btcd — 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 btcsuite/btcd | Confirms the artifact applies here, not a fork | | 2 | License is still ISC | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(ISC)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"ISC\"" package.json 2>/dev/null) \\
  && ok "license is ISC" \\
  || miss "license drift — was ISC 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 "blockchain/chain.go" \\
  && ok "blockchain/chain.go" \\
  || miss "missing critical file: blockchain/chain.go"
test -f "blockchain/accept.go" \\
  && ok "blockchain/accept.go" \\
  || miss "missing critical file: blockchain/accept.go"
test -f "blockchain/validate.go" \\
  && ok "blockchain/validate.go" \\
  || miss "missing critical file: blockchain/validate.go"
test -f "blockchain/utxoviewpoint.go" \\
  && ok "blockchain/utxoviewpoint.go" \\
  || miss "missing critical file: blockchain/utxoviewpoint.go"
test -f "addrmgr/addrmanager.go" \\
  && ok "addrmgr/addrmanager.go" \\
  || miss "missing critical file: addrmgr/addrmanager.go"

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

btcd is a production-grade Bitcoin full node implementation written in Go that downloads, validates, and serves the entire blockchain using Bitcoin Core's exact consensus rules (including its bugs). It maintains a transaction mempool, relays blocks and transactions, and validates them against the full rule set—but deliberately excludes wallet functionality, making it a pure node implementation suitable for infrastructure rather than direct payments. Modular monorepo architecture: top-level packages handle distinct concerns (addrmgr/ manages peer addresses, blockchain/ handles chain validation and storage, txscript/ implements script evaluation, wire/ handles protocol messages, rpcclient/ exposes RPC). The blockchain package is the core validator with accept.go processing blocks, chainio.go managing persistent state, and fullblocktests/ containing 500+ consensus test vectors run on every commit.

Bitcoin infrastructure operators, node runners, and developers building services that need a robust, independently-implemented full node in Go; also blockchain researchers and btcsuite ecosystem contributors who need an alternative consensus implementation to Bitcoin Core for validation, testing, or redundancy.

Production-ready and actively maintained: btcd has been stable in production since October 2013, passes full block validation test suites on every PR, and achieves continuous integration with GitHub Actions. The codebase is large (~6.2MB Go code), well-structured with clear package separation (blockchain, addrmgr, txscript, etc.), and recent activity is visible through the workflows and test coverage infrastructure.

Low structural risk but high responsibility: the codebase is consensus-critical (a fork or divergence breaks the network), so any modification requires extreme care and extensive testing via the fullblocks_test framework. Dependencies are limited but core ones like secp256k1 (decred/dcrd) are external; the single-maintainer risk is mitigated by the btcsuite organization, but any breaking Bitcoin protocol changes must be carefully tracked and integrated.

Active maintenance focused on consensus correctness and Go version support: recent work targets Go 1.22+, the CI pipeline (main.yml) runs on every push, and the full block test suite is continuously expanded. No specific major features are visible in the file list, suggesting the focus is stability, performance, and staying synchronized with Bitcoin Core consensus rule changes.

Clone and build with Go 1.22+:

git clone https://github.com/btcsuite/btcd.git
cd btcd
go install ./cmd/btcd
go install ./cmd/btcctl

Then run: btcd (starts syncing the blockchain to ~/.btcd/ on mainnet by default).

Daily commands: Start the node: btcd (syncs mainnet to ~/.btcd/ by default). Control it via RPC: btcctl --help (connects to localhost:8334 by default). Run tests: go test ./... or per-package (e.g., cd blockchain && go test). CI runs: see .github/workflows/main.yml for the full test pipeline.

• blockchain/chain.go — Core blockchain chain management and validation logic; essential for understanding block acceptance and chain state.
• blockchain/accept.go — Block acceptance validation pipeline implementing Bitcoin consensus rules; critical for preventing chain forks.
• blockchain/validate.go — Script validation and transaction validation implementation; load-bearing for consensus correctness.
• blockchain/utxoviewpoint.go — UTXO set management and view; central to transaction validation and state integrity.
• addrmgr/addrmanager.go — Bitcoin peer address discovery and management; essential for network connectivity and node bootstrap.
• blockchain/blockindex.go — Block header indexing and lookup; critical for chain navigation and reorganization handling.

Add a new consensus validation rule

1. Implement validation logic for the new rule (e.g., check transaction field or script operation) (blockchain/validate.go)
2. Integrate the new validation into the block acceptance pipeline (blockchain/accept.go)
3. Add activation logic using version bits soft-fork mechanism if rule is optional (blockchain/versionbits.go)
4. Add test vectors to the test suite and verify against official block tests (blockchain/fullblocktests/generate.go)

Add a new blockchain indexer

1. Create new indexer file in blockchain/indexers/ implementing the indexer interface (blockchain/indexers/manager.go)
2. Register indexer with the manager and implement OnBlockConnected/OnBlockDisconnected callbacks (blockchain/indexers/manager.go)
3. Store indexed data using the database backend via chainio interface (blockchain/chainio.go)
4. Write tests validating index consistency across chain reorganizations (blockchain/indexers/addrindex_test.go)

Improve peer discovery and connection strategy

1. Modify peer address bucketing and selection logic in address manager (addrmgr/addrmanager.go)
2. Update reliability scoring for peer quality assessment (addrmgr/knownaddress.go)
3. Adjust network classification if targeting specific networks (IPv4, IPv6, Tor, etc.) (addrmgr/network.go)
4. Add tests for peer selection distribution and bootstrap scenarios (addrmgr/addrmanager_test.go)

Optimize UTXO set performance

1. Analyze current UTXO caching strategy and access patterns (blockchain/utxocache.go)
2. Modify cache eviction policy or size thresholds if bottleneck identified (blockchain/utxocache.go)
3. Update utxoviewpoint to leverage cache more aggressively (blockchain/utxoviewpoint.go)
4. Benchmark impact on block validation throughput (blockchain/bench_test.go)

• Go (golang) — Compiled performance for consensus-critical path; lightweight goroutines for concurrent peer management and block validation; strong standard library for networking and cryptography
• btcsuite/btcd/chaincfg (config package) — Network-agnostic chain parameters (mainnet, testnet, regtest); enables single binary to run on multiple Bitcoin networks
• secp256k1 ECDSA (decred/dcrd) — Bitcoin's signature algorithm; decred implementation provides audited Go bindings to C library for performance
• Leveldb-style key-value database — Efficient block storage and chainstate persistence; supports fast range queries for block index and UTXO operations

• Full blockchain validation from genesis block on startup

  • Why: Ensures node never accepts invalid blockchain state; prevents consensus forks due to bugs in earlier validation
  • Consequence: Slow initial sync (hours to days); high CPU/disk I/O during IBD; mitigated by checkpoints and parallel validation

• UTXO cache with bounded memory

  • Why: Balance memory usage against block validation speed; avoids loading entire UTXO set into RAM
  • Consequence: Cache misses trigger database lookups; potential performance cliff if working set exceeds cache size

• Orphan block pool with memory limits

  • Why: Prevent DoS from peers sending many valid but disconnected blocks
  • Consequence: May need to re-request blocks during reorgs; limits reorg depth to ~500 blocks

• Optional indexers (address index, tx index, compact filters)

  • Why: Allow operators to trade disk space for query performance; not all nodes need all indexes
  • Consequence: Multiple data structures to keep in sync; adds complexity to chain reorganization logic

• Mining pool implementation (does not include stratum protocol or work distribution)
• Wallet management (focuses on node validation; separate btcwallet project handles keys/spending)
• RPC API completeness (implements core subset; not meant to be drop-in bitcoind replacement for all use cases)
• Layer 2 protocols (does not validate Lightning Channel updates or sidechains)
• Privacy enhancements (does not implement coin mixing, stealth addresses, or Taproot privacy features beyond consensus rules)

Consensus-critical code must not diverge from Bitcoin Core: subtle bugs in accept.go or txscript/ silently fork the network with no error message—the fullblocks_test suite is your only defense, so always run it. Chain state is versioned in chainio.go; upgrading btcd can trigger database migrations that are one-way. RPC is opt-in (not enabled by default); you must set --rpclisten and credentials (user/pass in btcd.conf). Testnet/regtest modes exist but require different network parameters (chaincfg/); using wrong ones silently produces invalid-to-mainnet blocks. The code uses secp256k1 from decred/dcrd, not btcd's own btcec fork—ensure crypto libraries match.

• Consensus Rule Validation — btcd's core mission is to validate blocks against exact Bitcoin Core rules (including bugs); understanding how accept.go enforces these rules is critical to any modification
• Bitcoin Script (BTC Script) — txscript/ implements the stack-based scripting language that authorizes all Bitcoin transactions; consensus bugs in script evaluation cause network forks
• UTXO (Unspent Transaction Output) Model — Bitcoin's state model differs fundamentally from account-based systems; btcd's chainstate tracks UTXOs, not balances, and this architecture pervades blockchain/chainio.go and accept.go
• Merkle Tree Block Verification — blockchain/blockindex.go and accept.go verify block headers and merkle roots; understanding tree hashing is essential for grasp block integrity validation
• Peer Discovery and Address Management — addrmgr/ implements Bitcoin's gossip-based peer discovery and reputation system; critical for node bootstrapping and resilience against sybil attacks
• Difficulty Adjustment (Proof of Work) — blockchain/difficulty.go recalculates mining difficulty every 2 weeks; subtle bugs here cause consensus forks or allow invalid chains
• Transaction Mempool and Fee Estimation — btcd maintains a transaction pool (mempool) and validates against miner-defined 'standard' rules; this filters spam and prioritizes transactions by fee without enforcing consensus

• btcsuite/btcwallet — Official companion wallet implementation for btcd that handles key management and transaction creation; btcd cannot create/receive payments directly
• btcsuite/btcutil — Shared utility library across btcsuite providing address encoding, transaction helpers, and bitcoin-specific primitives used by btcd
• bitcoin/bitcoin — Bitcoin Core reference implementation in C++; btcd must match its consensus rules exactly to avoid forking the network
• btcsuite/btcec — btcsuite's elliptic curve cryptography library (though btcd currently uses decred/dcrd/dcrec/secp256k1); historically the native btcd crypto layer
• lightningnetwork/lnd — Lightning Network daemon that can run on top of btcd as its consensus layer via RPC, demonstrating btcd's role in the broader Bitcoin ecosystem

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 integration tests for blockchain/indexers package

The blockchain/indexers directory contains critical components (addrindex.go, cfindex.go, txindex.go) but lacks integration tests that verify indexer behavior across multiple blocks and chain reorganizations. This is a high-value contribution as indexers are essential for wallet and filtering operations. The existing *_test.go files appear to be unit tests only. New tests should verify consistency between different indexer types during chain forks and verify query accuracy.

• [ ] Review blockchain/indexers/addrindex_test.go and blockchain/indexers/txindex.go for existing test coverage gaps
• [ ] Create blockchain/indexers/integration_test.go with tests for: (1) concurrent indexing during fast block sync, (2) indexer consistency after chain reorg, (3) query correctness after partial index rebuilds
• [ ] Add test cases that use blockchain/fullblocktests test data to verify indexer behavior against real block scenarios
• [ ] Run coverage tools to ensure new tests achieve >80% line coverage for manager.go and common.go

Add GitHub Actions workflow for security-focused Go vulnerability scanning

While .github/workflows/main.yml exists for basic CI, there is no dedicated security scanning workflow. Given btcd's role as a production Bitcoin node (used since 2013), a specific GitHub Actions job for detecting vulnerable dependencies and code issues would be valuable. This should use Go's native go list -json -m all | nancy sleuth or similar tools to check for CVEs in dependencies like decred/dcrd and other critical packages listed in go.mod files.

• [ ] Review .github/workflows/main.yml to understand current test matrix
• [ ] Create .github/workflows/security.yml with: (1) nancy or trivy vulnerability scanning on all modules in btcd/*, (2) govulncheck scanning (Go 1.18+ native tool), (3) golangci-lint with security-focused config from .golangci.yml
• [ ] Configure workflow to run on PRs and scheduled daily to catch transitive dependency vulnerabilities
• [ ] Add badge to README.md similar to existing Build Status and Coverage badges

Add missing unit tests for blockchain/internal/workmath package

The blockchain/internal/workmath directory exists with a README.md but appears in the file structure without accompanying *_test.go files visible in the partial listing. Difficulty calculations and work verification are consensus-critical code paths. This package likely contains functions for PoW validation that must be exhaustively tested, including edge cases around difficulty retargeting and overflow conditions.

• [ ] Examine blockchain/internal/workmath source files (README suggests calculation utilities exist)
• [ ] Create blockchain/internal/workmath/workmath_test.go with test cases for: (1) difficulty calculations against known Bitcoin test vectors, (2) integer overflow scenarios, (3) boundary conditions for retargeting periods
• [ ] Add tests comparing calculations against Bitcoin Core's reference implementation using values from blockchain/fullblocktests
• [ ] Ensure test coverage matches or exceeds coverage in blockchain/internal/testhelper package

• Add missing unit tests to addrmgr/knownaddress.go for edge cases in address eviction and retention logic (the file exists but test coverage is incomplete per the test_coverage.txt marker)
• Expand blockchain/compress.go test coverage for ultra-large block compression scenarios—the file handles block serialization but compress_test.go only covers common cases
• Document the full block test vector format and how to add custom consensus tests to blockchain/fullblocktests/—currently no README explains the vector structure or how contributors can add regression tests for consensus bugs they discover

The btcd codebase demonstrates generally good security practices with proper use of Go dependency management, documented security policy, and signed Docker images. The primary concern is a truncated Docker image SHA256 digest which needs immediate correction. The project maintains an active security reporting mechanism and uses a modern Go version. Indirect dependencies are properly tracked. Recommendations focus on completing the Docker configuration, enhancing the security policy documentation, and implementing regular dependency audits. No injection vulnerabilities, hardcoded secrets, or critical misconfigurations were identified in the provided file structure.

• Medium · Incomplete Docker Image SHA256 Digest — Dockerfile, line ~25. The Dockerfile specifies a golang base image with a SHA256 digest that appears truncated (ends with '264' instead of a complete hash). This could result in pulling an unintended image version or causing build failures. The digest should be the full SHA256 hash. Fix: Complete the SHA256 digest to the full 64-character hash. The commented example shows the correct format: sha256:4bb4be21ac98da06bc26437ee870c4973f8039f13e9a1a36971b4517632b0fc6
• Low · Overly Permissive Go Version Requirement — btcec/v2/go.mod. The go.mod file specifies 'go 1.22' without an upper bound. While Go maintains strong backward compatibility, this could potentially allow compilation with future major versions that introduce breaking changes or security issues specific to btcd's use cases. Fix: Consider adding comments documenting tested Go versions and establish a testing policy for new Go releases before deployment.
• Low · Security Policy Relies on External Email — SECURITY.md. The SECURITY.md file directs vulnerability reports to security@lightning.engineering. While this is a reasonable approach, there is no documented SLA for response times, no confirmation mechanism, or alternative reporting methods documented. Fix: Enhance the security policy with: (1) Expected response timeframes, (2) Confirmation that reports are received, (3) Alternative contact methods or a form-based submission system, (4) Information about the disclosure process and timeline.
• Low · Limited Dependency Pinning Information — btcec/v2/go.mod, indirect dependencies section. While the go.mod uses specific versions for direct dependencies, indirect dependencies (marked with '// indirect') are included but may not be regularly audited. The 'gopkg.in/yaml.v3' transitive dependency could warrant additional scrutiny. Fix: Implement a dependency audit process using 'go list -u -m all' and 'go mod audit' regularly. Consider using tools like Nancy or Snyk to identify vulnerable dependencies.

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.