feat: circuits distribution

.github/workflows/releases.yml

@@ -310,6 +310,55 @@ jobs:
         working-directory: packages/enclave-react
         run: npm publish --access public --tag ${{ steps.npm_tag.outputs.tag }} --provenance
 
+  download-circuits:
+    name: Download Circuit Artifacts
+    runs-on: ubuntu-latest
+    needs: validate-and-prepare
+    outputs:
+      found: ${{ steps.pull.outputs.found }}
+      source_hash: ${{ steps.pull.outputs.source_hash }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - uses: pnpm/action-setup@v4
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Pull circuit artifacts
+        id: pull
+        run: |
+          SOURCE_HASH=$(pnpm tsx scripts/build-circuits.ts hash)
+          echo "source_hash=$SOURCE_HASH" >> $GITHUB_OUTPUT
+
+          if git fetch origin circuit-artifacts 2>/dev/null; then
+            mkdir -p dist/circuits
+            git archive origin/circuit-artifacts | tar -x -C dist/circuits
+            echo "found=true" >> $GITHUB_OUTPUT
+          else
+            echo "found=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create release archive
+        if: steps.pull.outputs.found == 'true'
+        run: |
+          cd dist
+          tar -czvf circuits-${{ needs.validate-and-prepare.outputs.version }}.tar.gz circuits/
+
+      - uses: actions/upload-artifact@v4
+        if: steps.pull.outputs.found == 'true'
+        with:
+          name: noir-circuits
+          path: |
+            dist/circuits-*.tar.gz
+            dist/circuits/SHA256SUMS
+            dist/circuits/checksums.json
+
   create-github-release:
     name: Create GitHub Release
     runs-on: ubuntu-latest
@@ -321,6 +370,7 @@ jobs:
         build-binaries,
         publish-rust-crates,
         publish-npm-packages,
+        download-circuits,
       ]
     if: always() && needs.validate-and-prepare.result == 'success' && needs.build-binaries.result == 'success'
     steps:
@@ -456,6 +506,15 @@ jobs:
 
           echo '```' >> release_notes.md
 
+          if [[ "${{ needs.download-circuits.outputs.found }}" == "true" ]]; then
+            cat >> release_notes.md << EOF
+
+          ## 🔮 Noir Circuits
+
+          Source hash: \`${{ needs.download-circuits.outputs.source_hash }}\`
+          EOF
+          fi
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:

.gitignore

@@ -6,3 +6,5 @@ node_modules
 target
 
 *.DS_Store
+
+dist

package.json

@@ -14,6 +14,8 @@
   },
   "scripts": {
     "bump:versions": "tsx scripts/bump-versions.ts",
+    "build:circuits": "tsx scripts/build-circuits.ts",
+    "store:circuits": "tsx scripts/circuit-artifacts.ts",
     "clean": "tsx scripts/clean.ts",
     "compile": "pnpm build:ts && pnpm rust:build",
     "lint": "eslint . && pnpm evm:lint && pnpm rust:lint && pnpm noir:lint",

scripts/README.md

@@ -157,3 +157,86 @@ pnpm clean --help
 - **Provides granular control** over what gets cleaned via skip options
 - **Shows detailed statistics** about what was removed and space freed
 - **Prevents accidental deletion** of important files by using a whitelist approach
+
+## Circuit Builder
+
+`build-circuits.ts` - Compiles Noir circuits, generates verification keys, and prepares release
+artifacts.
+
+### Usage
+
+```bash
+# Build all circuits
+pnpm build:circuits
+
+# Build only specific group (dkg or threshold)
+pnpm build:circuits --group dkg
+
+# Skip verification key generation (faster)
+pnpm build:circuits --skip-vk
+
+# Dry run to see what would be built
+pnpm build:circuits --dry-run
+
+# Get source hash for change detection
+pnpm build:circuits hash
+```
+
+### What it does
+
+1. **Discovers circuits** in `circuits/bin/dkg/` and `circuits/bin/threshold/`
+2. **Compiles** each circuit using `nargo compile`
+3. **Generates verification keys** using `bb write_vk`
+4. **Sanitizes paths** in compiled JSON (removes local filesystem paths for opsec)
+5. **Generates checksums** (`SHA256SUMS` and `checksums.json`)
+6. **Copies artifacts** to `dist/circuits/`
+
+### Options
+
+- `--group <groups>` - Circuit groups (comma-separated: dkg,threshold)
+- `--circuit <name>` - Build specific circuit(s)
+- `--skip-vk` - Skip verification key generation
+- `--skip-checksums` - Skip checksum generation
+- `-o, --output <dir>` - Output directory (default: dist/circuits)
+- `--dry-run` - Show what would be built
+- `--no-clean` - Don't clean output directory
+
+### Prerequisites
+
+- `nargo` - Noir compiler ([install](https://noir-lang.org/docs/getting_started/installation/))
+- `bb` - Barretenberg prover (for verification keys)
+
+## Circuit Artifacts
+
+`circuit-artifacts.ts` - Push/pull pre-built circuit artifacts via git branch.
+
+### Usage
+
+```bash
+# Build circuits locally, then push to git branch
+pnpm build:circuits
+pnpm store:circuits push
+
+# Pull circuits from git branch (used by CI)
+pnpm store:circuits pull
+```
+
+### What it does
+
+- **Push**: Copies `dist/circuits/` to the `circuit-artifacts` orphan branch and pushes to origin
+- **Pull**: Fetches the `circuit-artifacts` branch and extracts to `dist/circuits/`
+
+### Workflow
+
+Circuits are built locally and stored in a git branch:
+
+1. **Local**: Build circuits and push to branch
+
+```bash
+   pnpm build:circuits
+   pnpm tsx scripts/circuit-artifacts.ts push
+```
+
+2. **CI**: Pulls from branch during release, attaches to GitHub release
+
+3. **After release**: Circuits live permanently in release assets