How to Design a Zero-Knowledge Proof Onboarding for Privacy

Traditional onboarding for financial or social applications requires users to submit sensitive personal data like government IDs or transaction histories, creating central points of failure and privacy risks. Zero-knowledge proof (ZKP)-based onboarding flips this model. Instead of sharing raw data, a user generates a cryptographic proof that attests to a specific statement about their data being true—such as "I am over 18" or "my credit score is above 700"—without revealing the data itself. This proof is then verified on-chain or by a service provider, enabling trustless and private access.

Designing a ZKP onboarding flow involves several core components. First, you need a trusted data source or attestation, like a government-issued verifiable credential or an on-chain history. Second, a circuit must be written (e.g., using Circom or Noir) that defines the logical statement to be proven. For example, a circuit could prove that a user's balance in a Merkle tree is greater than a threshold without revealing the amount. Finally, a prover generates the proof from the user's private data, and a verifier (often a smart contract) checks its validity.

A practical implementation for private DeFi access might use Semaphore or zkSNARKs. A user could prove membership in a verified group (e.g., holders of a specific NFT) or that their off-chain credit score meets a protocol's requirement. The smart contract verifier would only check the proof, not the user's identity or score. Key libraries include circomlib for circuit building and snarkjs for proof generation. This architecture shifts the security model from data custody to cryptographic verification.

Developers must consider the user experience. Generating ZKPs can be computationally intensive, so client-side proving in the browser via WASM or dedicated wallets like Sismo or zkLogin solutions is crucial. Furthermore, the system's trust assumptions hinge on the initial data attestation. Using decentralized identifiers (DIDs) and verifiable credentials from issuers like Bloom or Gitcoin Passport can create a robust, sybil-resistant, and privacy-preserving identity layer without relying on a single centralized validator.

A zero-knowledge proof (ZKP) allows one party (the prover) to convince another (the verifier) that a statement is true without revealing any information beyond the validity of the statement itself. For onboarding, this typically means proving you meet certain criteria (like holding a specific NFT or being on a whitelist) without exposing your wallet address or the specific asset. Core ZK concepts you must understand include zk-SNARKs (Succinct Non-interactive Arguments of Knowledge) and zk-STARKs (Scalable Transparent Arguments of Knowledge), along with the role of a trusted setup, proving keys, and verification keys.

You will need proficiency with a ZK-specific programming language and framework. Circom is the most common language for writing arithmetic circuits, which define the computational statement to be proven. You'll use it with the snarkjs library to generate and verify proofs. Alternatively, frameworks like Noir (used by Aztec) offer a more developer-friendly experience. A working knowledge of Elliptic Curve Cryptography (specifically the BN128 and BLS12-381 curves used in pairing-based proofs) is also crucial for understanding the underlying math.

On-chain integration requires smart contract expertise. The verification of a ZKP is performed by a verifier contract, often generated from your circuit. You must be comfortable writing and deploying contracts in Solidity or Vyper that can receive proof data (like a, b, c parameters and public inputs) and call the verifier. Understanding gas optimization for these computations is critical, as verification can be expensive. You should also be familiar with using Hardhat or Foundry for local development and testing of the entire proof generation and verification pipeline.

Designing the user flow requires frontend and backend components. The user's wallet (like MetaMask) must interact with your application to generate the proof client-side, often using a library like snarkjs in the browser. You'll need a backend service or a relayer to handle tasks that cannot be done client-side, such as fetching private inputs from a secure database or submitting the final verified transaction to avoid users paying gas. Understanding how to manage private inputs, public signals, and the user's privacy throughout this flow is a key design challenge.

Finally, consider the specific use case and its constraints. Are you proving membership in a Merkle tree (common for allowlists)? Are you proving a person's age is over 18 without revealing their birthdate? The circuit logic will vary dramatically. You must also decide on the trust model: will you use a trusted setup ceremony (like Perpetual Powers of Tau) for zk-SNARKs, or opt for a transparent system like zk-STARKs? Each choice has trade-offs in proof size, verification speed, and trust assumptions that impact the final user experience.

A ZK circuit is a program written in a domain-specific language like Circom or Noir that defines a set of arithmetic constraints. For an onboarding system, the circuit's purpose is to prove a user meets certain criteria—like being over 18, having a unique identity, or holding a specific credential—without revealing the underlying data. You start by identifying the private inputs (e.g., date of birth, passport hash), public inputs (e.g., the current date, a public eligibility threshold), and the output (a single boolean isValid). The circuit's logic performs computations on these inputs to output true only if all conditions are met.

Consider a proof-of-age gate. The private input is the user's birth date (birthYear, birthMonth, birthDay). The public input is today's date and the minimum age minAge. The circuit logic would: 1) Calculate the user's age in days, 2) Compare it to minAge * 365, and 3) Output 1 if ageInDays >= minAgeInDays. In Circom, this involves creating signals for inputs and using components like LessThan or GreaterEq to build constraints. The key is that the prover knows their birth date, but the verifier only sees the proof and the public statement: "This user is over 18."

Design choices directly impact performance and trust. A complex circuit with many constraints requires more proving time and generates larger proofs. Use optimal data types; representing an age as a 32-bit integer is more efficient than a 256-bit field element. Avoid non-deterministic operations like hashing inside the circuit unless necessary, as they are computationally expensive. For our onboarding example, you might require a hash of a government ID to be pre-computed and passed in as a private input, rather than hashing the raw ID within the circuit itself.

Security and correctness are paramount. The circuit must be deterministic and complete—it must accept all valid witness combinations and reject all invalid ones. Thorough testing with a range of valid and invalid inputs is essential before proceeding to proof generation. Tools like Circom's tester or Noir's nargo test allow you to write unit tests for your circuit logic. A bug in the circuit is a critical vulnerability, as it could allow invalid proofs to be verified as true, compromising the entire system's integrity.

Finally, document the circuit's public interface clearly. This includes the exact format of the public inputs the verifier will need and the meaning of the proof output. This specification becomes the verification key and solidity contract in later steps. A well-designed circuit is the foundation for a secure, efficient, and usable privacy-preserving onboarding flow.

We'll design a circuit that proves a user is over 18 without revealing their exact birth date. The core logic requires two private inputs: the user's birthYear and birthMonth. The circuit will compare these against a public currentYear and currentMonth to output a single public signal, isAdult, set to 1 if true. This demonstrates the fundamental ZK pattern: private data drives a public outcome.

First, define the circuit structure in a .circom file. We use the LessThan template from the circomlib library for comparisons. The key constraint is ensuring the calculated age is greater than or equal to 18. We must handle the edge case where the birthday hasn't occurred yet in the current year.

circomCopy
include "circomlib/compare.circuit";

template AgeCheck() {
    // Private inputs
    signal input birthYear;
    signal input birthMonth;
    // Public inputs
    signal input currentYear;
    signal input currentMonth;
    // Public output
    signal output isAdult;

    // Component to check if currentMonth >= birthMonth
    component isMonthPast = LessThan(32); // Months are < 32
    isMonthPast.in[0] <== birthMonth;
    isMonthPast.in[1] <== currentMonth;
    // monthFlag = 1 if currentMonth >= birthMonth (birthday passed this year)
    signal monthFlag <== 1 - isMonthPast.out;

    // Calculate raw age difference in years
    signal ageYears <== currentYear - birthYear;

    // Adjust age down by 1 if birthday hasn't occurred yet
    signal adjustedAge <== ageYears - (1 - monthFlag);

    // Check if adjustedAge >= 18
    component isAdultCheck = LessThan(128); // Age is < 128
    isAdultCheck.in[0] <== 18;
    isAdultCheck.in[1] <== adjustedAge;
    // LessThan(128).out is 1 if in[0] < in[1]. So we need 1 when 18 < adjustedAge.
    isAdult <== 1 - isAdultCheck.out;
}

After defining the circuit, you must compile it to generate the R1CS (Rank-1 Constraint System) and wasm files needed for proof generation. Use the Circom compiler:

bashCopy
circom ageCheck.circom --r1cs --wasm --sym

This creates a ageCheck_js/ directory containing the WebAssembly circuit and a ageCheck.r1cs file representing the constraint system. The R1CS defines the mathematical relationships between all signals that any valid proof must satisfy.

Next, you need a trusted setup to generate the proving and verification keys. For production, this requires a secure multi-party ceremony (like Perpetual Powers of Tau). For development, you can use a powersOfTau28_hez_final_17.ptau file and snarkjs to perform a Phase 2 setup specific to your circuit:

bashCopy
snarkjs groth16 setup ageCheck.r1cs powersOfTau28_hez_final_17.ptau ageCheck_0000.zkey
snarkjs zkey contribute ageCheck_0000.zkey ageCheck_final.zkey
snarkjs zkey export verificationkey ageCheck_final.zkey verification_key.json

The verification_key.json is used to build a verifier contract or verify proofs off-chain.

Finally, generate and verify a proof using sample inputs. In a Node.js script, you would use the generated WASM to compute the witness and then use snarkjs to create the proof.

javascriptCopy
// Inside ageCheck_js/generate_witness.js
const witness = await calculator.calculateWitness({"birthYear": 1990, "birthMonth": 5, "currentYear": 2024, "currentMonth": 10}, true);
// Then use snarkjs
// snarkjs groth16 prove ageCheck_final.zkey witness.wtns proof.json public.json
// snarkjs groth16 verify verification_key.json public.json proof.json

A successful verification returns true, confirming the proof is valid without exposing the private 1990 birth year. This circuit can now be integrated into an onboarding flow where users submit a ZK proof instead of a raw ID document.

The off-chain prover is the user's client-side application, responsible for generating the zero-knowledge proof. Using a circuit (a program written in a ZK language like Circom or Noir), the prover takes the private witness data (e.g., a valid credential or a secret) and the public statement (e.g., "I am over 18") as inputs. It then executes the circuit logic locally to produce a cryptographic proof, such as a zk-SNARK or zk-STARK. This proof is compact, often just a few hundred bytes, and cryptographically guarantees the statement is true without leaking the witness. Popular proving libraries include snarkjs for Circom and the Noir prover.

Before generating the final proof, you must compile the circuit and perform a trusted setup to generate proving and verification keys. The proving key is used by the prover to create proofs, while the verification key is used by the verifier to check them. For production, this often involves a multi-party ceremony (like Perpetual Powers of Tau) to ensure trustlessness. The workflow is: 1) Write the circuit (.circom), 2) Compile it to R1CS constraints, 3) Run the setup ceremony to generate proving_key.zkey and verification_key.json, 4) Use the proving key with the witness to generate proof.json and public_signals.json.

Verification is the process of checking the proof's validity against the public statement. Off-chain, this can be done in a Node.js server or a backend service using the verification key, the proof, and the public signals. For example, using snarkjs, you would call snarkjs.groth16.verify(vkey, publicSignals, proof), which returns true or false. This off-chain verification is useful for testing, gatekeeping API access, or in hybrid architectures where the final state transition occurs on-chain. It's crucial that the verifier checks that the public signals match the expected claim (e.g., the output hash is correct) to prevent prover malfeasance.

For a privacy-preserving onboarding system, the circuit is designed to prove membership or credential validity. A common pattern is a Merkle proof inclusion circuit. The private witness would be a leaf (your secret data) and the Merkle path, while the public statement is the known root of the allowlist. The proof demonstrates you possess a secret corresponding to a leaf in the tree without revealing which one. Another example is proving a credential's signature is valid from a known issuer (public key) without revealing the credential's contents. The public_signals output typically contains the public root or a nullifier hash to prevent double-spending the proof.

Optimizing proof generation is critical for user experience, as it can be computationally intensive. Techniques include: - Using WebAssembly builds of proving systems for browsers. - Implementing plonk or Halo2 proving systems which have faster trusted setups. - Recursive proofs to aggregate multiple actions. - Proof batching for similar operations. The goal is to keep generation under 2-10 seconds client-side. For verification, the key metric is gas cost on-chain, but off-chain verification is typically milliseconds. Always profile with realistic circuit sizes.

The final output of this step is the proof artifact (e.g., a JSON file) and the public signals. This data packet is what gets submitted to the on-chain verifier contract in the next step. Developers should implement robust error handling for proof generation failures and consider fallback mechanisms like alternative proving backends. The ZK Whiteboard and 0xPARC's ZK Learning are excellent resources for diving deeper into circuit design and proof system internals.

The core of a ZK onboarding system is the on-chain verifier contract. This smart contract does not process the private user data itself; instead, it contains the verification key for your zk-SNARK or zk-STARK circuit and a function to validate submitted proofs. When a user generates a proof off-chain (e.g., proving they are over 18 without revealing their birthdate), they submit this proof to the verifier contract. The contract's verifyProof function executes a cryptographic check, returning true only if the proof is valid according to the predefined circuit logic. This creates a trustless gateway: any action gated by this contract can be accessed by users who demonstrably meet the criteria, while their underlying data remains confidential.

To build this, you first need the verification key artifact generated during the circuit setup phase (Step 2). In a framework like Circom and snarkjs, this is typically a verification_key.json file. Your contract will hardcode or accept this key. A standard implementation involves importing a verifier template. For example, using the snarkjs library, you can generate a Solidity verifier contract with the command snarkjs zkey export solidityverifier circuit_final.zkey verifier.sol. This auto-generated contract contains a verifyProof function that accepts the proof parameters (a, b, c, input) as calldata.

Your custom parent contract will then inherit or interact with this verifier. Here is a basic skeleton:

solidityCopy
import "./Verifier.sol";

contract ZKOnboardingGate is Verifier {
    mapping(address => bool) public isOnboarded;
    uint256 public immutable merkleRoot;

    constructor(uint256 _merkleRoot) {
        merkleRoot = _merkleRoot;
    }

    function onboard(
        uint[2] memory a,
        uint[2][2] memory b,
        uint[2] memory c,
        uint[1] memory input
    ) public {
        // `input[0]` contains the public signal (e.g., the Merkle root)
        require(input[0] == merkleRoot, "Invalid public input");
        require(verifyProof(a, b, c, input), "Invalid proof");
        isOnboarded[msg.sender] = true;
    }
}

In this example, the onboard function checks that the proof's public input matches the expected system state (a Merkle root of allowed credentials) before calling the inherited verifyProof. Upon success, it records the user's address as onboarded.

Critical design considerations include gas optimization and proof freshness. Verification can be expensive; using a Groth16 zk-SNARK verifier on Ethereum may cost 200k-500k gas. Consider offloading verification to a layer-2 or using a verification outsourcing pattern if costs are prohibitive. To prevent proof replay attacks, your contract must enforce nullifier checks. The user's proof should include a nullifier hash—a unique identifier derived from a secret—that is stored on-chain after use, preventing the same proof from being submitted twice.

Finally, thoroughly test the contract with valid and invalid proofs before deployment. Use frameworks like Hardhat or Foundry to simulate transactions. The contract's security is paramount, as a bug could allow invalid proofs to be accepted or permanently lock out valid users. Once deployed, the verification key is immutable, so any circuit logic updates require a new contract deployment. This on-chain verifier becomes the definitive, permissionless judge for your privacy-preserving onboarding flow.

A privacy-focused dApp frontend must orchestrate three key tasks: generating the zero-knowledge proof client-side, managing user credentials without exposing them, and submitting the proof to the on-chain verifier. Use libraries like SnarkJS for proof generation in the browser or a Node.js backend service. The frontend's primary job is to collect user inputs (like a secret credential), pass them to the proving system, and handle the resulting proof data. Never send raw private inputs to your server; all sensitive computation should happen locally in the user's browser using WebAssembly-compiled circuits.

For the user flow, design a clear interface that requests only the necessary information. For example, to prove age without revealing a birthdate, the user might input their date of birth. The dApp then uses this to compute the witness and generate the ZK-SNARK or ZK-STARK proof. Use Ethers.js or Viem to prepare the transaction that calls the verifier contract's verifyProof function, passing the proof (a, b, c points) and any required public signals. Handle gas estimation and provide clear feedback on proof generation status, which can take several seconds.

Implement secure credential management. For reusable proofs, consider using localStorage or IndexedDB to cache the proving key or anonymized identifiers, but clearly communicate the privacy trade-offs to users. A common pattern is to generate a stealth address or a Semaphore identity from the private input as part of the proof, allowing for persistent but private user sessions. Always provide an option for users to clear all local data. The frontend should also verify the on-chain verifier contract address and ABI to prevent interacting with malicious contracts.

Testing is critical. Use a local development network like Hardhat or Anvil to deploy your verifier contract and test the full integration. Simulate the proof generation and submission flow extensively. Monitor for common issues such as gas limits being too low for the verify function or CORS errors when loading large proving key files. Provide fallback mechanisms; for instance, if client-side proof generation fails or is too slow, offer an option to use a trusted remote prover (with appropriate privacy disclosures).

Finally, audit the user experience for privacy assurances. The UI should visually reinforce what information is not being shared. For example, after onboarding, display "You have proven you are over 18 using zero-knowledge cryptography. Your exact age was never sent to our servers or the blockchain." Transparency builds trust in privacy-preserving systems. Document the technical stack (e.g., Circom, SnarkJS, React, Ethers.js) and provide links to the circuit source code and verifier contract to allow for community verification.