gnark is a fast zk-SNARK library that offers a high-level API to design circuits. The library is open source and developed under the Apache 2.0 license.
gnark uses gnark-crypto for the finite-field arithmetic and out-circuit implementation of cryptographic algorithms.
gnark powers Linea zk-rollup. Include your project in the known users section by opening a PR.
gnarkUser DocumentationgnarkPlaygroundgnarkIssuesgnarkBenchmarks 🏁gnark-announce- Announcement list for new releases and security patches
To get started with gnark and write your first circuit, follow these instructions.
Checkout the online playground to compile circuits and visualize constraint systems.
gnark and gnark-crypto have been extensively audited, but are provided as-is, we make no guarantees or warranties to its safety and reliability. In particular, gnark makes no security guarantees such as constant time implementation or side-channel attack resistance.
To report a security bug, please refer to gnark Security Policy.
Refer to known security advisories for a list of known security issues.
gnark employs the following testing procedures:
- unit testing - we test the primitives in unit tests
- circuit testing - we test the circuit implementation against several targets:
- test engine - instead of running the full prover and verifier stack, we run the computations only to ensure the completeness of the circuits
- proof engines - we compile the circuits, run the setup, prove and verify using native implementation
- Solidity verifier - in addition to the previous, we verify the proofs in Solidity verifier. See
gnark-solidity-checker
- regression testing - we have implemented tests for reported issues to avoid regressions
- constraint count testing - we have implemented circuit size tests to avoid regressions
- serialization testing - we check that serialization round-trip is complete
- side-effect testing - we check that circuit compilation is deterministic
- fuzz testing:
- circuit input fuzzing - we provide random inputs to the circuit to cause solver error
- native input fuzzing - we provide random inputs to various native methods to cause errors. We have also stored initial fuzzing corpus for regression tests.
- circuit definition fuzzing - we cooperate with Consensys Diligence to fuzz the circuit definitions to find bugs in the
gnarkcircuit compiler.
The tests are automatically run during every PR and merge commit. We run full test suite only for the Linux on amd64 target, but run short tests both for Windows target (amd64) and macOS target (arm64).
gnark and gnark-crypto packages are optimized for 64bits architectures (x86 amd64) using assembly operations. We have generic implementation of the same arithmetic algorithms for ARM backends (arm64). We do not implement vector operations.
gnark tries to be backwards compatible when possible, however we do not guarantee that serialized object formats are static over different versions of gnark. Particularly - we do not have versioning implemented in the serialized formats, so using files between different versions of gnark may lead to undefined behaviour or even crash the program.
gnark issues are tracked in the GitHub issues tab.
To report a security bug, please refer to gnark Security Policy.
If you have any questions, queries or comments, GitHub discussions is the place to find us.
You can also get in touch directly: [email protected]
- Kudelski Security - October 2022 - gnark-crypto (contracted by Algorand Foundation)
- Sigma Prime - May 2023 - gnark-crypto KZG (contracted by Ethereum Foundation)
- Consensys Diligence - June 2023 - gnark PLONK Solidity verifier
- LeastAuthority - August 2023 - gnark Groth16 Solidity verifier template (contracted by Worldcoin)
- OpenZeppelin - November 2023 - gnark PLONK Solidity verifier template
- ZKSecurity.xyz - May 2024 - gnark standard library
- OpenZeppelin - June 2024 - gnark PLONK prover and verifier
- LeastAuthority - September 2024 - gnark general and GKR
Refer to Proving schemes and curves for more details.
gnark support the following zk-SNARKs:
which can be instantiated with the following curves
- BN254
- BLS12-381
- BLS12-377
- BW6-761
- BLS24-315
- BW6-633
- BLS24-317
Refer to the gnark User Documentation
Here is what x**3 + x + 5 = y looks like
package main
import (
"github.com/consensys/gnark-crypto/ecc"
"github.com/consensys/gnark/backend/groth16"
"github.com/consensys/gnark/frontend"
"github.com/consensys/gnark/frontend/cs/r1cs"
)
// CubicCircuit defines a simple circuit
// x**3 + x + 5 == y
type CubicCircuit struct {
// struct tags on a variable is optional
// default uses variable name and secret visibility.
X frontend.Variable `gnark:"x"`
Y frontend.Variable `gnark:",public"`
}
// Define declares the circuit constraints
// x**3 + x + 5 == y
func (circuit *CubicCircuit) Define(api frontend.API) error {
x3 := api.Mul(circuit.X, circuit.X, circuit.X)
api.AssertIsEqual(circuit.Y, api.Add(x3, circuit.X, 5))
return nil
}
func main() {
// compiles our circuit into a R1CS
var circuit CubicCircuit
ccs, _ := frontend.Compile(ecc.BN254.ScalarField(), r1cs.NewBuilder, &circuit)
// groth16 zkSNARK: Setup
pk, vk, _ := groth16.Setup(ccs)
// witness definition
assignment := CubicCircuit{X: 3, Y: 35}
witness, _ := frontend.NewWitness(&assignment, ecc.BN254.ScalarField())
publicWitness, _ := witness.Public()
// groth16: Prove & Verify
proof, _ := groth16.Prove(ccs, pk, witness)
groth16.Verify(proof, vk, publicWitness)
}Unlock free GPU acceleration with OKX Zeknox library
Build from source, see guide in https://github.com/okx/zeknox
// main.go
groth16.Prove(r1cs, pk, witnessData)
// ->
groth16.Prove(r1cs, pk, witnessData, backend.WithZeknoxAcceleration())# run with zeknox build tag
go run -tags=zeknox main.go
# (place -tags before the filename)add the following to the mimc test
assert.ProverSucceeded(&mimcCircuit, &Circuit{
PreImage: "16130099170765464552823636852555369511329944820189892919423002775646948828469",
Hash: "12886436712380113721405259596386800092738845035233065858332878701083870690753",
}, test.WithCurves(ecc.BN254), test.WithProverOpts(backend.WithZeknoxAcceleration()))# test with zeknox build tag
go test github.com/consensys/gnark/examples/mimc -tags=prover_checks,zeknoxThe following schemes and curves support experimental use of Ingonyama's Icicle GPU library for low level zk-SNARK primitives such as MSM, NTT, and polynomial operations:
instantiated with the following curve(s)
- BN254
To use GPUs, add the icicle buildtag to your build/run commands, e.g. go run -tags=icicle main.go.
You can then toggle on or off icicle acceleration by providing the WithIcicleAcceleration backend ProverOption:
// toggle on
proofIci, err := groth16.Prove(ccs, pk, secretWitness, backend.WithIcicleAcceleration())
// toggle off
proof, err := groth16.Prove(ccs, pk, secretWitness)For more information about prerequisites see the Icicle repo.
If you use gnark in your research a citation would be appreciated.
Please use the following BibTeX to cite the most recent release.
@software{gnark-v0.11.0,
author = {Gautam Botrel and
Thomas Piellard and
Youssef El Housni and
Ivo Kubjas and
Arya Tabaie},
title = {ConsenSys/gnark: v0.11.0},
month = sep,
year = 2024,
publisher = {Zenodo},
version = {v0.11.0},
doi = {10.5281/zenodo.5819104},
url = {https://doi.org/10.5281/zenodo.5819104}
}Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is licensed under the Apache 2 License - see the LICENSE file for details