logos-delivery/simulations/mixnet

Mixnet simulation

Aim

Simulate a local mixnet along with a chat app to publish using mix. This is helpful to test any changes during development.

Simulation Details

The simulation includes:

1. A 5-node mixnet where run_mix_node.sh is the bootstrap node for the other 4 nodes
2. Two chat app instances that publish messages using lightpush protocol over the mixnet
3. A local LEZ sequencer, RLN registration program, and a JSON-RPC service for interacting with the program

Available Scripts

Script	Description
run_mix_node.sh	Bootstrap mix node (must be started first)
run_mix_node1.sh	Mix node 1
run_mix_node2.sh	Mix node 2
run_mix_node3.sh	Mix node 3
run_mix_node4.sh	Mix node 4
run_chat_mix.sh	Chat app instance 1
run_chat_mix1.sh	Chat app instance 2
build_setup.sh	Build and generate RLN credentials

Prerequisites

Before running the simulation, build wakunode2 and chat2mix:

cd <repo-root-dir>
source env.sh
make wakunode2 chat2mix

RLN Program and Service

Requires Docker.

Install Rust and the RISC Zero toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
curl -L https://risczero.com/install | bash
rzup install

Clone the RLN program repo and build the guest programs:

git clone -b feat/rln-service git@github.com:logos-co/logos-lez-rln.git
cd logos-lez-rln
cargo risczero build --manifest-path methods/guest/Cargo.toml

Start the local sequencer (runs in foreground):

./dev.sh

In another terminal, run setup and start the service:

source dev/env.sh && cargo run --bin run_setup && cargo run --bin rln_service

The service listens on http://127.0.0.1:3001.

RLN Spam Protection Setup

Generate RLN credentials and register them in the on-chain Merkle tree for all nodes:

cd simulations/mixnet
./build_setup.sh

This script will:

1. Build and run the setup_credentials tool
2. Generate RLN credentials for all nodes (5 mix nodes + 2 chat clients)
3. Create keystore files (rln_keystore_{peerId}.json) for each node
4. Call the RLN service to register each identity

Important: All scripts must be run from this directory (simulations/mixnet/) so they can access their credential files.

To regenerate credentials (e.g., after adding new nodes), run ./build_setup.sh again - it will clean up old files first.

Usage

Step 1: Start the Mix Nodes

Start the bootstrap node first (in a separate terminal):

./run_mix_node.sh

Look for the following log lines to ensure the node started successfully:

INF mounting mix protocol                      topics="waku node"
INF Node setup complete                        topics="wakunode main"

Verify RLN spam protection initialized correctly by checking for these logs:

INF Initializing MixRlnSpamProtection
INF MixRlnSpamProtection initialized, waiting for sync
INF Group manager started
INF MixRlnSpamProtection started

Then start the remaining mix nodes in separate terminals:

./run_mix_node1.sh
./run_mix_node2.sh
./run_mix_node3.sh
./run_mix_node4.sh

Step 2: Start the Chat Applications

Once all 5 mix nodes are running, start the first chat app:

./run_chat_mix.sh

Enter a nickname when prompted:

pubsub topic is: /waku/2/rs/2/0
Choose a nickname >>

Once you see the following log, the app is ready to publish messages over the mixnet:

Welcome, test!
Listening on
 /ip4/<local-network-ip>/tcp/60000/p2p/16Uiu2HAkxDGqix1ifY3wF1ZzojQWRAQEdKP75wn1LJMfoHhfHz57
ready to publish messages now

Start the second chat app in another terminal:

./run_chat_mix1.sh

Step 3: Test Messaging

Once both chat apps are running, send a message from one and verify it is received by the other.

To exit the chat apps, enter /exit:

>> /exit
quitting...