feat: Enable multiple GKR sub-circuits #1661

Tabaie · 2025-12-10T21:31:00Z

Note: deserialization tests are failing due to a change in the structure of constraint systems. Rather than a single "gkr info" sub-object, we now have a slice of them.

Note

Adds multi-GKR support (per-circuit), replaces AddGkr with NewGkr, updates solvers/hints and GKR API, and refactors GKR types/registry with minor fixes.

Constraint system / wiring:
- Switch System.GkrInfo to []*gkrinfo.StoringInfo; replace AddGkr with NewGkr() returning (infoPtr, index) across all curves.
Solvers & hints:
- Load multiple GKR infos via gkrtypes.NewSolvingInfo; wire new hints using gkrhints.TestEngineHints (GetAssignment, Solve, Prove).
- Adjust hint IDs via csolver.GetHintID and use new per-curve NewSolvingData (padded instances), removing worker-pool deps; ensure challenges use SetBytesCanonical.
GKR types/registry:
- Introduce gkrtypes.NewCircuit/NewSolvingInfo; augment Gate with allowed curves and SupportsCurve; add EqualGateFunction checks.
- Rework gkrgates.Register API (options now validate/return errors), curve selection, duplicate registration reconciliation, and add lightweight verifier helpers.
std/gkrapi (public API overhaul):
- New usage: gkrapi.New(api) → build circuit (e.g., NewInput, Gate, NamedGate) → Compile(hash) → AddInstance (per-instance I/O); add Circuit.GetValue for debugging.
- Remove old Solve/Verify and test-engine-only paths; integrate commitment-based initial challenge via multicommit.
Poseidon2 GKR integration:
- Update to new API (GkrCompressor) and gate registration; restrict to BLS12-377 via WithCurves.
Utilities & misc:
- Add utils.ExtendRepeatLast and utils.SliceOfRefs; cleanup unused helpers.
- Minor fixes: correct MulAcc (mul instead of add), typos, and small-rational SetBytesCanonical.
- Expose gkr.ComputeLogNbInstances; tweak tests accordingly.

^{Written by Cursor Bugbot for commit 72d954c. This will update automatically on new commits. Configure here.}

Co-authored-by: Copilot <[email protected]>

ivokub

I still think the automated gate degree testing during registration makes the implementation a bit too complex. Seems ok implementation wise, but I'm not fully confident.

And imo restricting the gates being only used when compiled on particular curves adds also unnnecessary complexity (and most of the times we provide gnark.Curves() everywhere). For example in Poseidon2 package we correctly error out if someone wants to call the circuit on mismatching curve, so the assertion is already done.

For me gate registration is still way too verbose. Instead of

gkrgates.Register(extKeyGate(&p.RoundKeys[round][varIndex]), 2, gkrgates.WithUnverifiedDegree(1), gkrgates.WithUnverifiedSolvableVar(0), gkrgates.WithName(gateNames.linear(varIndex, round)), gkrgates.WithCurves(ecc.BLS12_377))

imo it makes so much more sense if I could do

gkrgates.Register(xtKeyGate(&p.RoundKeys[round][varIndex]), 2 /*inputs*/, 1 /*degree*/, "NAME-R1-V2")

And the one-by-one instance addition. Makes sense, but have you checked the profiles how does it affect circuit compile/solve time? I can imagine when doing one by one there is overhead?

I can try working on the PR tomorrow to wrap it finally up.

ivokub · 2025-12-17T13:09:51Z

constraint/bls12-377/solver.go

+		gkrData := gkr.NewSolvingData(solvingInfo)
+		var gkrHints *gkrhints.TestEngineHints
+
+		newOpts := make([]csolver.Option, len(opts), len(opts)+3)


What is the point of allocating manually and then copying? Do you want to keep the initial opts argument intact?

If you just remove the manual allocation and copy, and only keep opts = append(opts, ...) then it achieves the same thing as append will allocate sufficient space and copy to fit everything.

Yes for an extra safety guarantee. For example if the caller gives a sub-slice and we append to it, it could overwrite the super-slice if I'm not mistaken. It's unlikely for anyone to do that but it costs so little to prevent it.

ivokub · 2025-12-17T13:13:24Z

constraint/bls12-377/solver.go

+		newOpts := make([]csolver.Option, len(opts), len(opts)+3)
+		copy(newOpts, opts)
+		opts = append(newOpts,
+			csolver.OverrideHint(csolver.GetHintID(gkrHints.GetAssignment), gkr.GetAssignmentHint(gkrData)),


I don't understhand, why do we call csolver.GetHintID(gkrHints.Solve)? You have just initialized gkrHints as a nil pointer -- so you use a method (*TestEngineHints)(nil).GetAssignment.

Instead we could just have a placeholder hint somewhere PlaceHolderGetAssignment at package level and use this. This is also how we do for API.Commit.

That hint is not just a placeholder. It is the actual hint for the test engine. Because it computes (at the solving stage) and uses (at the proving stage) the full circuit assignments in the background, so it needs to be tied to an object for those to persist.
But the empty object is only used to get references to those functions.

ivokub · 2025-12-17T13:13:45Z

constraint/bls12-377/solver.go

-			csolver.OverrideHint(cs.GkrInfo.ProveHintID, gkr.ProveHint(cs.GkrInfo.HashName, &gkrData)))
+
+		gkrData := gkr.NewSolvingData(solvingInfo)
+		var gkrHints *gkrhints.TestEngineHints


Why do we use TestEnghineHints? We run the actual solver here already?

We're not actually using the test engine hints. This object is used to get references to the test engine hints for them to be replaced.

ivokub · 2025-12-17T13:46:27Z

constraint/solver/gkrgates/registry.go

 // the curve's order, in which case the degree will be computed incorrectly.
-func WithCurves(curves ...ecc.ID) registerOption {
-	return func(settings *registerSettings) {
+func WithCurves(curves ...ecc.ID) RegisterOption {


The documentation does not match the implementation. Now in the registration you set allowedCurves based on the option.

For me this is complex - I think the gate should know itself where it can work (if it doesn't work over all fields) and then panic.

And I think we can still use the approach where we test the degree of the gate on a random modulus instead of letting the users define it themselves. Otherwise the user has to know what is the relation between gate degree and the provided modulus, which doesn't make sense as it is used for automatic degree testing.

The documentation does not match the implementation

Fixed!

I think the gate should know itself where it can work (if it doesn't work over all fields) and then panic.

I prefer a compile time error to a solving/proving time panic.

And I think we can still use the approach where we test the degree of the gate on a random modulus instead of letting the users define it themselves.

That idea is appealing, but for example in gates for hash functions we have the permutation constants cached as fr.Elements, and if we run that on a random modulus the gate will have to panic, making degree testing fail.

ivokub · 2025-12-17T13:58:37Z

constraint/solver/gkrgates/registry.go

+			return fmt.Errorf("gate \"%s\" already registered with a different number of inputs (%d != %d)", s.name, g.NbIn(), nbIn)
+		}
+
+		for _, curve := range curvesForTesting {


I would remove the automatic gate degree testing. For me the implementation becomes more complex and actually more fragile to use (the user could mess up options and have unverfied wrong degree etc). I'd keep this PR only for supporting multiple GKR instances.

I'm open to removing the unverified degrees. We can mostly rely on automatic testing and verified user hints (useful for debugging.)

ivokub · 2025-12-17T15:14:07Z

internal/gkr/gkrhints/engine_hints.go

+	"github.com/consensys/gnark/internal/utils"
+)
+
+type TestEngineHints struct {


It is called TestEngineHints, but it is referenced during actual SNARK circuit solving?

The test engine doesn't compile. It directly solves the circuit as it goes through the circuit Define function. So the default hints have to be compatible with the test engine, because unlike the R1CS / Plonkish case, we won't have the opportunity to replace them with the right ones later.

std/gkrapi/compile.go

ivokub · 2025-12-17T21:38:20Z

std/gkrapi/compile.go

-		return -1
+// New creates a new GKR API
+func New(api frontend.API) *API {
+	toStore, index := api.(gkrinfo.ConstraintSystem).NewGkr()


I would handle the error better - right now if the API doesn't implement it we just get "doesn't implement the interface" panic, but it doesn't allow user to fix the issue (perhaps they wrapped their builder for adding functionality etc)

The test engine, r1cs and scs APIs all implement this. Do we have a lot of use cases with user implemented APIs? If that's the case I agree we can return proper errors.

ivokub · 2025-12-17T21:47:21Z

std/gkrapi/compile.go

+			return nil, fmt.Errorf("missing entry for input variable %d", wI)
+		} else {
+			hintIn[hintInI+2] = inV
+			c.assignments[wI] = append(c.assignments[wI], inV)


Could we potentially have a perf regression here? If we add instances one-by-one then we append there the slices also one by one. If we have 50k instances, then it just adds up time- and allocation wise.

Thats why it would be nice to keep the previous approach as well -- then we know beforehand how big are the assignemnts and allocate only once. And we could also do solving only once?

Could we potentially have a perf regression here?

I think so but since this is only run during compile time (or with the test engine) I figured there's no need to worry much about perf. If we care about it I think a Circuit.Grow function similar to bytes.Buffer would be a good idea. Thoughts?

Thats why it would be nice to keep the previous approach as well

There's another PR that brings back v1. Would you like me to merge it into this?

std/gkrapi/compile.go

cursor · 2025-12-19T04:32:50Z

internal/generator/backend/template/gkr/solver_hints.go.tmpl

+		for j := n; j < len(a[i]); j++ {
+			a[i][j] = a[i][j-1]
+		}
+	}


Bug: Panic on zero instances in repeatUntilEnd

The repeatUntilEnd function's comment states it requires n > 0, but there's no validation. If a GKR circuit is registered with NbInstances = 0, then ecc.NextPowerOfTwo(0) returns 1, creating assignment arrays of length 1. When ProveHint calls repeatUntilEnd(0), the inner loop starts at j = 0 and attempts a[i][0] = a[i][-1], causing an index out of bounds panic instead of returning a meaningful error. The same issue exists in the inline padding loop within NewSolvingData.

Additional Locations (1)

internal/gkr/bn254/solver_hints.go#L225-L233

Tabaie and others added 30 commits June 1, 2025 11:36

refactor: addInstance instead of series etc

609d47d

feat: check for duplicate gates, allow limiting curves for gate

79d4cbf

refactor: gkr api tests

82e33e5

refactor gkr example

ba06e5d

refactor: solve hint called per instance

700c152

revert: newPrint back in std/gkr to avoid import cycle

30f5633

refactor: remove circuit/instance rearranging

44d6b4c

chore: generify

f5f726c

fix: registry duplicate detection

644fd6a

fix: solver hint id mismatch

2001e83

remove redundant make

d3ca3c1

fix: works on plonk

6474482

refactor: solve hint for test engine

0c0b6b0

fix prove hint

478d53d

fix package tests

6c83740

refactor: remove println

d6e382f

chore: generify print removal

a8f30a4

feat: GetValue

8ac5f9f

fix all gkrapi tests pass

5bb879d

fix gkr-poseidon2

7f9a0f1

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

355277c

fix: reduce in test engine

cfdb9d3

fix: rename GkrCompressions -> GkrPermutations

12788f3

bench: gkrposeidon2

9a0bf0e

fix pad for bls12377

618beff

some more padding fixes

22b77f2

fix: padding issue in bn254

250a35b

chore generify fix

1586760

Let Uint64 panic

e593d90

Update constraint/solver/gkrgates/registry.go

9df619a

Co-authored-by: Copilot <[email protected]>

Tabaie added 8 commits November 26, 2025 12:16

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

f05b1c1

feat: bw6-633 solver hints

369df42

fix: GetAssignment hint

93f4e5e

build: generify solver hints

e19b0c8

fix: compilation

88e053e

fix: code gen issue

e309eff

fix: slice reference bug

0f9f859

fix: hash circuits

d5d6b17

ivokub requested changes Dec 17, 2025

View reviewed changes

test: update test artefacts

6548bfa

ivokub added dep: linea Issues affecting Linea downstream feat: gkr PRs related to GKR labels Dec 17, 2025

ivokub and others added 15 commits December 18, 2025 09:39

chore: remove new allocation

ff9fa92

docs: comment why we refer to nil test engine in solver

aba526d

docs: rewrap

94bacc3

docs: add documentation for interface

2adfd0e

feat: explicit interface implementation checking

92ae7c8

chore: remove unused methods

1112c9f

docs: comment generated GKR hints methods

b53784d

fix: element type

a8fb331

docs: comment methods in gkrtypes

847caf5

fix/docs: WithCurves

6d4d0c2

remove api check

f80b29f

docs: initial challenge getter and dummy input.

b1e68c3

fix: assignment <-> circuit

17e1809

docs: WithAssignments

3c7ce0f

Merge branch 'master' into feat/gkr/multiple

72d954c

Tabaie marked this pull request as ready for review December 19, 2025 04:28

Tabaie requested a review from ivokub December 19, 2025 04:28

cursor bot reviewed Dec 19, 2025

View reviewed changes

feat: Enable multiple GKR sub-circuits #1661

Are you sure you want to change the base?

feat: Enable multiple GKR sub-circuits #1661

Uh oh!

Conversation

Tabaie commented Dec 10, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ivokub left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Tabaie Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor bot Dec 19, 2025

Choose a reason for hiding this comment

Bug: Panic on zero instances in repeatUntilEnd

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Tabaie commented Dec 10, 2025 •

edited by cursor bot

Loading

Tabaie Dec 19, 2025 •

edited

Loading