[Lightning-dev] [DRAFT] Multi-cell-hop onion with TLV (and example for multi-part-payment)

Rusty Russell rusty at rustcorp.com.au
Wed Nov 28 00:21:59 UTC 2018

There's a kinda-neat intersection between the "use TLV" proposal and the
"multi-cell-onion" idea, so I want to make a concrete proposal (wording
needs formalization):

Multi-cell structure:

1. `realm` (or `per_hop_type` if you prefer) meaning expanded.
2. Lower 4 bits is `num_extra_cells` to use (ie. total 1-17 cells).
3. Upper 4 bits reserved: if set, drop.
4. HMAC on end covers that many per-hops.
5. Padding is thus 12 bytes + 64 * `num_extra_cells`.

Structure of padding changes:

1. We make the onion `padding` contain TLV, rename to `tlv`.
2. TLVs (as always!) are in lexicographical order (with shortest-wins on
3. TLVs follow unknown-odd-is-ok rule.
4. No 0-type; that terminates (backwards compat with 0-filled padding).

New onion error value:

1. type: PERM|22 (`tlv_element_invalid`)
2. `2`:`offset`

The writer MUST set `offset` to a byte offset within the `tlv` field
of the tlv element it rejected.  It SHOULD use the offset of the `type` byte of the TLV
element if it didn't understand it, the offset the `len` byte of the TLV
element if it was an incorrect length, or otherwise within the `value`
if the value was somehow invalid.

TLVs defined for initial onion:

* type 2: `switch_chain`
  length: 32
  value: chain_id of new chain.

  Used to switch chains during transit or at final hop.

Use with multi-part payment ("base AMP"):

* type 4: `total_payment`
  length: variable, <= 8
  value: amount of total payment, in msat (big-endian of course).

  Writer must only use for final hop, and only if bolt11 flagged it as
  available (bolt11-multi_part_available).  May use even if this payment
  meets the total_payment requirement.

  Reader MUST reject if not final hop, MAY reject if invoice was not
  `bolt11-multi_part_available`.  Reader SHOULD wait until total parts
  meet or exceed `total_payment` (exceed may be due to fuzzing) [rest
  as per previous posts].

PS.  I prefer 'multi-part-payment' to 'base AMP' in the spec.  It's more
     explicit, and leaves the namespace clear for more atomicy AMPs.

More information about the Lightning-dev mailing list