From 274c0c0e08c65e9e0964663e2061d73ff80997fe Mon Sep 17 00:00:00 2001 From: t-bast Date: Wed, 26 Oct 2022 10:21:06 +0200 Subject: [PATCH] Clarify failure requirements And make `total_amount_msat` mandatory. --- 02-peer-protocol.md | 33 +++++++++++++++------------------ 04-onion-routing.md | 12 +++++++----- 2 files changed, 22 insertions(+), 23 deletions(-) diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 4a8a01989..d5dc407de 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -1141,6 +1141,16 @@ A node: commitment transactions: - MUST NOT send an `update_fulfill_htlc`, `update_fail_htlc`, or `update_fail_malformed_htlc`. + - When failing an incoming HTLC: + - If `current_blinding_point` is set in the onion payload: + - MUST send an `update_fail_htlc` error using the + `invalid_onion_blinding` failure code with the `sha256_of_onion` + of the onion it received, for any local or downstream errors. + - SHOULD add a random delay before sending `update_fail_htlc`. + - If `blinding_point` is set in the incoming `update_add_htlc`: + - MUST send an `update_fail_malformed_htlc` error using the + `invalid_onion_blinding` failure code with the `sha256_of_onion` + of the onion it received, for any local or downstream errors. A receiving node: - if the `id` does not correspond to an HTLC in its current commitment transaction: @@ -1157,23 +1167,10 @@ A receiving node: - if the `sha256_of_onion` in `update_fail_malformed_htlc` doesn't match the onion it sent: - MAY retry or choose an alternate error response. - - a receiving node which has an outgoing HTLC canceled by `update_fail_htlc`: - - if `current_blinding_point` is set in the onion payload of the corresponding incoming HTLC: - - MUST return an `update_fail_malformed_htlc` error using the - `invalid_onion_blinding` failure code, with the `sha256_of_onion` - of the onion it received. - - SHOULD add a random delay before sending `update_fail_malformed_htlc`. - - a receiving node which has an outgoing HTLC canceled by `update_fail_malformed_htlc`: - - if it is part of a blinded route: - - MUST return an `update_fail_malformed_htlc` error using the - `invalid_onion_blinding` failure code, with the `sha256_of_onion` - of the onion it received. - - If its onion payload contains `current_blinding_point`: - - SHOULD add a random delay before sending `update_fail_malformed_htlc`. - - otherwise: - - MUST return an error in the `update_fail_htlc` sent to the link which - originally sent the HTLC, using the `failure_code` given and setting the - data to `sha256_of_onion`. + - otherwise, a receiving node which has an outgoing HTLC canceled by `update_fail_malformed_htlc`: + - MUST return an error in the `update_fail_htlc` sent to the link which + originally sent the HTLC, using the `failure_code` given and setting the + data to `sha256_of_onion`. #### Rationale @@ -1193,7 +1190,7 @@ errors. However, without re-checking the actual encrypted packet sent, it won't know whether the error was its own or the remote's; so such detection is left as an option. -Nodes inside a blinded route must use `update_fail_malformed_htlc` to avoid +Nodes inside a blinded route must use `invalid_onion_blinding` to avoid leaking information to senders trying to probe the blinded route. ### Committing Updates So Far: `commitment_signed` diff --git a/04-onion-routing.md b/04-onion-routing.md index ba063dd3b..a62995650 100644 --- a/04-onion-routing.md +++ b/04-onion-routing.md @@ -263,8 +263,7 @@ The writer of `tlv_payload`: - For the first node in the blinded route: - MUST include the `blinding_point` provided by the recipient in `current_blinding_point` - If it is the final node: - - MUST include `amt_to_forward` and `outgoing_cltv_value`. - - MUST include `total_amount_msat` when using `basic_mpp`. + - MUST include `amt_to_forward`, `outgoing_cltv_value` and `total_amount_msat`. - MUST NOT include any other tlv field. - For every node outside of a blinded route: - MUST include `amt_to_forward` and `outgoing_cltv_value`. @@ -312,11 +311,12 @@ The reader: - `outgoing_cltv_value = cltv_expiry - payment_relay.cltv_expiry_delta` - If it is the final node: - MUST return an error if the payload contains other tlv fields than `encrypted_recipient_data`, `current_blinding_point`, `amt_to_forward`, `outgoing_cltv_value` and `total_amount_msat`. - - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present. + - MUST return an error if `amt_to_forward`, `outgoing_cltv_value` or `total_amount_msat` are not present. - MUST return an error if `amt_to_forward` is below what it expects for the payment. - MUST return an error if incoming `cltv_expiry` < `outgoing_cltv_value`. - MUST return an error if incoming `cltv_expiry` < `current_block_height` + `min_final_cltv_expiry_delta`. - Otherwise (it is not part of a blinded route): + - MUST return an error if `blinding_point` is set in the incoming `update_add_htlc` or `current_blinding_point` is present. - MUST return an error if `amt_to_forward` or `outgoing_cltv_value` are not present. - if it is not the final node: - MUST return an error if: @@ -1037,8 +1037,10 @@ The _erring node_: - SHOULD set `pad` such that the `failure_len` plus `pad_len` is equal to 256. - Note: this value is 118 bytes longer than the longest currently-defined message. - - If `blinding_point` is set in the incoming `update_add_htlc`: - - MUST return `invalid_onion_blinding` for any local error or other downstream errors. + - If `blinding_point` is set in the incoming `update_add_htlc` or + `current_blinding_point` is set in the onion payload: + - MUST return `invalid_onion_blinding` for any local error or other + downstream errors. The _origin node_: - once the return message has been decrypted: