_ Git - rust-lightning/blob - lightning-rapid-gossip-sync/README.md

   1 # lightning-rapid-gossip-sync
   2
   3 This crate exposes functionality for rapid gossip graph syncing, aimed primarily at mobile clients.
   4 Its server counterpart is the
   5 [rapid-gossip-sync-server](https://github.com/lightningdevkit/rapid-gossip-sync-server) repository.
   6
   7 ## Mechanism
   8
   9 The (presumed) server sends a compressed gossip response containing gossip data. The gossip data is
  10 formatted compactly, omitting signatures and opportunistically incremental where previous channel
  11 updates are known.
  12
  13 Essentially, the serialization structure is as follows:
  14
  15 1. Fixed prefix bytes `76, 68, 75` (the first three bytes are ASCII for `LDK`)
  16     - The purpose of this prefix is to identify the serialization format, should other rapid gossip
  17       sync formats arise in the future
  18 2. Version byte
  19    - Currently supported versions are 1 and 2
  20 3. Chain hash (32 bytes)
  21 4. Latest seen timestamp (`u32`)
  22 5. Version 2 only:
  23    - A byte indicating the number of default node features
  24    - An array of node features
  25 6. An unsigned int indicating the number of node IDs to follow
  26 7. An array of compressed node ID pubkeys (all pubkeys are presumed to be standard
  27    compressed 33-byte-serializations)
  28    - Version 2 only: Each pubkey is optionally followed by supplemental feature or address information.
  29 8. An unsigned int indicating the number of channel announcement messages to follow
  30 9. An array of significantly stripped down customized channel announcements
  31 10. An unsigned int indicating the number of channel update messages to follow
  32 11. A series of default values used for non-incremental channel updates
  33     - The values are defined as follows:
  34         1. `default_cltv_expiry_delta`
  35         2. `default_htlc_minimum_msat`
  36         3. `default_fee_base_msat`
  37         4. `default_fee_proportional_millionths`
  38         5. `default_htlc_maximum_msat` (`u64`, and if the default is no maximum, `u64::MAX`)
  39     - The defaults are calculated by the server based on the frequency among non-incremental
  40       updates within a given delta set
  41 12. An array of customized channel updates
  42
  43 You will also notice that `NodeAnnouncement` messages are omitted altogether as the node IDs are
  44 implicitly extracted from the channel announcements and updates.
  45
  46 The data is then applied to the current network graph, artificially dated to the timestamp of the
  47 latest seen message less one week, be it an announcement or an update, from the server's
  48 perspective. The network graph should not be pruned until the graph sync completes.
  49
  50 ### Custom Node Announcement (V2 Only)
  51
  52 In version 2 of the RGS protocol, node IDs may be followed by supplemental feature and socket address data. The presence
  53 of those additional fields is indicated by utilizing the unused bits of the 33-byte-pubkey parity byte as follows:
  54
  55 | 128             | 64       | 32           | 16           | 8            | 4            | 2          | 1                |
  56 |-----------------|----------|--------------|--------------|--------------|--------------|------------|------------------|
  57 | Additional data | Reminder | Feature data | Feature data | Feature data | Address data | Always set | Odd y-coordinate |
  58
  59 Note that bit indices 3-5 all indicate feature data. Specifically, if none of the bits are set, that means there is
  60 no feature data that follows the pubkey. If a subset of them are set, the bit triplet is interpreted as an index (less
  61 one) of the default node features that were supplied prior. If all three bits are set, a custom feature combination is
  62 sent.
  63
  64 If there have been no changes to a node, bit index 6 can be set to function as a reminder absent any address or feature
  65 data.
  66
  67 Lastly, bit index 7 indicates the presence of additional data, which will allow forwards compatibility.
  68
  69 ### Custom Channel Announcement
  70
  71 To achieve compactness and avoid data repetition, we're sending a significantly stripped down
  72 version of the channel announcement message, which contains only the following data:
  73
  74 1. `channel_features`: `u16` + `n`, where `n` is the number of bytes indicated by the first `u16`
  75 2. `short_channel_id`: `CompactSize` (incremental `CompactSize` deltas starting from 0)
  76 3. `node_id_1_index`: `CompactSize` (index of node id within the previously sent sequence)
  77 4. `node_id_2_index`: `CompactSize` (index of node id within the previously sent sequence)
  78
  79 ### Custom Channel Update
  80
  81 For the purpose of rapid syncing, we have deviated from the channel update format specified in
  82 BOLT 7 significantly. Our custom channel updates are structured as follows:
  83
  84 1. `short_channel_id`: `CompactSize` (incremental `CompactSize` deltas starting at 0)
  85 2. `custom_channel_flags`: `u8`
  86 3. `update_data`
  87
  88 Specifically, our custom channel flags break down like this:
  89
  90 | 128                 | 64 | 32 | 16 | 8 | 4 | 2                | 1         |
  91 |---------------------|----|----|----|---|---|------------------|-----------|
  92 | Incremental update? |    |    |    |   |   | Disable channel? | Direction |
  93
  94 If the most significant bit is set to `1`, indicating an incremental update, the intermediate bit
  95 flags assume the following meaning:
  96
  97 | 64                              | 32                              | 16                          | 8                                         | 4                               |
  98 |---------------------------------|---------------------------------|-----------------------------|-------------------------------------------|---------------------------------|
  99 | `cltv_expiry_delta` has changed | `htlc_minimum_msat` has changed | `fee_base_msat` has changed | `fee_proportional_millionths` has changed | `htlc_maximum_msat` has changed |
 100
 101 If the most significant bit is set to `0`, the meaning is almost identical, except instead of a
 102 change, the flags now represent a deviation from the defaults sent at the beginning of the update
 103 sequence.
 104
 105 In both cases, `update_data` only contains the fields that are indicated by the channel flags to be
 106 non-default or to have mutated.
 107
 108 ## Delta Calculation
 109
 110 The way a server is meant to calculate this rapid gossip sync data is by taking the latest time
 111 any change, be it either an announcement or an update, was seen. That timestamp is included in each
 112 rapid sync message, so all the client needs to do is cache one variable.
 113
 114 If a particular channel update had never occurred before, the full update is sent. If a channel has
 115 had updates prior to the provided timestamp, the latest update prior to the timestamp is taken as a
 116 reference, and the delta is calculated against it.
 117
 118 Depending on whether the rapid sync message is calculated on the fly or a snapshotted version is
 119 returned, intermediate changes between the latest update seen by the client and the latest update
 120 broadcast on the network may be taken into account when calculating the delta.
 121
 122 ## Performance
 123
 124 Given the primary purpose of this utility is a faster graph sync, we thought it might be helpful to
 125 provide some examples of various delta sets. These examples were calculated as of May 19th  2022
 126 with a network graph comprised of 80,000 channel announcements and 160,000 directed channel updates.
 127
 128 | Full sync                   |        |
 129 |-----------------------------|--------|
 130 | Message Length              | 4.7 MB |
 131 | Gzipped Message Length      | 2.0 MB |
 132 | Client-side Processing Time | 1.4 s  |
 133
 134 | Week-old sync               |        |
 135 |-----------------------------|--------|
 136 | Message Length              | 2.7 MB |
 137 | Gzipped Message Length      | 862 kB |
 138 | Client-side Processing Time | 907 ms |
 139
 140 | Day-old sync                |         |
 141 |-----------------------------|---------|
 142 | Message Length              | 191 kB  |
 143 | Gzipped Message Length      | 92.8 kB |
 144 | Client-side Processing Time | 196 ms  |