Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // lightning

Lightning Attack Surface

Congestion, channel probing, watchtower incentives, and lessons from real LN CVEs - adversarial thinking for Lightning builders.

advanced7 days

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Describe payment-channel congestion / jamming style griefing at a conceptual level
  • Explain channel balance probing and privacy implications
  • List defensive practices and why watchtowers / uptime matter

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search
Lightning attack surfacechannel jamming

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • docsPayment channel congestion discussion
  • articleOn the Difficulty of Hiding the Balance of Lightning Network Channels
  • article2019 LND/CLN/Eclair CVE disclosure

Reflection prompts

  1. How can an attacker lock liquidity without stealing funds outright, and why is that still damaging?
  2. What does successful channel probing reveal, and how should wallet UX talk about LN privacy?
  3. After reading a historical multi-implementation CVE disclosure, what process change would you add to your release checklist?

Lab // Adversarial tabletop

Complete Steps 2–3. Run a tabletop for a 3-node Polar graph. Pick congestion, probing, or offline breach. Write attacker steps, defender detections, and product mitigations.

evidence required

  • ·One-page tabletop writeup with roles and timeline
  • ·List of metrics/alerts you would monitor
  • ·Two product mitigations ranked by cost vs impact
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Lightning’s safety depends on timelocks, honesty assumptions, availability, and implementation correctness. Attackers may not need to steal immediately — locking liquidity, probing balances, or racing offline victims can still win.

Complete Step 1 // Required reading in the study plan above, then continue here. This closes Routing & Liquidity.

Step 2 — Core idea: griefing, probing, uptime

Builders shipping POS, wallets, or routing services inherit LN’s adversarial reality. Ignoring known griefing classes and past CVEs is negligence.

ClassIdea
Congestion / jammingHold HTLCs / paths to consume capacity and degrade success
ProbingLearn balances via success/failure of trial payments
Offline breachBroadcast old state while victim is offline — watchtowers help
Shared CVEsMulti-implementation bugs — patch process matters

Loading diagram…

Attack classes target liquidity, privacy, or offline justice — not only direct theft.

Defense in depth

Limits, monitoring, backups, towers, and conservative channel sizes beat clever one-off settings.

Done when: You can explain why locking liquidity without theft still damages a product.

Step 3 — Tabletop (lab)

Pick congestion, probing, or offline breach on a 3-node mental/Polar graph. Attacker steps → detections → two mitigations ranked by cost vs impact.

Common mistakes

  • Marketing “Lightning is private” without caveats
  • Running routing nodes with no capacity/HTLC metrics
  • Skipping patch discipline because “it’s just testnet”

Done when: Lab evidence (tabletop + alerts + mitigations) is complete. Complete the chapter quiz when prompted.

Next lesson

LND (Implementation) — gRPC, REST, and macaroon authentication.

further reading

  • bookMastering the Lightning Network

    Security / attacks overview

review // club

Chapter review picks

Practice on real Lightning OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

  • Lightning Loop docs

    Study how Loop moves liquidity between on-chain and channel balances; comment on doc gaps.

    gfi
    inbound capacityon-chain swaps
    35 min·intermediateopen on GitHub
  • BOLT4 onion routing spec

    Read BOLT4 and summarize what each hop can and cannot learn from an onion packet.

    spec review
    hop payloadssphinx
    50 min·advancedopen on GitHub
  • LND mission control / pathfinding

    Review a mission-control or pathfinding PR and note how failed attempts update edge scores.

    pr review
    failure learningfee budgets
    55 min·advancedopen on GitHub
review checklist
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

build // next

Apply this chapter in a project

You have the concepts — ship something small to prove it. These Pull projects connect directly to what you just studied.

  • project // custom-router

    Custom Router
    ./spec./submit

discussion

Discussion

prevFailure HandlingnextLND

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.