B++ Logo
Feedback

Lightning Onion Routing

Lightning Network uses Sphinx onion routing to provide privacy and security for payments. Each hop in a route only knows the previous and next hop, not the full route or payment details. Onion routing encrypts data in layers, like an onion. Each hop peels off one layer, revealing only the information needed for that hop to forward the payment. Key properties:

  • Privacy: Each hop only knows immediate neighbors
  • Integrity: HMACs prevent tampering
  • Source Hiding: Sender identity is hidden from all hops
  • Path Hiding: Full route is never revealed

Sphinx Protocol

Lightning uses the Sphinx protocol (adapted from Tor's design) for payment routing. It provides:

  • Compact fixed-size packets (1300 bytes)
  • Per-hop payload encryption
  • Replay attack protection
  • Forward secrecy

How It Works

  1. Sender builds onion: Encrypts routing data in layers (innermost first)
  2. Each hop processes: Peels off one layer, learns next hop
  3. Final hop: Receives payment details and claims HTLC
  4. Response: Preimage propagates back through same path
Onion Packet Structure:
┌─────────────────────────────────────┐
│ Version (1 byte)                    │
│ Public Key (33 bytes)               │
│ Encrypted Payload (1300 bytes)      │
│ HMAC (32 bytes)                     │
└─────────────────────────────────────┘
Total: 1366 bytes

Onion Packet Components

FieldSizeDescription
Version1 byteProtocol version (currently 0)
Public Key33 bytesEphemeral public key for ECDH
Payload1300 bytesEncrypted per-hop data
HMAC32 bytesAuthentication tag

Per-Hop Payload (TLV Format)

Each decrypted layer contains:

  • Short Channel ID: 8 bytes: Which channel to forward through
  • Amount to Forward: Variable: HTLC amount for next hop
  • Outgoing CLTV: 4 bytes: Expiry for outgoing HTLC
  • Padding: Variable: Random data to maintain fixed size

Shared Secret Derivation

Encryption Process

Layer Construction (Sender)

For a 3-hop route (Alice → Bob → Carol → Dave):

  1. Generate ephemeral keypair
  2. Compute shared secrets with all hops using ECDH
  3. Build payloads for each hop
  4. Encrypt from innermost (Dave) to outermost (Bob)
  5. Compute HMACs at each layer
Construction Order (inside-out):
1. Create Dave's payload (final hop data)
2. Encrypt with Dave's shared secret
3. Prepend Carol's payload
4. Encrypt with Carol's shared secret
5. Prepend Bob's payload
6. Encrypt with Bob's shared secret
7. Add ephemeral public key

Decryption (Each Hop)

Each hop performs:

  1. Compute shared secret using ephemeral pubkey and node's private key
  2. Derive decryption key (rho) and HMAC key (mu)
  3. Verify HMAC
  4. Decrypt payload to get routing instructions
  5. Shift payload left (removes own data, pads end with zeros)
  6. Blind ephemeral public key for next hop
  7. Forward modified packet

Privacy Guarantees

Information Visibility

InformationSenderIntermediateFinal Hop
Full routeYesNoNo
Sender identityYesNoNo
DestinationYesNoYes
Payment amountYesPartialYes
Route positionYesNoPartial

What Intermediaries Learn

An intermediate hop knows only:

  • Previous hop's node ID (who sent the packet)
  • Next hop's channel ID (where to forward)
  • Amount and CLTV for the forwarded HTLC
  • That they're neither first nor last (if route length > 2)

What Remains Hidden

  • Total route length
  • Sender's identity
  • Final destination
  • Total payment amount
  • Their position in the route

Fixed Packet Size

All onion packets are exactly 1366 bytes regardless of route length:

  • Prevents traffic analysis based on packet size
  • Unused space filled with random padding
  • Maximum 20 hops supported

Security Properties

Integrity

  • HMAC-SHA256 at each layer
  • Tampering detected immediately
  • Modified packets rejected

Forward Secrecy

  • Ephemeral keys used per-payment
  • Past payments cannot be decrypted if keys compromised later
  • No correlation between payments

Replay Protection

  • Each hop tracks seen shared secrets
  • Duplicate packets rejected
  • Prevents payment replay attacks

Common Failure Modes

HMAC Mismatch

Payment fails with BADONION error. Causes:

  • Packet corruption
  • Incorrect key derivation
  • Implementation bug

Invalid Onion Version

If version byte is not 0, packet is rejected.

Packet Too Short

Malformed packets are rejected immediately.

Summary

Onion routing provides Lightning's privacy layer:

  • Source privacy: Sender hidden from all hops
  • Path privacy: Full route never revealed
  • Amount privacy: Intermediaries don't know total payment
  • Fixed size: Route length hidden
  • Forward secrecy: Past payments stay private

Resources