blip-0034: the recommended_feerates message

README.md

@@ -17,13 +17,14 @@ 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 |
-| [25](./blip-0025.md) | Forward less than onion value | Valentine Wallace | Active |
-| [32](./blip-0032.md) | Onion Message DNS Resolution | Matt Corallo | 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 |
+| [25](./blip-0025.md) | Forward less than onion value | Valentine Wallace | Active |
+| [32](./blip-0032.md) | Onion Message DNS Resolution | Matt Corallo | Active |
+| [34](./blip-0034.md) | The `recommended_feerates` message | Bastien Teinturier | Active |

blip-0002.md

@@ -61,6 +61,7 @@ bLIPs may create new messages and reserve their type in the following table:
 
 | Type | Name | Link |
 | ------- | ------------------------------- | -------------------------- |
+| 39409 | `recommended_feerates` | [bLIP 34](./blip-0034.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) |

blip-0034.md

@@ -0,0 +1,120 @@
+```
+bLIP: 34
+Title: The `recommended_feerates` message
+Status: Active
+Author: Bastien Teinturier <[email protected]>
+Created: 2024-07-02
+License: CC0
+```
+
+## Abstract
+
+Many lightning messages include feerates for on-chain transactions. Nodes
+receiving those messages are supposed to reject them if they are considered
+too low or too high. However, there is no mechanism to let peers know which
+feerates we currently find acceptable, which leads to frequent failures,
+especially when the mempool feerates fluctuate quickly.
+
+We introduce an optional message to advertise to our peers the feerates we'd
+like to use when funding new or existing channels.
+
+## Copyright
+
+This bLIP is licensed under the CC0 license.
+
+## Motivation
+
+This feature is particularly useful when mobile wallets initiate channel
+operations with their service provider: in most cases, they should use what
+the service provider recommends since they don't have access to a full node
+and the service provider would reject unacceptable feerates anyway.
+
+## Specification
+
+### The `recommended_feerates` message
+
+1. type: 39409 (`recommended_feerates`)
+2. data:
+ * [`chain_hash`:`chain_hash`]
+ * [`u32`:`funding_feerate_per_kw`]
+ * [`u32`:`commitment_feerate_per_kw`]
+
+1. `tlv_stream`: `recommended_feerates_tlvs`
+2. types:
+ 1. type: 1 (`funding_feerate_range`)
+ 2. data:
+ * [`u32`:`min_funding_feerate_per_kw`]
+ * [`u32`:`max_funding_feerate_per_kw`]
+ 1. type: 3 (`commitment_feerate_range`)
+ 2. data:
+ * [`u32`:`min_commitment_feerate_per_kw`]
+ * [`u32`:`max_commitment_feerate_per_kw`]
+
+### Requirements
+
+The sender:
+
+* SHOULD frequently send `recommended_feerates` with feerates it currently
+ accepts for channel funding operations.
+* SHOULD set `funding_feerate_per_kw` to the feerate it uses for funding
+ channels.
+* SHOULD set `funding_feerate_range` to the range of acceptables feerates
+ for funding channels.
+* SHOULD set `commitment_feerate_per_kw` to the feerate it uses for channel
+ commitment transactions.
+* SHOULD set `commitment_feerate_range` to the range of acceptables feerates
+ for channel commitment transactions.
+* SHOULD accept feerates that are inside the ranges it advertised.
+
+The receiver:
+
+* SHOULD not send `open_channel`, `open_channel2`, `splice_init`, `tx_init_rbf`
+ or other channel funding messages using feerates that are outside of the
+ advertised ranges.
+
+### Rationale
+
+While it won't guarantee success every time, taking into account our peer's
+recommended feerates reduces the frequency of failures when funding channels.
+
+### Test vectors
+
+The following test vectors describe how the `recommended_feerates` message is
+encoded:
+
+```json
+[
+ {
+ "recommended_feerates": {
+ "chain": "testnet3",
+ "funding_feerate_per_kw": "2500 sat/kw",
+ "commitment_feerate_per_kw": "2500 sat/kw"
+ },
+ "encoded": "99f1 43497fd7f826957108f4a30fd9cec3aeba79972084e90ead01ea330900000000 000009c4 000009c4"
+ },
+ {
+ "recommended_feerates": {
+ "chain": "testnet3",
+ "funding_feerate_per_kw": "5000 sat/kw",
+ "commitment_feerate_per_kw": "253 sat/kw"
+ },
+ "encoded": "99f1 43497fd7f826957108f4a30fd9cec3aeba79972084e90ead01ea330900000000 00001388 000000fd"
+ },
+ {
+ "recommended_feerates": {
+ "chain": "testnet3",
+ "funding_feerate_per_kw": "10000 sat/kw",
+ "min_funding_feerate_per_kw": "5000 sat/kw",
+ "max_funding_feerate_per_kw": "15000 sat/kw",
+ "commitment_feerate_per_kw": "1000 sat/kw",
+ "min_commitment_feerate_per_kw": "253 sat/kw",
+ "max_commitment_feerate_per_kw": "2000 sat/kw"
+ },
+ "encoded": "99f1 43497fd7f826957108f4a30fd9cec3aeba79972084e90ead01ea330900000000 00002710 000003e8 01080000138800003a98 0308000000fd000007d0"
+ }
+]
+```
+
+## Reference Implementations
+
+* eclair: <https://github.com/ACINQ/eclair/pull/2860>