{"id":25420216,"url":"https://github.com/dl-solarity/hardhat-zkit","last_synced_at":"2025-04-05T13:01:40.450Z","repository":{"id":241289322,"uuid":"790764108","full_name":"dl-solarity/hardhat-zkit","owner":"dl-solarity","description":"The ultimate TypeScript environment for Circom development","archived":false,"fork":false,"pushed_at":"2024-12-19T10:39:02.000Z","size":485,"stargazers_count":78,"open_issues_count":2,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-19T15:51:21.482Z","etag":null,"topics":["circom","environment","hardhat","hardhat-plugin","snarkjs","solarity","typescript","zk","zkit","zkp"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/@solarity/hardhat-zkit","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/dl-solarity.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}},"created_at":"2024-04-23T13:38:40.000Z","updated_at":"2024-12-19T10:33:27.000Z","dependencies_parsed_at":null,"dependency_job_id":"fb9246b6-02b3-4c74-8b3f-3b5c372ff52f","html_url":"https://github.com/dl-solarity/hardhat-zkit","commit_stats":null,"previous_names":["dl-solarity/hardhat-zkit"],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-zkit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-zkit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-zkit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dl-solarity%2Fhardhat-zkit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dl-solarity","download_url":"https://codeload.github.com/dl-solarity/hardhat-zkit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339145,"owners_count":20923012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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","environment","hardhat","hardhat-plugin","snarkjs","solarity","typescript","zk","zkit","zkp"],"created_at":"2025-02-16T19:36:27.122Z","updated_at":"2025-04-05T13:01:40.394Z","avatar_url":"https://github.com/dl-solarity.png","language":"TypeScript","funding_links":[],"categories":["Code editors \u0026 tooling"],"sub_categories":["Cryptographic primitives in other languages"],"readme":"![](https://github.com/dl-solarity/hardhat-zkit/assets/47551140/938bf108-194d-45de-a6f1-7280aaa0c8c1)\n\n[![npm](https://img.shields.io/npm/v/@solarity/hardhat-zkit.svg)](https://www.npmjs.com/package/@solarity/hardhat-zkit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![tests](https://github.com/dl-solarity/hardhat-zkit/actions/workflows/tests.yml/badge.svg?branch=master)](./.github/workflows/tests.yml)\n[![GitPOAP Badge](https://public-api.gitpoap.io/v1/repo/dl-solarity/hardhat-zkit/badge)](https://www.gitpoap.io/gh/dl-solarity/hardhat-zkit)\n[![hardhat](https://hardhat.org/buidler-plugin-badge.svg?1)](https://hardhat.org)\n\n# Hardhat ZKit\n\n**The ultimate TypeScript environment for Circom development.**\n\n## What\n\nThis hardhat plugin is a zero-config, one-stop Circom development environment that streamlines circuits management and lets you focus on the important - code.\n\n- Developer-oriented abstractions that simplify `r1cs`, `witness`, `zkey`, and `vkey` generation processes.\n- Support of `groth16` and `plonk` proving systems.\n- Recompilation and resetup of only the modified circuits.\n- Full TypeScript typization of signals and ZK proofs.\n- Automatic downloads of phase-1 `ptau` files.\n- Convenient phase-2 contributions to `zkey` files.\n- Practical `witness` and proof testing via chai assertions.\n- Invisible platform-specific and `wasm`-based Circom compiler management.\n- Simplified `node_modules` libraries resolution.\n- Rich plugin configuration.\n- And much more!\n\n## Installation\n\n```bash\nnpm install --save-dev @solarity/hardhat-zkit\n```\n\nAnd add the following line to your `hardhat.config`:\n\n```ts\nimport \"@solarity/hardhat-zkit\"; // TypeScript\n\nrequire(\"@solarity/hardhat-zkit\"); // JavaScript\n```\n\n\u003e [!TIP]\n\u003e There is no need to download the Circom compiler separately. The plugin automatically installs required compilers under the hood.\n\n## Usage\n\nThe `hardhat-zkit` is a zero-config plugin, however, you may add the following to your `hardhat.config` file:\n\n```ts\nmodule.exports = {\n  zkit: {\n    compilerVersion: \"2.1.9\",\n    circuitsDir: \"circuits\",\n    compilationSettings: {\n      artifactsDir: \"zkit/artifacts\",\n      onlyFiles: [],\n      skipFiles: [],\n      c: false,\n      json: false,\n      optimization: \"O1\",\n    },\n    setupSettings: {\n      contributionSettings: {\n        provingSystem: \"groth16\", // or \"plonk\"\n        contributions: 2,\n      },\n      onlyFiles: [],\n      skipFiles: [],\n      ptauDir: undefined,\n      ptauDownload: true,\n    },\n    verifiersSettings: {\n      verifiersDir: \"contracts/verifiers\",\n      verifiersType: \"sol\", // or \"vy\"\n    },\n    typesDir: \"generated-types/zkit\",\n    quiet: false,\n  },\n};\n```\n\nWhere:\n\n- `compilerVersion` - The value to indicate which Circom compiler to use (latest by default).\n- `circuitsDir` - The directory where to look for the circuits.\n- `compilationSettings`\n  - `artifactsDir` - The directory where to save the circuits artifacts (r1cs, zkey, etc).\n  - `onlyFiles` - The list of directories (or files) to be considered for the compilation.\n  - `skipFiles` - The list of directories (or files) to be excluded from the compilation.\n  - `c` - The flag to generate the c-based witness generator (generates wasm by default).\n  - `json` - The flag to output the constraints in json format.\n  - `optimization` - The flag to set the level of constraint simplification during compilation (`\"O0\"`, `\"O1\"` or `\"O2\"`). \n- `setupSettings`\n  - `contributionSettings`\n    - `provingSystem` - The option to indicate which proving system to use (`\"groth16\"`, `\"plonk\"` or `[\"groth16\", \"plonk\"]`).\n    - `contributions` - The number of phase-2 `zkey` contributions to make if `groth16` is chosen.\n  - `onlyFiles` - The list of directories (or files) to be considered for the setup phase.\n  - `skipFiles` - The list of directories (or files) to be excluded from the setup phase.\n  - `ptauDir` - The directory where to look for the `ptau` files. `$HOME/.zkit/ptau/` by default.\n  - `ptauDownload` - The flag to allow automatic download of required `ptau` files.\n- `verifiersSettings`\n    - `verifiersDir` - The directory where to generate the Solidity | Vyper verifiers.\n    - `verifiersType` - The option (`\"sol\"` or `\"vy\"`) to indicate which language to use for verifiers generation.\n- `typesDir` - The directory where to save the generated typed circuits wrappers.\n- `quiet` - The flag indicating whether to suppress the output.\n\n### Tasks\n\nThere are several hardhat tasks in the `zkit` scope that the plugin provides:\n\n- `compile` task that compiles or recompiles the modified circuits with the main component.\n- `setup` task that generates or regenerates `zkey` and `vkey` for the previously compiled circuits.\n- `make` task that executes both `compile` and `setup` for convenience.\n- `verifiers` task that generates Solidity | Vyper verifiers for all the previously setup circuits.\n- `clean` task that cleans up the generated artifacts, types, etc.\n\nTo view the available options, run the help command:\n\n```bash\nnpx hardhat help zkit \u003czkit task name\u003e\n```\n\n### Typization\n\nThe plugin provides full TypeScript typization of Circom circuits leveraging [`zktype`](https://github.com/dl-solarity/zktype) library. Both `groth16` and `plonk` proving systems are supported.\n\nThe following config may be added to `tsconfig.json` file to allow for a better development experience:\n\n```json\n{\n  \"compilerOptions\": {\n    \"paths\": {\n      \"@zkit\": [\"./generated-types/zkit\"]\n    }\n  }\n}\n```\n\n### Testing\n\nIn order to utilize user-friendly [Chai](https://www.chaijs.com/) assertions for witness and ZK proof testing, the [`chai-zkit`](https://github.com/dl-solarity/chai-zkit) package needs to be installed:\n\n```bash\nnpm install --save-dev @solarity/chai-zkit\n```\n\nAnd add the following line to your `hardhat.config`:\n\n```ts\nimport \"@solarity/chai-zkit\"; // TypeScript\n\nrequire(\"@solarity/chai-zkit\"); // JavaScript\n```\n\nThe package extends `expect` chai assertion to recognize typed `zktype` objects for frictionless testing experience.\n\n\u003e [!NOTE]\n\u003e Please note that for witness testing purposes it is sufficient to compile circuits just with `zkit compile` task, without generating the keys.\n\n### Example\n\nThe plugin extends the hardhat environment with the `zkit` object that allows typed circuits to be used in scripts and tests:\n\n\u003ctable style=\"width:100%\"\u003e\n\u003ctr\u003e\n\u003cth\u003eCircom circuit\u003c/th\u003e\n\u003cth\u003eUsage example\u003c/th\u003e\n\u003c/tr\u003e\n\n\u003ctr\u003e\n\u003ctd\u003e\n\n```circom\n// file location: ./circuits/multiplier.circom\n\npragma circom 2.0.0;\n\ntemplate Multiplier() {\n   signal input in1;\n   signal input in2;\n   signal output out;\n\n   out \u003c== in1 * in2;\n}\n\n// main component to compile the circuit\ncomponent main = Multiplier();\n```\n\n\u003c/td\u003e\n\u003ctd\u003e\n\n```ts\n// file location: ./test/multiplier.test.ts\n\nimport { zkit } from \"hardhat\"; // hardhat-zkit plugin\nimport { expect } from \"chai\"; // chai-zkit extension\nimport { Multiplier } from \"@zkit\"; // zktype circuit-object\n\ndescribe(\"Multiplier\", () =\u003e {\n  it(\"should test the circuit\", async () =\u003e {\n    const circuit: Multiplier = await zkit.getCircuit(\"Multiplier\");\n    // or await zkit.getCircuit(\"circuits/multiplier.circom:Multiplier\");\n\n    // witness testing\n    await expect(circuit)\n        .with.witnessInputs({ in1: \"3\", in2: \"7\" })\n        .to.have.witnessOutputs({ out: \"21\" });\n\n    // proof testing\n    const proof = await circuit.generateProof({ in1: \"4\", in2: \"2\" });\n\n    await expect(circuit).to.verifyProof(proof);\n  });\n});\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nTo see the plugin in action, place the `Multiplier` circuit in the `circuits` directory and execute:\n\n```bash\nnpx hardhat zkit make\n```\n\nThis command will install the newest compatible Circom compiler, compile the provided circuit, download the necessary `ptau` file regarding the number of circuit's constraints and the proving system of choice, build the required `zkey` and `vkey` files, and generate TypeScript object wrappers to enable full typization of signals and ZK proofs.\n\nAfterward, copy the provided script to the `test` directory and run the tests via `npx hardhat test`. You will see that all the tests are passing!\n\n\u003e [!TIP]\n\u003e Check out the [Medium blog post](https://medium.com/@Arvolear/introducing-hardhat-zkit-how-did-you-even-use-circom-before-a7b463a5575b) and [Solarity circom-lib](https://github.com/dl-solarity/circom-lib) to learn more.\n\n### API reference\n\n---\n\n- **`async getCircuit(\u003ccircuitName|fullCircuitName\u003e, \u003cprovingSystem?\u003e) -\u003e zkit`**\n\nThe method accepts the name of the `main` component of the circuit, optional proving system and returns the instantiated zkit object pointing to that circuit.\n\nThe method works regardless of how the circuit was compiled, however, if `zkit compile` task was used, the zkit methods that utilize proof generation or proof verification would throw an error by design.\n\nIn case there are conflicts between circuit file names and `main` component names, you should use the `fullCircuitName`, which has the following form: `circuitSourceName:circuitName`.\n\nWhere:\n\n- `circuitSourceName` - Path to the circuit file from the project root.\n- `circuitName` - Circuit `main` component name.\n\nThe optional `provingSystem` parameter should only be specified if multiple proving systems were set in the config. Otherwise, leave it as `undefined`.\n\n\u003e [!IMPORTANT]\n\u003e Please note that the method actually returns the [`zktype`](https://github.com/dl-solarity/zktype) typed zkit wrapper objects which enable full TypeScript typization of signals and proofs. Also, check out the [`zkit`](https://github.com/dl-solarity/zkit) documentation to understand zkit object capabilities and how to interact with circuits.\n\n## Future work\n\n- [ ] ZK proofs generation with custom witness files (witness substitution).\n- [ ] Per-circuit plugin configuration.\n- [ ] `BLS12-381` on-chain ZK verifiers (EIP-2537).\n- [ ] Support for `--prime bls12381` Circom (and Snarkjs) compilation flag.\n\n## Known limitations\n\n- Currently there is minimal support for `var` Circom variables. Some circuits may not work if you are using complex `var`-dependent expressions.\n- Even though the plugin provides support of Circom `v2.2.0`, its newest feature `bus` is not supported.\n- Due to current `wasm` memory limitations (address space is 32-bit), the plugin may fail to compile especially large circuits on some platforms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdl-solarity%2Fhardhat-zkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdl-solarity%2Fhardhat-zkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdl-solarity%2Fhardhat-zkit/lists"}