Introduction to Logos Delivery Simulator

The logos-delivery-simulator is a protocol simulator for logos-delivery — the Nim implementation of a libp2p protocol suite for private, censorship-resistant peer-to-peer messaging.

What it does

The simulator orchestrates a network of logos-delivery nodes inside Docker, on a single machine, so you can exercise the protocol stack end-to-end without depending on any public network. Concretely, on docker-compose up it:

• spins up a configurable number of logos-delivery nodes (default: 5, upper bound around 200) all connected through a single bootstrap node via discv5,
• launches a private Anvil blockchain (foundry) under your full control,
• deploys an RLN (Rate Limiting Nullifier) contract on that chain and registers an RLN membership for every node so they can publish valid rate-limited messages,
• exposes each node's REST API so you can inject traffic, query the store, attach external nodes, etc.,
• ships a Grafana + Prometheus + cAdvisor + Epirus block-explorer stack pre-wired to the simulated network for observability.

The whole network runs on an isolated Docker bridge (logos-delivery-simulator_simulation) and uses an ad-hoc cluster id (66) so it cannot accidentally talk to any production fleet.

What protocols you can exercise

The tutorials in this book each target one of the libp2p protocols implemented in logos-delivery:

A full list of the protocols implemented by logos-delivery (Relay, Store, Filter, Lightpush, Peer Exchange, RLN Relay, Metadata, Mix, Rendezvous) is in logos-delivery/AGENTS.md. The specifications themselves live at rfc.vac.dev/waku under the WAKU2-XXX identifiers.

Goals

• Test new protocol features end-to-end with multiple nodes before they go to a real fleet.
• Run as a long-lived network on master to catch breaking changes early.
• Explore the protocol's limits under different loads, message sizes, and rate limits.
• Provide a controlled, easily-reproducible environment for debugging.

A note on naming

logos-delivery was previously called nwaku, and Logos Messaging is a rebrand of the Waku project. A lot of legacy names are still in flight and you'll see them in this repo and the upstream — they all refer to the same thing:

• The compiled binary is still called wakunode2 (logos-delivery/Makefile).
• The shared library is liblogosdelivery.
• The published Docker image used by ${LD_IMAGE} is still pushed to quay.io/wakuorg/nwaku-pr:<tag> (logos-delivery/.github/workflows/container-image.yml:91).
• The default fallback in docker-compose.yml is wakuorg/nwaku:latest.
• Specifications still live under the WAKU2-XXX namespace at rfc.vac.dev/waku.
• Inside the source tree of logos-delivery, modules are still named waku/waku_relay, waku/waku_store, etc.

This is consistent with the upstream project's stance, quoted from logos-delivery/AGENTS.md: "Logos Messaging was formerly known as Waku. Waku-related terminology remains within the codebase for historical reasons."

You don't need to do anything about it — it's just useful to know that nwaku, wakunode2, and logos-delivery all refer to the same binary in this repo.

Deploy a Logos Delivery network

This page deploys a self-contained network of logos-delivery nodes (the wakunode2 binary, distributed as a Docker image) on a single machine. It requires docker and docker-compose. Configuration is exposed through environment variables — if a knob you need is missing, PRs are welcome.

The most important parameters are:

• LD_IMAGE — the logos-delivery Docker image that every node will run. The image is still published under the legacy wakuorg/nwaku namespace (see the upstream container build); pin a tag for reproducible runs.
• NUM_LD_NODES — number of logos-delivery nodes to launch (default 5; upper bound around 200 depending on host resources).
• RLN_RELAY_EPOCH_SEC and RLN_RELAY_MSG_LIMIT — RLNv2 parameters that cap how many messages each node may publish per epoch.
• TRAFFIC_DELAY_SECONDS and MSG_SIZE_KBYTES — used by the bundled rest-traffic injector to drive load through each node's REST API.

export LD_IMAGE=wakuorg/nwaku:latest
export NUM_LD_NODES=5
export RLN_RELAY_EPOCH_SEC=1
export RLN_RELAY_MSG_LIMIT=1

export TRAFFIC_DELAY_SECONDS=15
export MSG_SIZE_KBYTES=10

export PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
export ETH_FROM=0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266

Once configured, start all containers:

docker-compose --compatibility up -d

After a couple of minutes, everything should be running at:

• http://localhost:3000 Block explorer
• http://localhost:3001 Grafana metrics

For greater observability, one can access each node logs as follows:

# All nwaku replicas at once
docker-compose logs nwaku

# A specific replica (e.g. index 1 or 2)
docker-compose logs --index=1 nwaku
docker-compose logs --index=2 nwaku

Or if you want to follow the logs

docker-compose logs -f --index=1 nwaku

Once the network of logos-delivery nodes is up and running we can use it to perform different tests, connecting other nodes that we fully control with specific characteristics. This ranges from connecting spammer nodes, light clients, store nodes, and in the future unsynced nodes, etc.

Now that we have the network deployed we can use it. Hereunder we describe how to use the network deployed by logos-delivery-simulator to perform end-to-end tests of any desired feature. Each tutorial below targets a specific protocol from the logos-delivery suite:

• Inject traffic:
• Connect external full node:
• Connect external spammer node:
• Connect external light node:
• Register memberships:

⚠️ For every use case, ensure that your node is configured in the same way as the rest of the nodes, otherwise messages may be lost. Note that it can be also an intended test, seeing how the network reacts to other nodes connecting to it.

Inject traffic

Protocol exercised: Relay (gossipsub) — messages are published via the REST API and propagated to every node through the relay protocol from logos-delivery. The REST API itself is documented at waku-org.github.io/waku-rest-api.

In order to inject traffic into the network, we can use the REST API of each logos-delivery node. We have a simple dockerized script in rest-traffic, that can perform this task. In the following command we run a docker container connected to the logos-delivery-simulator network. This script will inject a message every delay-seconds with a size of msg-size-kbytes into a given pubsub-topic. Note that in multiple-nodes you can configure the nodes that will publish messages, where [1..5] will publish to nodes 1, 2, 3, 4, 5. You can publish to a single node (e.g. node 1) by using [1..1].

docker run -it --network logos-delivery-simulator_simulation alrevuelta/rest-traffic:d936446 \
--delay-seconds=10 \
--msg-size-kbytes=5 \
--pubsub-topic=/waku/2/rs/66/0 \
--multiple-nodes="http://logos-delivery-simulator_nwaku_[1..5]:8645"

Note that the REST API doesn’t allow to publish messages exceeding the rate limit, so this tool can’t be used to test beyond the rate limits.

🎯Goals:

• Test message publishing via the REST API and that they are valid across the network.
• Test the network under different message load: rates and sizes.

👀Observability:

• Check the logs of each nwaku node, verifying the messages are correctly received via the API and forwarded to other nodes.
• Check grafana dashboard localhost:3001 ”RLN Valid Messages Total” increases as expected.

Connect external full node

Protocol exercised: Relay + RLN Relay — attaches an additional logos-delivery node to the simulated network as a full relay participant with its own RLN membership.

If you want to attach a node with some custom configuration to the simulated Logos Delivery network — perhaps a different image, a different RLN epoch length, or any other knob — you can do it as follows. Bear in mind that if this node uses different RLN parameters (e.g. rln-relay-epoch-sec or rln-relay-user-message-limit) than the rest of the network, the gossipsub layer will treat its messages as invalid and you won't see them propagate.

• ⚠️set your own staticnode

docker run -it --network logos-delivery-simulator_simulation wakuorg/nwaku:latest \
      --relay=true \
      --rln-relay=true \
      --rln-relay-dynamic=true \
      --rln-relay-eth-client-address=http://foundry:8545 \
      --rln-relay-eth-contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
      --rln-relay-epoch-sec=1 \
      --rln-relay-user-message-limit=1 \
      --log-level=DEBUG \
      --staticnode=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
      --pubsub-topic=/waku/2/rs/66/0 \
      --cluster-id=66

You can for example try to connect a node running in a different cluster-id or other weird scenarios.

You can also try to connect multiple nodes with a loop. Note the &. Remember to kill the new nodes once you are done.

for i in {1..5}; do
    docker run -it --network logos-delivery-simulator_simulation wakuorg/nwaku:latest \
      --relay=true \
      --rln-relay=true \
      --rln-relay-dynamic=true \
      --rln-relay-eth-client-address=http://foundry:8545 \
      --rln-relay-eth-contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
      --rln-relay-epoch-sec=1 \
      --rln-relay-user-message-limit=1 \
      --log-level=DEBUG \
      --staticnode=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
      --pubsub-topic=/waku/2/rs/66/0 \
      --cluster-id=66 &
done

🎯Goals:

• Connect a different node(s) to the network for some ad hoc test.
• See how the network reacts to a node with different configuration.

👀Observability:

• Check the new node logs, ensuring the behaviour matches the expected.

Connect external spam node

Protocol exercised: RLN Relay (spam protection) + gossipsub peer scoring — verifies that nodes exceeding their RLN rate limit are detected and disconnected via peer score.

By using the nwaku-spammer build, you can connect a node to the network that spams the other nodes, sending messages exceeding its rate limit. It will register an RLN membership at startup. It should be configured with the same contract and rln-relay-user-message-limit as the rest of the network. If a node spams enough for its gossipsub peer score to drop below the threshold, the other logos-delivery nodes will disconnect from it.

• ⚠️ change staticnode to the node you wish. Note that the multiaddress is logged by every peer at startup.

docker run -it --network logos-delivery-simulator_simulation quay.io/wakuorg/nwaku-pr:2821 \
      --relay=true \
      --rln-relay=true \
      --rln-relay-dynamic=true \
      --rln-relay-eth-client-address=http://foundry:8545 \
      --rln-relay-eth-contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
      --rln-relay-epoch-sec=1 \
      --rln-relay-user-message-limit=1 \
      --log-level=DEBUG \
      --staticnode=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
      --pubsub-topic=/waku/2/rs/66/0 \
      --cluster-id=66 \
      --rln-relay-eth-private-key=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
      --rln-relay-cred-path=/keystore.json \
      --rln-relay-cred-password=password123 \
      --spammer=true \
      --spammer-delay-between-msg=200

An alternative config for the spamming node is to have it connect to the discv5 network instead of a single static node. The staticnode config can be replaced with the below config. The bootstrap node will log its ENR.

 --discv5-discovery=true \
 --discv5-enr-auto-update=True \
 --discv5-bootstrap-node=BOOTSTRAP_ENR\

You can also try to connect multiple spamming nodes, but it might be necessary to use a different private-key for each one to avoid the limitation of multiple contract transactions with the same nonce. Otherwise add a delay before running a new node. Note the &. Remember to kill the new nodes once you are done.

for i in {1..5}; do
docker run -it --network logos-delivery-simulator_simulation quay.io/wakuorg/nwaku-pr:2821 \
      --relay=true \
      --rln-relay=true \
      --rln-relay-dynamic=true \
      --rln-relay-eth-client-address=http://foundry:8545 \
      --rln-relay-eth-contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
      --rln-relay-epoch-sec=1 \
      --rln-relay-user-message-limit=1 \
      --log-level=DEBUG \
      --staticnode=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
      --pubsub-topic=/waku/2/rs/66/0 \
      --cluster-id=66 \
      --rln-relay-eth-private-key=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
      --rln-relay-cred-path=/keystore.json \
      --rln-relay-cred-password=password123 \
      --spammer=true \
      --spammer-delay-between-msg=200 &
done

The spammer node also provides a method to test burst messaging. It will send the total user-message-limit of messages sequentially without pauses, then rests for the epoch period and repeats.

docker run -it --network logos-delivery-simulator_simulation quay.io/wakuorg/nwaku-pr:2821 \
      --relay=true \
      --rln-relay=true \
      --rln-relay-dynamic=true \
      --rln-relay-eth-client-address=http://foundry:8545 \
      --rln-relay-eth-contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
      --rln-relay-epoch-sec=1 \
      --rln-relay-user-message-limit=1 \
      --log-level=DEBUG \
      --staticnode=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
      --pubsub-topic=/waku/2/rs/66/0 \
      --cluster-id=66 \
      --rln-relay-eth-private-key=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
      --rln-relay-cred-path=/keystore.json \
      --rln-relay-cred-password=password123 \
      --spammer=true \
      --spammer-burst=true

🎯Goals:

• Connect a spamming node(s) to the network where spam messages are rejected and misbehaving peers are disconnected for a time.
• See how the network reacts to different spamming rates.

👀Observability:

• Check the logs of the new node logs, ensuring the behaviour matches the expected.
• Check grafana metrics at localhost:3001.
• Check that the RLN membership was registered in the block explorer localhost:3000.

Connect external light node

Protocol exercised: Lightpush + RLN — a resource-restricted client publishes messages through a full logos-delivery node using the lightpush protocol, with RLN proofs fetched directly from the contract.

By using go-waku-light, you can connect one or multiple light clients to the network. This utility can be configured to send messages at a given rate using a given peer as light-push. It will register an RLN membership at startup. Bear in mind that it should be configured with the same contract and user-message-limit as the rest of the network. You should modify the lightpush-peer.

Note that if you spin up multiple services like this using the same priv-key some of the transactions registering the RLN membership may fail due to the nonce being repeated. This can be fixed by using multiple keys or waiting for the registration to be completed before spinning up the next process.

• ⚠️ change lightpush-peer to the node you wish. Note that the multiaddress is logged by every peer at startup.

docker run --network logos-delivery-simulator_simulation alrevuelta/go-waku-light:4fabb22 \
--eth-endpoint=http://foundry:8545 \
--contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
send-messages-loop \
--priv-key=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--user-message-limit=1 \
--message="light client sending a rln message" \
--content-topic=/basic2/1/test/proto \
--pubsub-topic=/waku/2/rs/66/0 \
--cluster-id=66 \
--lightpush-peer=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAmAA99YfoLitSXgY1bHaqjaTKhyrU4M4y3D1rVj1bmcgL8 \
--message-every-secs=5 \
--epoch-size-secs=1

Note that in some examples, it could be interesting to run multiple instances, either in parallel or one after the other. For example if you set amount-message-to-send=1 this will send just 1 message and exit. You can for example run this 100 times, where a fresh RLN membership will be created on every run, create a new peerId, send a message and exit.

for i in {1..5}; do
    docker run --rm --network logos-delivery-simulator_simulation alrevuelta/go-waku-light:4fabb22 \
    --eth-endpoint=http://foundry:8545 \
    --contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
    send-messages-loop \
    --priv-key=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
    --user-message-limit=1 \
    --message="light client sending a rln message" \
    --content-topic=/basic2/1/test/proto \
    --pubsub-topic=/waku/2/rs/66/0 \
    --cluster-id=66 \
    --lightpush-peer=/ip4/10.2.0.16/tcp/60000/p2p/16Uiu2HAm6a4kUT7YutsbwgQcmWw5VLzN3zj1StwiBVf2LUH9kb4A \
    --message-every-secs=5 \
    --epoch-size-secs=1 \
    --amount-message-to-send=1
    
    if [ $? -ne 0 ]; then
        echo "Command failed at iteration $i"
        break
    fi
done

🎯Goals:

• Tests lightpush end to end, where proofs are fetched directly from the contract

👀Observability:

• Check the logs of the node you provided as lightpush-peer.
• Check grafana metrics at localhost:3001.
• Check that the RLN membership was registered in the block explorer localhost:3000.

Connect external store node

Protocol exercised: Store — a logos-delivery node with persistent storage joins the network, archives messages it sees on the relay, and serves historical queries via the store protocol.

One or more external store nodes can be connected to the logos-delivery-simulator network by using configuration similar to that shown below. The store node(s) can use the DB as backend from an existing staging or production system DB or a custom one. When connecting to any DB ensure that the store-message-retention-policy matches that of the system. The staticnode that the store node connects to can be any existing node in the logos-delivery-simulator network, alternatively use the discv5 configuration.

 --discv5-discovery=true \
 --discv5-enr-auto-update=True \
 --discv5-bootstrap-node=BOOTSTRAP_ENR\

The store node can be queried via the waku rest API. An easy way to find a message hash to query is by checking the store node logs for the message archived message:

docker logs nwaku_storenode_1 | grep -i "message archived"

The store node will need to have log-level set to DEBUG for this logging to be available.

The message-finder tool could also be useful for store node testing.

docker run -it --network logos-delivery-simulator_simulation --name nwaku_storenode_1 -d harbor.status.im/wakuorg/nwaku:latest \
    --relay=true\
    --rest=true\
    --rest-address=0.0.0.0\
    --rest-port=8645\
    --log-level=DEBUG\
    --pubsub-topic=/waku/2/rs/66/0\
    --cluster-id=66\
    --metrics-server=true\
    --discv5-discovery=true\
    --discv5-enr-auto-update=true\
    --store=true\
    --store-message-db-url=<e.g. postgres://pguser:pgpasswrd@127.0.0.1:5432/postgres>\
    --store-message-retention-policy=size:120GB\
    --staticnode=/ip4/0.0.0.0/tcp/60000/p2p/16Uiu2HAmC8Fe4Egsq6AKubmBPr52TQmwc26yoCkszwo6dfQncZ4m\
    --nodekey=5978783f8b1a16795032371fff7a526af352d9dca38179af7d71c0122942fa20

🎯Goals:

• Connect a store node(s) to the network for ad hoc store protocol testing.
• Verify that store queries get the expected results.

👀Observability:

• Check the logs of the newly connected store node, ensuring the behaviour matches the expected.

Register memberships

Protocol exercised: RLN membership registration — bulk-registers RLN memberships against the on-chain RLN contract that the simulator deploys, so you can stress how the logos-delivery nodes pick up new memberships in real time.

The go-waku-light tool can be used as well to register multiple RLN memberships. This can be useful to stress test the nodes, forcing a large amount of memberships. Set amount to the amount of memberships that you want to register. Note that it takes some time, since memberships are registered one after the other. You can spin up multiple services like this, but in that case you must provide different priv-key to each. Note that these memberships are essentially throwaway — they are not used to send messages.

docker run --network logos-delivery-simulator_simulation alrevuelta/go-waku-light:07b8f32 \
--eth-endpoint=http://foundry:8545 \
--contract-address=0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9 \
register \
--priv-key=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 \
--user-message-limit=1 \
--amount=100

The foundry service in the logos-delivery-simulator generates deterministic accounts that can be used to register memberships. It is recommended to use different accounts for registering multiple memberships at the same time. The last 20 accounts generated are provided for ad-hoc testing purposes.

🎯Goals:

• Tests how the network reacts to a massive amount of memberships.
• Tests that nodes pick-up new memberships in real time and match.

👀Observability:

• Check the RLN memberships being registered in the block explorer localhost:3000.
• Check in grafana localhost:3001 the metric “RLN Registered Memberships” and verify the nodes are picking up the new registrations.