Introduce a dedicated payment_type field

The previous commits assumed that paying the liquidity fees in a different way than during the `interactive-tx` session would be introduced by creating a new `lease_type`. However, it turns out that in most cases, how the fees are paid is not correlated to the `lease_type`. We thus introduce a dedicated type for payment options. We only define one `payment_type`, where the fees are paid from the buyer's channel balance during the `interactive-tx` session, but it is easy to introduce different `payment_type`s that reuse the existing lease type but pay the fees using pending HTLCs for example.
lightning · May 14, 2024 · b16ddfe · b16ddfe
1 parent 56b8b6a
commit b16ddfe
Show file tree

Hide file tree

Showing 4 changed files with 105 additions and 59 deletions.
diff --git a/01-messaging.md b/01-messaging.md
@@ -285,7 +285,7 @@ The `features` field MUST be padded to bytes with 0s.
         * [`...*byte`:`data`]
     1. type: 5 (`option_will_fund`)
     2. data:
-        * [`will_fund_lease_rates`:`will_fund_lease_rates`]
+        * [`will_fund_rates`:`will_fund_rates`]
 
 The optional `networks` indicates the chains the node is interested in.
 

diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -1190,8 +1190,8 @@ The sending node:
     - MUST set `require_confirmed_inputs`
   - If it wants the receiving node to contribute to the funding transaction
     using `option_will_fund`:
-    - MUST send `request_funding` containing one of the `lease_type`s
-      supported by the receiving node.
+    - MUST send `request_funding` containing one of the `lease_type`s and
+      `payment_type`s supported by the receiving node.
     - MUST set `requested_sats` to the amount of sats it wants to pay for at
       the advertised lease rate.
 
@@ -1305,8 +1305,8 @@ The receiving node:
     - `provide_funding` is set and:
       - the `will_fund.lease_witness` does not match the `request_funds.funding_lease`.
       - the `will_fund.signature` is invalid.
-  - MUST pay fees for the `option_will_fund` amount (if any) as detailed in the
-    [liquidity ads section](07-routing-gossip.md#liquidity-ads).
+  - MUST pay fees for the `option_will_fund` amount using the `payment_type` selected,
+    as detailed in the [liquidity ads section](07-routing-gossip.md#liquidity-ads).
 
 #### Rationale
 

diff --git a/07-routing-gossip.md b/07-routing-gossip.md
@@ -277,7 +277,7 @@ nodes not associated with an already known channel are ignored.
 2. types:
     1. type: 1 (`option_will_fund`)
     2. data:
-        * [`will_fund_lease_rates`:`will_fund_lease_rates`]
+        * [`will_fund_rates`:`will_fund_rates`]
 
 `timestamp` allows for the ordering of messages, in the case of multiple
 announcements. `rgb_color` and `alias` allow intelligence services to assign
@@ -1156,62 +1156,89 @@ above.
 
 Liquidity ads allow nodes to announce their willingness to provide funding to
 other nodes for a fee. Sellers advertise various rates for the liquidity they
-are selling depending on the guarantees offered to buyers.
+are selling.
 
-1. subtype: `will_fund_lease_rates`
+1. `lease_type`: 0 (`basic_funding_lease`)
 2. data:
-    * [`will_fund_lease_rates_tlvs`:`lease_rates`]
+    * [`u32`:`min_lease_amount_sat`]
+    * [`u32`:`max_lease_amount_sat`]
+    * [`u16`:`funding_weight`]
+    * [`u16`:`lease_fee_basis`]
+    * [`tu32`:`lease_fee_base_sat`]
 
-1. `tlv_stream`: `will_fund_lease_rates_tlvs`
-2. types:
-    1. type: 1 (`basic_funding_leases`)
-    2. data:
-        * [`...*basic_funding_lease`:`funding_lease_rates`]
+Each `lease_type` has a matching `lease_witness` that commits to the lease.
+
+1. `lease_type`: 0 (`basic_funding_lease_witness`)
+2. data:
+    * [`...*byte`:`funding_script`]
+
+Lease types and lease witnesses are encoded using the TLV format, using the
+`lease_type` for the type field.
+
+Sellers also define how the fees can be paid by listing the `payment_type`s
+they support.
+
+1. `payment_type`: 0 (`from_channel_balance`)
+
+Payment types are encoded using the TLV format, using the `payment_type` for
+the type field.
+
+Sellers advertize their rates and payment types using `will_fund_rates`.
+
+1. subtype: `will_fund_rates`
+2. data:
+    * [`u16`:`funding_rates_count`]
+    * [`funding_rates_count*funding_lease`:`funding_rates`]
+    * [`u16`:`payment_types_len`]
+    * [`payment_types_len*byte`:`payment_types`]
+
+Buyers select a specific lease and a `payment_type` offered by the seller
+and use `request_funds` to purchase that lease.
 
 1. subtype: `request_funds`
 2. data:
     * [`u64`:`requested_sats`]
-    * [`byte`:`lease_type`]
     * [`funding_lease`:`funding_lease`]
+    * [`payment_type`:`payment_type`]
 
-1. `lease_type`: 1 (`basic_funding_lease`)
-2. data:
-    * [`u32`:`min_lease_amount_sat`]
-    * [`u32`:`max_lease_amount_sat`]
-    * [`u16`:`funding_weight`]
-    * [`u16`:`lease_fee_basis`]
-    * [`u32`:`lease_fee_base_sat`]
+Sellers accept the purchase with `will_fund` containing a signature that
+commits to the lease parameters included in the `lease_witness`.
 
 1. subtype: `will_fund`
 2. data:
-    * [`byte`:`lease_witness_type`]
     * [`lease_witness`:`lease_witness`]
     * [`signature`:`signature`]
 
-1. `lease_witness_type`: 1 (`basic_funding_lease_witness`)
-2. data:
-    * [`u16`:`funding_script_size`]
-    * [`funding_script_size`:`funding_script`]
+### Requirements
 
-Sellers may offer multiple `lease_type`s, described in the following sections.
-Buyers select a specific lease offered by the seller and use `request_funds`
-to purchase that lease. Sellers answer with `will_fund` containing a signature
-that commits to the lease parameters included in the `lease_witness`.
+A node selling liquidity:
+  - MUST advertise its funding rates with `will_fund_rates`:
+    - MUST include a list of `lease_type`s in `funding_rates`.
+    - MUST encode each `funding_lease` using the TLV format.
+    - MAY include multiple `funding_lease`s with the same `lease_type`.
+    - MUST include a `payment_types` bitfield: for each `payment_type` that it
+      supports, the bit at the position matching this type MUST be set.
+  - When receiving `request_funds`:
+    - If the `funding_lease` does not match a lease it offers:
+      - MUST reject the funding attempt.
+    - If the `payment_type` is not supported:
+      - MUST reject the funding attempt.
+    - Otherwise:
+      - MUST send `will_fund` with the `lease_witness` matching the requested
+        `funding_lease` and a signature covering that witness (see below).
+
+A node buying liquidity:
+  - MUST ignore any unknown `lease_type` in `will_fund_rates.funding_rates`.
+  - MUST ignore any unknown `payment_type` in `will_fund_rates.payment_types`.
+  - MUST create `request_funds` with a `funding_lease` from the `funding_rates`
+    and a `payment_type` from the `payment_types` bitfield.
+  - MUST encode `funding_lease` and `payment_type` using the TLV format.
 
 ### The `basic_funding_lease` type
 
-A `basic_funding_lease` does not provide any guarantee that the seller won't
-close the channel or increase their routing fees after the purchase, if the
-liquidity isn't actually used.
-
-When `request_funds` and `will_fund` have been exchanged, the buyer must pay
-fees to the seller for the funding they provide to the channel based on the
-agreed upon `funding_weight`, `lease_fee_basis` and `lease_fee_base_sat`.
-
-The lease fee is taken from the buyer's funding inputs and added to the
-seller's channel balance during the funding flow. The buyer must contribute
-enough funds to cover their channel balance, the lease fee, and the on-chain
-fees for the weight of the funding transaction they're responsible for.
+When `request_funds` and `will_fund` have been exchanged, the buyer agrees to
+pay fees to the seller for the funding they provide to the channel based on
+the proposed `funding_weight`, `lease_fee_basis` and `lease_fee_base_sat`.
 
 The lease fee has three components:
 
@@ -1231,6 +1258,8 @@ associated with their `node_id`. The data signed is:
 
     SHA256("basic_funding_lease" || basic_funding_lease_witness)
 
+The `basic_funding_lease_witness` is encoded using the TLV format.
+
 We use a tagged hash to ensure that this signature cannot be used in a
 different context.
 
@@ -1246,14 +1275,23 @@ A node selling a `basic_funding_lease`:
     It ensures that the funding node is refunded for some of the on-chain
     fees it will pay to contribute the requested funds to a channel.
 
+### The `from_channel_balance` payment type
+
+The lease fee is taken from the buyer's transaction inputs and added to the
+seller's channel balance during the funding flow, using the
+[interactive-tx](./02-peer-protocol.md#interactive-transaction-construction)
+protocol. The buyer must contribute enough funds to cover their channel
+balance, the lease fee, and the on-chain fees for the weight of the funding
+transaction they're responsible for.
+
 #### Example
 
 A node contributes `500_000 sats` to a channel and requests `1_000_000 sats`
 from its peer, at a feerate of `2500 sat/kw`. The total weight of their inputs
 and outputs in the funding transaction is 720. More details about transaction
 weight can be found in the [interactive-tx section](02-peer-protocol.md#interactive-transaction-construction).
 
-The seller contributes `1_100_000 sats` with the following `lease_rate`:
+The seller contributes `1_100_000 sats` with the following lease rate:
 
 	funding_weight = 444
 	lease_fee_base_sat = 233 sats

diff --git a/bolt07/liquidity-ads.json b/bolt07/liquidity-ads.json
@@ -13,30 +13,35 @@
     "timestamp": 1713171401,
     "tlvStream": {
       "option_will_fund": {
-        "basic_funding_leases": [
+        "funding_rates": [
           {
+            "lease_type": "basic",
             "min_lease_amount_sat": 100000,
             "max_lease_amount_sat": 500000,
             "funding_weight": 550,
             "lease_fee_basis": 100,
             "lease_fee_base_sat": 5000,
-            "encoded": "000186a0 0007a120 0226 0064 00001388"
+            "encoded": "00 0e 000186a0 0007a120 0226 0064 1388"
           },
           {
+            "lease_type": "basic",
             "min_lease_amount_sat": 500000,
             "max_lease_amount_sat": 5000000,
             "funding_weight": 1100,
             "lease_fee_basis": 75,
             "lease_fee_base_sat": 0,
-            "encoded": "0007a120 004c4b40 044c 004b 00000000"
+            "encoded": "00 0c 0007a120 004c4b40 044c 004b"
           }
+        ],
+        "payment_types": [
+          "from_channel_balance"
         ]
       }
     },
-    "signature": "e473dd03d777f752252af8c0829bd855cff52e56b45a92b0f26ad39bbbd714971afb3c11f708fd83fe04d39ee403fcd9765cfdb6f8b0e6dce984e50beaa15bcb",
-    "encoded": "0101 e473dd03d777f752252af8c0829bd855cff52e56b45a92b0f26ad39bbbd714971afb3c11f708fd83fe04d39ee403fcd9765cfdb6f8b0e6dce984e50beaa15bcb 0000 661cebc9 03ca9b880627d2d4e3b33164f66946349f820d26aa9572fe0e525e534850cbd413 2a7557 4c4e2d4c69717569646974790000000000000000000000000000000000000000 0000 01 20 000186a0 0007a120 0226 0064 00001388 0007a120 004c4b40 044c 004b 00000000 03 30 03f0 000186a0 000f4240 0258 0096 000003e8 004b 00002710 07e0 0007a120 0016e360 03e8 00fa 00002710 0064 00002710"
+    "signature": "4cdb99cb32b7ac3488e4c039716aa358ddad610436c23bf6b5949754cd09cc30707eccaa1dbc542d9f8fda072d5b6cb2d7b8ee8f87bfab06fdf425145bc1f563",
+    "encoded": "0101 4cdb99cb32b7ac3488e4c039716aa358ddad610436c23bf6b5949754cd09cc30707eccaa1dbc542d9f8fda072d5b6cb2d7b8ee8f87bfab06fdf425145bc1f563 0000 661cebc9 03ca9b880627d2d4e3b33164f66946349f820d26aa9572fe0e525e534850cbd413 2a7557 4c4e2d4c69717569646974790000000000000000000000000000000000000000 0000 01 23 0002 000e000186a00007a120022600641388 000c0007a120004c4b40044c004b 0001 01"
   },
-  "open_channel2_with_basic_lease": {
+  "open_channel2": {
     "chainHash": "6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000",
     "temporaryChannelId": "0100000000000000000000000000000000000000000000000000000000000000",
     "fundingFeerate": 5000,
@@ -61,19 +66,21 @@
     "tlvStream": {
       "request_funding": {
         "requested_sats": 750000,
-        "lease_type": 1,
         "funding_lease": {
+          "lease_type": "basic",
           "min_lease_amount_sat": 500000,
           "max_lease_amount_sat": 5000000,
           "funding_weight": 1100,
           "lease_fee_basis": 75,
           "lease_fee_base_sat": 0
-        }
+        },
+        "payment_type": "from_channel_balance",
+        "encoded": "03 18 00000000000b71b0 000c0007a120004c4b40044c004b 0000"
       }
     },
-    "encoded": "0040 6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000 0100000000000000000000000000000000000000000000000000000000000000 00001388 00000fa0 000000000003d090 00000000000001f4 000000000000c350 000000000000000f 0090 01e3 0009eb10 031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f 024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766 02531fe6068134503d2723133227c867ac8fa6c83c537e9a44c3c5bdbdcb1fe337 03462779ad4aad39514614751a71085f2f10e1c7a593e4e030efb5b8721ce55b0b 0362c0a046dacce86ddd0343c6d3c7c79c2208ba0d9c9cf24a6d046d21d21f90f7 03f006a18d5653c4edf5391ff23a61f03ff83d237e880ee61187fa9f379a028e0a 02989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f 01 03 19 00000000000b71b0 01 0007a120004c4b40044c004b00000000"
+    "encoded": "0040 6fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000 0100000000000000000000000000000000000000000000000000000000000000 00001388 00000fa0 000000000003d090 00000000000001f4 000000000000c350 000000000000000f 0090 01e3 0009eb10 031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f 024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766 02531fe6068134503d2723133227c867ac8fa6c83c537e9a44c3c5bdbdcb1fe337 03462779ad4aad39514614751a71085f2f10e1c7a593e4e030efb5b8721ce55b0b 0362c0a046dacce86ddd0343c6d3c7c79c2208ba0d9c9cf24a6d046d21d21f90f7 03f006a18d5653c4edf5391ff23a61f03ff83d237e880ee61187fa9f379a028e0a 02989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f 01 031800000000000b71b0000c0007a120004c4b40044c004b0000"
   },
-  "accept_channel2_with_basic_lease": {
+  "accept_channel2": {
     "temporaryChannelId": "0100000000000000000000000000000000000000000000000000000000000000",
     "fundingAmount": 700000,
     "dustLimit": 473,
@@ -91,13 +98,14 @@
     "secondPerCommitmentPoint": "02989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f",
     "tlvStream": {
       "provide_funding": {
-        "lease_witness_type": 1,
+        "lease_type": "basic",
         "lease_witness": {
           "funding_script": "00202ec38203f4cf37a3b377d9a55c7ae0153c643046dbdbe2ffccfb11b74420103c"
         },
-        "signature": "2766629334a0cd5a8835fe6fb1790fea7a85da49dab7740d72c8b591247f905a5400c576bd196e9394a92c4340179f0aaf5076b4b4953b3ca2928ded94d1dc8b"
-      },
-      "encoded": "0041 0100000000000000000000000000000000000000000000000000000000000000 00000000000aae60 00000000000001d9 0000000005f5e100 0000000000000001 00000006 0090 0032 031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f 024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766 02531fe6068134503d2723133227c867ac8fa6c83c537e9a44c3c5bdbdcb1fe337 03462779ad4aad39514614751a71085f2f10e1c7a593e4e030efb5b8721ce55b0b 0362c0a046dacce86ddd0343c6d3c7c79c2208ba0d9c9cf24a6d046d21d21f90f7 03f006a18d5653c4edf5391ff23a61f03ff83d237e880ee61187fa9f379a028e0a 02989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f 03 65 01 002200202ec38203f4cf37a3b377d9a55c7ae0153c643046dbdbe2ffccfb11b74420103c 2766629334a0cd5a8835fe6fb1790fea7a85da49dab7740d72c8b591247f905a5400c576bd196e9394a92c4340179f0aaf5076b4b4953b3ca2928ded94d1dc8b"
-    }
+        "signature": "2766629334a0cd5a8835fe6fb1790fea7a85da49dab7740d72c8b591247f905a5400c576bd196e9394a92c4340179f0aaf5076b4b4953b3ca2928ded94d1dc8b",
+        "encoded": "03 64 002200202ec38203f4cf37a3b377d9a55c7ae0153c643046dbdbe2ffccfb11b74420103c 2766629334a0cd5a8835fe6fb1790fea7a85da49dab7740d72c8b591247f905a5400c576bd196e9394a92c4340179f0aaf5076b4b4953b3ca2928ded94d1dc8b"
+      }
+    },
+    "encoded": "0041 0100000000000000000000000000000000000000000000000000000000000000 00000000000aae60 00000000000001d9 0000000005f5e100 0000000000000001 00000006 0090 0032 031b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f 024d4b6cd1361032ca9bd2aeb9d900aa4d45d9ead80ac9423374c451a7254d0766 02531fe6068134503d2723133227c867ac8fa6c83c537e9a44c3c5bdbdcb1fe337 03462779ad4aad39514614751a71085f2f10e1c7a593e4e030efb5b8721ce55b0b 0362c0a046dacce86ddd0343c6d3c7c79c2208ba0d9c9cf24a6d046d21d21f90f7 03f006a18d5653c4edf5391ff23a61f03ff83d237e880ee61187fa9f379a028e0a 02989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f 0364002200202ec38203f4cf37a3b377d9a55c7ae0153c643046dbdbe2ffccfb11b74420103c2766629334a0cd5a8835fe6fb1790fea7a85da49dab7740d72c8b591247f905a5400c576bd196e9394a92c4340179f0aaf5076b4b4953b3ca2928ded94d1dc8b"
   }
 }