— —
Follow on X
LESSONS

Onion routing and pathfinding

Senders build routes from a gossiped channel graph and wrap each payment in layers of encryption. Balances are private, so payments probe and retry; multipath splits big ones.

6 MIN READ
A stack describing gossip, pathfinding, onion routing, retries and multipath payments.
LEVEL · Advanced
IN THIS LESSON · 3 OF 6
BY THE END YOU WILL BE ABLE TO ANSWER
  • Who chooses the route of a Lightning payment?
  • Why do Lightning payments sometimes fail and retry?

Then prove it: a 2-question quiz. The lesson marks itself complete at 100%.

The channel graph

Public channels are announced over a gossip network: the funding output, the two node keys, and each side's fee policy and limits. Every routing node keeps this graph. Private channels (most mobile wallets') are not announced; the receiver includes a route hint in the invoice so senders can reach them through their peer.

Source routing

Unlike the internet, the sender chooses the whole path. From the graph it finds a route to the destination that satisfies the amount, minimising fees and timeouts. Only the sender knows the full route.

Sphinx onion

The sender encrypts the route in layers, one per hop, like an onion. Each node peels its layer with its own key and learns only: where the payment came from, where to send it next, and the amount and timeout to forward. It cannot tell whether the previous node was the sender or a relay, or how many hops remain. The packet is a fixed size so its position in the route cannot be inferred.

Why payments fail

The graph shows channel capacity but not how it is split between the two sides. A route may look fine and fail because a channel lacks balance in the needed direction. The sender receives an error, updates its view, and tries another route, usually within a second. Large payments fail more; multipath payments split them into parts sent over several routes, which succeed or fail together.

Fees and policy

Each hop charges a base fee (often around 1 sat) plus a proportional fee (often tens of parts per million). Routing nodes set these to balance their channels. Fees are usually tiny; what the sender pays for most is reliability.

CHECK YOURSELF
1/2 Who chooses the route of a Lightning payment?
2/2 Why do Lightning payments sometimes fail and retry?
pick an answer for each question

SOURCES

  1. Lightning Network specifications (BOLTs)
Progress is saved in this browser only.