Contributor's Guide

Triggering a New Release for Nomos Circuits

To trigger a release build:

Create and push a tag in the format vX.Y.Z.
This will automatically trigger the .github/workflows/build_circuits.yml workflow.
Once the workflow finishes, the generated artifacts will be attached to a new release.

Currently, releases published this way are marked as Draft and Pre-Release to ensure that the changelog and pre-release steps are manually reviewed first.

Generated Artifacts

Each release includes a single unified bundle per platform:

Unified Release Bundles

For each supported platform (Linux x86_64, macOS aarch64, Windows x86_64):

nomos-circuits-{version}-{os}-{arch}.tar.gz

A complete bundle containing all components needed to generate and verify proofs for all circuits.

Bundle Structure:

nomos-circuits-{version}-{os}-{arch}/
├── VERSION
├── pol/
│   ├── witness_generator[.exe]
│   ├── witness_generator.dat
│   ├── proving_key.zkey
│   └── verification_key.json
├── poq/
│   ├── witness_generator[.exe]
│   ├── witness_generator.dat
│   ├── proving_key.zkey
│   └── verification_key.json
├── zksign/
│   ├── witness_generator[.exe]
│   ├── witness_generator.dat
│   ├── proving_key.zkey
│   └── verification_key.json
└── poc/
    ├── witness_generator[.exe]
    ├── witness_generator.dat
    ├── proving_key.zkey
    └── verification_key.json

Each circuit directory contains:

witness_generator: Compiled C++ binary for generating witnesses from inputs
witness_generator.dat: Required data file for the witness generator
proving_key.zkey: Groth16 proving key for generating zk-SNARK proofs
verification_key.json: Verification key for verifying proofs

The proving keys are generated using the Hermez Powers of Tau ceremony (powersOfTau28_hez_final_17.ptau), which supports circuits with up to 2^17 constraints.

Example

git tag v1.2.3 -m "Release v1.2.3"
git push --tags

Publishing the Release

After triggering the release, it will appear as a Draft and Pre-Release.
Before making it public, make sure to:

Review the changelog
Ensure that all relevant changes are clearly listed and properly formatted.
Confirm the pre-release checklist
Verify that all required steps have been completed, then remove the checklist from the release notes.

Once everything looks good:

Mark the release as published
- Uncheck “This is a pre-release.”
- Publish the release (removing the Draft state).

⚡ Important: Nomos builds will only pick up the new circuits once the release is published as Latest (i.e. not marked as draft or pre-release).

2.8 KiB Raw Blame History