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

BOLTs & Spec Landscape

Navigate the BOLT specifications and how implementations stay interoperable.

intermediate4 days

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

./sign-in

On this page

Learning objectives

  • Identify what BOLTs are and why they exist
  • Map major BOLT numbers to features you will implement
  • Know where to follow spec discussions

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
BOLTLightning Network

Step 1 // Required reading

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

  • boltLightning BOLTs

Reflection prompts

  1. Explain BOLTs & Spec Landscape to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood BOLTs & Spec Landscape?
  3. Which BOLT or implementation doc did you treat as the source of truth, and what did you confirm by reading it?

Lab // BOLT map worksheet

Complete Steps 2–3. From the intro BOLT, list three BOLT numbers you will hit later and which Pull lesson covers each. Skim one open bolts PR title (optional).

evidence required

  • ·Table of at least three BOLT numbers → topic → later lesson name
  • ·One sentence on why blogs are not authoritative over the spec
  • ·Link to BOLTs intro section you used
  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.

BOLTs (Basis of Lightning Technology) are the interoperability specs for Lightning. LND, Core Lightning, and LDK aim to speak the same protocol so heterogeneous nodes can route.

Complete Step 1 // Required reading in the study plan above, then continue here.

Step 2 — Core idea: shared plugs, different products

Without shared specs, every implementation would be an island. Builders reading BOLTs can debug wire mismatches and evaluate new features (offers, splicing) before they are universal.

Analogy: BOLTs are the electrical code for Lightning. Different manufacturers (LND/CLN/LDK) ship distinct products, but plugs must still fit.

You do not need to read these cover-to-cover now — each gets a dedicated lesson later:

BOLTFocusLater lesson
2Channel management / HTLCsChannels & HTLCs
3TransactionsCommitment Transactions
4Onion routingOnion Routing
7GossipRouting & Pathfinding
11InvoicesBOLT11 Invoices
12Offers (evolving)BOLT12 Offers

Loading diagram…

Multiple implementations converge on BOLTs for network compatibility.

Read with a question, not cover-to-cover

Open a BOLT when a later lesson or a bug points you there. Keep Mastering Lightning nearby for narrative context.

Done when: You can name LND, CLN, and LDK as implementations that target the same BOLTs.

Step 3 — Map three BOLTs (lab)

Fill a three-row map from the table (or BOLTs intro). Optional: note one open bolts PR title — feature or clarification?

Common mistakes

  • Assuming a feature in one implementation is already a ratified BOLT everywhere
  • Treating blog posts as authoritative over the spec text
  • Ignoring feature bits / negotiations between peers

Done when: Lab evidence (BOLT map + authority sentence + source link) is complete.

Next lesson

Invoices — the BOLT11 payment requests wallets actually scan.

further reading

  • bookMastering the Lightning Network

    Spec references throughout, keep BOLTs open while reading

  • docsLightning RFC discussions

review // club

Review club

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.

  • Open BOLT pull requests

    Review an open BOLT PR using the spec checklist: problem, interop, failure modes, tests.

    spec review
    rollouttest vectorsambiguity
    60 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.

progress // sign in

Reading is public. Sign in to mark lessons complete, sync across devices, and unlock your roadmap.

./sign-in-to-track

discussion

Discussion

prevLightning OverviewnextInvoices

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.