integrate RLN spam protection into mix protocol with OffChainGroupManager and logos-messaging for broadcasting membership changes and general coordination with API updates and fixes

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: chaitanyaprem

.gitignore

@@ -43,6 +43,7 @@ node_modules/
 
 # RLN / keystore
 rlnKeystore.json
+rln_keystore*.json
 *.tar.gz
 
 # Nimbus Build System

.gitmodules

@@ -195,3 +195,8 @@
 	url = https://github.com/logos-messaging/nim-ffi/
 	ignore = untracked
 	branch = master
+[submodule "vendor/mix-rln-spam-protection-plugin"]
+	path = vendor/mix-rln-spam-protection-plugin
+	url = https://github.com/logos-co/mix-rln-spam-protection-plugin.git
+	ignore = untracked
+	branch = master

apps/chat2mix/chat2mix.nim

@@ -35,6 +35,7 @@ import
 import
   waku/[
     waku_core,
+    waku_core/topics/sharding,
     waku_lightpush/common,
     waku_lightpush/rpc,
     waku_enr,
@@ -47,6 +48,8 @@ import
     common/utils/nat,
     waku_store/common,
     waku_filter_v2/client,
+    waku_filter_v2/common as filter_common,
+    waku_mix/protocol,
     common/logging,
   ],
   ./config_chat2mix
@@ -57,6 +60,105 @@ import ../../waku/waku_rln_relay
 logScope:
   topics = "chat2 mix"
 
+#########################
+## Mix Spam Protection ##
+#########################
+
+# Forward declaration
+proc maintainSpamProtectionSubscription(
+  node: WakuNode, contentTopics: seq[ContentTopic]
+) {.async.}
+
+proc setupMixSpamProtectionViaFilter(node: WakuNode) {.async.} =
+  ## Setup filter-based spam protection coordination for mix protocol.
+  ## Since chat2mix doesn't use relay, we subscribe via filter to receive
+  ## spam protection coordination messages.
+
+  # Register message handler for spam protection coordination
+  let spamTopics = node.wakuMix.getSpamProtectionContentTopics()
+
+  proc handleSpamMessage(
+      pubsubTopic: PubsubTopic, message: WakuMessage
+  ): Future[void] {.async, gcsafe.} =
+    await node.wakuMix.handleMessage(pubsubTopic, message)
+
+  node.wakuFilterClient.registerPushHandler(handleSpamMessage)
+
+  # Wait for filter peer and maintain subscription
+  asyncSpawn maintainSpamProtectionSubscription(node, spamTopics)
+
+proc maintainSpamProtectionSubscription(
+    node: WakuNode, contentTopics: seq[ContentTopic]
+) {.async.} =
+  ## Maintain filter subscription for spam protection topics.
+  ## Monitors subscription health with periodic pings and re-subscribes on failure.
+  const RetryInterval = chronos.seconds(5)
+  const SubscriptionMaintenance = chronos.seconds(30)
+  const MaxFailedSubscribes = 3
+  var currentFilterPeer: Option[RemotePeerInfo] = none(RemotePeerInfo)
+  var noFailedSubscribes = 0
+
+  while true:
+    # Select or reuse filter peer
+    if currentFilterPeer.isNone():
+      let filterPeerOpt = node.peerManager.selectPeer(WakuFilterSubscribeCodec)
+      if filterPeerOpt.isNone():
+        debug "No filter peer available yet for spam protection, retrying..."
+        await sleepAsync(RetryInterval)
+        continue
+      currentFilterPeer = some(filterPeerOpt.get())
+      info "Selected filter peer for spam protection",
+        peer = currentFilterPeer.get().peerId
+
+    # Check if subscription is still alive with ping
+    let pingErr = (await node.wakuFilterClient.ping(currentFilterPeer.get())).errorOr:
+      # Subscription is alive, wait before next check
+      await sleepAsync(SubscriptionMaintenance)
+      if noFailedSubscribes > 0:
+        noFailedSubscribes = 0
+      continue
+
+    # Subscription lost, need to re-subscribe
+    warn "Spam protection filter subscription ping failed, re-subscribing",
+      error = pingErr, peer = currentFilterPeer.get().peerId
+
+    # Determine pubsub topic from content topics (using auto-sharding)
+    if node.wakuAutoSharding.isNone():
+      error "Auto-sharding not configured, cannot determine pubsub topic for spam protection"
+      await sleepAsync(RetryInterval)
+      continue
+
+    let shardRes = node.wakuAutoSharding.get().getShard(contentTopics[0])
+    if shardRes.isErr():
+      error "Failed to determine shard for spam protection", error = shardRes.error
+      await sleepAsync(RetryInterval)
+      continue
+
+    let shard = shardRes.get()
+    let pubsubTopic: PubsubTopic = shard # converter toPubsubTopic
+
+    # Subscribe to spam protection topics
+    let res = await node.wakuFilterClient.subscribe(
+      currentFilterPeer.get(), pubsubTopic, contentTopics
+    )
+    if res.isErr():
+      noFailedSubscribes += 1
+      warn "Failed to subscribe to spam protection topics via filter",
+        error = res.error, topics = contentTopics, failCount = noFailedSubscribes
+
+      if noFailedSubscribes >= MaxFailedSubscribes:
+        # Try with a different peer
+        warn "Max subscription failures reached, selecting new filter peer"
+        currentFilterPeer = none(RemotePeerInfo)
+        noFailedSubscribes = 0
+
+      await sleepAsync(RetryInterval)
+    else:
+      info "Successfully subscribed to spam protection topics via filter",
+        topics = contentTopics, peer = currentFilterPeer.get().peerId
+      noFailedSubscribes = 0
+      await sleepAsync(SubscriptionMaintenance)
+
 const Help =
   """
   Commands: /[?|help|connect|nick|exit]
@@ -210,20 +312,21 @@ proc publish(c: Chat, line: string) {.async.} =
   try:
     if not c.node.wakuLightpushClient.isNil():
       # Attempt lightpush with mix
-
-      (
-        waitFor c.node.lightpushPublish(
-          some(c.conf.getPubsubTopic(c.node, c.contentTopic)),
-          message,
-          none(RemotePeerInfo),
-          true,
-        )
-      ).isOkOr:
-        error "failed to publish lightpush message", error = error
+      let res = await c.node.lightpushPublish(
+        some(c.conf.getPubsubTopic(c.node, c.contentTopic)),
+        message,
+        none(RemotePeerInfo),
+        true,
+      )
+      if res.isErr():
+        error "failed to publish lightpush message", error = res.error
+        echo "Error: " & res.error.desc.get("unknown error")
     else:
       error "failed to publish message as lightpush client is not initialized"
+      echo "Error: lightpush client is not initialized"
   except CatchableError:
     error "caught error publishing message: ", error = getCurrentExceptionMsg()
+    echo "Error: " & getCurrentExceptionMsg()
 
 # TODO This should read or be subscribe handler subscribe
 proc readAndPrint(c: Chat) {.async.} =
@@ -452,7 +555,11 @@ proc processInput(rfd: AsyncFD, rng: ref HmacDrbgContext) {.async.} =
     error "failed to generate mix key pair", error = error
     return
 
-  (await node.mountMix(conf.clusterId, mixPrivKey, conf.mixnodes)).isOkOr:
+  (
+    await node.mountMix(
+      conf.clusterId, mixPrivKey, conf.mixnodes, some(conf.rlnUserMessageLimit)
+    )
+  ).isOkOr:
     error "failed to mount waku mix protocol: ", error = $error
     quit(QuitFailure)
 
@@ -487,6 +594,10 @@ proc processInput(rfd: AsyncFD, rng: ref HmacDrbgContext) {.async.} =
 
   #await node.mountRendezvousClient(conf.clusterId)
 
+  # Subscribe to spam protection coordination topics via filter since chat2mix doesn't use relay
+  if not node.wakuFilterClient.isNil():
+    asyncSpawn setupMixSpamProtectionViaFilter(node)
+
   await node.start()
 
   node.peerManager.start()

apps/chat2mix/config_chat2mix.nim

@@ -237,6 +237,13 @@ type
       name: "kad-bootstrap-node"
     .}: seq[string]
 
+    ## RLN spam protection config
+    rlnUserMessageLimit* {.
+      desc: "Maximum messages per epoch for RLN spam protection.",
+      defaultValue: 100,
+      name: "rln-user-message-limit"
+    .}: int
+
 proc parseCmdArg*(T: type MixNodePubInfo, p: string): T =
   let elements = p.split(":")
   if elements.len != 2:

config.nims

@@ -1,5 +1,8 @@
 import os
 
+when fileExists("nimbus-build-system.paths"):
+  include "nimbus-build-system.paths"
+
 if defined(release):
   switch("nimcache", "nimcache/release/$projectName")
 else:

simulations/mixnet/README.md

@@ -3,66 +3,127 @@
 ## Aim
 
 Simulate a local mixnet along with a chat app to publish using mix.
-This is helpful to test any changes while development.
-It includes scripts that run a `4 node` mixnet along with a lightpush service node(without mix) that can be used to test quickly.
+This is helpful to test any changes during development.
 
 ## Simulation Details
 
-Note that before running the simulation both `wakunode2` and `chat2mix` have to be built.
+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
+
+### 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`:
 
 ```bash
 cd <repo-root-dir>
-make wakunode2
-make chat2mix
+make wakunode2 chat2mix
+```
+
+## RLN Spam Protection Setup
+
+Before running the simulation, generate RLN credentials and the shared Merkle tree for all nodes:
+
+```bash
+cd simulations/mixnet
+./build_setup.sh
 ```
 
-Simulation includes scripts for:
+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 `rln_tree.db` - the shared Merkle tree with all members
+4. Create keystore files (`rln_keystore_{peerId}.json`) for each node
 
-1. a 4 waku-node mixnet where `node1` is bootstrap node for the other 3 nodes.
-2. scripts to run chat app that publishes using lightpush protocol over the mixnet
+**Important:** All scripts must be run from this directory (`simulations/mixnet/`) so they can access their credentials and tree file.
+
+To regenerate credentials (e.g., after adding new nodes), run `./build_setup.sh` again - it will clean up old files first.
 
 ## Usage
 
-Start the service node with below command, which acts as bootstrap node for all other mix nodes.
+### Step 1: Start the Mix Nodes
+
+Start the bootstrap node first (in a separate terminal):
 
-`./run_lp_service_node.sh`
+```bash
+./run_mix_node.sh
+```
 
-To run the nodes for mixnet run the 4 node scripts in different terminals as below.
+Look for the following log lines to ensure the node started successfully:
 
-`./run_mix_node1.sh`
+```log
+INF mounting mix protocol                      topics="waku node"
+INF Node setup complete                        topics="wakunode main"
+```
 
-Look for following 2 log lines to ensure node ran successfully and has also mounted mix protocol.
+Verify RLN spam protection initialized correctly by checking for these logs:
 
 ```log
-INF 2025-08-01 14:51:05.445+05:30 mounting mix protocol                      topics="waku node" tid=39996871 file=waku_node.nim:231 nodeId="(listenAddresses: @[\"/ip4/127.0.0.1/tcp/60001/p2p/16Uiu2HAmPiEs2ozjjJF2iN2Pe2FYeMC9w4caRHKYdLdAfjgbWM6o\"], enrUri: \"enr:-NC4QKYtas8STkenlqBTJ3a1TTLzJA2DsGGbFlnxem9aSM2IXm-CSVZULdk2467bAyFnepnt8KP_QlfDzdaMXd_zqtwBgmlkgnY0gmlwhH8AAAGHbWl4LWtleaCdCc5iT3bo9gYmXtucyit96bQXcqbXhL3a-S_6j7p9LIptdWx0aWFkZHJzgIJyc4UAAgEAAIlzZWNwMjU2azGhA6RFtVJVBh0SYOoP8xrgnXSlpiFARmQkF9d8Rn4fSeiog3RjcILqYYN1ZHCCIymFd2FrdTIt\")"
+INF Initializing MixRlnSpamProtection
+INF MixRlnSpamProtection initialized, waiting for sync
+DBG Tree loaded from file
+INF MixRlnSpamProtection started
+```
 
-INF 2025-08-01 14:49:23.467+05:30 Node setup complete                        topics="wakunode main" tid=39994244 file=wakunode2.nim:104
+Then start the remaining mix nodes in separate terminals:
+
+```bash
+./run_mix_node1.sh
+./run_mix_node2.sh
+./run_mix_node3.sh
+./run_mix_node4.sh
 ```
 
-Once all the 4 nodes are up without any issues, run the script to start the chat application.
+### Step 2: Start the Chat Applications
+
+Once all 5 mix nodes are running, start the first chat app:
 
-`./run_chat_app.sh`
+```bash
+./run_chat_mix.sh
+```
 
-Enter a nickname to be used.
+Enter a nickname when prompted:
 
 ```bash
 pubsub topic is: /waku/2/rs/2/0
 Choose a nickname >>
 ```
 
-Once you see below log, it means the app is ready for publishing messages over the mixnet.
+Once you see the following log, the app is ready to publish messages over the mixnet:
 
 ```bash
 Welcome, test!
 Listening on
- /ip4/192.168.68.64/tcp/60000/p2p/16Uiu2HAkxDGqix1ifY3wF1ZzojQWRAQEdKP75wn1LJMfoHhfHz57
+ /ip4/<local-network-ip>/tcp/60000/p2p/16Uiu2HAkxDGqix1ifY3wF1ZzojQWRAQEdKP75wn1LJMfoHhfHz57
 ready to publish messages now
 ```
 
-Follow similar instructions to run second instance of chat app.
-Once both the apps run successfully, send a message and check if it is received by the other app.
+Start the second chat app in another terminal:
+
+```bash
+./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.
 
-You can exit the chat apps by entering `/exit` as below
+To exit the chat apps, enter `/exit`:
 
 ```bash
 >> /exit