Zerokit RLN Module

The Zerokit RLN Module provides a Rust implementation for working with Rate-Limiting Nullifier RLN zkSNARK proofs and primitives. This module allows you to:

• Generate and verify RLN proofs
• Work with Merkle trees for commitment storage
• Implement rate-limiting mechanisms for distributed systems

Quick Start

[!IMPORTANT] Version 0.7.0 is the only version that does not support WASM and x32 architecture. WASM support is available in version 0.8.0 and above.

Add RLN as dependency

We start by adding zerokit RLN to our Cargo.toml

[dependencies]
rln = { git = "https://github.com/vacp2p/zerokit" }

Basic Usage Example

The RLN object constructor requires the following files:

• rln_final.arkzkey: The proving key in arkzkey format.
• graph.bin: The graph file built for the input tree size

Additionally, rln.wasm is used for testing in the rln-wasm module.

In the following we will use cursors as readers/writers for interfacing with RLN public APIs.

use std::io::Cursor;

use rln::{
    circuit::Fr,
    hashers::{hash_to_field, poseidon_hash},
    protocol::{keygen, prepare_prove_input, prepare_verify_input},
    public::RLN,
    utils::fr_to_bytes_le,
};
use serde_json::json;

fn main() {
    // 1. Initialize RLN with parameters:
    // - the tree depth;
    // - the tree config, if it is not defined, the default value will be set
    let tree_depth = 20;
    let input = Cursor::new(json!({}).to_string());
    let mut rln = RLN::new(tree_depth, input).unwrap();

    // 2. Generate an identity keypair
    let (identity_secret_hash, id_commitment) = keygen();

    // 3. Add a rate commitment to the Merkle tree
    let id_index = 10;
    let user_message_limit = Fr::from(10);
    let rate_commitment = poseidon_hash(&[id_commitment, user_message_limit]);
    let mut buffer = Cursor::new(fr_to_bytes_le(&rate_commitment));
    rln.set_leaf(id_index, &mut buffer).unwrap();

    // 4. Set up external nullifier (epoch + app identifier)
    // We generate epoch from a date seed and we ensure is
    // mapped to a field element by hashing-to-field its content
    let epoch = hash_to_field(b"Today at noon, this year");
    // We generate rln_identifier from a date seed and we ensure is
    // mapped to a field element by hashing-to-field its content
    let rln_identifier = hash_to_field(b"test-rln-identifier");
    // We generate a external nullifier
    let external_nullifier = poseidon_hash(&[epoch, rln_identifier]);
    // We choose a message_id satisfy 0 <= message_id < user_message_limit
    let message_id = Fr::from(1);

    // 5. Generate and verify a proof for a message
    let signal = b"RLN is awesome";

    // 6. Prepare input for generate_rln_proof API
    // input_data is [ identity_secret<32> | id_index<8> | external_nullifier<32>
    //    | user_message_limit<32> | message_id<32> | signal_len<8> | signal<var> ]
    let prove_input = prepare_prove_input(
        identity_secret_hash,
        id_index,
        user_message_limit,
        message_id,
        external_nullifier,
        signal,
    );

    // 7. Generate a RLN proof
    // We generate a RLN proof for proof_input
    let mut input_buffer = Cursor::new(prove_input);
    let mut output_buffer = Cursor::new(Vec::<u8>::new());
    rln.generate_rln_proof(&mut input_buffer, &mut output_buffer)
        .unwrap();

    // We get the public outputs returned by the circuit evaluation
    // The byte vector `proof_data` is serialized as
    //  `[ zk-proof | tree_root | external_nullifier | share_x | share_y | nullifier ]`.
    let proof_data = output_buffer.into_inner();

    // 8. Verify a RLN proof
    // Input buffer is serialized as `[proof_data | signal_len | signal ]`,
    //   where `proof_data` is (computed as) the output obtained by `generate_rln_proof`.
    let verify_data = prepare_verify_input(proof_data, signal);

    // We verify the zk-proof against the provided proof values
    let mut input_buffer = Cursor::new(verify_data);
    let verified = rln.verify_rln_proof(&mut input_buffer).unwrap();

    // We ensure the proof is valid
    assert!(verified);
}

Comments for the code above for point 4

The external nullifier includes two parameters.

The first one is epoch and it's used to identify messages received in a certain time frame. It usually corresponds to the current UNIX time but can also be set to a random value or generated by a seed, provided that it corresponds to a field element.

The second one is rln_identifier and it's used to prevent a RLN ZK proof generated for one application to be re-used in another one.

Features

• Stateless Mode: Allows the use of RLN without maintaining state of the Merkle tree.
• Pre-compiled Circuits: Ready-to-use circuits with Merkle tree depth of 20
• Wasm Support: WebAssembly bindings via rln-wasm crate with features like:
  • Browser and Node.js compatibility
  • Optional parallel feature support using wasm-bindgen-rayon
  • Headless browser testing capabilities
• Merkle Tree Implementations: Multiple tree variants optimized for different use cases:
  • Full Merkle Tree: Fastest access with complete pre-allocated tree in memory. Best for frequent random access (enable with fullmerkletree feature).
  • Optimal Merkle Tree: Memory-efficient sparse storage using HashMap. Ideal for partially populated trees (enable with optimalmerkletree feature).
  • Persistent Merkle Tree: Disk-based storage with sled for persistence across application restarts and large datasets (enable with pmtree-ft feature).

Building and Testing

Prerequisites

git clone https://github.com/vacp2p/zerokit.git
make installdeps
cd zerokit/rln

Build Commands

# Build with default features
cargo make build

# Test with default features
cargo make test

# Test with stateless features
cargo make test_stateless

Advanced: Custom Circuit Compilation

The rln (https://github.com/rate-limiting-nullifier/circom-rln) repository, which contains the RLN circuit implementation is using for pre-compiled RLN circuit for zerokit RLN. If you want to compile your own RLN circuit, you can follow the instructions below.

1. Compile ZK Circuits for getting the zkey file

This script actually generates not only the zkey file for the RLN circuit, but also the execution wasm file used for witness calculation. However, the wasm file is not needed for the rln module, because current implementation uses the iden3 graph file for witness calculation. This graph file is generated by the circom-witnesscalc tool in step 2.

To customize the circuit parameters, modify circom-rln/circuits/rln.circom:

pragma circom 2.1.0;
include "./rln.circom";
component main { public [x, externalNullifier] } = RLN(N, M);

Where:

• N: Merkle tree depth, determining the maximum membership capacity (2^N members).

• M: Bit size for range checks, setting an upper bound for the number of messages per epoch (2^M messages).

[!NOTE] However, if N is too big, this might require a larger Powers of Tau ceremony than the one hardcoded in ./scripts/build-circuits.sh, which is 2^14. In such case, we refer to the official Circom documentation for instructions on how to run an appropriate Powers of Tau ceremony and Phase 2 in order to compile the desired circuit.
Additionally, while M sets an upper bound on the number of messages per epoch (2^M), you can configure lower message limit for your use case, as long as it satisfies user_message_limit ≤ 2^M.
Currently, the rln module comes with a pre-compiled RLN circuit with a Merkle tree of depth 20 and a bit size of 16, allowing up to 2^20 registered members and a 2^16 message limit per epoch.

Install circom compiler

You can follow the instructions below or refer to the installing Circom guide for more details, but make sure to use the specific version v2.1.0.

# Clone the circom repository
git clone https://github.com/iden3/circom.git

# Checkout the specific version
cd circom && git checkout v2.1.0

# Build the circom compiler
cargo build --release

# Install the circom binary globally
cargo install --path circom

# Check the circom version to ensure it's v2.1.0
circom --version

Generate the zkey and verification key files example

# Clone the circom-rln repository
git clone https://github.com/rate-limiting-nullifier/circom-rln

# Install dependencies
cd circom-rln && npm install

# Build circuits
./scripts/build-circuits.sh rln

# Use the generated zkey file in subsequent steps
cp zkeyFiles/rln/final.zkey <path_to_rln_final.zkey>

2. Generate Witness Calculation Graph

The execution graph file used for witness calculation can be compiled following instructions in the circom-witnesscalc repository. As mentioned in step 1, we should use rln.circom file from circom-rln repository.

# Clone the circom-witnesscalc repository
git clone https://github.com/iden3/circom-witnesscalc

# Load the submodules
cd circom-witnesscalc && git submodule update --init --recursive

# Build the circom-witnesscalc tool
cargo build

# Generate the witness calculation graph
cargo run --package circom_witnesscalc --bin build-circuit ../circom-rln/circuits/rln.circom <path_to_graph.bin>

The rln module comes with pre-compiled execution graph files for the RLN circuit.

3. Generate Arkzkey Representation for zkey file

For faster loading, compile the zkey file into the arkzkey format using ark-zkey. This is fork of the original repository with the uncompressed arkzkey support.

# Clone the ark-zkey repository
git clone https://github.com/seemenkina/ark-zkey.git

# Build the ark-zkey tool
cd ark-zkey && cargo build

# Generate the arkzkey representation for the zkey file
cargo run --bin arkzkey-util <path_to_rln_final.zkey>

This will generate the rln_final.arkzkey file, which is used by the rln module.

Currently, the rln module comes with pre-compiled arkzkey keys for the RLN circuit.

[!NOTE] You can use this convert_zkey.sh script to automate the process of generating the arkzkey file from any zkey file

Run the script as follows:

chmod +x ./convert_zkey.sh
./convert_zkey.sh <path_to_rln_final.zkey>

Get involved

Zerokit RLN public and FFI APIs allow interaction with many more features than what briefly showcased above.

We invite you to check our API documentation by running

cargo doc --no-deps

and look at unit tests to have an hint on how to interface and use them.

Detailed Protocol Flow

1. Identity Creation: Generate a secret key and commitment
2. Rate Commitment: Add commitment to a Merkle tree
3. External Nullifier Setup: Combine epoch and application identifier
4. Proof Generation: Create a zkSNARK proof that:
   • Proves membership in the Merkle tree
   • Ensures rate-limiting constraints are satisfied
   • Generates a nullifier to prevent double-usage
5. Proof Verification: Verify the proof without revealing the prover's identity

Getting Involved

• Check the unit tests for more usage examples
• RFC specification for the Rate-Limiting Nullifier protocol
• GitHub repository for the latest updates