Skip to content
keep-starknet-strangePublic

About

State-of-the-art Elliptic Curve operations and SNARKS verification for Cairo & Starknet 🐺.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

258 stars

Watchers

3 watching

Forks

Latest commit

Β 

History

579 Commits

Folders and files

Repository files navigation


CI Status Project license Pull Requests welcome

Exploration_Team

About

State-of-the-art Elliptic Curve tooling and SNARKS verification for Cairo & Starknet 🐺.

Garaga enables efficient elliptic curve operations on Starknet. It achieves state of the art performance by

  • using a dedicated builtin made by Starkware for emulated modular arithmetic
  • using a suite of non-deterministic techniques for extension field multiplication, pairings, and multi scalar multiplication to reduce the number of steps to verify results.

Garaga currently supports:

  • Scalar & Multi-scalar multiplication for any Weirstrass curve, including BN254, BLS12_381, SECP256/R1, and ED25519. You can add the one you need by specifying the curve parameters.
  • Pairing operations for BN254 and BLS12_381.
  • Groth16 smart contract verifiers generators for BN254 and BLS12_381.
  • Noir smart contract verifiers generators for ultra keccak honk flavour.

Architecture overview

Architecture Overview

Garaga consists of a Pythonic backend with Rust bindings and CairoZero / Cairo libraries.

  • The Pythonic backend is here to define emulated modular arithmetic circuits that can be compiled to Cairo or Cairo1 code. It also handles witnesses generation for the non-deterministic computations, smart contract contract generation for a given proof system and elliptic curve, and calldata generation from a given proof.
  • The CairoZero / Starknet interfaces are responsible for composing and calling the circuits, as well as adding all the extra logic needed to make the algorithms work (Fiat-Shamir heuristic, SNARKS verifiers algorithms, etc).

Quickstart : deploying a SNARK verifier on Starknet

Currently, only Groth16 on BN254 and BLS12_381 is supported with automatic support for json files coming from SnarkJS and Gnark.

  1. Create a new directory for you project, and bring the jsons files for verification key, proof file and public inputs inside it.

  2. Install the garaga pip package with pip install garaga. Python 3.11+ is required and a virtual environment is recommended. Enter garaga in your terminal to get started.

  3. Run the garaga gen command in your terminal to generate the code for the SNARK verifier given your verification key.

  4. Edit the generated smart contract to fit the needs of your dapp.

  5. Create an environment file .secrets following the .secrets.template file in the root of this repository, containing the Starkner RPC url, your account address, and the private key.

  6. Run the garaga declare command in your terminal to declare the smart contract on Starknet and obtain its class hash. Note that this is an expensive operation.

  7. Run the garaga deploy command in your terminal using the class hash obtained in the previous step to get the contract address.

  8. Run the garaga verify-onchain command in your terminal using the contract address, the verification key, the proof and the public inputs to verify the proof against the SNARK verifier contract.

For more details, please refer to the documentation.

Developer setup

To get started with Garaga, you'll need to have some tools and dependencies installed. Here's everything you need:

Prerequisites

Ensure you have the following installed:

  • Rust - Required for building the garaga_rs extension.
  • Scarb 2.21.0 - The Cairo package manager. Comes with Cairo inside.

Python 3.11-3.14 is used for development but does not need to be installed manually β€” make setup will auto-install it via uv if it's not already available. fastecdsa 4 uses a Rust backend and does not require GMP.

Optionally :
  • pprof - A tool for visualization and analysis of profiling data. Requires Go.
  • graphviz - Necessary for generating graphical representations of profiling data.

Setup

Clone the repository and run the setup command from the root:

make setup

This will automatically:

  • Install uv if not present
  • Install Python 3.14 via uv if no compatible version (3.11-3.14) is found
  • Create a virtual environment and install all dependencies
  • Build the Rust extension

The setup is idempotent β€” running it again will update dependencies without recreating the virtual environment.

Before proceeding, activate the virtual environment by running source venv/bin/activate.

Cairo Benchmarks

πŸ“Š Click on any section below to expand and view detailed benchmark tables with test performance metrics.

Toolchain: Cairo 2.21.0, Starknet Foundry 0.64.1.

Note: Click on the test name to view the profiling image. Resources shown in the table for contracts include extra costs due to the foundry logic. Check the profile file for more details.

contracts
└── groth16_example_bls12_381_integrationtest::test_contract
Test Name Steps Range Check Range Check 96 Poseidon Add Mod Mul Mod Sierra Gas
test_verify_groth16_proof_bls12_381 337,407 10,978 90,280 586 7,506 10,868 48,143,218
└── groth16_example_bn254_integrationtest::test_contract
Test Name Steps Range Check Range Check 96 Poseidon Add Mod Mul Mod Sierra Gas
test_verify_groth16_proof_bn254 233,190 9,791 67,149 509 5,401 8,754 34,544,279
└── noir_ultra_keccak_zk_honk_example_integrationtest::test_contract
Test Name Steps Range Check Range Check 96 Bitwise Poseidon Add Mod Mul Mod Sierra Gas
test_verify_ultra_keccak_zk_honk_proof 634,568 58,141 377,190 2,168 461 41,372 40,267 123,976,433

The gas column above is the profiler estimate. See the Barretenberg v6 report for actual Sierra gas, bytecode size, and the baseline comparison.

└── risc0_verifier_bn254_integrationtest::test_contract
Test Name Steps Range Check Range Check 96 Bitwise Poseidon Add Mod Mul Mod Sierra Gas
test_verify_r0_groth16_proof_bn254 274,309 11,888 74,896 6,698 509 6,303 9,541 43,824,543
└── sp1_verifier_bn254_integrationtest::test_contract
Test Name Steps Range Check Range Check 96 Bitwise Poseidon Add Mod Mul Mod Sierra Gas
test_verify_sp1_groth16_proof_bn254 258,001 11,131 75,027 2,230 509 6,314 9,555 39,554,231
garaga
└── apps
β”‚ └── drand::tests
Test Name Steps Range Check Range Check 96 Bitwise Add Mod Mul Mod Sierra Gas
test_decrypt_at_round 290,146 3,899 385,790 14,506 57,320 28,871 89,970,452
test_hash_to_curve 26,469 962 4,559 12,289 422 602 10,594,699
test_hash_to_two_bls_felts 23,561 895 74 12,289 2 8 9,592,673
test_drand_quicknet_public_key 12,973 68 14,864 0 1,490 1,674 3,488,240
test_isogeny 1,847 58 878 0 51 111 316,702
test_map_to_curve 642 11 264 0 6 39 104,690
β”‚ └── noir::zk_honk_transcript::tests
Test Name Steps Range Check Bitwise Poseidon Sierra Gas
test_transcript_zk_keccak 33,943 2,405 2,216 1 4,855,069
β”‚ └── risc0::risc0_utils_tests
Test Name Steps Range Check Bitwise Sierra Gas
test_receipt_claim 11,122 431 5,591 4,401,923
test_output_digest 4,427 170 2,230 1,754,690
β”‚ └── sp1::tests
Test Name Steps Range Check Sierra Gas
test_convert_u32_to_u128 58 3 6,010
└── crypto::mmr::tests
Test Name Steps Range Check Sierra Gas
test_trailing_ones 345 33 36,810
└── ec::ec_ops_g2::tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_ec_mul_g2 104,697 1,054 87,664 8,551 9,755 23,311,414
└── hashes::poseidon_bn254::tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_run_poseidon_grumpkin_circuit_1 9,916 327 6,393 353 919 2,008,764
└── tests
β”‚ └── autogenerated
β”‚ β”‚ └── ecdsa_tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_ecdsa_SECP256R1 14,152 1,072 20,022 2,367 2,184 4,475,018
test_ecdsa_SECP256K1 18,822 2,082 15,629 1,810 1,592 4,281,032
β”‚ β”‚ └── eddsa_tests
Test Name Steps Range Check Range Check 96 Bitwise Add Mod Mul Mod Sierra Gas
test_eddsa_32_64B 88,156 13,782 20,762 3,288 2,412 2,276 14,789,380
test_eddsa_16_32B 52,378 7,641 20,840 1,656 2,418 2,284 9,840,834
test_eddsa_0_0B 51,802 7,547 20,865 1,656 2,419 2,286 9,779,492
β”‚ β”‚ └── msm_tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_msm_SECP256R1_3P 20,208 1,576 29,835 3,546 3,252 6,581,668
test_msm_SECP256K1_3P 27,115 3,087 23,194 2,707 2,359 6,273,900
test_msm_SECP256R1_2P 13,528 1,053 19,865 2,363 2,166 4,390,704
test_msm_SECP256K1_2P 18,028 2,061 15,369 1,799 1,564 4,166,160
test_msm_SECP256R1_1P 7,026 530 9,945 1,182 1,084 2,223,216
test_msm_SECP256K1_1P 9,278 1,037 7,697 900 783 2,111,354
β”‚ β”‚ └── pairing_tests
Test Name Steps Range Check Range Check 96 Poseidon Add Mod Mul Mod Sierra Gas
test_BN254_mpcheck_3P_2F_with_extra_miller_loop_result 59,625 472 59,008 509 4,469 7,922 15,362,665
test_BLS12_381_mpcheck_3P_2F_with_extra_miller_loop_result 53,413 356 44,885 586 3,482 5,791 12,466,130
test_BN254_mpcheck_2P_2F 48,044 393 33,047 460 1,731 4,665 10,124,192
test_BLS12_381_mpcheck_2P_2F 45,358 308 25,250 544 1,420 3,340 8,582,424
β”‚ β”‚ └── rsa_tests
Test Name Steps Range Check Range Check 96 Bitwise Add Mod Mul Mod Sierra Gas
test_rsa2048_sha256_positive_seed_0 59,956 2,288 38,159 1,115 2,354 4,741 12,347,693
test_rsa2048_positive_seed_0 56,417 2,078 38,159 0 2,354 4,741 11,329,048
test_rsa2048_tampered_message_seed_0 56,374 2,078 38,159 0 2,354 4,741 11,324,748
test_rsa2048_tampered_limb_seed_0 18,588 2,067 3,469 0 214 431 2,507,298
β”‚ β”‚ └── schnorr_tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_schnorr_SECP256K1 18,419 2,082 15,512 1,808 1,580 4,226,472
β”‚ β”‚ └── tower_pairing_tests
Test Name Steps Range Check Range Check 96 Add Mod Mul Mod Sierra Gas
test_tower_pairing_BN254_3P 272,843 474 626,255 94,555 50,514 114,645,866
test_tower_pairing_BLS12_381_3P 249,742 556 538,321 86,187 37,849 97,842,902
test_tower_pairing_BN254_2P 222,114 398 486,548 73,494 38,661 89,740,812
test_tower_pairing_BLS12_381_2P 207,799 493 422,516 67,911 28,926 77,566,140
test_tower_pairing_BN254_1P 171,551 322 346,841 52,433 26,808 64,852,358
test_tower_pairing_BLS12_381_1P 166,022 430 306,711 49,635 20,003 57,305,978
test_tower_final_exp_BN254 120,847 246 207,134 31,372 14,955 39,949,804
test_tower_final_exp_BLS12_381 124,104 367 190,906 31,359 11,080 37,031,716
β”‚ └── calldata_tests
Test Name Steps Range Check Sierra Gas
test_deserialize_full_proof_with_hints_bls12_381 22,273 4,714 2,557,280
β”‚ └── sha512_tests
Test Name Steps Range Check Bitwise Sierra Gas
test_sha512_lorem_ipsum 103,289 18,163 4,904 14,459,342
test_size_zero 37,724 6,402 1,640 5,176,660
test_sha512_size_one 37,709 6,401 1,640 5,175,090
β”‚ └── sp1_groth_16_tests
Test Name Steps Range Check Range Check 96 Bitwise Poseidon Add Mod Mul Mod Sierra Gas
test_verify_sp1_groth16_proof_bn254 122,587 8,987 75,027 2,230 509 6,314 9,555 25,862,751
└── utils::neg_3::tests
Test Name Steps Range Check Sierra Gas
test_scalar_to_epns 6,104 928 675,360
test_scalar_to_epns_single 1,941 297 214,890

πŸ”„ To regenerate these benchmarks: Run make profile-test from the project root.

Support & How to Contribute

We warmly welcome contributions and support from the community! Here's how you can help Garaga grow and improve:

Reporting Issues & Requesting Features

  • Spot a bug? Have a feature request? Check out our issues page to see if it's already been reported or to open a new issue.

Contributing to Garaga

  • Interested in contributing? Please take a moment to read our contribution guidelines for details on how to get started. Your contributions make the open-source community an incredible place for learning, inspiration, and creation.

Showing Support

  • Love Garaga? Give us a star on GitHub to show your support.
  • Spread the word: Share your excitement about Garaga on social platforms like Twitter, Dev.to, Medium, or your personal blog.
  • Join the conversation: Connect with us and other Garaga enthusiasts on our Telegram group.

Every contribution, whether it's code, feedback, or spreading the word, greatly benefits everyone and is deeply appreciated. Thank you for being a part of Garaga's journey!

Security

Garaga follows good practices of security, but 100% security cannot be assured. Garaga is provided "as is" without any warranty. Use at your own risk.

For more information and to report security issues, please refer to our security documentation.

License

This project is licensed under the MIT license.

See LICENSE for more information.

Acknowledgements

Resources

Note: This list is not exhaustive, and is not intended to be.

Contributors

For a full list of all authors and contributors, see the contributors page.

Thanks goes to these wonderful people (emoji key):

Feltroid Prime
Feltroid Prime

πŸ’»
Abdel @ StarkWare
Abdel @ StarkWare

πŸ’»
Tarik K.
Tarik K.

πŸ’»
Bachir Arif
Bachir Arif

πŸ’»
Renaud Dubois
Renaud Dubois

πŸ’»
Rodrigo Ferreira
Rodrigo Ferreira

πŸ’»
Luiz Vasconcelos JΓΊnior
Luiz Vasconcelos JΓΊnior

πŸ’»
Shramee Srivastav
Shramee Srivastav

πŸ’»
Andrija Novakovic
Andrija Novakovic

πŸ’»
Liam Eagen
Liam Eagen

πŸ’»
Paul Etscheit
Paul Etscheit

πŸ’»
stefanMadzharov
stefanMadzharov

πŸ’»
Add your contributions

This project follows the all-contributors specification. Contributions of any kind welcome!

About

State-of-the-art Elliptic Curve operations and SNARKS verification for Cairo & Starknet 🐺.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

258 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages