Merge branch 'master' into feat/gkr/add-instance

Author: Tabaie

.github/workflows/pr.yml

@@ -33,7 +33,7 @@ jobs:
 
   test:
     needs: staticcheck
-    runs-on: ubuntu-latest-128
+    runs-on: gha-runner-scale-set-ubuntu-24-amd64-xxl
     permissions: 
       pull-requests: write
     steps:
@@ -65,9 +65,9 @@ jobs:
       run: |
         set -euo pipefail
         go test -json -v -p 4 -short -timeout=30m ./... 2>&1 | gotestfmt -hide=all | tee /tmp/gotest.log
-        go test -json -v -p 4 -tags=release_checks,solccheck . 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
-        go test -json -v -p 4 -tags=prover_checks ./test/... 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
-        go test -json -v -p 4 -tags=prover_checks ./examples/... 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
+        go test -json -v -p 4 -timeout=30m -tags=release_checks,solccheck . 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
+        go test -json -v -p 4 -timeout=30m -tags=prover_checks ./test/... 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
+        go test -json -v -p 4 -timeout=30m -tags=prover_checks ./examples/... 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
         go test -json -v -run=NONE -fuzz=FuzzIntcomp -fuzztime=30s ./internal/backend/ioutils 2>&1 | gotestfmt -hide=all | tee -a /tmp/gotest.log
 
 

.github/workflows/push.yml

@@ -38,7 +38,7 @@ jobs:
     strategy:
       matrix:
         go-version: [1.23.x]
-        os: [ubuntu-latest-128, windows-latest, macos-latest]
+        os: [gha-runner-scale-set-ubuntu-24-amd64-xxl, windows-latest, macos-latest]
     runs-on: ${{ matrix.os }}
     needs:
       - staticcheck
@@ -54,7 +54,7 @@ jobs:
         go install golang.org/x/tools/cmd/goimports@latest && go install github.com/klauspost/asmfmt/cmd/asmfmt@latest
         go install github.com/ethereum/go-ethereum/cmd/[email protected]
     - name: install solc deps
-      if: startsWith(matrix.os, 'ubuntu') == true
+      if: startsWith(matrix.os, 'gha-runner-scale-set-ubuntu') == true
       run: |
         go install github.com/consensys/[email protected]
         sudo add-apt-repository ppa:ethereum/ethereum
@@ -63,11 +63,11 @@ jobs:
 
     - name: Test (windows / mac)
       # on macOS CI / Windows CI we avoid running the std/ tests (they are run on ubuntu CI)
-      if: startsWith(matrix.os, 'ubuntu') == false
+      if: startsWith(matrix.os, 'gha-runner-scale-set-ubuntu') == false
       run: |
         go test -tags=release_checks -v -timeout=60m .
     - name: Test (ubuntu - race and solc)
-      if: startsWith(matrix.os, 'ubuntu') == true
+      if: startsWith(matrix.os, 'gha-runner-scale-set-ubuntu') == true
       run: |
         go test -v -p 4 -short -timeout=30m ./...
         go test -v -p 4 -timeout=120m -tags=release_checks ./std/math/emulated/...

README.md

@@ -171,20 +171,11 @@ The following schemes and curves support experimental use of Ingonyama's ICICLE
 instantiated with the following curve(s)
 
 - [x] BN254
+- [x] BLS12-377
+- [x] BLS12-381
+- [x] BW6-761
 
-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:
-
-```go
-    // 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](https://github.com/ingonyama-zk/icicle-gnark).
+For usage instructions see [accelerated backend documentation](backend/accelerated/icicle/doc.go) and [ICICLE repo](https://github.com/ingonyama-zk/icicle-gnark).
 
 ## Citing
 

backend/accelerated/icicle/doc.go

@@ -0,0 +1,74 @@
+// Package icicle implements backends using ICICLE library.
+//
+// This backend depends on the MIT-licensed [ICICLE] library. We currently
+// support Groth16 proving system on the following curves:
+//   - BLS12-377
+//   - BLS12-381
+//   - BN254
+//   - BW6-761
+//
+// # Setup
+//
+// Before using the GPU-acceleration for ICICLE backend, you must install the
+// CUDA toolkit and have a compatible NVIDIA GPU. See [CUDA instructions] for
+// more details. We have tested with CUDA 13 on Linux (Ubuntu 24.04), but other
+// versions should work as well.
+//
+// Additionally, for building ICICLE backend, you need to have a working clang
+// toolchain.
+//
+// To initialize the ICICLE backend, follow the instructions in the [ICICLE]
+// repository. Namely, first you should install the ICICLE library:
+//
+//	git clone https://github.com/ingonyama-zk/icicle-gnark
+//	cd icicle-gnark/wrappers/golang
+//	sudo ./build.sh -curve=all
+//
+// After that, the libraries are installed in `/usr/local/lib` and backend in
+// `/usr/local/lib/backend`.
+//
+// Now set the environment variables:
+//
+//	export CGO_LDFLAGS="-L/usr/local/lib -licicle_device -lstdc++ -lm -Wl,-rpath=/usr/local/lib"
+//	export ICICLE_BACKEND_INSTALL_DIR="/usr/local/lib/backend/"
+//
+// # Usage
+//
+// To use the ICICLE backend in your code, you should use the `icicle_groth16`
+// package and use it for proving:
+//
+//	import icicle_groth "github.com/consensys/gnark/backend/accelerated/icicle/groth16"
+//	...
+//	pk := icicle_groth.NewProvingKey(curve)
+//	n, err = pk.ReadFrom(r)
+//	...
+//	proof, err := icicle_groth.Prove(ccs, pk, witness)
+//
+// Finally, to build the application, use the `icicle` build tag to ensure the ICICLE integration is built:
+//
+//	go build -tags=icicle main.go
+//
+// # Proving key
+//
+// Keep in mind that the definitions of ICICLE and native gnark proving keys are
+// different, so you cannot directly use the native gnark proving key with the
+// ICICLE backend. However, the serialization is compatible, so you can use the
+// `ReadFrom` and `WriteTo` methods to read/write the proving keys in binary
+// format and use the same proving key for both backends.
+//
+// # Non-free backends
+//
+// gnark by default depends on the MIT-licensed ICICLE backend library. However, ICICLE
+// can be used with non-free backends (newer CUDA and Metal), but this is not tested
+// and we do not provide support for this.
+//
+// # Future compatibility
+//
+// Keep in mind that the accelerated backends are not automatically tested in
+// the CI, so we cannot guarantee that future changes in gnark will not break
+// the ICICLE integration. We also may change interfaces in the sub-packages to
+// align with the external dependency changes.
+//
+// [ICICLE]: https://github.com/ingonyama-zk/icicle-gnark
+// [CUDA instructions]: https://developer.nvidia.com/cuda-downloads?target_os=Linux
+package icicle