logos-co
/
nomos-node
mirror of
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add mixnet usage docs (#408)

This commit is contained in:
Youngjoon Lee 2023-09-15 17:36:28 +09:00 committed by GitHub
parent 3121a41b60
commit 8c4d1577df
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 173 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
mixnet/README.md Normal file
View File

@ -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.

9
nodes/mixnode/README.md Normal file
View File

@ -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.

7
nodes/mixnode/config.yaml
View File

@ -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"

92
nodes/nomos-node/README.md Normal file
View File

@ -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.

16
nodes/nomos-node/config.yaml
View File

@ -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"