From 8c4d1577df84950bbbb9b96da6f4a5107dfd8a1a Mon Sep 17 00:00:00 2001 From: Youngjoon Lee Date: Fri, 15 Sep 2023 17:36:28 +0900 Subject: [PATCH] Add mixnet usage docs (#408) --- mixnet/README.md | 50 ++++++++++++++++++++ nodes/mixnode/README.md | 9 ++++ nodes/mixnode/config.yaml | 7 +++ nodes/nomos-node/README.md | 92 ++++++++++++++++++++++++++++++++++++ nodes/nomos-node/config.yaml | 16 ++++++- 5 files changed, 173 insertions(+), 1 deletion(-) create mode 100644 mixnet/README.md create mode 100644 nodes/mixnode/README.md create mode 100644 nodes/nomos-node/README.md diff --git a/mixnet/README.md b/mixnet/README.md new file mode 100644 index 00000000..78efa28f --- /dev/null +++ b/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. diff --git a/nodes/mixnode/README.md b/nodes/mixnode/README.md new file mode 100644 index 00000000..a4f759ce --- /dev/null +++ b/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. diff --git a/nodes/mixnode/config.yaml b/nodes/mixnode/config.yaml index 901d94a4..a98c9a34 100644 --- a/nodes/mixnode/config.yaml +++ b/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" diff --git a/nodes/nomos-node/README.md b/nodes/nomos-node/README.md new file mode 100644 index 00000000..fee51f7d --- /dev/null +++ b/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. + + + diff --git a/nodes/nomos-node/config.yaml b/nodes/nomos-node/config.yaml index d60e6c86..88a0a787 100644 --- a/nodes/nomos-node/config.yaml +++ b/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"