You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
1.`signature`: bitcoin-style signature of above. (520 bits)
91
+
1. Zero or more tagged parts
92
+
1.`signature`: bitcoin-style signature of above (520 bits)
76
93
77
94
## Requirements
78
95
79
-
A writer MUST set `timestamp` to the time to
96
+
A writer MUST set `timestamp` to
80
97
the number of seconds since Midnight 1 January 1970, UTC in
81
-
big-endian. A writer MUST set `signature` to a valid
98
+
big-endian. A writer MUST set `signature` to a valid
82
99
512-bit secp256k1 signature of the SHA2 256-bit hash of the
83
-
Human Readable Part, represented as UTF-8 bytes, concatenated with the
84
-
Data Part (excluding the signature) with zero bits appended to pad the
100
+
human-readable part, represented as UTF-8 bytes, concatenated with the
101
+
data part (excluding the signature) with zero bits appended to pad the
85
102
data to the next byte boundary, with a trailing byte containing
86
103
the recovery ID (0, 1, 2 or 3).
87
104
@@ -90,29 +107,29 @@ field specified below).
90
107
91
108
## Rationale
92
109
93
-
`signature` covers an exact number of bytes because although the SHA-2
94
-
standard actually supports hashing in bit boundaries, it's not widely
95
-
implemented. The recovery ID allows publickey recovery, so the
110
+
`signature` covers an exact number of bytes even though the SHA-2
111
+
standard actually supports hashing in bit boundaries because it's not widely
112
+
implemented. The recovery ID allows public-key recovery, so the
96
113
identity of the payee node can be implied.
97
114
98
115
## Tagged Fields
99
116
100
-
Each Tagged Field is of format:
117
+
Each Tagged Field is of the form:
101
118
102
119
1.`type` (5 bits)
103
120
1.`data_length` (10 bits, big-endian)
104
121
1.`data` (`data_length` x 5 bits)
105
122
106
-
Currently defined Tagged Fields are:
123
+
Currently defined tagged fields are:
107
124
108
-
*`p` (1): `data_length` 52. 256-bit SHA256 payment_hash: preimage of this provides proof of payment.
109
-
*`d` (13): `data_length` variable. short description of purpose of payment (ASCII), e.g. '1 cup of coffee'
110
-
*`n` (19): `data_length` 53. The 33-byte public key of the payee node.
111
-
*`h` (23): `data_length` 52. 256-bit description of purpose of payment (SHA256). This is used to commit to an associated description which is too long to fit, such as may be contained in a web page.
112
-
*`x` (6): `data_length` variable. `expiry` time in seconds (big-endian). Default is 3600 (1 hour) if not specified.
125
+
*`p` (1): `data_length` 52. 256-bit SHA256 payment_hash. Preimage of this provides proof of payment
126
+
*`d` (13): `data_length` variable. short description of purpose of payment (ASCII), e.g. '1 cup of coffee'
127
+
*`n` (19): `data_length` 53. 33-byte public key of the payee node
128
+
*`h` (23): `data_length` 52. 256-bit description of purpose of payment (SHA256). This is used to commit to an associated description that is too long to fit, such as on a web page.
129
+
*`x` (6): `data_length` variable. `expiry` time in seconds (big-endian). Default is 3600 (1 hour) if not specified.
113
130
*`c` (24): `data_length` variable. `min_final_cltv_expiry` to use for the last HTLC in the route. Default is 9 if not specified.
114
-
*`f` (9): `data_length` variable, depending on version. Fallback on-chain address: for bitcoin, this starts with a 5bit `version`; a witness program or P2PKH or P2SH address.
115
-
*`r` (3): `data_length` variable. One or more entries containing extra routing information for a private route; there may be more than one `r` field, too.
131
+
*`f` (9): `data_length` variable, depending on version. Fallback on-chain address: for bitcoin, this starts with a 5-bit `version` and contains a witness program or P2PKH or P2SH address.
132
+
*`r` (3): `data_length` variable. one or more entries containing extra routing information for a private route; there may be more than one `r` field
116
133
*`pubkey` (264 bits)
117
134
*`short_channel_id` (64 bits)
118
135
*`fee_base_msat` (32 bits, big-endian)
@@ -122,12 +139,12 @@ Currently defined Tagged Fields are:
122
139
### Requirements
123
140
124
141
A writer MUST include exactly one `p` field, and set `payment_hash` to
125
-
the SHA-2 256-bit hash of the `payment_preimage`which will be given
142
+
the SHA-2 256-bit hash of the `payment_preimage`that will be given
126
143
in return for payment.
127
144
128
-
A writer MUST include either exactly one `d` or exactly one `h` field. If included, a
145
+
A writer MUST include either exactly one `d` or exactly one `h` field. If included, a
129
146
writer SHOULD make `d` a complete description of
130
-
the purpose of the payment. If included, a writer MUST make the preimage
147
+
the purpose of the payment. If included, a writer MUST make the preimage
131
148
of the hashed description in `h` available through some unspecified means,
132
149
which SHOULD be a complete description of the purpose of the payment.
133
150
@@ -145,12 +162,12 @@ A writer MAY include one or more `f` fields. For bitcoin payments, a writer MUST
145
162
`f` field to a valid witness version and program, or `17` followed by
146
163
a public key hash, or `18` followed by a script hash.
147
164
148
-
A writer MUST include at least one `r` field if it does not have a
149
-
public channel associated with its public key. The `r` field MUST contain
165
+
A writer MUST include at least one `r` field if there is not a
166
+
public channel associated with its public key. The `r` field MUST contain
150
167
one or more ordered entries, indicating the forward route from a
151
-
public node to the final destination. For each entry, the `pubkey` is the
152
-
node ID of the start of the channel,`short_channel_id` is the short channel ID
153
-
field to identify the channel, `fee_base_msat`, `fee_proportional_millionths` and `cltv_expiry_delta` are as specified in [BOLT #7](07-routing-gossip.md#the-channel_update-message). A writer MAY include more than one `r` field to
168
+
public node to the final destination. For each entry, the `pubkey` is the
169
+
node ID of the start of the channel;`short_channel_id` is the short channel ID
170
+
field to identify the channel; and `fee_base_msat`, `fee_proportional_millionths` and `cltv_expiry_delta` are as specified in [BOLT #7](07-routing-gossip.md#the-channel_update-message). A writer MAY include more than one `r` field to
154
171
provide multiple routing options.
155
172
156
173
A writer MUST pad field data to a multiple of 5 bits, using zeroes.
@@ -160,7 +177,7 @@ the most-preferred field first, followed by less-preferred fields in
160
177
order.
161
178
162
179
A reader MUST skip over unknown fields, an `f` field with unknown
163
-
`version`, or a `p`, `h`, or `n` field which does not have `data_length` 52,
180
+
`version`, or a `p`, `h`, or `n` field that does not have `data_length` 52,
164
181
52, or 53 respectively.
165
182
166
183
A reader MUST check that the SHA-2 256 in the `h` field exactly
@@ -172,8 +189,8 @@ performing signature recovery if a valid `n` field is provided.
172
189
### Rationale
173
190
174
191
The type-and-length format allows future extensions to be backward
175
-
compatible. `data_length` is always a multiple of 5 bits, for easy
176
-
encoding and decoding. For fields we expect may change, readers
192
+
compatible. `data_length` is always a multiple of 5 bits, for easy
193
+
encoding and decoding. For fields that we expect may change, readers
177
194
also ignore ones of different length.
178
195
179
196
The `p` field supports the current 256-bit payment hash, but future
@@ -183,27 +200,27 @@ the one not the correct length.
183
200
184
201
The `d` field allows inline descriptions, but may be insufficient for
185
202
complex orders; thus the `h` field allows a summary, though the method
186
-
by which the description is served is as-yet unspecified, and will
187
-
probably be transport-dependent. The `h` format could change in future
188
-
by changing the length, so readers ignore it if not 256 bits.
203
+
by which the description is served is as-yet unspecified and will
204
+
probably be transportdependent. The `h` format could change in future
205
+
by changing the length, so readers ignore it if it's not 256 bits.
189
206
190
207
The `n` field can be used to explicitly specify the destination node ID,
191
208
instead of requiring signature recovery.
192
209
193
210
The `x` field gives advance warning as to when a payment will be
194
-
refused; this is mainly to avoid confusion. The default was chosen
195
-
to be reasonable for most payments, and allow sufficient time for
211
+
refused; this is mainly to avoid confusion. The default was chosen
212
+
to be reasonable for most payments and to allow sufficient time for
196
213
on-chain payment if necessary.
197
214
198
215
The `c` field gives a way for the destination node to require a specific
199
-
minimum cltv expiry for its incoming HTLC. Destination nodes may use this
216
+
minimum CLTV expiry for its incoming HTLC. Destination nodes may use this
200
217
to require a higher, more conservative value than the default one, depending
201
218
on their fee estimation policy and their sensitivity to time locks. Note
202
-
that other nodes in the route specify their required `cltv_expiry_delta`
219
+
that remote nodes in the route specify their required `cltv_expiry_delta`
203
220
in the `channel_update` message, which they can update at all times.
204
221
205
-
The `f` field allows on-chain fallback. This may not make sense for
206
-
tiny or very time-sensitive payments, however. It's possible that new
222
+
The `f` field allows on-chain fallback. This may not make sense for
223
+
tiny or very time-sensitive payments, however. It's possible that new
207
224
address forms will appear, and so multiple `f` fields in an implied
208
225
preferred order help with transition, and `f` fields with versions 19-31
209
226
will be ignored by readers.
@@ -214,29 +231,29 @@ assist in future partial-knowledge routing.
214
231
215
232
# Payer / Payee Interactions
216
233
217
-
These are generally defined by the rest of the lightning BOLT series,
218
-
but it's worth noting that BOLT #5 specifies that the payee SHOULD
234
+
These are generally defined by the rest of the Lightning BOLT series,
235
+
but it's worth noting that [BOLT #5](05-onchain.md) specifies that the payee SHOULD
219
236
accept up to twice the expected `amount`, so the payer can make
220
237
payments harder to track by adding small variations.
221
238
222
239
The intent is that the payer recover the payee's node ID from the
223
-
signature, and after checking the conditions are acceptable (fees,
224
-
expiry, block timeout), attempt a payment. It can use `r` fields to
240
+
signature, and after checking that conditions such as fees,
241
+
expiry, and block timeout are acceptable, attempt a payment. It can use `r` fields to
225
242
augment its routing information if necessary to reach the final node.
226
243
227
244
If the payment succeeds but there is a later dispute, the payer can
228
-
prove both the signed offer from the payee, and the successful
245
+
prove both the signed offer from the payee and the successful
229
246
payment.
230
247
231
248
## Payer / Payee Requirements
232
249
233
250
A payer SHOULD NOT attempt a payment after the `timestamp` plus
234
-
`expiry` has passed. Otherwise, if a lightning payment fails, a payer
235
-
MAY attempt to use the address given the first `f` field it
236
-
understands for payment. A payer MAY use the sequence of channels
237
-
specified by `r` to route to the payee. A payer SHOULD consider the
238
-
fee amount and payment timeout before initiating payment. A payer
239
-
SHOULD use the first `p` field did not skip as the payment hash.
251
+
`expiry` has passed. Otherwise, if a Lightning payment fails, a payer
252
+
MAY attempt to use the address given in the first `f` field that it
253
+
understands for payment. A payer MAY use the sequence of channels
254
+
specified by the `r`field to route to the payee. A payer SHOULD consider the
255
+
fee amount and payment timeout before initiating payment. A payer
256
+
SHOULD use the first `p` field that it did not skip as the payment hash.
240
257
241
258
A payee SHOULD NOT accept a payment after `timestamp` plus `expiry`.
0 commit comments