mirrors/lightning-bolts
1
0
Fork 0
mirror of https://github.com/lightning/bolts.git synced 2025-02-22 22:25:42 +01:00
Code Issues Projects Releases Wiki Activity

bolt04: Describe the variable size hop_payload

Browse source 
Signed-off-by: Christian Decker <decker.christian@gmail.com>
This commit is contained in:
Christian Decker 2019-06-06 09:46:23 +02:00
parent 3ac0091ef9
commit a148abbad5
1 changed files with 37 additions and 33 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
04-onion-routing.md
View file

@ -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`