git.bitcoin.ninja Git - rust-lightning/blob - ARCH.md

   1 Rust-Lightning is broken into a number of high-level structures with APIs to hook them
   2 together, as well as APIs for you, the user, to provide external data.
   3
   4 The two most important structures which nearly every application of Rust-Lightning will
   5 need to use are `ChannelManager` and `ChannelMonitor`. `ChannelManager` holds multiple
   6 channels, routes payments between them, and exposes a simple API to make and receive
   7 payments. Individual `ChannelMonitor`s monitor the on-chain state of a channel, punish
   8 counterparties if they misbehave, and force-close channels if they contain unresolved
   9 HTLCs which are near expiration. The `chain::Watch` interface provides a way for you to
  10 receive `ChannelMonitorUpdate`s from `ChannelManager` and persist them to disk before the
  11 channel steps forward.
  12
  13 There are two additional important structures that you may use either on the same device
  14 as the `ChannelManager` or on a separate one. `NetGraphMsgHandler` handles receiving channel
  15 and node announcements, which are then used to calculate routes by `get_route` for sending payments.
  16 `PeerManager` handles the authenticated and encrypted communication protocol,
  17 monitoring for liveness of peers, routing messages to `ChannelManager` and `NetGraphMsgHandler`
  18 instances directly, and receiving messages from them via the `EventsProvider` interface.
  19
  20 These structs communicate with each other using a public API, so that you can easily add
  21 a proxy in between for special handling. Further, APIs for key generation, transaction
  22 broadcasting, block fetching, and fee estimation must be implemented and the data
  23 provided by you, the user.
  24
  25 The library does not rely on the presence of a runtime environment outside of access to
  26 heap, atomic integers, and basic Mutex primitives. This means the library will never
  27 spawn threads or take any action whatsoever except when you call into it. Thus,
  28 `ChannelManager` and `PeerManager` have public functions which you should call on a timer,
  29 network reads and writes are external and provided by you, and the library relies only on
  30 block time for current time knowledge.
  31
  32 At a high level, some of the common interfaces fit together as follows:
  33
  34
  35 ```
  36
  37                      -----------------
  38                      | KeysInterface |  --------------
  39                      -----------------  | UserConfig |
  40          --------------------       ^   --------------
  41    ------| MessageSendEvent |       |   ^     ----------------
  42   /      --------------------       |   |     | FeeEstimator | <-----------------------
  43  |   (as MessageSendEventsProvider) |   |     ----------------                         \
  44  |                         ^        |   |    ^                ------------------------  |
  45  |                          \       |   |   /      ---------> | BroadcasterInterface |  |
  46  |                           \      |   |  /      /           ------------------------  |
  47  |                            \     |   | /      /                          ^           |
  48  |    (as                      ------------------       ----------------    |           |
  49  |    ChannelMessageHandler)-> | ChannelManager | ----> | chain::Watch |    |           |
  50  v               /             ------------------       ----------------    |           |
  51 --------------- /                  (as EventsProvider)         ^            |           |
  52 | PeerManager |-                             \                 |            |           |
  53 ---------------                               \                | (is-a)     |           |
  54  |                    -----------------        \       _----------------   /           /
  55  |                    | chain::Access |         \     / | ChainMonitor |---------------
  56  |                    -----------------          \   /  ----------------
  57  |                            ^                   \ /          |
  58 (as RoutingMessageHandler)    |                    v           v
  59   \                   ----------------------   ---------   -----------------
  60    -----------------> | NetGraphMsgHandler |   | Event |   | chain::Filter |
  61                       ----------------------   ---------   -----------------
  62 ```