Runtime Composition — Replacing Feature Flags with Enums

[seemenkina]

The Problem

Every configuration dimension in zerokit is a compile-time #[cfg(feature = "...")] gate. Each new dimension doubles the binary matrix:

Dimension	Options
Tree type	full · optimal · pmtree · stateless
Message mode	single · multi-message-id
Proving	standard · partial (planned)
Target	native · wasm32

This gives us 30+ logical binary combinations today, with ~50 #[cfg] gates for multi-message-id alone. Adding new features can double this binaries

Why this hurts:

• Binaries compiled with multi-message-id cannot verify single-mode proofs (and vice versa)
• Cross-mode slashing is impossible — you'd need two separate binaries
• CI must test every feature combination
• FFI exposes 6 constructor variants with different signatures per build
• WASM needs separate .wasm builds for single vs multi mode

Proposal: Runtime Enums

Replace business logic feature flags with Rust enums. Keep compile-time flags only for platform concerns and heavy dependencies.

What we replace

Remove	Becomes
multi-message-id	MessageMode::Single / MessageMode::Multi { max_out }
fullmerkletree	TreeType::Full
optimalmerkletree	TreeType::Optimal
stateless	TreeState::Stateless

What stays compile-time

• target_arch = "wasm32" — platform boundary, only graph excluded (witness calc is external in JS)
• parallel — rayon threading, changes dependency tree
• pmtree-ft — pulls in sled/rocksdb, heavy optional dependency
• headers — C header generation, build-time only
• default-circuits-single / default-circuits-multi (new) — control which circuit blobs are embedded (~3.5 MB / ~4.3 MB)

Key Design Decisions

Why enums, not trait objects

ZerokitMerkleTree has generic methods (set_range<I>, override_range<I, J>) which makes it not object-safe — Box<dyn> won't compile. Additionally, safer-ffi's #[derive_ReprC] rejects trait objects inside #[repr(opaque)] structs.

Enums give us exhaustive match, zero overhead (branch predictor), and compiler errors when adding new variants.

No Option — explicit enum variants

The current codebase avoids Option to prevent None/empty-path errors. The new architecture continues this:

// Instead of Option<TreeBackend>:
pub enum TreeState {
    Stateless,
    Active(TreeBackend),
}

// Instead of Option<PartialProof>:
pub enum ProverBackend {
    Standard,
    TwoStepPending,
    TwoStepReady(PartialProof),
}

// Instead of Option<usize> for max_out:
pub enum MessageMode {
    Single,                    // max_out is always 1
    Multi { max_out: usize },  // max_out > 1
}

New Traits

RlnSerialize

Replaces 12+ free serialization functions with a version-tagged trait:

pub trait RlnSerialize: Sized {
    fn to_bytes_le(&self) -> Vec<u8>;
    fn to_bytes_be(&self) -> Vec<u8>;
    fn from_bytes_le(input: &[u8]) -> Result<(Self, usize)>;
    fn from_bytes_be(input: &[u8]) -> Result<(Self, usize)>;
}

// Implemented by: RLNProof, RLNProofValues, RLNWitnessInput
// Version byte dispatch: 0x00 = SingleV1, 0x01 = MultiV1
// Both formats always compiled — no #[cfg] in serialization

WitnessCompute

Abstracts the witness calculation backend:

pub trait WitnessCompute {
    fn calc_witness(&self, inputs: HashMap<String, Vec<Fr>>) -> Result<Vec<Fr>>;
    fn tree_depth(&self) -> usize;
    fn max_out(&self) -> usize;
}

// Implemented by: Graph (native iden3 calculator)
// WASM: witness is calculated externally in JS — this trait is not used

Unified RLN Struct

// Before — 5 #[cfg]-gated constructors, incompatible signatures
pub struct RLN {
    zkey: Zkey,
    #[cfg(not(target_arch = "wasm32"))]
    graph: Graph,
    #[cfg(not(feature = "stateless"))]
    tree: PoseidonTree,
}

// After — one struct, runtime enums
pub struct RLN {
    zkey: Zkey,
    message_mode: MessageMode,
    tree: TreeState,
    prover: ProverBackend,

    // Only graph is permanently excluded from WASM.
    // Witness calculation is done externally in JS.
    #[cfg(not(target_arch = "wasm32"))]
    graph: Graph,
}

Builder Pattern

One entry point replaces 5+ constructors:

// Minimal — stateless, single mode, default circuits
let rln = RLNBuilder::new().build()?;

// Full configuration
let rln = RLNBuilder::new()
    .tree(TreeType::Persistent, 20)
    .tree_config(r#"{"path":"./db"}"#)
    .message_mode_multi(4)
    .two_step_prover()
    .circuit_from_bytes(zkey, graph)
    .build()?;

// build() validates:
//   circuit max_out == MessageMode max_out
//   circuit tree_depth == tree depth
//   embedded circuit exists for chosen mode

FFI gets a single JSON-based constructor:

// One C function replaces six
ffi_rln_new_with_config(json_config, &out)

{
  "tree": { "type": "optimal", "depth": 20 },
  "messageMode": { "mode": "multi", "maxOut": 4 },
  "prover": "standard",
  "circuit": "embedded"
}

WASM

Only graph is excluded from WASM — tree and prover are runtime enums available in the struct (defaulting to Stateless / Standard for now).

Before: separate .wasm builds per mode, #[cfg]-gated getters (y() vs ys()), stateless feature required.

After: one .wasm handles both modes, unified getters (ys() always returns Vec), no feature flags in rln-wasm/Cargo.toml.

// Single mode
const rln = new WasmRLN(zkeyBytes);

// Multi mode — same binary
const rln = WasmRLN.newMulti(zkeyBytes, 4);

// Cross-mode verify — one .wasm does both
rln.verifyWithRoots(singleProof, roots, x);
rln.verifyWithRoots(multiProof, roots, x);

// Unified getters
proof.getValues().ys();         // always Vec
proof.getValues().nullifiers(); // always Vec

Migration Plan (8 PRs)

Each PR is independently reviewable and mergeable:

PR	Scope	Blocks
01	RlnSerialize trait — wrap existing free functions, no behavior change	nothing
02	WitnessCompute trait — wrap Graph, no behavior change	nothing
03	Always-compile message enums — remove #[cfg] from RLNMessageInputs + RLNOutputs + SerializationVersion, named constructors, all #[cfg] → match (~50 gates)	nothing
04	MessageMode enum — add to RLN struct, validate mode ↔ circuit	PR 03
05	TreeState + TreeBackend — new enums, wrap tree impls, remove stateless + tree-type flags	PR 03
06	ProverBackend — new enum, merge ark-groth16-partial, TwoStep variant	PR 03
07	RLNBuilder + FFI — builder pattern, ffi_rln_new_with_config(json), deprecate old constructors	PR 04 + 05 + 06
08	WASM update — builder internally, named constructors, unified getters	PR 07

PRs 01 and 02 can land immediately. PRs 04, 05, 06 are independent of each other (only depend on 03).

Result

• One binary handles all message modes, tree types, and prover backends
• One C header — stable forever, new features = new setter
• One .wasm module — verifies both modes, cross-mode slashing
• New feature = one enum variant + one builder setter, zero breaking changes

[vinhtc27]

Comment

Looking at the "The Problem" section, there are five issues in total. Two are critical and could affect users in the long run.

Binaries compiled with multi-message-id can't verify single-mode proofs (and the other way around)

Cross-mode slashing doesn't work — you'd literally need two separate binaries

I believe I already have temporary solutions for them in the upcoming version 2.0.0 that should maintain compatibility or at least make migration for future version easier. The remaining issues should not significantly affect usability.

---

1. Multi-message-id binaries can't verify single-mode proofs

With a version 2.0.0 release, users could work around this. They'd just import the zerokit library twice with different feature mode, spin up two instances one for single and one for multi, and then check the first byte of the RLN type to route things to the right instance for witness/proof generation or verification.

Not the prettiest solution, but it works at the application level.

---

2. Cross-mode slashing needs two binaries

I actually ran into this while working on the multi-message-id PR and added a solution for it.

There's a function — compute_id_secret(share1, share2) slashing.rs (line 14) — that's exposed so it can work across modes. You retrieve the (x, y) pair from any active proof slot with the same nullifier, whether in Single or Multi mode, and compute the secret.

I also added a user usage pattern for slashing in difference mode to the README — Slashing Across Mode

---

Long term, once zerokit gets refactored like this proposal for version 3.0.0, users should be able to upgrade without breaking any existing flows or serialized data. They’ll get a cleaner API compared to version 2.0.0, with some changes to the public API, but it will be easier to use and result in a smaller application binary since we don’t have separate instances anymore.