From 9dd08ea0dc7a9dab33b87e01c93f6007cb5e592c Mon Sep 17 00:00:00 2001 From: t-bast Date: Tue, 2 Jul 2024 17:21:43 +0200 Subject: [PATCH] blip-0036: on-the-fly channel funding Payments sent to mobile wallets often fail because the recipient doesn't have enough inbound liquidity to receive it. we add a mechanism to create an on-chain transaction on-the-fly before relaying such payments, which allow them to be relayed once the on-chain transaction is accepted by both peers. This protocol uses dual-funding, splicing and liquidity ads, leveraging liquidity ads' extensions for paying funding fees. It is recommended to use 0-conf, to avoid keeping upstream HTLCs held for a long time and locking up liquidity in the network. --- README.md | 17 +- blip-0002.md | 24 +- blip-0036.md | 814 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 841 insertions(+), 14 deletions(-) create mode 100644 blip-0036.md diff --git a/README.md b/README.md index bba6b55..6bdcbee 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,12 @@ published here. For more detail on the process, please read [bLIP-0001](./blip-0001.md) and [bLIP-0002](./blip-0002.md). -| Number | Title | Author | Status | -|--------------------------|---------------------------|-----------------------------|--------| -| [1](./blip-0001.md) | bLIP Process | Ryan Gentry | Active | -| [2](./blip-0002.md) | Reserved Values | Bastien Teinturier | Active | -| [3](./blip-0003.md) | Keysend | Valentine Wallace | Active | -| [10](./blip-0010.md) | Podcasting 2.0 | Satoshis Stream | Active | -| [11](./blip-0011.md) | NameDesc | Hampus Sjöberg | Active | -| [17](./blip-0017.md) | Hosted Channels | Anton Kumaigorodskiy | Active | +| Number | Title | Author | Status | +|--------------------------|--------------------------------|-----------------------------|--------| +| [1](./blip-0001.md) | bLIP Process | Ryan Gentry | Active | +| [2](./blip-0002.md) | Reserved Values | Bastien Teinturier | Active | +| [3](./blip-0003.md) | Keysend | Valentine Wallace | Active | +| [10](./blip-0010.md) | Podcasting 2.0 | Satoshis Stream | Active | +| [11](./blip-0011.md) | NameDesc | Hampus Sjöberg | Active | +| [17](./blip-0017.md) | Hosted Channels | Anton Kumaigorodskiy | Active | +| [36](./blip-0036.md) | On-the-fly channel funding | Bastien Teinturier | Active | diff --git a/blip-0002.md b/blip-0002.md index 15ad52f..fc6c0cb 100644 --- a/blip-0002.md +++ b/blip-0002.md @@ -45,11 +45,12 @@ Custom feature bits used in the `I` [Bolt 11](https://github.com/lightning/bolts bLIPs may reserve feature bits by adding them to the following table: -| Bits | Name | Description | Context | Dependencies | Link | -| --------- | ---------------------- | ------------------------------------------------- | ---------------- | -------------------------------- | -------------------------------- | -| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) | -| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) | -| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) | +| Bits | Name | Description | Context | Dependencies | Link | +| --------- | ---------------------- | ------------------------------------------------- | ---------------- | ----------------------------------- | -------------------------------- | +| 54/55 | `keysend` | A form of spontaneous payment | N | `var_onion_optin` | [bLIP 3](./blip-0003.md) | +| 256/257 | `hosted_channels` | This node accepts requests for hosted channels | IN | | [bLIP 17](./blip-0017.md) | +| 258/259 | `dns_resolver` | This node accepts DNSSEC proof requests | N | | [bLIP 32](./blip-0032.md) | +| 560/561 | `on_the_fly_funding` | On-the-fly channel funding | IN | `option_splice`, `option_will_fund` | [bLIP 36](./blip-0036.md) | ### Messages @@ -61,6 +62,10 @@ bLIPs may create new messages and reserve their type in the following table: | Type | Name | Link | | ------- | ------------------------------- | -------------------------- | +| 41041 | `will_add_htlc` | [bLIP 36](./blip-0036.md) | +| 41042 | `will_fail_htlc` | [bLIP 36](./blip-0036.md) | +| 41043 | `will_fail_malformed_htlc` | [bLIP 36](./blip-0036.md) | +| 41044 | `cancel_on_the_fly_funding` | [bLIP 36](./blip-0036.md) | | 65535 | `invoke_hosted_channel` | [bLIP 17](./blip-0017.md) | | 65533 | `init_hosted_channel` | [bLIP 17](./blip-0017.md) | | 65531 | `last_cross_signed_state` | [bLIP 17](./blip-0017.md) | @@ -103,7 +108,6 @@ The following table contains extension tlv fields for the `payment_onion_payload | 7629169 | `podcasting_2_0` | [bLIP 10](./blip-0010.md) | | 5482373484 | `keysend_preimage` | [bLIP 3](./blip-0003.md) | - #### `ping` The following table contains extension tlv fields for the `ping` message: @@ -112,6 +116,14 @@ The following table contains extension tlv fields for the `ping` message: |-------|-----------------------------|--------------------------------| | 65536 | `tlv_field_name` | Link to the corresponding bLIP | +#### `update_add_htlc` + +The following table contains extension tlv fields for the `update_add_htlc` message: + +| Type | Name | Link | +|-------|-----------------------------|--------------------------------| +| 41041 | `funding_fee` | [bLIP 36](./blip-0036.md) | + ### Onion Messages The following table contains tlv fields for use in onion messages as the payload type: diff --git a/blip-0036.md b/blip-0036.md new file mode 100644 index 0000000..48fb935 --- /dev/null +++ b/blip-0036.md @@ -0,0 +1,814 @@ +``` +bLIP: 36 +Title: On-the-fly channel funding +Status: Active +Author: Bastien Teinturier +Created: 2024-07-02 +License: CC0 +``` + +## Abstract + +Payments sent to mobile wallets often fail because the recipient doesn't have +enough inbound liquidity to receive it. This bLIP adds a mechanism to create +an on-chain transaction on-the-fly before relaying such payments, to allow +them to be relayed once the on-chain transaction is accepted by both peers. + +## Copyright + +This bLIP is licensed under the CC0 license. + +## Motivation + +This mechanism increases the payment success rate, which provides a better +payment experience for end users and ensures that intermediate nodes aren't +missing out on relay and service fees. + +## Specification + +### The `funding_fee` TLV field + +We define a TLV field for `update_add_htlc` that allows a relaying node to +relay a smaller amount than the amount encoded in the onion: + +1. `tlv_stream`: `update_add_htlc_tlvs` +2. types: + 1. type: 41041 (`funding_fee`) + 2. data: + - [`u64`:`fee_msat`] + - [`sha256`:`funding_txid`] + +The amount encoded in the onion will be equal to the sum of the `amount_msat` +field from `update_add_htlc` and `fee_msat`. + +The `funding_txid` field references the funding transaction for which this +HTLC is (partially) paying the fees. + +### Liquidity Ads HTLC payment types + +We define three new liquidity ads `payment_type`s that leverage the +`funding_fee` field above to pay liquidity fees. + +1. `payment_type`: 128 (`from_future_htlc`) +2. data: + - [`...*sha256`:`payment_hashes`] + +When using `from_future_htlc`, the funding fees are not paid during the +`interactive-tx` session, because the buyer doesn't have enough funds to do +so. Fees are instad paid from HTLCs that will be relayed once liquidity has +been added, using the `funding_fee` field. + +In this option, the seller trusts that the buyer will fulfill the HTLCs when +it relays them after the funding transaction is complete. If the buyer doesn't +fulfill, the seller doesn't get paid for the funding transaction. + +1. `payment_type`: 129 (`from_future_htlc_with_preimage`) +2. data: + - [`...*32*byte`:`payment_preimages`] + +The `from_future_htlc_with_preimage` payment type works like `from_future_htlc` +but the preimages are immediately revealed, which ensures that the seller is +paid. The buyer trusts that the seller will relay the corresponding HTLCs after +the funding attempt, otherwise it overpaid for the funding transaction. + +1. `payment_type`: 130 (`from_channel_balance_for_future_htlc`) +2. data: + - [`...*sha256`:`payment_hashes`] + +The `from_channel_balance_for_future_htlc` payment type is used when the buyer +has enough funds in an existing channel to pay the funding fees for a splice +from its channel balance. This is the preferred option that doesn't require +trust from the buyer or the seller. + +### On-the-fly funding messages + +We introduce lightning messages that are similar to HTLC messages, but aren't +tied to a specific channel when liquidity is missing to relay a payment. + +1. type: 41041 (`will_add_htlc`) +2. data: + - [`chain_hash`:`chain_hash`] + - [`32*byte`:`id`] + - [`u64`:`amount_msat`] + - [`sha256`:`payment_hash`] + - [`u32`:`cltv_expiry`] + - [`1366*byte`:`onion_routing_packet`] + - [`will_add_htlc_tlvs`:`tlvs`] + +The `will_add_htlc` message supports the same TLVs as `update_add_htlc`. + +1. `tlv_stream`: `will_add_htlc_tlvs` +2. types: + 1. type: 0 (`blinding_point`) + 2. data: + - [`point`:`blinding`] + +We define a message similar to `update_fail_htlc`. + +1. type: 41042 (`will_fail_htlc`) +2. data: + - [`32*byte`:`id`] + - [`sha256`:`payment_hash`] + - [`u16`:`len`] + - [`len*byte`:`reason`] + +And another message similar to `update_fail_malformed_htlc`. + +1. type: 41043 (`will_fail_malformed_htlc`) +2. data: + - [`32*byte`:`id`] + - [`sha256`:`payment_hash`] + - [`sha256`:`sha256_of_onion`] + - [`u16`:`failure_code`] + +When rejecting an on-the-fly `open_channel2` or `splice_init`, we use an +explicit message instead of `error` or `tx_abort`. + +1. type: 41044 (`cancel_on_the_fly_funding`) +2. data: + - [`32*byte`:`channel_id`] + - [`u16`:`payment_hashes_count`] + - [`payment_hashes_count*sha256`:`payment_hashes`] + - [`u16`:`reason_len`] + - [`reason_len*byte`:`reason`] + +### Requirements + +The sending node: + +- SHOULD send `will_add_htlc` if it doesn't have enough channel balance to send `update_add_htlc`. +- When sending `will_add_htlc`: + - MUST NOT fail the matching upstream HTLC(s). + - MUST start a `will_add_htlc_timeout` timer associated with that `payment_hash`. + - If a `will_add_htlc_timeout` timer was already running for that `payment_hash`: + - MUST restart it. + - SHOULD set `will_add_htlc_timeout` to at least 90 seconds (greater than the MPP timeout). + - If the `will_add_htlc_timeout` timer expires before signing a matching funding transaction: + - MUST fail all matching upstream HTLCs. + - MUST forget all `will_add_htlc` associated with that `payment_hash`. + - SHOULD send a `warning` to its peer. +- When receiving `open_channel2` containing `request_funding`: + - If a channel already exists with that peer: + - MAY reject the funding attempt in favor of a splice on the existing channel. + - If the `payment_type` is `from_future_htlc` or `from_future_htlc_with_preimage`: + - If the matching `will_add_htlc`s cannot pay the liquidity fees or if `request_funding` is smaller + than the `will_add_htlc`s total amount: + - MUST send `cancel_on_the_fly_funding`. + - MUST discard the matching `will_add_htlc`s. + - MUST fail all matching upstream HTLCs. + - MUST cancel the `will_add_htlc_timeout` timer associated with those `payment_hash`es. + - Otherwise: + - SHOULD allow the sender to contribute nothing to the funding transaction if combined + with [bLIP 33](./blip-0033.md). + - MUST respond with `accept_channel2` including the `provide_funding` field. + - If the `will_add_htlc_timeout` timer expires before exchanging `commitment_signed`: + - MUST cancel the channel funding attempt. + - MUST fail all matching upstream HTLCs. + - MUST forget all `will_add_htlc` associated with those `payment_hash`es. + - After exchanging `commitment_signed` for the funding transaction: + - MUST cancel the `will_add_htlc_timeout` timer associated with those `payment_hash`es. + - If one of the offered `will_add_htlc` is close to its CLTV expiry: + - MUST cancel the channel funding attempt if it hasn't been signed yet. + - MUST fail all matching upstream HTLCs. + - MUST forget all `will_add_htlc` associated with those `payment_hash`es. + - After exchanging `channel_ready`: + - MUST relay the HTLCs matching those `payment_hash`es. + - MUST set `funding_fee` in `update_add_htlc` to collect the liquidity fees. + - MUST set `funding_fee`, even if `fees_msat` is `0 msat`. + - SHOULD split the funding fee across multiple HTLCs if necessary. + - If the receiver fails those HTLCs: + - SHOULD retry HTLC relay until it gets too close to the CLTV expiry. + - MAY blacklist that node and close the channel whenever possible if that doesn't work. +- When receiving `splice_init` containing `request_funding`: + - If the sender has enough channel balance to pay the liquidity fees: + - SHOULD reject `splice_init` if it doesn't use the `from_channel_balance_for_future_htlc` payment type. + - MUST send `cancel_on_the_fly_funding` if it rejects `splice_init`. + - If the `payment_type` is `from_future_htlc` or `from_future_htlc_with_preimage`: + - MUST apply similar requirements as `open_channel2` above. + - After exchanging `splice_locked`: + - MUST relay the HTLCs matching those `payment_hash`es. + - MUST set `funding_fee` in `update_add_htlc` to collect the liquidity fees. + - MUST set `funding_fee`, even if `fees_msat` is `0 msat`. + - SHOULD split the funding fee across multiple HTLCs if necessary. + - If the receiver fails those HTLCs: + - SHOULD retry HTLC relay until it gets too close to the CLTV expiry. + - MAY blacklist that node and close the channel whenever possible. +- On disconnection or restart: + - If no funding transaction was signed that matches the pending `will_add_htlc`: + - MUST cancel the `will_add_htlc_timeout` timer. + - MUST forget all `will_add_htlc` associated with that `payment_hash`. + - MUST fail all matching upstream HTLCs. + - Otherwise: + - SHOULD retry HTLC relay until it gets too close to the CLTV expiry. + - If one of the offered `will_add_htlc` is close to its CLTV expiry: + - MUST fail all matching upstream HTLCs. + - MUST forget all `will_add_htlc` associated with those `payment_hash`es. + - MAY blacklist that node and close the channel whenever possible. + +The receiving node: + +- SHOULD use a large enough `min_final_expiry_delta` to allow funding to complete before receiving HTLCs. +- MUST process `will_add_htlc` as if it were a normal HTLC. +- MUST use the latest `funding_rates` it has received from the sending node. +- If it would have failed that HTLC: + - MUST send `will_fail_htlc` or `will_fail_malformed_htlc`. + - MUST forget this `will_add_htlc`. +- If the funding fee is too high: + - MUST fail the corresponding `will_add_htlc`. +- Otherwise, if wants to accept that payment: + - If it has enough channel balance to pay the funding fee: + - MUST send `splice_init` using the `from_channel_balance_for_future_htlc` payment type. + - When receiving the matching `update_add_htlc`: + - MUST reject them if `funding_fee.fees_msat` is not `0 msat`. + - Otherwise: + - MUST send `open_channel2` or `splice_init` using `from_future_htlc` or `from_future_htlc_with_preimage`. + - After exchanging `commitment_signed` for the funding transaction: + - MUST NOT send `will_fail_htlc` or `will_fail_malformed_htlc` for those `will_add_htlc`. + - MUST persist the liquidity fees owed for this funding transaction and the corresponding `payment_hash`es. + - When receiving the matching `update_add_htlc`: + - If the total `funding_fee.fees_msat` exceeds the expected fee: + - MUST fail those `update_add_htlc`. + - Otherwise: + - MUST fulfill those `update_add_htlc`. + - When receiving `cancel_on_the_fly_funding`: + - MUST consider the funding attempt for the corresponding `payment_hash`es failed. + +### Rationale + +On-the-fly funding should be used with 0-conf: this ensures that upstream +HTLCs aren't held for long periods of time before settling them. + +It is recommended to use a single channel per peer, which makes it easier +to prevent duplicate payments and race conditions (and minimizes on-chain +fees over the channel's lifetime). + +If relaying HTLCs after funding the channel fails, this doesn't always mean +that the buyer is malicious: other unrelated HTLCs may have been concurrently +relayed which consumed the added liquidity. We recommend retrying relay when +liquidity is available again before deciding whether the peer is malicious +or not. + +We always set `funding_fee`, even for `from_channel_balance_for_future_htlc`. +This makes it easier to detect on-the-fly HTLCs and ensure consistency between +the sender and the receiver. + +We provide both `from_future_htlc` and `from_future_htlc_with_preimage` to +allow buyers and sellers to choose the trust trade-offs they are comfortable +with. Note that both of those may be avoided entirely by restricting payments +to `from_channel_balance_for_future_htlc` (at the cost of requiring on-chain +funds from the buyer for the initial channel creation). + +### On-the-fly funding examples + +This section contains protocol flows that show how messages are exchanged in +various common scenarios. This is also a good check-list to verify that your +implementation correctly handles known edge cases. + +Note that we omit the `commit_sig` / `revoke_and_ack` messages exchanged +between Bob and Carol for simplicity. + +#### On-the-fly channel creation + +In this example, Alice and Bob don't have a channel yet. Bob receives two HTLCs +that should be relayed to Alice. Those two HTLCs may or may not use the same +`payment_hash`. + +After successfully creating the channel, Bob relays the HTLCs and splits the +funding fee. If the HTLC amount allows it, Bob may claim the entire funding +fee in only one of the HTLCs. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | open_channel2 | | + | (from_future_htlc) | | + |----------------------------->| | + | accept_channel2 | | + | (will_fund) | funding_fee = 1200 sat | + |<-----------------------------| | + | | | + | | | + | | | + | channel_ready | | + |----------------------------->| | + | channel_ready | | + |<-----------------------------| | + | | | + | | | + | | | + | update_add_htlc | | + | (funding_fee = 700 sat) | | + |<-----------------------------| | + | update_add_htlc | | + | (funding_fee = 500 sat) | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | update_fulfill_htlc | | + |----------------------------->| | + | update_fulfill_htlc | | + |----------------------------->| update_fulfill_htlc | + | commit_sig |----------------------------->| + |----------------------------->| update_fulfill_htlc | + | revoke_and_ack |----------------------------->| + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | | +``` + +#### On-the-fly splicing using channel balance + +In this example, Alice and Bob already have a channel, but all of the channel +liquidity is on Alice's side. Alice thus has enough channel balance to pay the +funding fee via the splice transaction. The `splice_init` message she sends to +Bob uses `from_channel_balance_for_future_htlc`. When relaying the HTLCs after +sending `splice_locked`, Bob doesn't need to claim the funding fee since he has +already been paid. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | stfu | | + |----------------------------->| | + | stfu | | + |<-----------------------------| | + | splice_init | | + |----------------------------->| | + | splice_ack | | + | (will_fund) | | + |<-----------------------------| | + | | | + | | | + | | | + | splice_locked | | + |----------------------------->| | + | splice_locked | | + |<-----------------------------| | + | | | + | | | + | | | + | update_add_htlc | | + |<-----------------------------| | + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | update_fulfill_htlc | | + |----------------------------->| | + | update_fulfill_htlc | | + |----------------------------->| update_fulfill_htlc | + | commit_sig |----------------------------->| + |----------------------------->| update_fulfill_htlc | + | revoke_and_ack |----------------------------->| + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | | +``` + +#### On-the-fly splicing without channel balance + +In this example, Alice and Bob already have a channel. Alice doesn't have +enough channel balance to pay the funding fee, and Bob doesn't have enough +channel balance to relay the HTLCs coming from Carol. + +After exchanging `splice_locked`, Bob relays the HTLCs and splits the funding +fee. If the HTLC amount allows it, Bob may claim the entire funding fee in +only one of the HTLCs. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | stfu | | + |----------------------------->| | + | stfu | | + |<-----------------------------| | + | splice_init | | + | (from_future_htlc) | | + |----------------------------->| | + | splice_ack | | + | (will_fund) | funding_fee = 1500 sat | + |<-----------------------------| | + | | | + | | | + | | | + | splice_locked | | + |----------------------------->| | + | splice_locked | | + |<-----------------------------| | + | | | + | | | + | | | + | update_add_htlc | | + | (funding_fee = 650 sat) | | + |<-----------------------------| | + | update_add_htlc | | + | (funding_fee = 850 sat) | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | update_fulfill_htlc | | + |----------------------------->| | + | update_fulfill_htlc | | + |----------------------------->| update_fulfill_htlc | + | commit_sig |----------------------------->| + |----------------------------->| update_fulfill_htlc | + | revoke_and_ack |----------------------------->| + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | | +``` + +#### Reject on-the-fly funding + +In this example, Alice receives a multi-part payment that can be partially +relayed with HTLCs. The remaining part requires on-the-fly funding, but Alice +rejects it (e.g. the funding fee is too high). + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | will_fail_htlc | | + |----------------------------->| | + | | update_fail_htlc | + | |----------------------------->| + | | | + | | | + | | | + | update_fail_htlc | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | update_fail_htlc | + | |----------------------------->| + | | | +``` + +#### On-the-fly funding timeout + +In this example, Alice receives a multi-part payment with one normal HTLC and +the remaining part as an on-the-fly funding proposal. Alice accepts the funding +proposal, but Bob times out before receiving Alice's response. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | stfu | | + |----------------------------->| | + | stfu | | + |<-----------------------------| | + | | | + | | | + | | | + | warning | | + | <-----------| update_fail_htlc | + | splice_init |----------------------------->| + |---------------> | | + | warning | | + |<----------- | | + | splice_init | | + | --------------->| | + | cancel_on_the_fly_funding | | + |<-----------------------------| | + | | | + | | | + | | | + | update_fail_htlc | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | update_fail_htlc | + | |----------------------------->| + | | | +``` + +#### On-the-fly funding with HTLCs timing out + +In this example, Alice accepts an on-the-fly funding proposal, but doesn't send +`channel_ready`. The upstream HTLC times out, which forces Bob to fail them. At +that point, Bob cannot relay the HTLC to Alice anymore, and wasn't paid for the +channel funding. Bob may require using `from_future_htlc_with_preimage` instead +of `from_future_htlc` to protect against this issue. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | open_channel2 | | + | (from_future_htlc) | | + |----------------------------->| | + | accept_channel2 | | + | (will_fund) | | + |<-----------------------------| | + | | | + | | | + | | | + | channel_ready | | + |<-----------------------------| | + | | | + | | | + | | | + | | update_fail_htlc | + | |----------------------------->| + | warning | | + |<-----------------------------| | + | channel_ready | | + |----------------------------->| | + | | | + | | | + | | | +``` + +#### Disconnection before signing funding transaction + +In this example, Alice and Bob are disconnected before completing the funding +transaction. The funding attempt is aborted, and the matching upstream HTLC +are failed. Once the MPP timeout hits, Alice fails the first payment part that +was relayed with a normal HTLC. + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | stfu | | + |----------------------------->| | + | stfu | | + |<-----------------------------| | + | splice_init | | + | (from_future_htlc) | | + |----------------------------->| | + | splice_ack | | + | (will_fund) | | + |<-----------------------------| | + | | | + | | update_fail_htlc | + | |----------------------------->| + | channel_reestablish | | + |<-----------------------------| | + | channel_reestablish | | + |----------------------------->| | + | | | + | | | + | | | + | update_fail_htlc | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | update_fail_htlc | + | |----------------------------->| + | | | +``` + +#### Disconnection after signing funding transaction + +In this example, Alice and Bob are disconnected after completing the funding +transaction. Bob must keep track of the HTLCs that need to be relayed when +reconnecting (unless the upstream HTLCs timeout before that). + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | open_channel2 | | + | (from_future_htlc) | | + |----------------------------->| | + | accept_channel2 | | + | (will_fund) | | + |<-----------------------------| | + | | | + | | | + | | | + | channel_ready | | + |-----------------X | | + | | | + | | | + | | | + | channel_reestablish | | + |<-----------------------------| | + | channel_reestablish | | + |----------------------------->| | + | | | + | | | + | | | + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | update_fulfill_htlc | | + |----------------------------->| update_fulfill_htlc | + | commit_sig |----------------------------->| + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | | +``` + +#### Disconnection after relaying post-funding HTLCs + +In this example, Alice and Bob are disconnected after completing the funding +transaction and trying to relay the corresponding HTLCs. Bob must keep track +of those HTLCs and relay them again when reconnecting (unless the upstream +HTLCs timeout before that). + +```txt + Alice Bob Carol + | | update_add_htlc | + | |<-----------------------------| + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | | update_add_htlc | + | |<-----------------------------| + | will_add_htlc | | + |<-----------------------------| | + | stfu | | + |----------------------------->| | + | stfu | | + |<-----------------------------| | + | splice_init | | + | (from_future_htlc) | | + |----------------------------->| | + | splice_ack | | + | (will_fund) | | + |<-----------------------------| | + | | | + | | | + | | | + | splice_locked | | + |<-----------------------------| | + | splice_locked | | + |----------------------------->| | + | | | + | | | + | | | + | update_add_htlc | | + | X-------------------| | + | | | + | | | + | | | + | channel_reestablish | | + |<-----------------------------| | + | channel_reestablish | | + |----------------------------->| | + | | | + | | | + | | | + | update_add_htlc | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | commit_sig | | + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | update_fulfill_htlc | | + |----------------------------->| update_fulfill_htlc | + | update_fulfill_htlc |----------------------------->| + |----------------------------->| update_fulfill_htlc | + | commit_sig |----------------------------->| + |----------------------------->| | + | revoke_and_ack | | + |<-----------------------------| | + | commit_sig | | + |<-----------------------------| | + | revoke_and_ack | | + |----------------------------->| | + | | | +``` + +## Reference Implementations + +- eclair: +- lightning-kmp: