Onion Routing

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

Why this matters

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.

Hop payloads

Each peeled layer yields instructions: next node, amounts, outgoing CLTV, and possibly custom records. Intermediate hops should not learn the final destination (beyond probabilistic guesses from graph/timing).

Error onions

Failures return encrypted error packets that only the payer can fully interpret for the failed hop, enabling retries without broadcasting the entire route to every peer.

Builder guidance

• Do not log decrypted onion internals in production
• Treat timing correlation as a real privacy leak vector
• Prefer longer randomized routes only when fees/latency budgets allow

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 Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

Hands-on habit

Every protocol idea should be paired with one local experiment:

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)

That habit turns reading into builder instinct.

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.

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.

Next steps

Pathfinding algorithms: how wallets pick the hops that fill the onion.