diff --git a/04-onion-routing.md b/04-onion-routing.md index f9ec47c..f564903 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -136,8 +136,8 @@ The packet consists of four sections: - a `version` byte - a 33-byte compressed `secp256k1` `public_key`, used during the shared secret generation - - a 1300-byte `hops_data` consisting of twenty fixed-size packets, each containing - information to be used by its associated hop during message forwarding + - a 1300-byte `hop_payloads` consisting of multiple, variable length, + `hop_payload` payloads or up to 20 fixed sized legacy `hop_data` payloads. - a 32-byte `HMAC`, used to verify the packet's integrity The network format of the packet consists of the individual sections @@ -156,47 +156,46 @@ The overall structure of the packet is as follows: For this specification (_version 0_), `version` has a constant value of `0x00`. -The `hops_data` field is a structure that holds obfuscations of the next hop's -address, transfer information, and its associated HMAC. It is 1300 bytes (`20x65`) long -and has the following structure: +The `hop_payloads` field is a structure that holds obfuscated routing information, and associated HMAC. +It is 1300 bytes long and has the following structure: -1. type: `hops_data` +1. type: `hop_payloads` 2. data: - * [`byte`:`realm`] - * [`32*byte`:`per_hop`] + * [`varint`:`length`] + * [`hop_payload_length`:`hop_payload`] * [`32*byte`:`HMAC`] * ... * `filler` -Where, the `realm`, `per_hop` (with contents dependent on `realm`), and `HMAC` -are repeated for each hop; and where, `filler` consists of obfuscated, -deterministically-generated padding, as detailed in -[Filler Generation](#filler-generation). Additionally, `hops_data` is -incrementally obfuscated at each hop. +Where, the `length`, `hop_payload` (with contents dependent on `length`), and `HMAC` are repeated for each hop; +and where, `filler` consists of obfuscated, deterministically-generated padding, as detailed in [Filler Generation](#filler-generation). +Additionally, `hop_payloads` is incrementally obfuscated at each hop. -The `realm` byte determines the format of the `per_hop` field; currently, only `realm` -0 is defined, for which the `per_hop` format follows: +Using the `hop_payload` field, the origin node is able to specify the path and structure of the HTLCs forwarded at each hop. +As the `hop_payload` is protected under the packet-wide HMAC, the information it contains is fully authenticated with each pair-wise relationship between the HTLC sender (origin node) and each hop in the path. -1. type: `per_hop` (for `realm` 0) +Using this end-to-end authentication, each hop is able to cross-check the HTLC +parameters with the `hop_payload`'s specified values and to ensure that the +sending peer hasn't forwarded an ill-crafted HTLC. + +The `length` field determines both the length and the format of the `hop_payload` field; the following formats are defined: + + - Legacy `hop_data` format, identified by a single `0x00` byte for length. In this case the `hop_payload_length` is defined to be 32 bytes. + - `tlv_payload` format, identified by any length over `1`. In this case the `hop_payload_length` is equal to the numeric value of `length`. + - A single `0x01` byte for length is reserved for future use to signal a different payload format. This is safe since no TLV value can ever be shorter than 2 bytes. In this case the `hop_payload_length` MUST be defined in the future specification making use of this `length`. + +## Legacy `hop_data` payload format + +The `hop_data` format is identified by a single `0x00`-byte length, for backward compatibility. +It's payload is defined as: + +1. type: `hop_data` (for `realm` 0) 2. data: * [`short_channel_id`:`short_channel_id`] * [`u64`:`amt_to_forward`] * [`u32`:`outgoing_cltv_value`] * [`12*byte`:`padding`] -Using the `per_hop` field, the origin node is able to precisely specify the path and -structure of the HTLCs forwarded at each hop. As the `per_hop` is protected -under the packet-wide HMAC, the information it contains is fully authenticated -with each pair-wise relationship between the HTLC sender (origin node) and each -hop in the path. - -Using this end-to-end authentication, -each -hop is able to -cross-check the HTLC parameters with the `per_hop`'s specified values -and to ensure that the sending peer hasn't forwarded an -ill-crafted HTLC. - Field descriptions: * `short_channel_id`: The ID of the outgoing channel used to route the @@ -234,11 +233,15 @@ Field descriptions: leaking its position in the route. * `padding`: This field is for future use and also for ensuring that future non-0-`realm` - `per_hop`s won't change the overall `hops_data` size. + `hop_data`s won't change the overall `hop_payloads` size. -When forwarding HTLCs, nodes MUST construct the outgoing HTLC as specified within -`per_hop` above; otherwise, deviation from the specified HTLC parameters -may lead to extraneous routing failure. +When forwarding HTLCs, nodes MUST construct the outgoing HTLC as specified +within `hop_data` above; otherwise, deviation from the specified HTLC +parameters may lead to extraneous routing failure. + +### `tlv_payload` payload format + +TBD ## Non-strict Forwarding @@ -287,6 +290,7 @@ using an alternate channel. When building the route, the origin node MUST use a payload for the final node with the following values: + * `outgoing_cltv_value`: set to the final expiry specified by the recipient (e.g. `min_final_cltv_expiry` from a [BOLT #11](11-payment-encoding.md) payment invoice) * `amt_to_forward`: set to the final amount specified by the recipient (e.g. `amount`