jose-compu / jose-compu/opencircom

Circuit: ZK Mixer template (deposit + nullifier withdraw)

Open
#3 0 comments 0 reactions 0 assignees View on GitHub
circuits enhancement priority: medium security
Dominant language
Circom
Stars
2
Forks
2
PR merge metrics
No merged PRs in 30d

Description

## Summary

Add a reusable **ZK mixer** template: deposit commitment + Merkle inclusion + nullifier-based withdrawal.

## Motivation

Mixer circuits (Tornado-style) are among the most deployed ZK apps. opencircom already provides the primitives (`MerkleInclusionProof`, `Nullifier`, `Poseidon`, `AllowlistMembership`) but no composed end-to-end template. Application repos reimplement wiring inconsistently — a common source of bugs.

## Proposed templates

- `MixerDeposit()` — output commitment = Poseidon(secret, nullifierSecret, amount)
- `MixerWithdraw(levels)` — prove: commitment in tree, correct nullifier, recipient/relayer binding, amount consistency
- Optional: `MixerWithdrawWithAllowlist(levels)` — restrict withdraw to allowlisted recipients

## Security notes

- Unique `externalNullifier` per pool instance
- Amount range-checked with `StrictNum2Bits`
- Root must be public and match on-chain state
- Document relayer fee bounds

## Depends on

Existing Merkle + Nullifier + BalanceProof templates.

## Acceptance criteria

- [ ] Deposit + withdraw templates with full constraint coverage
- [ ] Negative tests (double-spend, wrong root, replay)
- [ ] Documented integration example in boilerplate repo

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the existing MerkleInclusionProof, Nullifier, Poseidon, AllowlistMembership, and BalanceProof templates. Define the deposit and withdrawal scope, then add negative tests for double-spend, wrong-root, and replay cases. Done means full constraint coverage plus a documented integration example in the boilerplate repository.

Written by the indexing model from the issue text.

Assessment

Domain
cryptography, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.