Generate and deploy your verifier contract

Prepare your Groth16 verifying key

Pairing operations over BLS12-381 are cheaper than BN254 on Garaga, so if possible, prefer using BLS12-381. The security of this curve is also much closer to 128 bits than BN254.

To deploy a groth16 verifier, you need the associated verifying key in .json format. Both BN254 and BLS12-381 are supported.

Snarkjs and Gnark jsons output are supported out of the box.

You can find a bunch of example of verifying keys that will work directly in the hydra/garaga/starknet/groth16_contract_generator/examples folder.

While Snarkjs jsons export are easy and working well, the gnark documentation is a bit outdated. Below we show a quick example on how to export the verifying key from your Gnark circuit .

Gnark export to json example

package main

import (
	"encoding/json"
	"os"

	"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"`
	B frontend.Variable
	A 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))
	api.AssertIsEqual(circuit.B, circuit.A)
	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, A: 3, B: 3}
	witness, _ := frontend.NewWitness(&assignment, ecc.BN254.ScalarField())
	publicWitness, _ := witness.Public()

	// groth16: Prove & Verify
	proof, _ := groth16.Prove(ccs, pk, witness)

	groth16.Verify(proof, vk, publicWitness)
	vk.ExportSolidity(os.Stdout)
	// Export to JSON:
	schema, _ := frontend.NewSchema(&circuit)
	pubWitnessJSON, _ := publicWitness.ToJSON(schema)

	SaveToJSON("gnark_vk_bn254.json", vk)
	SaveToJSON("gnark_proof_bn254.json", proof)
	os.WriteFile("gnark_public_bn254.json", pubWitnessJSON, 0644)

}

func SaveToJSON(filePath string, v interface{}) error {
	jsonData, err := json.MarshalIndent(v, "", "  ")

	if err != nil {
		return err
	}

	err = os.WriteFile(filePath, jsonData, 0644)
	if err != nil {
		return err
	}
	return nil
}

Generate the Smart contract code

Using the Developer setup & guides or the Python package, you should now have access to the Garaga CLI from your terminal, using the command garaga

garaga

Once your verifying key is ready, you can use the following command :

garaga gen --system groth16 --vk vk.json

You should see an output like this :

(venv) :~/garaga-flow garaga gen --system groth16 --vk vk_bls.json
Please enter the name of your project. Press enter for default name. [my_project]:
Detected curve: CurveID.BLS12_381
⠧ Generating Smart Contract project for ProofSystem.Groth16 using vk_bls.json...
Done!
Smart Contract project created:
/home/garaga-flow/my_project/
├── Scarb.lock
├── Scarb.toml
├── src/
│   ├── groth16_verifier.cairo
│   ├── groth16_verifier_constants.cairo
│   └── lib.cairo
└── target/
    └── dev/
        ├── groth16_example_bls12_381.starknet_artifacts.json
        ├── groth16_example_bls12_381_Groth16VerifierBLS12_381.compiled_contract
        │   _class.json
        └── groth16_example_bls12_381_Groth16VerifierBLS12_381.contract_class.js
            on
You can now modify the groth16_verifier.cairo file to adapt the verifier to your
use case.

The curve identifier is automatically detected from the content of your verifying key.

Build your contract

The generated verifier contract only verifies a proof and returns the public inputs on success. You can extend it to add your dapp logic, or use it as a library call from another contract.

The generated template is as follows. The main endpoint is verify_groth16_proof_[curve_name].

The function takes a single full_proof_with_hints: Span<felt252> parameter (generated using the garaga calldata command or the SDK) and returns:

• Result::Ok(public_inputs) if the proof is valid

• Result::Err(error) if the proof is invalid

groth16_verifier.cairo

// Generated by Garaga version 1.0.1

use super::groth16_verifier_constants::{N_PUBLIC_INPUTS, ic, precomputed_lines, vk};

#[starknet::interface]
pub trait IGroth16VerifierBLS12_381<TContractState> {
    fn verify_groth16_proof_bls12_381(
        self: @TContractState, full_proof_with_hints: Span<felt252>,
    ) -> Result<Span<u256>, felt252>;
}

#[starknet::contract]
mod Groth16VerifierBLS12_381 {
    use garaga::definitions::{G1G2Pair, G1Point};
    use garaga::ec_ops::{G1PointTrait, ec_safe_add};
    use garaga::groth16::{
        Groth16ProofRawTrait, multi_pairing_check_bls12_381_3P_2F_with_extra_miller_loop_result,
    };
    use garaga::utils::calldata::deserialize_full_proof_with_hints_bls12_381;
    use starknet::SyscallResultTrait;
    use super::{N_PUBLIC_INPUTS, ic, precomputed_lines, vk};

    const ECIP_OPS_CLASS_HASH: felt252 =
        0x312d1dd5f967eaf6f86965e3fa7acbc9d0fbd979066a17721dd913736af2f5e;

    #[storage]
    struct Storage {}

    #[abi(embed_v0)]
    impl IGroth16VerifierBLS12_381 of super::IGroth16VerifierBLS12_381<ContractState> {
        fn verify_groth16_proof_bls12_381(
            self: @ContractState, full_proof_with_hints: Span<felt252>,
        ) -> Result<Span<u256>, felt252> {
            // DO NOT EDIT THIS FUNCTION UNLESS YOU KNOW WHAT YOU ARE DOING.
            // This function returns Result::Ok(public_inputs) if the proof is valid.
            // If the proof is invalid, it returns Result::Err(error).
            // Read the documentation to learn how to generate the full_proof_with_hints array given
            // a proof and a verifying key.
            let fph = deserialize_full_proof_with_hints_bls12_381(full_proof_with_hints);
            let groth16_proof = fph.groth16_proof;
            let mpcheck_hint = fph.mpcheck_hint;
            let msm_hint = fph.msm_hint;

            groth16_proof.raw.check_proof_points(1);

            let ic = ic.span();

            let vk_x: G1Point = match ic.len() {
                0 => panic!("Malformed VK"),
                1 => *ic.at(0),
                _ => {
                    // Start serialization with the hint array directly to avoid copying it.
                    let mut msm_calldata: Array<felt252> = array![];
                    // Add the points from VK and public inputs to the proof.
                    Serde::serialize(@ic.slice(1, N_PUBLIC_INPUTS), ref msm_calldata);
                    Serde::serialize(@groth16_proof.public_inputs, ref msm_calldata);
                    // Complete with the curve indentifier (1 for BLS12_381):
                    msm_calldata.append(1);
                    // Add the hint array.
                    for x in msm_hint {
                        msm_calldata.append(*x);
                    }

                    // Call the multi scalar multiplication endpoint on the Garaga ECIP ops contract
                    // to obtain vk_x.
                    let mut _vx_x_serialized = starknet::syscalls::library_call_syscall(
                        ECIP_OPS_CLASS_HASH.try_into().unwrap(),
                        selector!("msm_g1"),
                        msm_calldata.span(),
                    )
                        .unwrap_syscall();

                    ec_safe_add(
                        Serde::<G1Point>::deserialize(ref _vx_x_serialized).unwrap(), *ic.at(0), 1,
                    )
                },
            };
            // Perform the pairing check.
            let check = multi_pairing_check_bls12_381_3P_2F_with_extra_miller_loop_result(
                G1G2Pair { p: vk_x, q: vk.gamma_g2 },
                G1G2Pair { p: groth16_proof.raw.c, q: vk.delta_g2 },
                G1G2Pair { p: groth16_proof.raw.a.negate(1), q: groth16_proof.raw.b },
                vk.alpha_beta_miller_loop_result,
                precomputed_lines.span(),
                mpcheck_hint,
            );
            match check {
                Result::Ok(_) => Result::Ok(groth16_proof.public_inputs),
                Result::Err(error) => Result::Err(error),
            }
        }
    }
}

Declare and deploy your contract

When you are satisfied with your contract it's time to send it to Starknet!

The CLI provides utilities to simplify the process. Otherwise, it is a similar process than for every other contracts, please refer to Starknet documentation. You will to create a file containing the following variables, depending on if you want to declare & deploy on Starknet Sepolia or Starknet Mainnet. Create the following file and update its content.

.secrets

SEPOLIA_RPC_URL="https://free-rpc.nethermind.io/sepolia-juno"
SEPOLIA_ACCOUNT_PRIVATE_KEY=0x1
SEPOLIA_ACCOUNT_ADDRESS=0x2

MAINNET_RPC_URL="https://"
MAINNET_ACCOUNT_PRIVATE_KEY=0x3
MAINNET_ACCOUNT_ADDRESS=0x4

Then, you can run the command garaga declare, which will build the contract and declare it to Starknet. If the class hash is already deployed, it will return it as well. Declaring the contract involves sending all its bytecode and it is quite an expensive operation. Make sure you dapp is properly tested before!

 Usage: garaga declare [OPTIONS]

 Declare your smart contract to Starknet. Obtain its class hash and a explorer link.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --project-path          DIRECTORY          Path to the Cairo project holding the Scarb.toml file to declare                         │
│                                            [default: /home/felt/garaga-flow/my_project/]                            │
│ --env-file              FILE               Path to the environment file                                                             │
│                                            [default: /home/felt/garaga-flow/my_project/.secrets]                    │
│ --network               [sepolia|mainnet]  Starknet network [default: sepolia]                                                      │
│ --fee                   TEXT               Fee token type [eth, strk] [default: eth]                                                │
│ --help          -h                         Show this message and exit.                                                              │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

garaga declare --project-path my_project/ --env-file .secrets --network sepolia --fee strk

This command will return the class hash, used in the next step. Finally, to deploy the contract, a use garaga deploy :

 Usage: garaga deploy [OPTIONS]

 Deploy an instance of a smart contract class hash to Starknet. Obtain its address, the available endpoints and a explorer link.

╭─ Options ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *  --class-hash          TEXT               Contract class hash to deploy. Can be decimal or hex string [default: None] [required]  │
│    --env-file            FILE               Path to the environment file containing rpc, address, private_key                       │
│                                             [default: /home/felt/garaga-flow/my_project/.secrets]                   │
│    --network             [sepolia|mainnet]  Starknet network [default: sepolia]                                                     │
│    --fee                 TEXT               Fee token type [eth, strk] [default: strk]                                              │
│    --help        -h                         Show this message and exit.                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The contract address will be prompted. Be sure to save it! \