feat: use stateless rln (#9)

* feat(rln): replace pmtree backend with Nim IMT for stateless zerokit

Move Merkle tree state from zerokit's pmtree-ft to a pure-Nim
IncrementalMerkleTree (depth-20 Poseidon).  Lets the plugin build
against zerokit --features stateless and share a single archive with
relay -- eliminates the dual-archive symbol collision after zerokit's
v0.9->v2.0 FFI rename.

Architecture matches zerokit's documented stateless pattern
("stateless RLN and separate Merkle tree", rln-cli/README.md).
Byte-parity with pmtree locked down by a 61-op fixture captured from
the default-features build, plus delete/sparse-setLeaf/idempotency/
out-of-capacity coverage.

* chore(nimble): bump nim-libp2p to d4cd68b91b

Aligns with nim-libp2p-mix's libp2p pin so the diamond dependency
(waku -> {libp2p, nim-libp2p-mix -> libp2p}) resolves to a single
libp2p source.  d4cd68b91b is 14 commits past b16873f07, which means
the boringssl URL+range form is in place -- nimble vnext SAT can
solve without --solver:legacy.

No code changes; plugin only uses libp2p/protobuf/minprotobuf and
libp2p/varint, neither of which changed in the e1bbda4f6..d4cd68b91b
window.  All 29 plugin tests still green.

* chore(nimble): bump nim-libp2p-mix pin to 99d2ca0

nim-libp2p-mix#f24cd25a (its master tip) still pins libp2p#7e72c0d6,
which uses the pre-fix URL+tag form for boringssl and triggers the
nimble vnext SAT bug at any downstream consumer that also requires
modern libp2p (URL+range form).

99d2ca0 (chore/bump-libp2p-master tip on origin) bumps that pin to
libp2p#d4cd68b91b -- same as our pin in the prior commit -- so the
constraint graph is consistent end-to-end.  Carries PR #10's
Rng-type migration; does not affect this plugin (only
libp2p_mix/spam_protection is imported and its API surface is
unchanged).

All 29 plugin tests green against the new pin.

* chore(stateless-rln): drop pmtree-parity scaffolding, keep IMT regression test

capture_golden.nim and the pmtree-derived golden fixture served as the
one-time migration acceptance criterion; capture_golden.nim only compiled
against non-stateless zerokit and is now uncompilable in the plugin's build.
The IMT is internal-only, so pmtree parity is no longer a load-bearing
invariant — what we need is regression protection for the Nim IMT itself,
which the renamed test still provides.

* chore(nimble): bump libp2p to release/v2.0.0 tip + libp2p-mix to v2.0 bump

- libp2p pin: d4cd68b91b → c43199378 (release/v2.0.0 tip; 3 patch commits
  past the v2.0.0 bump). SHA-pinned because vacp2p/nim-libp2p has not yet
  published a v2.0.0 git tag.
- libp2p-mix pin: 99d2ca07 → a32af1a4 (chore/bump-libp2p-v2.0.0 tip after
  the v2.0.0 adaptation commit).
- nim minimum: 2.0.0 → 2.2.4 to match v2.0.0's transitive requirement.

Zero plugin code changes needed: libp2p v2.0.0's API churn (LPProtocol stream
limits, Switch service lifecycle, sink changes, etc.) does not affect the
plugin (no LPProtocol subclassing, no Service subclassing, no Connection
subclassing). Verified compile-link against the new libp2p-mix.

* chore(nimble): bump libp2p_mix pin to PR #14 HEAD

Brings in the move-semantics propagation + lockfile-as-build-artefact
cleanup. Pinned to the PR HEAD (50c4ab4) until logos-co/nim-libp2p-mix#14
and #12 merge to master.

waku.nimble pins the same SHA to keep the diamond dep collapsed to a
single libp2p_mix source.

* fix(nimble): correct libp2p_mix SHA to actual PR #14 tip

Previous commit (78995fc) pinned a fabricated SHA suffix
(50c4ab43904baa3...) that doesn't exist on the remote. The actual tip of
experiment/drop-nimble-lock is 50c4ab4fa788a33eb12a0a2cecaa708873352b58.
Both `git ls-remote origin experiment/drop-nimble-lock` and the cold-cache
build failure confirmed this.

waku.nimble pin will mirror this corrected SHA.

* refactor: rename newMixRlnSpamProtection to MixRlnSpamProtection.new

* feat: make PublishCallback return Result and track broadcast futures (#11)

Previously PublishCallback returned Future[void], so publish errors were
silently dropped, and the proof-metadata broadcast in the synchronous
verifyProof method was fired via an untracked asyncSpawn.

- PublishCallback now returns Future[Result[void, string]] so callers can
  handle publish failures.
- group_manager membership broadcasts handle the returned error (warn).
- verifyProof is a sync method (overrides a sync base), so it cannot await;
  its proof-metadata broadcast now runs as a tracked background future
  (pruned when finished, cancelled in stop()) instead of asyncSpawn.
- update createLoggingPublishCallback and doc examples accordingly.

Addresses review feedback on logos-delivery#3931.

Author: chaitanyaprem

README.md

@@ -22,12 +22,15 @@ This plugin provides:
 │    - verifyProof(proof, bindingData) → bool                     │
 │    - proofSize() → 301 bytes (protobuf-encoded)                 │
 ├─────────────────────────────────────────────────────────────────┤
-│  RLN Core (zerokit v2.0.2 FFI)                                  │
+│  RLN Core (zerokit v2.0.2 FFI, --features stateless)            │
 │    - Proof generation/verification (RLN-v2 format)              │
 │    - Partial-proof caching for faster steady-state sends         │
-│    - Merkle tree operations                                      │
 │    - Poseidon hash, secret recovery                              │
 ├─────────────────────────────────────────────────────────────────┤
+│  IncrementalMerkleTree (pure Nim, src/.../merkle_tree.nim)      │
+│    - depth-20 Poseidon Merkle tree, byte-parity with pmtree     │
+│    - set/get/delete leaves, root, inclusion proofs               │
+├─────────────────────────────────────────────────────────────────┤
 │  OffchainGroupManager                                            │
 │    - Membership tree (depth 20, ~1M members)                     │
 │    - Credential management                                       │
@@ -48,21 +51,23 @@ This plugin provides:
 
 ### Zerokit Library (librln)
 
-This plugin requires the zerokit RLN library (v2.0.2) for proof generation and verification.
+This plugin requires the zerokit RLN library (v2.0.2) for Poseidon hashing,
+witness construction, and Groth16 prove/verify.
 
-The plugin keeps a local Merkle tree (offchain membership), so zerokit must be
-built with default features — do **not** enable the `stateless` cargo feature.
+The Merkle tree of memberships lives on the **Nim side** (see
+`src/mix_rln_spam_protection/merkle_tree.nim`), so the consuming application
+**must** build zerokit with `--features stateless` to avoid carrying a
+second zerokit archive alongside relay's.  The plugin will not link against
+a default-features (pmtree-ft) build — `ffi_set_next_leaf`, `ffi_get_root`,
+`ffi_get_merkle_proof`, etc. are no longer referenced.
 
 ```bash
-# Option 1: Build from source
+# Build from source
 git clone https://github.com/vacp2p/zerokit
 cd zerokit
 git checkout v2.0.2
-cargo build --release -p rln
+cargo build --release -p rln --no-default-features --features stateless
 cp target/release/librln.a /path/to/your/project/
-
-# Option 2: Download prebuilt
-# https://github.com/vacp2p/zerokit/releases/tag/v2.0.2
 ```
 
 ## Installation
@@ -75,7 +80,7 @@ requires "mix_rln_spam_protection >= 0.1.0"
 
 ### Dependencies
 
-- [zerokit-rln](https://github.com/vacp2p/zerokit) v2.0.2 - RLN proving library (static linking, default features — no `stateless`)
+- [zerokit-rln](https://github.com/vacp2p/zerokit) v2.0.2 - RLN proving library (static linking, **`--no-default-features --features stateless`**)
 - nim >= 2.0.0
 - chronos, results, chronicles, nimcrypto
 
@@ -93,7 +98,7 @@ config.keystorePassword = "my-secure-password"
 # config.proofMetadataContentTopic = "/my-app/rln/metadata/v1"
 
 # Create plugin
-let plugin = newMixRlnSpamProtection(config).valueOr:
+let plugin = MixRlnSpamProtection.new(config).valueOr:
   echo "Failed to create plugin: ", error
   return
 

mix_rln_spam_protection.nimble

@@ -6,7 +6,7 @@ license = "MIT OR Apache-2.0"
 srcDir = "src"
 
 # Dependencies
-requires "nim >= 2.0.0"
+requires "nim >= 2.2.4"
 requires "results >= 0.4.0"
 requires "stew >= 0.4.2"
 requires "chronicles >= 0.11.0"
@@ -15,11 +15,21 @@ requires "nimcrypto >= 0.6.0"
 requires "secp256k1 >= 0.5.0"
 requires "json_serialization >= 0.2.0"
 
-# nim-libp2p — used directly for protobuf/minprotobuf and varint
-requires "https://github.com/vacp2p/nim-libp2p.git#e1bbda4f6"
+# nim-libp2p — used directly for protobuf/minprotobuf and varint. Pinned to
+# the same commit nim-libp2p-mix uses so the diamond dep resolves to a single
+# libp2p source. c43199378 is the release/v2.0.0 tip (3 patch commits past
+# the v2.0.0 bump). SHA-pinned because vacp2p/nim-libp2p has not yet
+# published a v2.0.0 git tag.
+requires "https://github.com/vacp2p/nim-libp2p.git#c43199378f46d0aaf61be1cad1ee1d63e8f665d6"
 
-# libp2p_mix — extracted into its own repo; previously libp2p/protocols/mix
-requires "https://github.com/logos-co/nim-libp2p-mix.git#f24cd25a54e2156d66b497f6d576aab3ccfc8fa6"
+# libp2p_mix — extracted into its own repo; previously libp2p/protocols/mix.
+# Tip of experiment/drop-nimble-lock (currently PR #14, stacked on top of
+# chore/bump-libp2p-v2.0.0). Carries the v2.0.0 bump + sink overrides +
+# AddressConfidence.Infinite + the deeper move-semantics propagation +
+# the lockfile-as-build-artefact cleanup. Pinned to the PR HEAD until the
+# stack lands on master; waku.nimble pins the same SHA to keep the diamond
+# dep collapsed to one libp2p_mix source.
+requires "https://github.com/logos-co/nim-libp2p-mix.git#50c4ab4fa788a33eb12a0a2cecaa708873352b58"
 
 # Tasks
 task test, "Run tests":

src/mix_rln_spam_protection.nim

@@ -22,12 +22,15 @@
 ## config.keystorePassword = "my-password"
 ##
 ## # Create and initialize plugin
-## let plugin = newMixRlnSpamProtection(config).get()
+## let plugin = MixRlnSpamProtection.new(config).get()
 ## await plugin.init()
 ##
 ## # Set up logos-messaging integration
-## plugin.setPublishCallback(proc(topic: string, data: seq[byte]) {.async.} =
+## plugin.setPublishCallback(proc(
+##     topic: string, data: seq[byte]
+## ): Future[Result[void, string]] {.async.} =
 ##   await logosMessaging.publish(topic, data)
+##   ok()
 ## )
 ##
 ## # Start the plugin
@@ -71,26 +74,10 @@
 
 import
   ./mix_rln_spam_protection/[
-    types,
-    constants,
-    protobuf,
-    codec,
-    rln_interface,
-    group_manager,
-    nullifier_log,
-    spam_protection,
-    coordination,
-    credentials
+    types, constants, protobuf, codec, rln_interface, group_manager, nullifier_log,
+    spam_protection, coordination, credentials,
   ]
 
 export
-  types,
-  constants,
-  protobuf,
-  codec,
-  spam_protection,
-  coordination,
-  credentials,
-  group_manager,
-  nullifier_log,
-  rln_interface
+  types, constants, protobuf, codec, spam_protection, coordination, credentials,
+  group_manager, nullifier_log, rln_interface

src/mix_rln_spam_protection/coordination.nim

@@ -25,7 +25,8 @@ logScope:
 type
   # Subscription handler types
   MembershipSubscriptionHandler* = proc(update: MembershipUpdate) {.gcsafe, raises: [].}
-  MetadataSubscriptionHandler* = proc(metadata: ProofMetadataBroadcast) {.gcsafe, raises: [].}
+  MetadataSubscriptionHandler* =
+    proc(metadata: ProofMetadataBroadcast) {.gcsafe, raises: [].}
 
   # Coordination layer wrapper
   CoordinationLayer* = ref object
@@ -45,7 +46,7 @@ proc newCoordinationLayer*(spamProtection: MixRlnSpamProtection): CoordinationLa
     spamProtection: spamProtection,
     publishCallback: none(PublishCallback),
     onMembershipUpdate: none(MembershipSubscriptionHandler),
-    onProofMetadata: none(MetadataSubscriptionHandler)
+    onProofMetadata: none(MetadataSubscriptionHandler),
   )
 
 proc setPublishCallback*(cl: CoordinationLayer, callback: PublishCallback) =
@@ -54,18 +55,20 @@ proc setPublishCallback*(cl: CoordinationLayer, callback: PublishCallback) =
   cl.publishCallback = some(callback)
   cl.spamProtection.setPublishCallback(callback)
 
-proc setMembershipUpdateHandler*(cl: CoordinationLayer, handler: MembershipSubscriptionHandler) =
+proc setMembershipUpdateHandler*(
+    cl: CoordinationLayer, handler: MembershipSubscriptionHandler
+) =
   ## Set additional handler for membership updates (for custom processing).
   cl.onMembershipUpdate = some(handler)
 
-proc setProofMetadataHandler*(cl: CoordinationLayer, handler: MetadataSubscriptionHandler) =
+proc setProofMetadataHandler*(
+    cl: CoordinationLayer, handler: MetadataSubscriptionHandler
+) =
   ## Set additional handler for proof metadata (for custom processing).
   cl.onProofMetadata = some(handler)
 
 proc handleIncomingMessage*(
-  cl: CoordinationLayer,
-  contentTopic: string,
-  data: seq[byte]
+    cl: CoordinationLayer, contentTopic: string, data: seq[byte]
 ): Future[RlnResult[void]] {.async.} =
   ## Route incoming messages from logos-messaging to appropriate handlers.
   ##
@@ -85,7 +88,6 @@ proc handleIncomingMessage*(
       let update = MembershipUpdate.decode(data).valueOr:
         return err("Failed to decode update for handler: " & $error)
       cl.onMembershipUpdate.get()(update)
-
   elif contentTopic == metadataTopic:
     # Handle proof metadata
     let metadataResult = cl.spamProtection.handleProofMetadata(data)
@@ -97,7 +99,6 @@ proc handleIncomingMessage*(
       let metadata = ProofMetadataBroadcast.decode(data).valueOr:
         return err("Failed to decode metadata for handler: " & $error)
       cl.onProofMetadata.get()(metadata)
-
   else:
     return err("Unknown content topic: " & contentTopic)
 
@@ -112,12 +113,14 @@ proc getDefaultContentTopics*(): seq[string] =
   @[MembershipContentTopic, ProofMetadataContentTopic]
 
 # Helper function for building a logos-messaging subscription filter
-proc buildSubscriptionFilter*(cl: CoordinationLayer): seq[tuple[contentTopic: string, handler: string]] =
+proc buildSubscriptionFilter*(
+    cl: CoordinationLayer
+): seq[tuple[contentTopic: string, handler: string]] =
   ## Build a subscription filter for logos-messaging.
   ## Returns tuples of (contentTopic, handlerName) for documentation.
   @[
     (cl.spamProtection.getMembershipContentTopic(), "handleMembershipUpdate"),
-    (cl.spamProtection.getProofMetadataContentTopic(), "handleProofMetadata")
+    (cl.spamProtection.getProofMetadataContentTopic(), "handleProofMetadata"),
   ]
 
 # Integration example documentation
@@ -133,15 +136,18 @@ var config = defaultConfig()
 # config.membershipContentTopic = "/my-app/rln/membership/v1"
 # config.proofMetadataContentTopic = "/my-app/rln/metadata/v1"
 
-let spamProtection = newMixRlnSpamProtection(config).get()
+let spamProtection = MixRlnSpamProtection.new(config).get()
 await spamProtection.init()
 
 # Create coordination layer
 let coordination = newCoordinationLayer(spamProtection)
 
 # Wire up publish callback to logos-messaging
-coordination.setPublishCallback(proc(topic: string, data: seq[byte]) {.async.} =
+coordination.setPublishCallback(proc(
+    topic: string, data: seq[byte]
+): Future[Result[void, string]] {.async.} =
   await logosMessaging.publish(topic, data)
+  ok()
 )
 
 # Subscribe to RLN topics (uses configured content topics)
@@ -167,20 +173,25 @@ let mixProto = MixProtocol.new(
 # Utility for creating a simple publish callback that logs (for testing)
 proc createLoggingPublishCallback*(): PublishCallback =
   ## Create a publish callback that just logs messages (for testing).
-  proc callback(contentTopic: string, data: seq[byte]): Future[void] {.async, gcsafe.} =
+  proc callback(
+      contentTopic: string, data: seq[byte]
+  ): Future[Result[void, string]] {.async, gcsafe.} =
     debug "Would publish to coordination layer",
-      topic = contentTopic,
-      dataLen = data.len
+      topic = contentTopic, dataLen = data.len
+    ok()
+
   return callback
 
 # Utility for printing membership update in human-readable form
 proc formatMembershipUpdate*(update: MembershipUpdate): string =
   ## Format a membership update for logging/display.
-  let actionStr = case update.action
+  let actionStr =
+    case update.action
     of MembershipAction.Add: "ADD"
     of MembershipAction.Remove: "REMOVE"
 
-  result = actionStr & " member at index " & $update.index &
-           " (idCommitment: " & update.idCommitment[0..7].toHex() & "...)"
+  result =
+    actionStr & " member at index " & $update.index & " (idCommitment: " &
+    update.idCommitment[0 .. 7].toHex() & "...)"
 
 # Note: toHex is imported from types module via spam_protection