Onion routing

When Alice pays Dina through Bob and Chan, Bob needs to know where to send the payment next, but not that it's going to Dina. onion routing gives each node exactly what it needs and nothing more.

Layers, like an onion

Alice knows the whole route. She builds a message in layers, innermost first:

1. The Dina layer: "you are the final hop; the amount is 21,000."
2. Wrapped in the Chan layer: "forward 21,000 to Dina."
3. Wrapped in the Bob layer: "forward 21,001 to Chan."

Each layer is encrypted with a key only that hop can work out. Bob peels his layer, reads "forward to Chan", and passes on the rest, which to him is random-looking bytes. Chan peels the next one. Only Dina's layer says "it's for you".

Build a toy onion

The real thing uses elliptic-curve shared secrets and ChaCha20; ours uses a SHA-256 stream. The layering is the same idea. Fill in wrap and peel:

⚡Build a toy onion

Python

NodeAlice · LNDBob · c-lightningChan · c-lightningDina · LNDNo node

import hashlib def keystream(key: bytes, n: int) -> bytes: """A toy stream cipher: SHA-256 in counter mode. (Real Lightning uses ChaCha20.)""" out = b"" counter = 0 while len(out) < n: out += hashlib.sha256(key + counter.to_bytes(4, "big")).digest() counter += 1 return out[:n] def xor(data: bytes, stream: bytes) -> bytes: return bytes(a ^ b for a, b in zip(data, stream)) def wrap(message: bytes, keys: list[bytes]) -> bytes: """Encrypt one layer per hop. keys[0] is the first hop (Bob).""" onion = message # TODO: add a layer for every key, so the first hop's layer is on the outside return onion def peel(onion: bytes, key: bytes) -> bytes: """Remove one layer with this hop's key.""" # TODO return onion keys = [b"bob-secret", b"chan-secret", b"dina-secret"] onion = wrap(b"lipa Dina sats 21000", keys) print("onion:", onion.hex()[:40], "...") for key in keys: onion = peel(onion, key) print("after", key.decode(), "->", onion)

▶ RunCheckReset lessonRestore starter code

These exercises need a laptop with the lab running. You can read the lesson on your phone.

The check runs your functions with random keys and messages, and makes sure the message only appears after the last layer.

What real onions add (Sphinx)

• Fixed size. Every onion is 1,366 bytes, padded with filler, so a hop can't count the remaining hops.
• Per-hop shared secrets. Alice uses a fresh ephemeral key per payment; each hop derives its secret with ECDH, and the key is blinded at every step so hops can't link the onion they received with the one they send on.
• HMACs. Each layer carries an integrity tag. A tampered onion is rejected, and the error travels back encrypted, layer by layer, to Alice.