_ Git - rapid-gossip-sync-server/blob - README.md

   1 # rust-ln-sync
   2
   3 This is a server that connects to peers on the Lightning network and calculates compact rapid sync
   4 gossip data.
   5
   6 These are the components it's comprised of.
   7
   8 ## config
   9
  10 A config file where the Postgres credentials and Lightning peers can be adjusted. Most adjustments
  11 can be made by setting environment variables, whose usage is as follows:
  12
  13 | Name                     | Default       | Description                                                                                                |
  14 |:-------------------------|:--------------|:-----------------------------------------------------------------------------------------------------------|
  15 | RUST_LN_SYNC_DB_HOST     | localhost     | Domain of the Postgres database                                                                            |
  16 | RUST_LN_SYNC_DB_USER     | alice         | Username to access Postgres                                                                                |
  17 | RUST_LN_SYNC_DB_PASSWORD | _None_        | Password to access Postgres                                                                                |
  18 | RUST_LN_SYNC_DB_NAME     | ln_graph_sync | Name of the database to be used for gossip storage                                                         |
  19 | BITCOIN_REST_DOMAIN      | 127.0.0.1     | Domain of the [bitcoind REST server](https://github.com/bitcoin/bitcoin/blob/master/doc/REST-interface.md) |
  20 | BITCOIN_REST_PORT        | 80            | HTTP port of the bitcoind REST server                                                                      |
  21 | BITCOIN_REST_PATH        | /rest/        | Path infix to access the bitcoind REST endpoints                                                           |
  22
  23 Notably, one property needs to be modified in code, namely the `ln_peers()` method. It specifies how
  24 many and which peers to use for retrieving gossip.
  25
  26 ## download
  27
  28 The module responsible for initiating the scraping of the network graph from its peers.
  29
  30 ## persistence
  31
  32 The module responsible for persisting all the downloaded graph data to Postgres.
  33
  34 ## server
  35
  36 The server is responsible for returning dynamic and snapshotted rapid sync data.
  37
  38 Dynamic sync data is fed a timestamp of the last sync, and it dynamically calculates a delta
  39 such that a minimal change set is returned based on changes which are assumed to have been seen
  40 by the client (ignoring any intermediate changes). Dynamic sync is only available after the first
  41 full graph sync completes on startup.
  42
  43 Snapshot sync data is also based on a timestamp, but unlike dynamic sync, its responses are
  44 precalculated, which is done in a way that considers the possibility that the client may have
  45 intermittently seen later updates.
  46
  47 ### snapshot
  48
  49 The snapshotting module is responsible for calculating and storing snapshots. It's started up
  50 as soon as the first full graph sync completes, and then keeps updating the snapshots at a
  51 24-hour-interval.
  52
  53 ### lookup
  54
  55 The lookup module is responsible for fetching the latest data from the network graph and Postgres,
  56 and reconciling it into an actionable delta set that the server can return in a serialized format.
  57
  58 It works by collecting all the channels that are currently in the network graph, and gathering
  59 announcements as well as updates for each of them. For the updates specifically, the last update
  60 seen prior to the given timestamp, the latest known updates, and, if necessary, all intermediate
  61 updates are collected.
  62
  63 Then, any channel that has only had an announcement but never an update is dropped. Additionally,
  64 every channel whose first update was seen after the given timestamp is collected alongside its
  65 announcement.
  66
  67 Finally, all channel update transitions are evaluated and collected into either a full or an
  68 incremental update.
  69
  70 ## Making a call
  71
  72 ### Dynamic
  73
  74 Make a call to
  75
  76 `http://localhost:3030/dynamic/1652644698`
  77
  78 Where `1652644698` is the last sync timestamp.
  79
  80 ### Snapshotted
  81
  82 Same as above, but sub `dynamic` for `snapshot`:
  83
  84 `http://localhost:3030/snapshot/1652644698`
  85
  86 ## License
  87
  88 MIT