diff --git a/README.md b/README.md index bba6b55..a7c8b16 100644 --- a/README.md +++ b/README.md @@ -25,3 +25,4 @@ For more detail on the process, please read [bLIP-0001](./blip-0001.md) and | [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 | +| [38](./blip-0038.md) | Block header gossip | Bastien Teinturier | Active | diff --git a/blip-0002.md b/blip-0002.md index 15ad52f..15c579b 100644 --- a/blip-0002.md +++ b/blip-0002.md @@ -92,7 +92,7 @@ The following table contains extension tlv fields for the `init` message: | Type | Name | Link | |-------|-----------------------------|--------------------------------| -| 65536 | `tlv_field_name` | Link to the corresponding bLIP | +| 32411 | `latest_block_header` | [bLIP 38](./blip-0038.md) | #### `payment_onion_payload` diff --git a/blip-0038.md b/blip-0038.md new file mode 100644 index 0000000..90edf6d --- /dev/null +++ b/blip-0038.md @@ -0,0 +1,80 @@ +``` +bLIP: 38 +Title: Block header gossip +Status: Active +Author: Bastien Teinturier +Created: 2024-07-03 +License: CC0 +``` + +## Abstract + +Lightning nodes must stay in sync with the blockchain to protect themselves +against malicious peers that could publish revoked commitment transactions. +Honest nodes should help their peers by letting them know about the latest +block header they have received: this allows detecting when a node is behind +and may need to fix their bitcoin node. + +## Copyright + +This bLIP is licensed under the CC0 license. + +## Motivation + +We have several messages that are frequently exchanged between lightning nodes. +They are a good opportunity to include some blockchain data. + +## Specification + +We add the following TLV field to the `init` message: + +1. `tlv_stream`: `init_tlvs` +2. types: + 1. type: 32411 (`latest_block_header`) + 2. data: + - [`u32`:`block_height`] + - [`80*bytes`:`block_header`] + +### Requirements + +The sender of `init`: + +- SHOULD include the `latest_block_header` field. +- MUST set `block_header` to the latest valid block header its bitcoin node has received. +- MUST set `block_height` to the corresponding height in the blockchain. + +The reader of `init`: + +- If the received `block_height` is greater than the local block height: + - SHOULD verify the received `block_header`'s proof of work. + - SHOULD alert the node operator if it is missing many blocks. + +### Rationale + +This extension only allows detecting that we're behind: there is no easy way +to automatically fix a connection issue to the bitcoin network. Node operators +should troubleshoot their bitcoin node to figure out how to resolve the issue. + +We use an odd TLV field, which will automatically be ignored by readers who +don't support this extension: senders can thus always include this field. + +### Test vectors + +The following test vector describes how an `init` message containing a block +header is encoded: + +```json +{ + "features": [], + "network": "mainnet", + "latest_block_header": { + "height": 800000, + "header": "00601d3455bb9fbd966b3ea2dc42d0c22722e4c0c1729fad17210100000000000000000055087fab0c8f3f89f8bcfd4df26c504d81b0a88e04907161838c0c53001af09135edbd64943805175e955e06" + }, + "encoded": "0010 0000 0000 01206fe28c0ab6f1b372c1a6a246ae63f74f931e8365e15a089c68d6190000000000 fd7e9b54000c350000601d3455bb9fbd966b3ea2dc42d0c22722e4c0c1729fad17210100000000000000000055087fab0c8f3f89f8bcfd4df26c504d81b0a88e04907161838c0c53001af09135edbd64943805175e955e06" +} +``` + +## Reference Implementations + +- eclair: