PHASE 26 Lightning and production proof · 20–40 hours

Lightning Engineering & Production Capstone

Lightning is a payment network with online operational requirements. Model payment states and reconciliation explicitly; do not equate an invoice string with settlement.

Goal — deliver a recoverable, observable Lightning payment integration or an equivalent EVM/Bitcoin production capstone with evidence another engineer can reproduce.

1. Channel and payment state

State	What the application must do
Invoice created	Persist idempotency key, amount, expiry, destination/account, and status; do not credit user.
Payment pending	Show pending; retain correlation IDs; retry only using a defined policy.
Settled	Consume node event, reconcile durable ledger, credit exactly once.
Failed/expired	Record reason; do not silently create another payment attempt.
Channel impaired	Surface liquidity/route issue; do not claim the network is unavailable without evidence.
Force close/recovery	Follow the documented backup/watchtower/reconciliation runbook.

Study BOLTs and choose LND, Core Lightning, or LDK deliberately. Channels use funding outputs, commitment transactions, HTLCs, timelocks, routing, and liquidity management. Inbound and outbound liquidity are separate constraints.

1b. LDK embedding & watchtowers

LDK — Rust library for custom nodes; you implement chain sync, persistence, and signer IPC. See labs/phase-26-lightning/ldk/README.md.
Watchtowers — backup encrypted channel states; tower reacts to revoked commitments. Runbook: labs/phase-26-lightning/watchtower/RUNBOOK.md.

2. Service implementation pattern

POST /invoices
  require(Idempotency-Key)
  validate(amount, currency, customer)
  persist(orderId, idempotencyKey, status="created")
  create invoice through authenticated node adapter
  persist(invoiceId, expiresAt, status="pending")

node event consumer
  verify event identity and deduplicate
  transactionally transition pending → settled
  append immutable ledger entry
  emit application event

reconciler (scheduled)
  compare node invoices/payments, channel state, on-chain wallet and ledger
  alert on mismatches; never auto-delete evidence

3. Operational drills

Restore from encrypted backups into an isolated test environment and verify expected channel/accounting state.
Simulate a node restart, duplicate event, expired invoice, route failure, insufficient inbound liquidity, force close, and chain confirmation delay.
Monitor payment success/latency, pending/expired counts, liquidity by channel, on-chain fee/confirmation state, node health, reconciliation mismatches, and alert delivery.
Keep node RPC authentication and wallet keys in a dedicated secret/signer boundary. Give application code the narrowest possible capability.

4. Capstone acceptance criteria

Track	Required evidence
EVM protocol	Threat model, Foundry unit/fuzz/invariant/fork tests, verified testnet deploy, Safe/timelock plan, monitoring and incident drill
EVM infrastructure	Reorg-safe indexer, provider failover, replay tests, durable nonce handling, dashboard and load/failure evidence
Bitcoin wallet	Descriptor/PSBT tests, independent transaction review, multisig recovery drill, RBF/CPFP policy, signer isolation
Lightning service	Idempotent settlement ledger, event/reconciliation tests, liquidity/channel monitoring, recovery and force-close drill

Deliverable — publish a repository that can be cloned and run from a documented environment. Include pinned dependencies, test commands, a threat model, architecture diagram, deployment/config manifest (without secrets), dashboard screenshots or definitions, runbooks, and a postmortem for one induced failure. A reviewer must be able to reproduce the most important tests without your help.

Template: labs/phase-26-capstone/ · Rubric: capstone rubric · Lightning lab: labs/phase-26-lightning/

Safety — completing a course capstone does not make real-money systems safe. Obtain independent review, start with limits and controlled rollout, and do not keep user custody unless you are prepared to operate the security and compliance program it requires.