Add mixnet usage docs (#408)

mixnet/README.md

@@ -0,0 +1,50 @@
+# Mixnet
+
+## Components
+
+- `node`: A mixnode implementation that will be assigned to one of the mixnet layers and will be responsible for receiving packets and forwarding them to the next mixnet layer.
+- `client`: A mixclient implementation
+    - which splits a message into multiple Sphinx packets, constructs mix routes for them, and sends the packets to the first mixnode in each route.
+    - which receives Sphinx packets from a mixnode and reconstructs a message.
+
+## Recommended Architecture
+
+```mermaid
+flowchart LR
+    subgraph layer-1
+        mixnode-1-1
+        mixnode-1-2
+    end
+    subgraph layer-2
+        mixnode-2-1
+        mixnode-2-2
+    end
+    subgraph layer-3
+        mixnode-3-1
+        mixnode-3-2
+    end
+    mixnode-1-1 --> mixnode-2-1
+    mixnode-1-1 --> mixnode-2-2
+    mixnode-1-2 --> mixnode-2-1
+    mixnode-1-2 --> mixnode-2-2
+    mixnode-2-1 --> mixnode-3-1
+    mixnode-2-1 --> mixnode-3-2
+    mixnode-2-2 --> mixnode-3-1
+    mixnode-2-2 --> mixnode-3-2
+    mixclient-sender-1 --> mixnode-1-1
+    mixclient-sender-1 --> mixnode-1-2
+    mixnode-3-1 --> mixclient-senderreceiver-1
+    mixnode-3-2 --> mixclient-senderreceiver-2
+```
+
+The mix `node` component can be integrated into a separate application, for example, so that it can be run independently with mixclients for better reliability or privacy.
+
+The mix `client` component is also designed to be integrated into any application that wants to send/receive packets to/from the mixnet.
+The `client` can be configured with one of modes described [below](#mixclient-modes).
+
+## Mixclient Modes
+
+- `Sender`: A mixclient only sends Sphinx packets to mixnodes, but doesn't receive any packets from mixnodes.
+- `SenderReceiver`: A mixclient not only sends Sphinx packets to mixnodes, but also receive packets from mixnodes.
+    - Due to the design of mixnet, mixclients always receive packets from mixnodes in the last mixnet layer.
+    - Currently, only 1:1 mapping is supported. In other words, multiple mixclients cannot listen from the same mixnode. It also means that it is recommended that a single node operator runs both a mixnode and a mixclient.

nodes/mixnode/README.md

@@ -0,0 +1,9 @@
+# Mixnode
+
+A mixnode application that runs the mixnet [`node`](../../mixnet/node/) component, which will be deployed as a part of the mixnet.
+
+For the recommended architecture of mixnet, please see the [mixnet](../../mixnet/README.md) documentation.
+
+## Configurations
+
+A mixnode can be configured by [`config.yaml`](./config.yaml), for example.

nodes/mixnode/config.yaml

@@ -1,7 +1,14 @@
 mixnode:
+  # A listen address for other mixnodes in the mixnet and mixclients who want to send packets.
   listen_address: 127.0.0.1:7777
+  # A (internal) listen address only for a "single" mixclient who wants to receive packets
+  # from the last mixnet layer.
+  # For more details, see the documentation in the "mixnet" crate.
   client_listen_address: 127.0.0.1:7778
+  # A ed25519 private key for decrypting inbound Sphinx packets
+  # received from mixclients or mixnodes in the previous mixnet layer.
   private_key: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
+  # A max number of connections that will stay connected to mixnodes in the next layer.
   connection_pool_size: 255
 log:
   backend: "Stdout"

nodes/nomos-node/README.md

@@ -0,0 +1,92 @@
+# Nomos Node
+
+Nomos blockchain node 
+
+
+## Network service
+
+Nomos node can be configured with one of the following network backends:
+- [libp2p](../../nomos-services/backends/libp2p.rs)
+- [Waku](../../nomos-services/backends/waku.rs)
+
+### Mixclient integration
+
+The [mixclient](../../mixnet/client/) is currently integrated as a part of the libp2p network backend.
+To run a Nomos node with the libp2p network backend, the `mixnet_client` and `mixnet_delay` fields in the [`config.yaml`](./config.yaml) must be specified, so the Nomos node can send/receive packets to/from mixnodes.
+
+For more detials about the mixnode/mixclient architecture, see the [mixnet documentation](../../mixnet/README.md).
+
+```mermaid
+flowchart LR
+
+    subgraph mixnet
+        direction LR
+
+        subgraph layer-1
+            direction TB
+            mixnode-1-1
+            mixnode-1-2
+        end
+        subgraph layer-2
+            direction TB
+            mixnode-2-1
+            mixnode-2-2
+        end
+        subgraph layer-3
+            direction TB
+            mixnode-3-1
+            mixnode-3-2
+        end
+
+        mixnode-1-1 --> mixnode-2-1
+        mixnode-1-1 --> mixnode-2-2
+        mixnode-1-2 --> mixnode-2-1
+        mixnode-1-2 --> mixnode-2-2
+        mixnode-2-1 --> mixnode-3-1
+        mixnode-2-1 --> mixnode-3-2
+        mixnode-2-2 --> mixnode-3-1
+        mixnode-2-2 --> mixnode-3-2
+    end
+
+    subgraph nomos-network
+        direction TB
+
+        subgraph nomos-node-1
+            libp2p-1[libp2p] --> mixclient-sender-1[mixclient-sender]
+        end
+        subgraph nomos-node-2
+            libp2p-2[libp2p] --> mixclient-sender-2[mixclient-sender]
+        end
+        subgraph nomos-node-3
+            libp2p-3[libp2p] <--> mixclient-senderreceiver
+        end
+    end
+    
+    mixclient-sender-1 --> mixnode-1-1
+    mixclient-sender-1 --> mixnode-1-2
+    mixclient-sender-2 --> mixnode-1-1
+    mixclient-sender-2 --> mixnode-1-2
+    mixclient-senderreceiver --> mixnode-1-1
+    mixclient-senderreceiver --> mixnode-1-2
+    mixnode-3-2 --> mixclient-senderreceiver
+```
+
+#### Sender mode
+
+If you are a node operator who wants to run only a Nomos node (not a mixnode),
+you can configure the mixclient as the `Sender` mode (like `nomos-node-1` or `nomos-node-2` above).
+Then, the Nomos node sends messages to the mixnet instead of broadcasting them directly through libp2p gossipsub.
+
+The mixclient in the `Sender` mode will splits a message into multiple Sphinx packets by constructing mix routes based on the mixnet topology configured, and sends packets to the mixnode.
+
+#### SenderReceiver mode
+
+If you are a node operator who runs both a Nomos node and a mixnode,
+you can configure the mixclient as the `SenderReceiver` mode by specifying the client listen address of your mixnode (like `nomos-node-3` and `mixnode-3-2` above).
+
+The Nomos node with the mixclient in the `SenderRecevier` mode will behave essentially the same as the one in the `Sender` mode.
+In addition, the node will receive packets from the connected mixnode, reconstruct a message, and broadcast it through libp2p gossipsub, if the connected mixnode is part of the last mixnet layer.
+In other words, at least one Nomos node in the entire network must have a mixclient in the `SenderReceiver` mode, so that reconstructed messages can be broadcasted to all other Nomos nodes.
+
+
+

nodes/nomos-node/config.yaml

@@ -19,14 +19,28 @@ network:
     discV5BootstrapNodes: []
     initial_peers: []
     relayTopics: []
+    # Mixclient configuration to communicate with mixnodes.
+    # The libp2p network backend always requires this mixclient configuration
+    # (cannot be disabled for now).
     mixnet_client:
+      # A mixclient mode. For details, see the documentation of the "mixnet" crate.
+      # - Sender
+      # - !SenderReceiver [mixnode_client_listen_address]
       mode: Sender
+      # A mixnet topology, which contains the information of all mixnodes in the mixnet.
+      # (The topology is static for now.)
       topology:
+        # Each mixnet layer consists of a list of mixnodes.
         layers:
          - nodes:
-            - address: 127.0.0.1:7777
+            - address: 127.0.0.1:7777  # A listen address of the mixnode
+              # A ed25519 public key for encrypting Sphinx packets for the mixnode
               public_key: "0000000000000000000000000000000000000000000000000000000000000000"
+      # A max number of connections that will stay connected to mixnodes in the first mixnet layer.
       connection_pool_size: 255
+    # A range of total delay that will be set to each Sphinx packets
+    # sent to the mixnet for timing obfuscation.
+    # Panics if start > end.
     mixnet_delay:
       start: "0ms"
       end: "0ms"