Advertise liquidity ads rates

01-messaging.md

@@ -283,6 +283,9 @@ 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:
+        * [`...*24*byte`:`lease_rates`]
 
 The optional `networks` indicates the chains the node is interested in.
 The optional `remote_addr` can be used to circumvent NAT issues.

02-peer-protocol.md

@@ -44,6 +44,7 @@ operation, and closing.
       * [Completing the Transition to the Updated State: `revoke_and_ack`](#completing-the-transition-to-the-updated-state-revoke_and_ack)
       * [Updating Fees: `update_fee`](#updating-fees-update_fee)
     * [Message Retransmission: `channel_reestablish` message](#message-retransmission)
+    * [Funding Lease Fee](#funding-lease-fee)
   * [Authors](#authors)
 
 # Channel
@@ -1171,6 +1172,11 @@ This message initiates the v2 channel establishment workflow.
    2. data:
         * [`...*byte`:`type`]
    1. type: 2 (`require_confirmed_inputs`)
+   1. type: 3 (`request_funds`)
+   2. data:
+        * [`u64`:`requested_sats`]
+        * [`u16`:`lease_duration`]
+        * [`u32`:`lease_expiry`]
 
 Rationale and Requirements are the same as for [`open_channel`](#the-open_channel-message),
 with the following additions.
@@ -1185,11 +1191,20 @@ 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 set `lease_duration` to one of the lease durations offered by the
+      receiving node in `init` or `node_announcement`.
+    - MUST set `requested_sats` to the amount of sats it wants to pay for at
+      the advertised `lease_rate`.
+    - MUST set `lease_expiry` to be `lease_duration` blocks in the future.
 
 The receiving node:
   - MAY fail the negotiation if:
     - the `locktime` is unacceptable
     - the `funding_feerate_perkw` is unacceptable
+    - `request_funds.lease_duration` does not match a duration it advertised.
+    - `request_funds.lease_expiry` is too far in the past or in the future.
   - MUST fail the negotiation if:
     - `require_confirmed_inputs` is set but it cannot provide confirmed inputs
 
@@ -1258,6 +1273,14 @@ acceptance of the new channel.
    2. data:
         * [`...*byte`:`type`]
    1. type: 2 (`require_confirmed_inputs`)
+   1. type: 3 (`will_fund`)
+   2. data:
+        * [`signature`:`signature`]
+        * [`u16`:`funding_weight`]
+        * [`u16`:`lease_fee_basis`]
+        * [`u32`:`lease_fee_base_sat`]
+        * [`u16`:`max_channel_fee_basis`]
+        * [`u32`:`max_channel_fee_base_msat`]        
 
 Rationale and Requirements are the same as listed above,
 for [`accept_channel`](#the-accept_channel-message) with the following
@@ -1270,10 +1293,36 @@ 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_funds` 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 `will_fund` tlv.
+    - Otherwise, if it decides to be paid for its contributions:
+      - MUST include the `will_fund` tlv.
+      - MUST set `funding_satoshis` to a value greater than `0`.
+      - MAY set `funding_satoshis` less or more than `requested_sats`.
+      - MUST fill the `will_fund` tlv with values from the `lease_rate`
+        that matches the `lease_duration` from `request_funds`.
+      - MUST set `signature` to the ECDSA signature of the SHA256 hash
+        of the corresponding `lease_witness` using the `node_id` key.
 
 The receiving node:
+  - MAY fail the negotiation if:
+    - It sent `request_funds` and `will_fund` is set and:
+      - `funding_satoshis` is smaller than requested.
+  - SHOULD fail the negotiation if:
+    - It sent `request_funds` and `will_fund` is set and:
+      - `funding_weight` is too high.
+      - `lease_fee_basis` is too high.
+      - `lease_fee_base_sat` is too high.
+      - `max_channel_fee_basis` is too high.
+      - `max_channel_fee_base_msat` is too high.
   - MUST fail the negotiation if:
     - `require_confirmed_inputs` is set but it cannot provide confirmed inputs
+    - `will_fund` is set but `request_funds` was not sent in `open_channel2`.
+    - `will_fund` is set but the `signature` is invalid.
+  - MUST pay fees for the `option_will_fund` amount (if any) as detailed in the
+    [funding lease fee section](funding-lease-fee).
 
 #### Rationale
 
@@ -1286,6 +1335,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_funds` 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
+`will_fund` 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
@@ -2578,6 +2635,70 @@ interactive transaction construction, or safely abort that transaction
 if it was not signed by one of the peers, who has thus already removed
 it from its state.
 
+## Funding Lease Fee
+
+When `request_funds` and `will_fund` have been set in `open_channel2` and
+`accept_channel2`, the opener must pay fees to the accepter for the funding
+they provide to the channel based on the agreed upon `lease_rate`.
+
+The lease fee is taken from the opener's funding inputs and added to the
+accepter's channel balance during the funding flow. The opener must contribute
+enough funds to cover `open_channel2.funding_satoshis`, the lease fee, and the
+on-chain fees for the weight of the funding transaction they're responsible for.
+
+The lease fee has three components:
+
+* a fixed amount: `lease_fee_base_sat`
+* a proportional amount based on the accepter's funding contribution:
+  * `paid_funding_contribution = min(accept_channel2.funding_satoshis, open_channel2.requested_sats)`
+  * `lease_fee_proportional_sat = paid_funding_contribution * lease_fee_basis / 10_000`
+* a contribution to the on-chain fees paid by the accepter:
+  * `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`.
+
+### 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](interactive-transaction-construction).
+
+The accepter 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-opener:     500_000 sats
+	to-accepter: 1_103_543 sats
+
+The miner fee for the opener will be `720 * 2500 / 1000 = 1800 sats`.
+
+Minimum funds that the opener 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 accepter 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.
+
 # Authors
 
 [ FIXME: Insert Author List ]

07-routing-gossip.md

@@ -270,6 +270,34 @@ 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:
+       * [`...*24*byte`:`lease_rates`]
+
+1. subtype: `lease_rate`
+2. data:
+   * [`u16`:`lease_duration`]
+   * [`u32`:`min_lease_amount_sat`]
+   * [`u32`:`max_lease_amount_sat`]
+   * [`u16`:`funding_weight`]
+   * [`u16`:`lease_fee_basis`]
+   * [`u32`:`lease_fee_base_sat`]
+   * [`u16`:`max_channel_fee_basis`]
+   * [`u32`:`max_channel_fee_base_msat`]
+
+1. subtype: `lease_witness`
+2. data:
+   * [`16*byte`:`0x6f7074696f6e5f77696c6c5f66756e64`]
+   * [`u16`:`funding_script_size`]
+   * [`funding_script_size`:`funding_script`]
+   * [`u16`:`lease_duration`]
+   * [`u32`:`lease_expiry`]
+   * [`u16`:`max_channel_fee_basis`]
+   * [`u32`:`max_channel_fee_base_msat`]
 
 `timestamp` allows for the ordering of messages, in the case of multiple
 announcements. `rgb_color` and `alias` allow intelligence services to assign
@@ -280,6 +308,14 @@ 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.
 
+`lease_rates` allows nodes to announce their willingness to provide funding to
+other nodes for a fee. They also commit to a maximum routing fee they will charge
+for transmitting funds over the channel for the duration of the funding lease.
+
+`lease_witness` contains the data that is signed when committing to a funding
+lease. It starts with `option_will_fund` in ASCII to ensure that this signature
+cannot be used in a different context.
+
 The following `address descriptor` types are defined:
 
    * `1`: ipv4; data = `[4:ipv4_addr][2:port]` (length 6)
@@ -323,6 +359,25 @@ 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`:
+    - MUST set `lease_duration` to the number of blocks during which the lease
+      will be active.
+    - MUST set `min_lease_amount_sat` and `max_lease_amount_sat` to the minimum
+      and maximum amount it will contribute at this rate.
+    - SHOULD include one `lease_rate` for each lease duration it supports.
+    - SHOULD include one `lease_rate` for each amount range it supports.
+    - MUST NOT include more than ten `lease_rate`s.
+    - 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.
+    - MUST set `max_channel_fee_base_msat` to the maximum `fee_base_msat` it
+      will use in its `channel_update` while the lease is active.
+    - MUST set `max_channel_fee_basis` to match (when converted from basis
+      points to millionths) the maximum `fee_proportional_millionths` it will
+      use in its `channel_update` while the lease is active.
 
 The receiving node:
   - if `node_id` is NOT a valid compressed public key:
@@ -363,6 +418,8 @@ any future fields appended to the end):
   - if more than one `type 5` address is announced:
     - SHOULD ignore the additional data.
     - MUST not forward the `node_announcement`.
+  - if more than ten `lease_rate`s are included:
+    - MUST not forward the `node_announcement`.
 
 ### Rationale
 
@@ -377,6 +434,11 @@ to be ordered in ascending order, unknown ones can be safely ignored.
 Additional fields beyond `addresses` may also be added in the future—with
 optional padding within `addresses`, if they require certain alignment.
 
+When using `option_will_fund`, a `signature` will be provided over the
+`lease_witness`. This provides the buyer with a proof in case the seller
+does not honor the lease terms, for example by updating the routing fees
+of their `channel_update` to a greater value than the `lease_rate`.
+
 ### Security Considerations for Node Aliases
 
 Node aliases are user-defined and provide a potential avenue for injection
@@ -498,6 +560,11 @@ The origin node:
   - SHOULD NOT create redundant `channel_update`s
   - If it creates a new `channel_update` with updated channel parameters:
     - SHOULD keep accepting the previous channel parameters for 10 minutes
+  - If it is the seller of a currently active lease on this channel (`option_will_fund`):
+    - MUST NOT set `fee_base_msat` greater than `max_channel_fee_base_msat`
+      (as committed to in `accept_channel2.will_fund.signature`).
+    - MUST NOT set `fee_proportional_millionths` greater than `max_channel_fee_basis` * 100
+      (as committed to in `accept_channel2.will_fund.signature`).
 
 The receiving node:
   - if the `short_channel_id` does NOT match a previous `channel_announcement`,