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

Onion Routing

Sphinx packets, hop payloads, and payment privacy on Lightning.

advanced5 days

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

./sign-in

On this page

Learning objectives

  • Explain Sphinx-style onion encapsulation
  • Describe what each hop can and cannot learn
  • Connect BOLT4 to real payment privacy expectations

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
BOLT4onion routing

Step 1 // Required reading

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

  • bookMastering the Lightning Network

    Ch. 10: Onion Routing

Reflection prompts

  1. Explain Onion Routing to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Onion Routing?
  3. Which BOLT (or implementation doc) is the source of truth for this topic, and what did you verify there?

Lab // Hop visibility brief

Complete Steps 2–3. Write what an intermediate hop learns vs does not learn on a 3-hop payment. Optionally pay on Polar and note you cannot see the full path from a middle node’s logs (if inspected).

evidence required

  • ·Table or bullets: hop learns / does not learn
  • ·One honest privacy caveat (amount, timing, or graph leakage)
  • ·Link to Ch. 10 or BOLT4 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.

Lightning payments travel in onion packets: each hop peels one layer, learns only the next peer and its instructions, then forwards.

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

Step 2 — Core idea: peel one layer

Without onions, intermediate nodes would see the full route and payload. Privacy and security against some attackers depend on this layering — but Lightning is not anonymous cash by default.

Analogy: Nested envelopes. Each post office opens only its envelope, stamps the next address, and cannot read the inner letters.

Loading diagram…

Each hop peels one layer; the full path stays hidden.

Each peeled layer yields instructions: next node, amounts, outgoing CLTV, maybe custom records. Failures return encrypted error onions the payer can interpret for retries.

Builder habits: do not log decrypted onion internals; treat timing correlation as a leak vector; lengthen routes only within fee/latency budgets.

Privacy is not absolute

Amounts, timing, and graph structure can still leak information. Design threat models honestly.

Done when: You can state what a middle hop must not learn about the final destination.

Step 3 — Visibility brief (lab)

Write the learns / does not learn list for a middle hop. Add one privacy caveat you would put in a README.

Done when: Lab evidence (visibility brief + caveat + source) is complete.

Next lesson

Transport & Noise — encrypted authenticated peer links under the BOLTs.

further reading

  • boltBOLT4 Onion Routing
  • articleSphinx mix format (background)

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.

  • 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
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

prevRoutingnextTransport & Noise

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

No questions yet — be the first to ask.