Trampoline onion format (Feature 56/57)

[t-bast]

Trampoline routing uses layered onions to trustlessly and privately offload the calculation of parts of a payment route to remote trampoline nodes.

A normal onion contains a smaller onion for the last hop of the route, and that smaller onion contains routing information about the next trampoline hop.

Intermediate trampoline nodes "fill the gap" by finding a route to the next trampoline node, and sending it the peeled trampoline onion, until that reaches the final destination.

This PR details the onion construction and requirements for supporting nodes. I advise readers to also have a look at #829 which gives a more high-level view of the different components, how they interact, and provides nice diagrams that help understand the low-level details.

[rustyrussell]

I like it, but I'm not sure I understand the purpose of the payment_secret except inside the internal onion for the final node?

[lightning-developer]

I believe the spec should make a recommendation for CLTV and fee budgets that senders of trampoline onions should use for each trampoline to reduce the usage of temporary_trampoline_failure.

Also it seems reasonable to just reply with a single fee_budget_msat instead of * [u32:fee_base_msat] and [u32:fee_proportional_millionths] as those fields seem not to make sense in the context of trampolines.

Trampolines could announce the fee_budget_msat and cltv_budget (in case you like the new name) that they believe to be sufficient in their node announcements?

[a-mpch]

It is no clear to me that whenever the receiver is the first trampoline and something fails, should the receiver node just use the outer onion shared secret or would it use the double obfuscation?
It could be seen in different perspectives:

1. payment reaches the trampoline and then try to route it, figuring out it is itself.
2. Before trying to route it as trampoline, payment is received.

I didn't find a test case for this in eclair (don't know much of Scala tho)

[t-bast]

You're right, there is some subtlety here, this depends on who the error is encrypted for:

• if the failing trampoline node wants the error to be for the previous trampoline node, they use the outer onion shared secret: this is used for example when the payment is using MPP but not all parts were received in time, which is an error made by the previous trampoline node which could (probably should) retry, so we don't want the error to go all the way back to the sender
• if the failing trampoline node wants the error to be for the sender, they use the double obfuscation, which forces the previous trampoline node to relay the error upstream: this is used for example when receiving a payment that an invoice that was already paid, or that has a trampoline expiry that is too close

I don't think we can list all cases in the spec, but we probably should better explain the distinction between those two cases. Is that clear enough? Otherwise feel free to suggest the wording you'd like to see in the spec that would make this clear.

[a-mpch]

I think that wording makes sense. Thanks!