blip-0038: block header gossip

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 |

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`
 

blip-0038.md

@@ -0,0 +1,80 @@
+```
+bLIP: 38
+Title: Block header gossip
+Status: Active
+Author: Bastien Teinturier <[email protected]>
+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: <https://github.com/ACINQ/eclair/pull/2874>