Extensible liquidity ads rates

01-messaging.md

@@ -283,10 +283,18 @@ The `features` field MUST be padded to bytes with 0s.
     1. type: 3 (`remote_addr`)
     2. data:
         * [`...*byte`:`data`]
+    1. type: 5 (`option_will_fund`)
+    2. data:
+        * [`will_fund_rates`:`will_fund_rates`]
 
 The optional `networks` indicates the chains the node is interested in.
+
 The optional `remote_addr` can be used to circumvent NAT issues.
 
+`option_will_fund` allows nodes to announce their willingness to provide funding
+to other nodes using one of the included lease rates, as described in the
+[liquidity ads section](07-routing-gossip.md#liquidity-ads).
+
 #### Requirements
 
 The sending node:

02-peer-protocol.md

@@ -1171,6 +1171,9 @@ This message initiates the v2 channel establishment workflow.
    2. data:
         * [`...*byte`:`type`]
    1. type: 2 (`require_confirmed_inputs`)
+   1. type: 3 (`request_funding`)
+   2. data:
+        * [`request_funds`:`request_funds`]
 
 Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message),
 with the following additions.
@@ -1185,11 +1188,18 @@ The sending node:
   - MUST set `funding_feerate_perkw` to the feerate for this transaction
   - If it requires the receiving node to only use confirmed inputs:
     - 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 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.
 
 The receiving node:
   - MAY fail the negotiation if:
     - the `locktime` is unacceptable
     - the `funding_feerate_perkw` is unacceptable
+    - `request_funds.funding_lease` does not match a lease it advertised.
   - MUST fail the negotiation if:
     - `require_confirmed_inputs` is set but it cannot provide confirmed inputs
 
@@ -1258,6 +1268,9 @@ acceptance of the new channel.
    2. data:
         * [`...*byte`:`type`]
    1. type: 2 (`require_confirmed_inputs`)
+   1. type: 3 (`provide_funding`)
+   2. data:
+        * [`will_fund`:`will_fund`]
 
 Rationale and Requirements are the same as listed above,
 for [`accept_channel`](#the-accept_channel-message) with the following
@@ -1270,10 +1283,30 @@ The accepting node:
   - MAY respond with a `funding_satoshis` value of zero.
   - If it requires the opening node to only use confirmed inputs:
     - MUST set `require_confirmed_inputs`
+  - If the `request_funding` TLV was sent in `open_channel2`:
+    - If it does not want to contribute funds or to be paid for its
+      funding contributions:
+      - SHOULD omit the `provide_funding` TLV.
+    - Otherwise, if it decides to be paid for its contributions:
+      - MUST include the `provide_funding` TLV.
+      - MUST set `funding_satoshis` to a value greater than `0`.
+      - MAY set `funding_satoshis` less or more than `requested_sats`.
+      - MUST fill the `provide_funding` TLV with a lease witness that
+        matches the lease from `request_funds` ([liquidity ads](07-routing-gossip.md#liquidity-ads)).
 
 The receiving node:
+  - MAY fail the negotiation if:
+    - It sent `request_funding` and `provide_funding` is not set.
+    - It sent `request_funding` and `provide_funding` is set and:
+      - `funding_satoshis` is smaller than requested.
   - MUST fail the negotiation if:
     - `require_confirmed_inputs` is set but it cannot provide confirmed inputs
+    - `provide_funding` is set but `request_funding` was not sent in `open_channel2`.
+    - `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 using the `payment_type` selected,
+    as detailed in the [liquidity ads section](07-routing-gossip.md#liquidity-ads).
 
 #### Rationale
 
@@ -1286,6 +1319,14 @@ Instead, the channel reserve is fixed at 1% of the total channel balance
 rounded down to the nearest whole satoshi or the `dust_limit_satoshis`,
 whichever is greater.
 
+If the opener sent `request_funding` in their `open_channel2` message, the
+accepter node may choose to contribute funds, but they don't have to.
+
+If the accepter node has run out of available funds, they should either fail
+the negotiation or reply with a `funding_satoshis` set to `0` and omit the
+`provide_funding` TLV, allowing the opener to decide whether they want to
+proceed anyway or fail the negotiation.
+
 ### Funding Composition
 
 Funding composition for channel establishment v2 makes use of the

07-routing-gossip.md

@@ -33,6 +33,7 @@ To support channel and node discovery, three *gossip messages* are supported:
   * [HTLC Fees](#htlc-fees)
   * [Pruning the Network View](#pruning-the-network-view)
   * [Recommendations for Routing](#recommendations-for-routing)
+  * [Liquidity Ads](#liquidity-ads)
   * [References](#references)
 
 ## Definition of `short_channel_id`
@@ -270,6 +271,13 @@ nodes not associated with an already known channel are ignored.
    * [`32*byte`:`alias`]
    * [`u16`:`addrlen`]
    * [`addrlen*byte`:`addresses`]
+   * [`node_announcement_tlvs`:`tlvs`]
+
+1. `tlv_stream`: `node_announcement_tlvs`
+2. types:
+    1. type: 1 (`option_will_fund`)
+    2. data:
+        * [`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
@@ -280,6 +288,10 @@ connections: it contains a series of `address descriptor`s for connecting to the
 node. The first byte describes the address type and is followed by the
 appropriate number of bytes for that type.
 
+`option_will_fund` allows nodes to announce their willingness to provide funding
+to other nodes using one of the included lease rates, as described in the
+[liquidity ads section](#liquidity-ads).
+
 The following `address descriptor` types are defined:
 
    * `1`: ipv4; data = `[4:ipv4_addr][2:port]` (length 6)
@@ -323,6 +335,10 @@ The origin node:
   bits it sets.
   - SHOULD not announce a Tor v2 onion service.
   - MUST NOT announce more than one `type 5` DNS hostname.
+  - If it includes `option_will_fund`:
+    - MAY include multiple lease types, if it supports them.
+    - MAY include multiple lease rates for every lease type it supports.
+    - SHOULD NOT include more than 10 different lease rates.
 
 The receiving node:
   - if `node_id` is NOT a valid compressed public key:
@@ -1136,6 +1152,181 @@ A->D's `update_add_htlc` message would be:
 And D->C's `update_add_htlc` would again be the same as B->C's direct payment
 above.
 
+## Liquidity Ads
+
+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.
+
+1. `lease_type`: 0 (`basic_funding_lease`)
+2. data:
+    * [`u32`:`min_lease_amount_sat`]
+    * [`u32`:`max_lease_amount_sat`]
+    * [`u16`:`funding_weight`]
+    * [`u16`:`lease_fee_basis`]
+    * [`tu32`:`lease_fee_base_sat`]
+
+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`]
+    * [`funding_lease`:`funding_lease`]
+    * [`payment_type`:`payment_type`]
+
+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:
+    * [`lease_witness`:`lease_witness`]
+    * [`signature`:`signature`]
+
+### Requirements
+
+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
+
+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:
+
+* a fixed amount: `lease_fee_base_sat`
+* a proportional amount based on the seller's `funding_amount`:
+  * `paid_funding_contribution = min(funding_amount, request_funds.requested_sats)`
+  * `lease_fee_proportional_sat = paid_funding_contribution * lease_fee_basis / 10_000`
+* a contribution to the on-chain fees paid by the seller:
+  * `lease_fee_mining_sat = funding_weight * funding_feerate_perkw / 1000`
+
+The lease fee is then:
+
+    lease_fee_total = lease_fee_base_sat + lease_fee_proportional_sat + lease_fee_mining_sat
+
+The seller provides an ECDSA signature in `will_fund` using the private key
+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.
+
+#### Requirements
+
+A node selling a `basic_funding_lease`:
+  - MUST set `min_lease_amount_sat` and `max_lease_amount_sat` to the minimum
+    and maximum amount it will contribute at this rate.
+  - MUST set `lease_fee_base_sat` to the base fee (in satoshi) it will charge.
+  - MUST set `lease_fee_basis` to the amount it will charge per contributed
+    satoshi (in basis points, ie 1/10_000).
+  - MUST set `funding_weight` to the transaction weight that will be charged.
+    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:
+
+	funding_weight = 444
+	lease_fee_base_sat = 233 sats
+	lease_fee_basis = 22
+
+The lease fee is:
+
+	lease_fee_base_sat = 233 sats
+	lease_fee_proportional_sat = min(1_000_000, 1_100_000) * 22 / 10_000 = 2200 sats
+	lease_fee_mining_sat = 444 * 2500 / 1000 = 1110 sats
+	lease_fee_total = 3543 sats
+
+The outputs to the peers in the commitment transaction will be
+
+	to-buyer:     500_000 sats
+	to-seller: 1_103_543 sats
+
+The miner fee for the buyer will be `720 * 2500 / 1000 = 1800 sats`.
+
+Minimum funds that the buyer must contribute to the funding transaction:
+
+	open_channel2.funding_satoshis: 500_000 sats
+	lease fee:                        3_543 sats
+	miner fee:                        1_800 sats
+	total required contribution:    505_343 sats
+
+Minimum funds that the seller must contribute to the funding transaction:
+
+	accept_channel2.funding_satoshis: 1_100_000 sats
+	miner fee [1]:                        1_110 sats
+	total required contribution:      1_101_110 sats
+
+[1] assumes `funding_weight = 444` is their total weight for this transaction.
+
+## References
 
 ![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png "License CC-BY")
 <br>