From e91d18cf0b494e78ed2a8b49c73c840a27a80369 Mon Sep 17 00:00:00 2001 From: Danish Arora Date: Thu, 24 Jul 2025 16:27:10 +0530 Subject: [PATCH 1/4] chore: draft Waku's requirements on Zerokit from js-waku perspective --- requirements/zerokit.md | 56 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 requirements/zerokit.md diff --git a/requirements/zerokit.md b/requirements/zerokit.md new file mode 100644 index 0000000..89deb23 --- /dev/null +++ b/requirements/zerokit.md @@ -0,0 +1,56 @@ +# Waku’s Requirements on Zerokit + +## Context + +Zerokit is the recommended library for cryptographic operations including Poseidon hashing, RLN identity generation, and proof verification. +Waku relies on Zerokit, primarily for two implementaions: +- js-waku (rln-wasm): credentials +- nwaku: credentials + proof generation & verification + +Current JS integration faces two main challenges: +- **WASM cold start/load latency:** The WASM blob load time improved from ~15 seconds (v0.1.0) to ~5 seconds (v0.2.0). Notably, the current `rln-wasm` build includes proof generation and verification, which js-waku does not require. This suggests a smaller, credential-only WASM library could further reduce load times for js-waku. +- **Endianness mismatch:** js-waku uses big-endian (BE) throughout, as required by contracts, while Zerokit expects little-endian (LE). This necessitates conversion when interfacing between the two, though this is less critical than load latency. + +Additional minor challenges: +- Insufficient documentation and upgrade notes. +- Unclear purpose and usage of `InitOutput` and root exports. +- Ambiguity around the sequence and role of initialization functions such as `init()`, `initPanicHook()`, etc. + +We aim to align expectations and optimize collaboration between the Waku and Vac ACZ teams by clearly expressing our functional and non-functional requirements. + +--- + +## Use Case 1: Credential Generation and Management + +**Used during:** +- RLN registration +- Identity derivation and key export +- Interoperability between js-waku and nwaku + +### Functionality + +- **F1.1:** Generate deterministic identity commitment (`idCommitment`) from entropy/seed. +- **F1.2:** Generate full identity object (`commitment`, `secret`, `nullifier`, `trapdoor`). +- **F1.3:** Support Big-Endian (BE), instead of Little-Endian (LE) + +### Usability + +- **U1.1:** WASM load time should be <5s in cold start on most browsers. +- **U1.3:** _Optional:_ Provide a reduced WASM build or a dedicated `@zerokit/credentials` package that only supports credentials (no proof logic). + +### Reliability + +- **R1.1:** Deterministic outputs — BE/LE encoding should not affect hash reproducibility (if possible). +- **R1.2:** Cross-language consistency between js-waku and nwaku. +- **R1.3:** Exposed APIs should be stable and well-documented. + +### Performance + +- **P1.1:** Cold start under 5s for full WASM blob; ideally under 1s for reduced credential-only blob. + +### Supportability + +- **S1.1:** Available for: JavaScript/TypeScript (browsers), nim +--- + +## Use Case 2: Proof Generation and Verification From 9e7a7b3e8579d4f2bca399e08cb4d59405411f4b Mon Sep 17 00:00:00 2001 From: Danish Arora Date: Mon, 28 Jul 2025 16:31:30 +0530 Subject: [PATCH 2/4] chore: address review comments Co-authored-by: fryorcraken <110212804+fryorcraken@users.noreply.github.com> --- requirements/zerokit.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/requirements/zerokit.md b/requirements/zerokit.md index 89deb23..9ce7851 100644 --- a/requirements/zerokit.md +++ b/requirements/zerokit.md @@ -4,16 +4,15 @@ Zerokit is the recommended library for cryptographic operations including Poseidon hashing, RLN identity generation, and proof verification. Waku relies on Zerokit, primarily for two implementaions: -- js-waku (rln-wasm): credentials -- nwaku: credentials + proof generation & verification +- js-waku (rln-wasm): credentials (now), proof generation and verification (2025H2) +- nwaku: proof generation & verification (now), credentials (2025H2) Current JS integration faces two main challenges: -- **WASM cold start/load latency:** The WASM blob load time improved from ~15 seconds (v0.1.0) to ~5 seconds (v0.2.0). Notably, the current `rln-wasm` build includes proof generation and verification, which js-waku does not require. This suggests a smaller, credential-only WASM library could further reduce load times for js-waku. +- **WASM cold start/load latency:** The WASM blob load time improved from ~15 seconds (v0.1.0) to ~5 seconds (v0.2.0). Notably, the current `rln-wasm` build includes proof generation and verification, which not all web apps built with Waku require. And even if one web app requires both credentials and proof verification/generation, it is likely done in different areas from a UX and functional PoV. This suggests a smaller, credential-only and proof-handling-only WASM libraries could further reduce load times for js-waku. - **Endianness mismatch:** js-waku uses big-endian (BE) throughout, as required by contracts, while Zerokit expects little-endian (LE). This necessitates conversion when interfacing between the two, though this is less critical than load latency. Additional minor challenges: -- Insufficient documentation and upgrade notes. -- Unclear purpose and usage of `InitOutput` and root exports. +- Lack of documentation regarding `InitOutput` and root exports. - Ambiguity around the sequence and role of initialization functions such as `init()`, `initPanicHook()`, etc. We aim to align expectations and optimize collaboration between the Waku and Vac ACZ teams by clearly expressing our functional and non-functional requirements. @@ -31,18 +30,16 @@ We aim to align expectations and optimize collaboration between the Waku and Vac - **F1.1:** Generate deterministic identity commitment (`idCommitment`) from entropy/seed. - **F1.2:** Generate full identity object (`commitment`, `secret`, `nullifier`, `trapdoor`). -- **F1.3:** Support Big-Endian (BE), instead of Little-Endian (LE) ### Usability - **U1.1:** WASM load time should be <5s in cold start on most browsers. -- **U1.3:** _Optional:_ Provide a reduced WASM build or a dedicated `@zerokit/credentials` package that only supports credentials (no proof logic). +- **U1.2:** API accepts and return Big-Endian (BE), so data can be passed to Web3 RPC API without manipulation. +- **U1.3:** Documentation is provided to use APIs to generate and load credentials. ### Reliability -- **R1.1:** Deterministic outputs — BE/LE encoding should not affect hash reproducibility (if possible). -- **R1.2:** Cross-language consistency between js-waku and nwaku. -- **R1.3:** Exposed APIs should be stable and well-documented. +- **R1.1:** Inter-operability between Zerokit FFI (x86_64, ARM, binaries) and WASI (browser WASM) APIs. ### Performance @@ -50,7 +47,7 @@ We aim to align expectations and optimize collaboration between the Waku and Vac ### Supportability -- **S1.1:** Available for: JavaScript/TypeScript (browsers), nim ---- +- **S1.1:** Available for: JavaScript/TypeScript (browsers) +- **S1.2:** Available for Nim + -## Use Case 2: Proof Generation and Verification From a765a0f1929b6278a79fe4a6260db8fd7333620b Mon Sep 17 00:00:00 2001 From: Danish Arora Date: Tue, 29 Jul 2025 16:05:35 +0530 Subject: [PATCH 3/4] chore: add clarifications for load times --- requirements/zerokit.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/requirements/zerokit.md b/requirements/zerokit.md index 9ce7851..0a55bbf 100644 --- a/requirements/zerokit.md +++ b/requirements/zerokit.md @@ -4,11 +4,16 @@ Zerokit is the recommended library for cryptographic operations including Poseidon hashing, RLN identity generation, and proof verification. Waku relies on Zerokit, primarily for two implementaions: -- js-waku (rln-wasm): credentials (now), proof generation and verification (2025H2) +- js-waku (rln-wasm): credentials registrations, proof generation and verification (planned 2025H2) - nwaku: proof generation & verification (now), credentials (2025H2) Current JS integration faces two main challenges: -- **WASM cold start/load latency:** The WASM blob load time improved from ~15 seconds (v0.1.0) to ~5 seconds (v0.2.0). Notably, the current `rln-wasm` build includes proof generation and verification, which not all web apps built with Waku require. And even if one web app requires both credentials and proof verification/generation, it is likely done in different areas from a UX and functional PoV. This suggests a smaller, credential-only and proof-handling-only WASM libraries could further reduce load times for js-waku. +- **WASM cold start/load latency:** The WASM blob load time improved from ~15 seconds (v0.1.0) to ~5 seconds (v0.2.0). + - The split of the 5 seconds is as follows: + - ~1.2 seconds for the WASM files download + decoding/compilation (~1MB) + - ~3.6 seconds for the zkey download (~3MB) +Notably, the current `rln-wasm` build includes proof generation and verification, which not all web apps built with Waku require. And even if one web app requires both credentials and proof verification/generation, it is likely done in different areas from a UX and functional PoV. This suggests a smaller, credential-only and proof-handling-only WASM libraries could further reduce load times for js-waku. + - **Endianness mismatch:** js-waku uses big-endian (BE) throughout, as required by contracts, while Zerokit expects little-endian (LE). This necessitates conversion when interfacing between the two, though this is less critical than load latency. Additional minor challenges: @@ -43,7 +48,7 @@ We aim to align expectations and optimize collaboration between the Waku and Vac ### Performance -- **P1.1:** Cold start under 5s for full WASM blob; ideally under 1s for reduced credential-only blob. +- **P1.1:** Cold start under 5s for full WASM blob, including the zkey; ideally under 1s for reduced credential-only blob. ### Supportability From bf93e420debba2a0ec52ce0579227e925d1ee1a8 Mon Sep 17 00:00:00 2001 From: Danish Arora Date: Thu, 31 Jul 2025 14:47:00 +0530 Subject: [PATCH 4/4] chore: address comments --- requirements/zerokit.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/requirements/zerokit.md b/requirements/zerokit.md index 0a55bbf..6a07b44 100644 --- a/requirements/zerokit.md +++ b/requirements/zerokit.md @@ -38,13 +38,13 @@ We aim to align expectations and optimize collaboration between the Waku and Vac ### Usability -- **U1.1:** WASM load time should be <5s in cold start on most browsers. -- **U1.2:** API accepts and return Big-Endian (BE), so data can be passed to Web3 RPC API without manipulation. -- **U1.3:** Documentation is provided to use APIs to generate and load credentials. +- **U1.1:** API accepts and return Big-Endian (BE), so data can be passed to Web3 RPC API without manipulation. +- **U1.2:** Documentation is provided to use APIs to generate and load credentials. ### Reliability - **R1.1:** Inter-operability between Zerokit FFI (x86_64, ARM, binaries) and WASI (browser WASM) APIs. +- **R2.2:** Zerokit must be fully interoperable the RLN EVM smart contract. ### Performance