GO — Healthy across the board

• Last commit 2d ago
• 6 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

Lightning Network Daemon (lnd) is a complete, production-grade implementation of a Lightning Network node written in Go. It enables fast, off-chain Bitcoin payments by managing payment channels, routing packets through the network, and maintaining a validated channel graph—all while conforming fully to the Lightning Rfc (BOLTs 1-11). lnd supports multiple blockchain backends (btcd, bitcoind, neutrino) and includes features like automated channel management via autopilot. Monorepo structure: the root contains core daemon code (accessman.go, main daemon logic), with isolated reusable libraries in subdirectories. The actor/ subdirectory (with its own go.mod) implements a mailbox-based actor system for concurrency (backpressure_mailbox.go, func_actor.go). Supporting packages like fn/ (functional utilities), queue/, and ticker/ are vendored via replace directives in go.mod. CLI and RPC interfaces wrap the core daemon.

Bitcoin/Lightning developers and node operators who need to run a Lightning Network node, accept fast payments without on-chain delays, forward payments across the network, or build Lightning-native applications. Contributors are typically blockchain engineers, protocol implementers, and infrastructure maintainers.

Production-ready and actively maintained. The project is mature with comprehensive BOLT compliance, extensive test coverage across core modules (see actor/, accessman_test.go), multiple CI workflows (.github/workflows/), and a large Go codebase (20.7M lines). Regular releases and active development are evident from versioning and GitHub actions infrastructure.

Standard open source risks apply.

Recent work includes GitHub Actions workflows for automated verification (claude-dedupe-issues.yml, pr-severity.yml, verify-release.yaml), Dockerfile support for containerization, and linting/style enforcement (.golangci.yml, .protolint.yaml). The codebase is actively integrating CI/CD practices and preparing releases (workflows/release.yaml). Actor subsystem (actor/) appears to be a newer pattern for managing concurrent operations.

git clone https://github.com/lightningnetwork/lnd.git
cd lnd
make

The Makefile is the primary build tool. Check Makefile for exact targets. Dependencies are managed via Go modules; ensure Go 1.25.5+ is installed (from go.mod).

Daily commands:

make build
./lnd  # Run the daemon

For development: make test runs the test suite. See Makefile for other targets (lint, docker, release-build). The daemon listens for gRPC connections by default.

• actor/actor.go — Core actor model implementation—foundational abstraction for concurrent message-passing patterns used throughout lnd's async communication.
• actor/system.go — Actor system lifecycle and supervision—critical for understanding how lnd manages goroutine pools, mailboxes, and fault tolerance.
• aezeed/cipherseed.go — Seed cipher implementation for wallet recovery—load-bearing crypto for lnd's mnemonic generation and key derivation.
• batch/batch.go — Batch operation coordinator—essential for batching blockchain operations and optimizing transaction throughput.
• autopilot/agent.go — Autopilot channel management engine—implements channel opening heuristics and capital allocation strategies.
• Makefile — Build orchestration and dependency management—entry point for compilation, testing, and deployment workflows.
• actor/mailbox.go — Message queue implementation for actors—handles backpressure and delivery semantics for async task processing.

Add a new Autopilot attachment strategy

1. Create new file in autopilot/ directory implementing AttachmentHeuristic interface (autopilot/myattach.go)
2. Implement Score(graph, nodeID) float64 method that ranks channel targets (autopilot/myattach.go)
3. Register in agent via CombinedAttachmentHeuristic in agent.go (autopilot/agent.go)
4. Add unit tests using graph fixtures and centrality test data (autopilot/myattach_test.go)

Add a new Actor-based subsystem

1. Create a struct implementing actor.Actor interface with Receive(ctx, from, msg) method (yoursubsystem/actor.go)
2. Use actor.Spawn(ctx, system) to register with ActorSystem (yoursubsystem/actor.go)
3. Send messages via actor.Tell() or ask() with timeout for request-reply (yoursubsystem/caller.go)
4. Write property-based tests using rapid package for message sequences (yoursubsystem/actor_test.go)

Add cryptographic seed operations

1. Implement new CipherSeed method or variant using aezeed primitives (aezeed/cipherseed.go)
2. Add KDF parameters and cipher selection logic matching AEZEED spec (aezeed/cipherseed.go)
3. Add test vectors from BIP32/SLIP39 specs (aezeed/cipherseed_test.go)
4. Run integration test with hardware wallets via cipherseed_integration.go (aezeed/cipherseed_integration.go)

Add batch operation type

1. Define batch operation struct in batch/batch.go with Apply/Rollback methods (batch/batch.go)
2. Register operation type in scheduler for coalescing with similar ops (batch/scheduler.go)
3. Write test asserting atomicity and failure recovery (batch/batch_test.go)

• Actor model (actor/) — Scalable concurrency without explicit locks; mailbox-based backpressure prevents goroutine explosion in high-load scenarios (thousands of peers)
• AEZEED (aezeed/) — BIP39-compatible deterministic seed generation with Argon2 KDF; enables hardware wallet recovery and cold storage compatibility
• Batch operations (batch/) — Amortizes blockchain I/O cost; reduces fee overhead by grouping channel opens, closing, and state updates into single transactions
• Graph topology analysis (autopilot/) — Centrality metrics guide capital allocation to high-value nodes, improving payment success rates and network utility
• Protobuf RPC (implied .proto files) — Language-neutral, versioned API for peers and clients; efficient binary serialization for high-throughput message passing

• Actor model over traditional thread pools

  • Why: Simpler mental model for message-driven systems; avoids mutex deadlocks and race conditions in complex state machines
  • Consequence: Added abstraction layer; requires familiarity with mailbox patterns and potential GC pressure if actors spawn unbounded

• Autopilot's off-chain heuristics over on-chain voting

  • Why: Fast, responsive channel creation without blockchain latency; low operational cost
  • Consequence: Cannot enforce global consensus; nodes may make suboptimal choices if heuristics diverge from network reality

• Block cache over full block fetch

  • Why: Reduces latency for recent headers and mempool queries; lower bandwidth
  • Consequence: Cache misses require fallback to full block fetch; not suitable for deep reorg detection

• Macaroon-based access control

  • Why: Fine-grained capabilities without centralized key server; portable and composable
  • Consequence: Requires careful caveat design; leakage of macaroon grants access to all capabilities until revocation

• Does not implement consensus layer; assumes Bitcoin blockchain finality
• Not a Bitcoin full node (relies on external chain service: btcd, bitcoind, or neutrino)
• Does not provide custodial wallet UI (lnd is daemon-only; clients build their own interfaces)
• Not a real-time order book or exchange; only routes payments based on network topology and channel liquidity

1. Actor system learning curve: the actor/ package uses futures and mailboxes; unfamiliar patterns from Go's goroutine idiom—study actor/example_*.go before modifying core concurrency. 2. Vendored modules: actor/, fn/, queue/, ticker/ use replace directives in go.mod; editing them requires rebuilding both the submodule and the parent. 3. BOLT compliance: channel state and payment forwarding logic must conform strictly to Lightning RFCs; casual changes can break consensus with the network. 4. Blockchain backend coupling: code assumes btcsuite library interfaces; swapping backends or updating btcd/bitcoind versions may require cascading changes. 5. Proto regeneration: if .proto files change, you must regenerate Go code (protoc tooling required, not in go.mod).

• Actor Model (Mailbox Pattern) — lnd's concurrency model relies on actors with mailboxes and backpressure; understanding this pattern (in actor/ package) is critical to modifying request/response handling without race conditions or deadlocks
• Lightning Network Channels — The entire purpose of lnd is channel creation, state management, and routing; channels are stateful, fund-locking constructs that require understanding BOLT-2 protocol
• Onion Routing — Multi-hop payment forwarding in lnd uses encrypted onion packets to hide route information; BOLT-4 compliance requires careful cryptographic handling
• Bitcoin Transaction Script & UTXO Model — Channel commitment transactions and on-chain settlement require deep knowledge of Bitcoin's UTXO model and script opcodes; lnd encodes channel state in transactions
• Path Finding & Graph Routing — lnd maintains and searches the channel graph to route payments optimally; the graph's accuracy and freshness directly impact payment success rates and fees
• gRPC & Protobuf Services — lnd exposes its daemon functionality via gRPC endpoints defined in .proto files; understanding proto-to-Go code generation is necessary for API modifications
• Property-Based Testing (Rapid) — lnd uses pgregory.net/rapid for property-based testing in actor and other critical systems; this finds edge cases that unit tests miss

• btcsuite/btcd — Full Bitcoin node implementation and primary blockchain backend for lnd; understanding btcd's chain APIs is essential for lnd's backend integration
• lightninglabs/neutrino — Lightweight Bitcoin light client backend option for lnd; allows running Lightning nodes without full blockchain sync
• lightningnetwork/lightning-rfc — BOLT specification documents that lnd implements; reference for protocol compliance and channel state machine rules
• lightninglabs/loop — Companion tool for submarine swaps and channel liquidity management; uses lnd as its underlying Lightning node
• lightninglabs/taproot-assets — Asset issuance and transfer layer built on top of lnd; demonstrates advanced use of Lightning channels for non-BTC assets

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 actor system with real mailbox scenarios

The actor module has unit tests (actor_test.go, mailbox_test.go, system_test.go) and example-based tests, but lacks integration tests covering edge cases like backpressure handling under sustained load, concurrent router operations, and future timeout scenarios. The backpressure_mailbox implementation deserves integration tests with real-world message patterns to ensure reliability in production lightning network operations.

• [ ] Create actor/integration_test.go with tests for concurrent actor communication patterns
• [ ] Add stress tests for backpressure_mailbox under high message volume (reference actor/backpressure_mailbox.go and actor/backpressure_mailbox_test.go)
• [ ] Test router.go with multiple concurrent subscribers and failure scenarios
• [ ] Add benchmarks comparing throughput with/without backpressure enabled
• [ ] Document expected performance characteristics in actor/README.md

Add missing unit tests for accessman.go access control manager

accessman.go is a core access management component but has no corresponding test coverage visible in the file structure (accessman_test.go exists but likely needs expansion based on typical LND security patterns). Given that access management is critical for lightning node security, comprehensive tests for permission checks, role-based access control, and concurrent access patterns are essential.

• [ ] Expand accessman_test.go to cover all public methods in accessman.go
• [ ] Add table-driven tests for permission validation scenarios with different access levels
• [ ] Test concurrent access patterns to ensure thread-safety of permission checks
• [ ] Add negative test cases for denied access attempts and permission escalation attempts
• [ ] Verify test coverage reaches >95% using 'go test -cover ./...'

Create GitHub Action workflow to validate local module replace directives and detect version conflicts

The actor/go.mod uses multiple local replace directives (queue, ticker, fn) which are prone to version drift issues when modules are updated independently. A new CI workflow should validate that all replace directives point to valid paths, that versions match across the monorepo, and that builds succeed with and without replace directives to catch integration issues early.

• [ ] Create .github/workflows/module-validation.yml workflow
• [ ] Add script to verify all 'replace' directives in go.mod files point to existing directories
• [ ] Add validation that version constraints in replace directives match the actual module versions in ../queue, ../ticker, ../fn
• [ ] Run 'go mod tidy' and 'go mod graph' in the workflow to detect cycles or conflicts
• [ ] Add step to verify builds work for actor module and dependent modules together

• Add comprehensive test coverage for accessman.go: the file exists but no corresponding accessman_test.go is visible in the file list for all public functions; write unit tests for permission checks and error cases.
• Document the actor system with a tutorial: actor/README.md exists but lacks practical examples beyond actor/example_*.go files; add a 'Getting Started' guide for developers unfamiliar with mailbox-based concurrency patterns.
• Improve Dockerfile optimization: the Dockerfile exists but is listed without specifics; review multi-stage build, layer caching, and add comments documenting which builder stages are for which backends (btcd vs bitcoind vs neutrino).

The lnd Lightning Network Daemon codebase demonstrates generally good security practices with active maintenance, proper vulnerability reporting channels, and reasonable dependency management. However, several areas could be improved: (1) Container security scanning should be integrated into CI/CD pipelines, (2) dependency management could be more rigorous with automated scanning for known vulnerabilities, (3) Git-based artifact retrieval could use stronger authentication mechanisms, and (4) dependency versions should be regularly audited and consolidated. The codebase lacks evidence of SAST/DAST security testing in visible workflows. Overall security posture is solid for a production cryptocurrency/financial infrastructure project, but continuous security improvements are recommended.

• Medium · Outdated Go Version in Dockerfile — Dockerfile, line 4. The Dockerfile uses Go 1.25.5, which may contain known vulnerabilities. While this is a relatively recent version, it's important to ensure the Go runtime is regularly updated to patch security issues in the standard library and tooling. Fix: Regularly monitor Go security advisories and update to the latest stable Go version. Consider implementing automated dependency updates via Dependabot or similar tools.
• Medium · Potential Dependency Supply Chain Risk — actor/go.mod, replace directives. The go.mod file contains multiple local replace directives (../queue, ../ticker, ../fn) which create local module dependencies. While this is a valid monorepo pattern, it increases the risk surface if any of these local modules are compromised or contain vulnerabilities. Fix: Ensure all local modules are regularly audited and maintain strict access controls on the repository. Consider using vendoring or checksum verification for critical dependencies.
• Low · Alpine-based Docker Image Without Security Scanning — Dockerfile, FROM statements. While Alpine Linux is lightweight, the Dockerfile does not include any security scanning or vulnerability checks in the build pipeline. The base image should be regularly scanned for vulnerabilities. Fix: Implement container image scanning in the CI/CD pipeline using tools like Trivy, Snyk, or similar. Add security scanning to the GitHub Actions workflows.
• Low · Git Clone from Unauthenticated Source — Dockerfile, line 13. The Dockerfile clones from a Git URL using HTTP by default (via ARG git_url). While GitHub is generally trusted, this could be vulnerable to MITM attacks if used on untrusted networks or with private Git servers. Fix: Consider using SSH-based Git URLs or HTTPS with credential verification. Add checksum verification for cloned code when possible.
• Low · Missing Security Headers in Documentation — SECURITY.md. While the SECURITY.md file provides a vulnerability reporting process, it could be enhanced with additional security best practices, dependency vulnerability disclosure, and security incident response procedures. Fix: Expand SECURITY.md to include: bug bounty program details, security update procedures, CVE disclosure timeline, and links to security advisories.
• Low · Indirect Dependency on Older btclog Version — actor/go.mod, dependencies. The actor/go.mod has both btclog/v2 v2.0.1 and an indirect dependency on btclog v0.0.0-20241003133417-09c4e92e319c. This version mismatch could indicate unused or outdated dependencies that should be cleaned up. Fix: Run 'go mod tidy' to remove unused dependencies. Review and consolidate dependency versions to reduce the attack surface.

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

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

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/lightningnetwork/lnd 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.

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

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

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "actor/actor.go" \\
  && ok "actor/actor.go" \\
  || miss "missing critical file: actor/actor.go"
test -f "actor/system.go" \\
  && ok "actor/system.go" \\
  || miss "missing critical file: actor/system.go"
test -f "aezeed/cipherseed.go" \\
  && ok "aezeed/cipherseed.go" \\
  || miss "missing critical file: aezeed/cipherseed.go"
test -f "batch/batch.go" \\
  && ok "batch/batch.go" \\
  || miss "missing critical file: batch/batch.go"
test -f "autopilot/agent.go" \\
  && ok "autopilot/agent.go" \\
  || miss "missing critical file: autopilot/agent.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 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
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/lightningnetwork/lnd"
  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).

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