diff --git a/02-peer-protocol.md b/02-peer-protocol.md index 1779b0872..484d092d0 100644 --- a/02-peer-protocol.md +++ b/02-peer-protocol.md @@ -926,6 +926,25 @@ is destined, is described in [BOLT #4](04-onion-routing.md). * [`sha256`:`payment_hash`] * [`u32`:`cltv_expiry`] * [`1366*byte`:`onion_routing_packet`] + * [`update_add_htlc_tlvs`:`tlvs`] + +1. `tlv_stream`: `update_add_htlc_tlvs` +2. types: + 1. type: 0 (`hold_htlc`) + 2. data: + * [`32*bytes`:`payment_release_secret`] + +#### TLV fields for `held_htlc_available` +1. `tlv_stream`: `held_htlc_available` +2. types: + +#### TLV fields for `release_held_htlc` + +1. `tlv_stream`: `release_held_htlc` +2. types: + 1. type: 0 (`payment_release_secret`) + 2. data: + * [`32*bytes`:`payment_release_secret`] #### Requirements @@ -962,6 +981,19 @@ A sending node: - for the first HTLC it offers: - MUST set `id` to 0. - MUST increase the value of `id` by 1 for each successive offer. + - MUST NOT include a `hold_htlc` TLV unless the sending node expects the + final recipient of the HTLC to be offline at the time the HTLC would arrive + - MUST NOT include a `hold_htlc` TLV unless the sending node expects to be + offline for an extended duration starting soon. + - If the `hold_htlc` TLV is present: + - MUST immediately send at least two onion messages across at least two + different paths to the final HTLC recipient. + - Each onion message MUST contain a `held_htlc_available` TLV. + - Each onion message MUST contain a unique `reply_path`s which terminates + at the reciever of the `update_add_htlc` message. + - Each `reply_path` MUST contain a `release_held_htlc` TLV for the + `update_add_htlc` recipient in the `encrypted_data_tlvs` with a + `payment_release_secret` matching that in the `hold_htlc` TLV. `id` MUST NOT be reset to 0 after the update is complete (i.e. after `revoke_and_ack` has been received). It MUST continue incrementing instead. @@ -986,6 +1018,12 @@ A receiving node: - if other `id` violations occur: - MAY send a `warning` and close the connection, or send an `error` and fail the channel. + - if the `hold_htlc` TLV is present: + - MUST NOT forward the HTLC until a corresponding `release_held_htlc` onion + message is received with a matching `payment_release_secret`. + - Upon receipt of a `release_held_htlc` onion message with a matching + `payment_release_secret` the HTLC SHOULD be treated as any HTLC without + the `hold_htlc` TLV and forwarded as usual. The `onion_routing_packet` contains an obfuscated list of hops and instructions for each hop along the path. It commits to the HTLC by setting the `payment_hash` as associated data, i.e. includes the `payment_hash` in the computation of HMACs. @@ -1021,6 +1059,19 @@ maintaining its channel reserve (because of the increased weight of the commitment transaction), resulting in a degraded channel. See [#728](https://github.com/lightningnetwork/lightning-rfc/issues/728) for more details. +For often-offline recipients, e.g. mobile clients, nodes can use the +`hold_htlc` TLV to prevent further forwarding of an HTLC until the recipient +comes online. As long as the final recipients' counterparty is online and +storing onion messages for the recipient, the recipient can reply to the onion +message when they come online, unblock the HTLC, and expect to receive it +quickly thereafter. + +Note that if the sender expects to be online when the recipient comes online, +they can utilize the `release_held_htlc` onion message without utilizing the +`hold_htlc` TLV - they can simply send a `held_htlc_available` onion message +to the final recipient and wait to send any HTLC at all until they receive a +`release_held_htlc` message back. + ### Removing an HTLC: `update_fulfill_htlc`, `update_fail_htlc`, and `update_fail_malformed_htlc` For simplicity, a node can only remove HTLCs added by the other node. diff --git a/09-features.md b/09-features.md index 814094f0d..9cb2d0126 100644 --- a/09-features.md +++ b/09-features.md @@ -43,6 +43,7 @@ The Context column decodes as follows: | 26/27 | `option_shutdown_anysegwit` | Future segwit versions allowed in `shutdown` | IN | | [BOLT #2][bolt02-shutdown] | | 44/45 | `option_channel_type` | Node supports the `channel_type` field in open/accept | IN | | [BOLT #2](02-peer-protocol.md#the-open_channel-message) | | 48/49 | `option_payment_metadata` | Payment metadata in tlv record | 9 | | [BOLT #11](11-payment-encoding.md#tagged-fields) +| 52/53 | `option_htlc_hold` | Hold HTLCs and forward on receipt of an onion message | IN | `option_onion_messages` | ## Definitions