zerokit/rln/ffi_nim_examples/README.md

RLN Nim FFI example

This example shows how to use the RLN C FFI from Nim in stateless mode. It demonstrates:

• Creating an RLN handle using the stateless constructor
• Building a witness for a mock Merkle path (no exported tree APIs)
• Generating a proof and verifying it

Build the RLN library

From the repository root:

# Stateless build (no tree APIs)
cargo build -p rln --release --no-default-features --features stateless

# Non-stateless build (with tree APIs)
cargo build -p rln --release

This produces the shared library in target/release:

• macOS: librln.dylib
• Linux: librln.so
• Windows: rln.dll

Build the Nim example (two modes)

From this directory:

# Stateless (uses local mock path, no tree exports)
nim c -d:release -d:ffiStateless main.nim

# Non-stateless (uses exported tree APIs to insert leaf and fetch proof)
nim c -d:release main.nim

Notes:

• The example links dynamically. If your OS linker cannot find the library at runtime, set an rpath or environment variable as shown below.
• The example auto-picks a platform-specific default library name. You can override it with -d:RLN_LIB:"/absolute/path/to/lib" if needed.

Run the example

Ensure the dynamic loader can find the RLN library, then run the binary.

macOS:

DYLD_LIBRARY_PATH=../../target/release ./main

Linux:

LD_LIBRARY_PATH=../../target/release ./main

Windows (PowerShell):

$env:PATH = "$PWD\..\..\target\release;$env:PATH"
./main.exe

You should see output similar to:

RLN created
Witness built
Proof generated
Verify: OK

What the example does (stateless mode)

1. Creates an RLN handle via the stateless constructor.

2. Generates identity keys and sets a user_message_limit and message_id.

3. Hashes a signal and external nullifier (ffi_hash).

4. Computes rateCommitment = Poseidon(id_commitment, user_message_limit) using ffi_poseidon_hash.

5. Builds a mock Merkle path for an empty depth-20 tree at index 0 (no exported tree APIs):

   • Path siblings: level 0 sibling is 0, then each level uses precomputed default hashes H(0,0), H(H(0,0),H(0,0)), ...
   • Path indices: all zeros (left at every level)
   • Root: folds the path upwards with rateCommitment at index 0

6. Builds the witness, generates the proof, and verifies it with ffi_verify_with_roots, passing a one-element roots vector containing the computed root (length must be 1).

What the example does (non-stateless mode)

1. Creates an RLN handle with a Merkle tree backend and configuration.

2. Generates identity keys and computes rateCommitment = Poseidon(id_commitment, user_message_limit).

3. Inserts the leaf with ffi_set_next_leaf and fetches a real Merkle path for index 0 via ffi_get_merkle_proof.

4. Builds the witness from the exported proof, generates the proof, and verifies with ffi_verify_rln_proof using the current tree root.