diff --git a/README.md b/README.md index 602b3c7..c56c198 100644 --- a/README.md +++ b/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 | diff --git a/blip-0002.md b/blip-0002.md index 14b104c..8157b4e 100644 --- a/blip-0002.md +++ b/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) | diff --git a/blip-0034.md b/blip-0034.md new file mode 100644 index 0000000..66df8ea --- /dev/null +++ b/blip-0034.md @@ -0,0 +1,123 @@ +``` +bLIP: 34 +Title: The `recommended_feerates` message +Status: Active +Author: Bastien Teinturier +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. +* SHOULD NOT send `update_fee` using feerates that are outside of the + advertised range, unless it is necessary to guarantee the safety of its + channel funds. + +### 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: