{"id":27396769,"url":"https://github.com/zekele-win/zkvault-basic","last_synced_at":"2026-04-18T11:31:05.530Z","repository":{"id":286386761,"uuid":"961254581","full_name":"zekele-win/zkvault-basic","owner":"zekele-win","description":"A minimal, functional zero-knowledge proof project based on zkSNARKs, designed to help developers understand the fundamental workflow of zk applications—including circuit writing, proof generation, and smart contract verification.","archived":false,"fork":false,"pushed_at":"2025-04-14T03:31:01.000Z","size":90,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-23T03:43:57.432Z","etag":null,"topics":["circom","learning-project","privacy","security","solidity","web3","zero-knowledge","zk-snark"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zekele-win.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-06T05:22:39.000Z","updated_at":"2025-04-14T03:31:04.000Z","dependencies_parsed_at":"2025-04-06T12:21:03.156Z","dependency_job_id":"15a32c3b-1b93-482a-96eb-5fafaeaf7515","html_url":"https://github.com/zekele-win/zkvault-basic","commit_stats":null,"previous_names":["zekele-win/tornadolite","zekele-win/zkvault-basic"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/zekele-win/zkvault-basic","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zekele-win%2Fzkvault-basic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zekele-win%2Fzkvault-basic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zekele-win%2Fzkvault-basic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zekele-win%2Fzkvault-basic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zekele-win","download_url":"https://codeload.github.com/zekele-win/zkvault-basic/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zekele-win%2Fzkvault-basic/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31966883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["circom","learning-project","privacy","security","solidity","web3","zero-knowledge","zk-snark"],"created_at":"2025-04-14T00:20:56.803Z","updated_at":"2026-04-18T11:31:05.510Z","avatar_url":"https://github.com/zekele-win.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ❄️ zkvault-basic\n\n**zkvault-basic** is a minimal, functional zero-knowledge proof project based on zkSNARKs, designed to help developers understand the fundamental workflow of zk applications—including circuit writing, proof generation, and smart contract verification.\n\nThis project guides you through building a complete zk application, from ciruits build setup and contract compile to testing and deployment, CLI operations.\n\n---\n\n## 🎯 Project Goals\n\nzkvault-basic is designed as a learning and sharing tool to replicate a typical anonymous deposit/withdrawal scenario:\n\n- Use zkSNARK to enable anonymous deposits and withdrawals to arbitrary wallets\n- Combine Circom and Solidity to construct a full zero-knowledge workflow\n- Emphasize minimal implementation, focusing on core concepts for easier understanding\n\nThis project is a simplified version of Tornado Cash’s basic mechanism—an ideal reference for getting started with zk app development.\n\n---\n\n## ✨ Feature Overview\n\n### Deposit\n\n- The user generates a random secret\n- A commitment is derived from this secret\n- ETH of a fixed denomination is deposited into _CONTRACT_ using this commitment, enabling anonymous deposit\n\n### Withdrawal\n\n- Provide the original deposit secret\n- Generate the corresponding zero-knowledge proof\n- Use any wallet to execute the withdrawal and transfer funds to any desired address\n\n---\n\n## Design Philosophy\n\nThe purpose of `zkvault` is to achieve the following three core characteristics:\n\n- **Consistency**\n- **Security**\n- **Privacy** (Not implemented yet)\n\nWe will explain these three characteristics by detailing the deposit and withdrawal processes.\n\n### Deposit Process\n\n1. _APP_ prepares to call _CONTRACT_ function `deposit(commitment)`\n   - _APP_ randomly generates a `secret` (the user ensures it is kept private)\n   - _APP_ calculates the parameter `commitment = hash(secret)` needed for _CONTRACT_ function `deposit`. `commitment` is public.\n2. _CONTRACT_ function `deposit(commitment)` handles the process:\n   - Ensures that the user's deposit amount (`msg.value`) is correct.\n   - Saves the `commitment` and marks it as `DEPOSITED` status.\n\n### Withdrawal Process\n\n1. _APP_ prepares to call _CONTRACT_ function `withdraw(pA, pB, pC, pubSignals)`\n\n   - Parameter explanation:\n     - `(pA, pB, pC, pubSignals)` are standard zkSNARK proof parameters.\n     - `pubSignals[0] = commitment`, `pubSignals[1] = recipient`\n   - _APP_ uses the `secret` saved during deposit and the specified `recipient` to call _zk-circuit_ `Withdraw(public: commitment, public: recipient, private: secret)`, generating the zkProof (standard components: `pA`, `pB`, `pC`, `pubSignals`).\n   - The zkProof generated by _zk-circuit_ binds `commitment`, `recipient`, and the algorithm that calculates `commitment`, ensuring that any modification of values in the zkProof cannot be validated by _CONTRACT_ .\n   - If the `commitment` in the zkProof for the `withdraw` (i.e., `pubSignals[0]`) does not match the `commitment` from the deposit, _CONTRACT_ will reject the `withdraw` — either the verifier fails or the `commitment` status cannot be properly recognized. This ensures **Consistency**.\n   - Additionally, because the zkProof binds the `recipient`, even if an unexpected failure (e.g., insufficient gas) causes the execution of _CONTRACT_ function `withdraw` to fail, other users cannot steal funds by modifying the `recipient` parameter. Changing the `recipient` would require the _APP_ to regenerate the zkProof, and to do so, the `secret` is needed. This ensures **Security**.\n\n2. _CONTRACT_ function `withdraw(pA, pB, pC, pubSignals)` handles the process:\n   - Checks the `commitment` status.\n   - Calls the `verifier` to validate the zkProof (`pA`, `pB`, `pC`, `pubSignals`).\n     - The `verifier` is the corresponding contract generated when _APP_ compiles _zk-circuit_.\n\n### Risks\n\nThroughout the deposit/withdraw process, to ensure **Consistency**, both `deposit` and `withdraw` expose the `commitment`, which means the account addresses for performing the deposit and withdrawal are linked. This results in a lack of **Privacy**.\n\n---\n\n## 🧱 Project Structure\n\n```bash\n.\n├── circuits/                          # Circom ZK circuits\n│   └── ZkVaultBasic.circom            # Main circuit implementing deposit/withdraw logic\n│\n├── contracts/                         # Solidity smart contracts\n│   ├── ZkVaultBasic.sol               # ZK-enabled Vault contract\n│   └── ZkVaultBasicVerifier.sol       # Auto-generated Groth16 verifier contract\n│\n├── scripts/                           # CLI and deployment scripts\n│   ├── cli.ts                         # Command-line interface for deposit/withdraw testing\n│   └── deploy.ts                      # Deploys contracts to local or testnet environments\n│\n├── test/                              # Tests for circuits and contracts\n│   ├── utils.hex.test.ts              # Unit tests for hex encoding utilities\n│   ├── utils.pedersen.test.ts         # Unit tests for Pedersen hash implementation\n│   ├── ZkVaultBasic.circom.test.ts    # Tests for circuit correctness and witness verification\n│   └── ZkVaultBasic.sol.test.ts       # Tests for smart contract behavior and proof validation\n│\n├── types/                             # Type declarations for external JS/TS libraries\n│   ├── circom_tester.d.ts             # Types for circom_tester (circuit tester wrapper)\n│   └── ffjavascript.d.ts              # Types for ffjavascript (bigint/buffer utils)\n│\n├── utils/                             # Utility modules used across scripts and tests\n│   ├── hex.ts                         # Hex encoding/decoding helpers\n│   └── pedersen.ts                    # Pedersen hash implementation (compatible with circom)\n│\n├── .mocharc.json                      # Mocha testing framework configuration\n├── hardhat.config.ts                  # Hardhat config for smart contract compilation/deployment\n├── package.json                       # Project dependencies and scripts\n└── tsconfig.json                      # TypeScript configuration\n```\n\n---\n\n## ⚙️ Prerequisites\n\n1. Install Node.js (recommended version: **v22**)\n2. Install Circom 2  \n   Installation guide: [https://docs.circom.io/getting-started/installation/](https://docs.circom.io/getting-started/installation/)\n   ```bash\n   circom --version\n   ```\n3. Install Anvil (local testnet tool)  \n   Installation: [https://github.com/foundry-rs/foundry](https://github.com/foundry-rs/foundry)\n\n---\n\n## 📦 Install Dependencies\n\n```bash\nnpm install\n```\n\n---\n\n## 🔧 Build Circuits\n\nGenerate `r1cs` and `wasm` files:\n\n```bash\nnpm run build\n```\n\n---\n\n## 🔐 Setup Circuits (Trusted Setup)\n\nPrecondition: Download `powersOfTau28_hez_final_12.ptau` and place it in the project root.\n\n- Download: [https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_12.ptau](https://storage.googleapis.com/zkevm/ptau/powersOfTau28_hez_final_12.ptau)\n- If the link is broken, refer to [iden3/snarkjs](https://github.com/iden3/snarkjs?tab=readme-ov-file#7-prepare-phase-2)\n\nRun setup to generate proving key, verifying key, and Solidity verifier:\n\n```bash\nnpm run setup\n```\n\n---\n\n## 📄 Compile Smart Contracts\n\nCompile Vault and Verifier contracts to EVM-compatible bytecode:\n\n```bash\nnpm run compile\n```\n\n---\n\n## 🧪 Run Tests\n\nIncludes Circom circuit tests and Solidity contract tests:\n\n```bash\nnpm run test\n```\n\n---\n\n## 🚀 Start Local Testnet (Anvil)\n\nDefault endpoint: `http://127.0.0.1:8545`:\n\n```bash\nnpm run srv\n```\n\n---\n\n## 🧾 Environment Variables (.env)\n\nCreate a `.env` file in the root directory, e.g.:\n\n```env\nNETWORK = \"test\"\nNODE_URL = \"http://127.0.0.1:8545\"\nMNEMONIC = \"\u003cyour test mnemonic\u003e\"\n```\n\n⚠️ The mnemonic is for local testing only. **Do NOT use real wallet credentials!**\n\n---\n\n## 📤 Deploy Contracts to Local Testnet\n\nDeploy the contract with 1 ETH denomination:\n\n```bash\nnpm run deploy -- --denomination 1\n```\n\n---\n\n## 🧭 CLI Commands\n\n### Make a Deposit\n\n```bash\nnpm run cli -- deposit\n```\n\nThe command will print a `secret` — store it securely.\n\n### Make a Withdrawal\n\nWithdraw using the previously printed secret:\n\n```bash\nnpm run cli -- withdraw --secret \u003cyour-secret\u003e\n```\n\n---\n\n## 📚 Further Reading \u0026 References\n\n- [Circom 2 Documentation](https://docs.circom.io/)\n- [Snarkjs Tutorial](https://github.com/iden3/snarkjs)\n- [Zero Knowledge Proofs on Ethereum.org](https://ethereum.org/en/zero-knowledge-proofs/)\n\n---\n\n## 🚧 Next Steps\n\nUpgrade to `zkvault-classic` by implementing a Merkle Tree to fully decouple deposit and withdrawal addresses.\n\n---\n\n## 📄 License\n\nThis project uses the MIT license. See [LICENSE](./LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzekele-win%2Fzkvault-basic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzekele-win%2Fzkvault-basic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzekele-win%2Fzkvault-basic/lists"}