claude-dev-suite Trampoline Routing
Mobile / light Lightning clients can't sync the full ~50,000-channel graph efficiently. Trampoline lets them target trampoline-capable nodes, which then do their own pathfinding to the destination.
Why
Pathfinding cost:
- Full sync: 50-100 MB graph + ~30 minutes initial sync.
- Memory: 50-100 MB resident.
- Update bandwidth: continuous gossip rate.
For battery-constrained mobile, trampoline shifts this to a server.
Mechanism
Sender constructs a 2-layer onion:
- Outer onion: routes to trampoline node, payload is opaque.
- Inner onion (encrypted): contains target destination + amount.
When trampoline receives the outer-onion HTLC:
- Decrypts inner payload → learns final destination + min CLTV.
- Computes route from itself to destination using its full graph.
- Builds a fresh outer-onion targeting that route.
- Forwards.
Multi-trampoline: multiple trampoline hops each doing their own pathfinding.
Cost
Trampoline node charges:
- Forwarding fees on its segment.
- Optionally: a "service fee" for pathfinding (e.g., higher fee_base).
Sender selects trampolines based on offered service quality + cost.
Onion structure
Sender's onion:
hop 1: trampoline_A
- Trampoline payload (BOLT 4 TLV with type 20 trampoline_onion):
Embedded onion targeting trampoline_B or destination.
hop 2: trampoline_B (if any)
...
Trampoline embedded onion carries the actual onion to the next trampoline (or the final hop).
Implementation status
| Implementation | Trampoline send | Trampoline receive |
|---|---|---|
| LDK | yes | partial |
| CLN | yes | yes |
| LND | partial | partial |
| Eclair | yes | yes |
| Phoenix | yes (uses ACINQ trampoline) | yes |
Trampoline + MPP
Sender splits a payment into multiple parts; each part can route via
different trampolines. Receiver assembles by payment_secret.
Use case
Phoenix wallet uses ACINQ as exclusive trampoline:
- Phoenix pays only ACINQ.
- ACINQ does all pathfinding to destinations.
- Simpler wallet code, slightly higher fees.
Common bugs
- Trampoline node rejects (insufficient fee/CLTV) → retry with bumped values.
- Inner onion CLTV / amount mismatch with outer → onion processing fails.
- Trampoline doesn't support feature → falls back to direct pathfinding (which mobile may not have data for).