docs: docs

Author: SupernaviX

modules/peer_network_interface/NOTES.md

@@ -0,0 +1,18 @@
+# Architecture
+
+This module uses an event-queue-based architecture. A `NetworkManager` is responsible for creating a set of `PeerConnection`s and sending commands to them. Each `PeerConnection` maintains a connection to a single peer; it responds to commands from the `NetworkManager`, and emits events to an event queue. The `NetworkManager` reads from that queue to decide which chain to follow. When blocks from the preferred chain have been fetched, it publishes those blocks to the message bus.
+
+This module requests the body for every block announced by any chain, from the first chain which announced it. When it has the body for the next block announced 
+
+```mermaid
+graph LR
+    EQ[Event Queue]-->NM[NetworkManager]
+    subgraph Peers
+        P1[PeerConnection 1]
+        P2[PeerConnection 2]
+        P3[PeerConnection 3]
+    end
+    NM -->|RequestBlock</br>FindIntersect| P1 & P2 & P3
+    Peers -->|ChainSync<br/>BlockFetched<br/>Disconnect|EQ
+    NM -->|BlockAvailable| MB[Message Bus]
+```

modules/peer_network_interface/README.md

@@ -0,0 +1,18 @@
+# Peer network interface module
+
+The peer network interface module uses the ChainSync and BlockFetch protocols to fetch blocks from one of several upstream sources. It chooses one peer to treat as the "preferred" chain to follow, but will gracefully switch which peer it follows during network issues.
+
+It can either run independently, either from the origin or current tip, or
+be triggered by a Mithril snapshot event (the default) where it starts from
+where the snapshot left off, and follows the chain from there.
+
+Rollbacks are handled by signalling in the block data - it is downstream
+subscribers' responsibility to deal with the effects of this.
+
+## Configuration
+
+See [./config.default.toml](./config.default.toml) for the available configuration options and their default values.
+
+## Messages
+
+This module publishes "raw block messages" to the configured `block-topic`. Each message includes the raw bytes composing the header and body of a block. The module follows the head of one chain at any given time, though that chain may switch during runtime. If that chain reports a rollback (or if this module switches to a different chain), the next message it emits will be the new head of the chain and have the status `RolledBack`.

modules/peer_network_interface/config.default.toml

@@ -1,13 +1,24 @@
+# The topic to publish blocks on
 block-topic = "cardano.block.available"
+# The topic to wait for when sync-point is "snapshot"
 snapshot-completion-topic = "cardano.snapshot.complete"
+# The topic to wait for when listening for genesis values from another module
 genesis-completion-topic = "cardano.sequence.bootstrapped"
 
+# Upstream node connections
 node-addresses = [
     "backbone.cardano.iog.io:3001",
     "backbone.mainnet.cardanofoundation.org:3001",
     "backbone.mainnet.emurgornd.com:3001",
 ]
+# The network magic for the chain to connect to
 magic-number = 764824073
 
-sync-point = "origin"
+# The initial point to start syncing from. Options:
+# - "origin": sync from the very start of the chain
+# - "tip": sync from the very end of the chain
+# - "cache": replay messages from a local filesystem cache, then sync from the point right after that cache.
+# - "snapshot": wait for another module to restore from a snapshot, then sync from the point right after that snapshot.
+sync-point = "snapshot"
+# The cache dir to use when sync-point is "cache"
 cache-dir = "upstream-cache"