Add separate node backup

* Add an additional node backup that can contain data unrelated to channels * Add a size restriction to the backup data * Add a recommendation to store backups after channel closes * Explain the asymmetry of the feature
lightning · Jul 7, 2021 · 18bd2af · 18bd2af
1 parent d873416
commit 18bd2af
Show file tree

Hide file tree

Showing 3 changed files with 121 additions and 47 deletions.
diff --git a/01-messaging.md b/01-messaging.md
@@ -20,6 +20,7 @@ All data fields are unsigned big-endian unless otherwise specified.
     * [The `error` Message](#the-error-message)
   * [Control Messages](#control-messages)
     * [The `ping` and `pong` Messages](#the-ping-and-pong-messages)
+  * [Node Backup Storage](#node-backup-storage)
   * [Appendix A: BigSize Test Vectors](#appendix-a-bigsize-test-vectors)
   * [Appendix B: Type-Length-Value Test Vectors](#appendix-b-type-length-value-test-vectors)
   * [Appendix C: Message Extension](#appendix-c-message-extension)
@@ -258,10 +259,15 @@ The `features` field MUST be padded to bytes with 0s.
     1. type: 1 (`networks`)
     2. data:
         * [`...*chain_hash`:`chains`]
-
+    1. type: 2 (`node_backup`)
+    2. data:
+        * [`...*byte`:`backup_data`]
 
 The optional `networks` indicates the chains the node is interested in.
 
+The `node_backup` contains the last backup our peer sent us, as described in
+the [Node Backup Storage](#node-backup-storage) section.
+
 #### Requirements
 
 The sending node:
@@ -443,6 +449,60 @@ every message maximally).
 Finally, the usage of periodic `ping` messages serves to promote frequent key
 rotations as specified within [BOLT #8](08-transport.md).
 
+## Node Backup Storage
+
+Nodes that advertise the `peer_backup_storage` feature offer storing arbitrary
+data for their peers. The data stored must not exceed 32000 bytes, which lets
+it fit in existing lightning messages (e.g. a `commitment_signed` message with
+483 htlc signatures).
+
+Nodes can verify that their `peer_backup_storage` peers correctly store their
+backup data at each reconnection, by comparing the contents of the retrieved
+backups with the last one they sent.
+
+This feature is asymmetric: nodes that can store backups for their peers will
+activate it, but nodes that want to have their backups stored must not activate
+it. If both nodes stored each other's backups, whenever one loses data it would
+force the other to close channels, which is undesirable.
+
+There are two types of backups:
+  - `node_backup`, described in this section
+  - `channel_backup`, described in [Bolt #2](02-peer-protocol.md#channel-backup-storage)
+
+Nodes ask their peers to store data using the `update_backup` message:
+
+1. type: 20 (`update_backup`)
+2. data:
+   * [`bigsize`: `length`]
+   * [`length*byte`:`node_backup`]
+
+A node whose peer has activated the `peer_backup_storage` feature:
+  - if it also has activated the `peer_backup_storage` feature:
+    - MUST NOT send `update_backup`
+  - otherwise:
+    - MAY send `update_backup` whenever necessary
+    - MUST limit its `node_backup` to 32000 bytes
+    - when it receives `init` with an outdated or missing `node_backup`:
+      - SHOULD send a warning
+      - MAY disconnect
+      - MAY fail all channels with that peer
+
+A node that has activated the `peer_backup_storage` feature:
+  - when it receives `update_backup`:
+    - if its peer also has activated the `peer_backup_storage` feature:
+      - SHOULD send a warning
+      - MUST NOT store this backup data
+    - otherwise:
+      - if the `node_backup` exceeds 32000 bytes:
+        - SHOULD send a warning
+        - MUST NOT store this backup data
+      - otherwise:
+        - MUST store this backup data
+  - when it sends `init`:
+    - MUST include the last `node_backup` it received from that peer
+  - when all channels with that peer are closed:
+    - SHOULD wait at least 2016 blocks before deleting the `node_backup`
+
 ## Appendix A: BigSize Test Vectors
 
 The following test vectors can be used to assert the correctness of a BigSize

diff --git a/02-peer-protocol.md b/02-peer-protocol.md
@@ -25,7 +25,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)
-    * [Peer Backup Storage](#peer-backup-storage)
+    * [Channel Backup Storage](#channel-backup-storage)
   * [Authors](#authors)
 
 # Channel
@@ -382,7 +382,7 @@ This message introduces the `channel_id` to identify the channel. It's derived f
 
 1. `tlv_stream`: `funding_signed_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -489,7 +489,7 @@ along with the `scriptpubkey` it wants to be paid to.
 
 1. `tlv_stream`: `shutdown_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -574,7 +574,7 @@ the channel.
 
 1. `tlv_stream`: `closing_signed_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -1023,7 +1023,7 @@ sign the resulting transaction (as defined in [BOLT #3](03-transactions.md)), an
 
 1. `tlv_stream`: `commitment_signed_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -1093,7 +1093,7 @@ The description of key derivation is in [BOLT #3](03-transactions.md#key-derivat
 
 1. `tlv_stream`: `revoke_and_ack_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -1213,7 +1213,7 @@ messages are), they are independent of requirements here.
 
 1. `tlv_stream`: `channel_reestablish_tlvs`
 2. types:
-    1. type: 1 (`peer_backup`)
+    1. type: 1 (`channel_backup`)
     2. data:
         * [`...*byte`:`backup_data`]
 
@@ -1420,30 +1420,43 @@ fall-behind detection.  An implementation can offer both, however, and
 fall back to the `option_data_loss_protect` behavior if
 `option_static_remotekey` is not negotiated.
 
-## Peer Backup Storage
+## Channel Backup Storage
 
 Nodes that advertise the `peer_backup_storage` feature offer storing arbitrary
-data for their peers. The data stored must fit in a lightning message, so it is
-inherently limited (less than 65535 bytes per channel).
-
-Nodes can verify that storage providers correctly store their backup data at
-each reconnection, by comparing the contents of the `peer_backup` of the
-`channel_reestablish` message to the last one they sent.
-
-A node connected to a storage provider:
-  - when it sends a message that completes an update of the channel state
-    (`funding_signed`, `commitment_signed`, `revoke_and_ack`, `shutdown` or
-    `closing_signed`):
-    - MAY include an optional `peer_backup` TLV field
-  - when it receives `channel_reestablish` with an outdated or missing
-    `peer_backup`:
-    - SHOULD fail the channel
-
-A storage provider:
-  - when it receives a `peer_backup`:
-    - MUST store this backup data
+data for their peers. [BOLT #1](01-messaging.md#node-backup-storage) describes
+how this allows storing per-node data, and the following section describes how
+this allows storing per-channel data.
+
+A node whose peer has activated the `peer_backup_storage` feature:
+  - if it also has activated the `peer_backup_storage` feature:
+    - MUST NOT send their `channel_backup`
+  - otherwise:
+    - when it sends a message that completes an update of the channel state
+      (`funding_signed`, `commitment_signed`, `revoke_and_ack`, `shutdown` or
+      `closing_signed`):
+      - MAY include an optional `channel_backup` TLV field
+      - MUST limit its `channel_backup` to 32000 bytes
+    - when it receives `channel_reestablish` with an outdated or missing
+      `channel_backup`:
+      - SHOULD send a warning
+      - MAY disconnect
+      - MAY fail the channel
+
+A node that has activated the `peer_backup_storage` feature:
+  - when it receives a `channel_backup`:
+    - if its peer also has activated the `peer_backup_storage` feature:
+      - SHOULD send a warning
+      - MUST NOT store this backup data
+    - otherwise:
+      - if the `channel_backup` exceeds 32000 bytes:
+        - SHOULD send a warning
+        - MUST NOT store this backup data
+      - otherwise:
+        - MUST store this backup data
   - when it sends `channel_reestablish`:
-    - MUST include the last `peer_backup` it received for that channel
+    - MUST include the last `channel_backup` it received for that channel
+  - when the channel is closed:
+    - SHOULD wait at least 2016 blocks before deleting the `channel_backup`
 
 # Authors
 

diff --git a/09-features.md b/09-features.md
@@ -26,22 +26,22 @@ The Context column decodes as follows:
 * `C+`: presented in the `channel_announcement` message, but always even (required).
 * `9`: presented in [BOLT 11](11-payment-encoding.md) invoices.
 
-| Bits  | Name                             | Description                                               | Context  | Dependencies      | Link                                  |
-|-------|----------------------------------|-----------------------------------------------------------|----------|-------------------|---------------------------------------|
-| 0/1   | `option_data_loss_protect`       | Requires or supports extra `channel_reestablish` fields   | IN       |                   | [BOLT #2][bolt02-retransmit]          |
-| 3     | `initial_routing_sync`           | Sending node needs a complete routing information dump    | I        |                   | [BOLT #7][bolt07-sync]                |
-| 4/5   | `option_upfront_shutdown_script` | Commits to a shutdown scriptpubkey when opening channel   | IN       |                   | [BOLT #2][bolt02-open]                |
-| 6/7   | `gossip_queries`                 | More sophisticated gossip control                         | IN       |                   | [BOLT #7][bolt07-query]               |
-| 8/9   | `var_onion_optin`                | Requires/supports variable-length routing onion payloads  | IN9      |                   | [Routing Onion Specification][bolt04] |
-| 10/11 | `gossip_queries_ex`              | Gossip queries can include additional information         | IN       | `gossip_queries`  | [BOLT #7][bolt07-query]               |
-| 12/13 | `option_static_remotekey`        | Static key for remote output                              | IN       |                   | [BOLT #3](03-transactions.md)         |
-| 14/15 | `payment_secret`                 | Node supports `payment_secret` field                      | IN9      | `var_onion_optin` | [Routing Onion Specification][bolt04] |
-| 16/17 | `basic_mpp`                      | Node can receive basic multi-part payments                | IN9      | `payment_secret`  | [BOLT #4][bolt04-mpp]                 |
-| 18/19 | `option_support_large_channel`   | Can create large channels                                 | IN       |                   | [BOLT #2](02-peer-protocol.md#the-open_channel-message) |
-| 20/21 | `option_anchor_outputs`          | Anchor outputs                                            | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)         |
-| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions   | IN       |                   | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful]|
-| 26/27 | `option_shutdown_anysegwit`         | Future segwit versions allowed in `shutdown`           | IN       |                   | [BOLT #2][bolt02-shutdown]   |
-| 36/37 | `peer_backup_storage`               | Allow storing encrypted peer backup data               | IN       |                   | [BOLT #2][bolt02-peer-backup]   |
+| Bits  | Name                              | Description                                              | Context  | Dependencies              | Link                                                                  |
+|-------|-----------------------------------|----------------------------------------------------------|----------|---------------------------|-----------------------------------------------------------------------|
+| 0/1   | `option_data_loss_protect`        | Requires or supports extra `channel_reestablish` fields  | IN       |                           | [BOLT #2][bolt02-retransmit]                                          |
+| 3     | `initial_routing_sync`            | Sending node needs a complete routing information dump   | I        |                           | [BOLT #7][bolt07-sync]                                                |
+| 4/5   | `option_upfront_shutdown_script`  | Commits to a shutdown scriptpubkey when opening channel  | IN       |                           | [BOLT #2][bolt02-open]                                                |
+| 6/7   | `gossip_queries`                  | More sophisticated gossip control                        | IN       |                           | [BOLT #7][bolt07-query]                                               |
+| 8/9   | `var_onion_optin`                 | Requires/supports variable-length routing onion payloads | IN9      |                           | [Routing Onion Specification][bolt04]                                 |
+| 10/11 | `gossip_queries_ex`               | Gossip queries can include additional information        | IN       | `gossip_queries`          | [BOLT #7][bolt07-query]                                               |
+| 12/13 | `option_static_remotekey`         | Static key for remote output                             | IN       |                           | [BOLT #3](03-transactions.md)                                         |
+| 14/15 | `payment_secret`                  | Node supports `payment_secret` field                     | IN9      | `var_onion_optin`         | [Routing Onion Specification][bolt04]                                 |
+| 16/17 | `basic_mpp`                       | Node can receive basic multi-part payments               | IN9      | `payment_secret`          | [BOLT #4][bolt04-mpp]                                                 |
+| 18/19 | `option_support_large_channel`    | Can create large channels                                | IN       |                           | [BOLT #2](02-peer-protocol.md#the-open_channel-message)               |
+| 20/21 | `option_anchor_outputs`           | Anchor outputs                                           | IN       | `option_static_remotekey` | [BOLT #3](03-transactions.md)                                         |
+| 22/23 | `option_anchors_zero_fee_htlc_tx` | Anchor commitment type with zero fee HTLC transactions   | IN       |                           | [BOLT #3][bolt03-htlc-tx], [lightning-dev][ml-sighash-single-harmful] |
+| 26/27 | `option_shutdown_anysegwit`       | Future segwit versions allowed in `shutdown`             | IN       |                           | [BOLT #2][bolt02-shutdown]                                            |
+| 36/37 | `peer_backup_storage`             | Allow storing encrypted peer backup data                 | IN       |                           | [BOLT #1][bolt01-node-backup], [BOLT #2][bolt02-channel-backup]       |
 
 ## Requirements
 
@@ -81,13 +81,14 @@ known to be set, and do not need to be validated at every feature gate.
 <br>
 This work is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/).
 
+[bolt01-node-backup]: 01-messaging.md#node-backup-storage
 [bolt02-retransmit]: 02-peer-protocol.md#message-retransmission
 [bolt02-open]: 02-peer-protocol.md#the-open_channel-message
 [bolt03-htlc-tx]: 03-transactions.md#htlc-timeout-and-htlc-success-transactions
 [bolt02-shutdown]: 02-peer-protocol.md#closing-initiation-shutdown
-[bolt02-peer-backup]: 02-peer-protocol.md#peer-backup-storage
+[bolt02-channel-backup]: 02-peer-protocol.md#channel-backup-storage
 [bolt04]: 04-onion-routing.md
+[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
 [bolt07-sync]: 07-routing-gossip.md#initial-sync
 [bolt07-query]: 07-routing-gossip.md#query-messages
-[bolt04-mpp]: 04-onion-routing.md#basic-multi-part-payments
 [ml-sighash-single-harmful]: https://lists.linuxfoundation.org/pipermail/lightning-dev/2020-September/002796.html