From 07f184b387f0c548423baca6d5ce0c423e90519f Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Thu, 12 May 2022 22:52:25 +0000 Subject: [PATCH 1/2] Add an init/node feature for HTLC holding --- 09-features.md | 1 + 1 file changed, 1 insertion(+) 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 From 61a3d904eda463f88fb6b5cea62c304a1f636e31 Mon Sep 17 00:00:00 2001 From: Matt Corallo Date: Fri, 13 May 2022 00:18:49 +0000 Subject: [PATCH 2/2] Add the ability to hold HTLCs before forwarding This is an incredibly simple first start towards the protocol sketched out at [1]. It adds the ability to have a counteraprty hold an HTLC before forwarding it. Specifically, the HTLC sender sets a required TLV on the `update_add_htlc` message and sends an onion message to the final recipient. From there, the final recipient uses the included `reply_path` to notify the sender's counterparty that they're online and ready to receive the HTLC. In order to fully flesh out the protocol as sketched, we'll need to add an onion message mailbox service (which should be as simple as a new feature bit), add PTLCs, and extensions to BOLT 12 to allow signaling that the final recipient is often-offline. While we could add such signaling to BOLT 11, there's not a whole lot of reason to - if the recipient is able to provide an invoice, they're currently online! [1] https://lists.linuxfoundation.org/pipermail/lightning-dev/2021-October/003307.html --- 02-peer-protocol.md | 51 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) 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.