feat: allow replacing hints in test engine (#1737)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Youssef El Housni <youssef.elhousni@consensys.net>

Author: 3 people

test/engine.go

@@ -45,6 +45,7 @@ type engine struct {
 	blueprints                []constraint.Blueprint
 	internalVariables         []*big.Int
 	noSmallFieldCompatibility bool
+	hintMapping               map[solver.HintID]solver.Hint
 }
 
 // TestEngineOption defines an option for the test engine.
@@ -75,6 +76,20 @@ func WithNoSmallFieldCompatibility() TestEngineOption {
 	}
 }
 
+// WithReplacementHint allows to replace a hint function in the test engine with
+// a custom one, for a given hint ID. This is useful for testing edge cases,
+// such as when the hint function returns incorrect values.
+func WithReplacementHint(id solver.HintID, f solver.Hint) TestEngineOption {
+	return func(e *engine) error {
+		if e.hintMapping == nil {
+			e.hintMapping = make(map[solver.HintID]solver.Hint)
+		}
+		// Later calls override earlier ones for the same hint ID, matching solver.OverrideHint behavior.
+		e.hintMapping[id] = f
+		return nil
+	}
+}
+
 // IsSolved returns an error if the test execution engine failed to execute the given circuit
 // with provided witness as input.
 //
@@ -527,6 +542,12 @@ func (e *engine) NewHint(f solver.Hint, nbOutputs int, inputs ...frontend.Variab
 	if nbOutputs <= 0 {
 		return nil, fmt.Errorf("hint function must return at least one output")
 	}
+	hintFn := f
+	if e.hintMapping != nil {
+		if mappedFn, exists := e.hintMapping[solver.GetHintID(f)]; exists {
+			hintFn = mappedFn
+		}
+	}
 
 	in := make([]*big.Int, len(inputs))
 
@@ -538,7 +559,7 @@ func (e *engine) NewHint(f solver.Hint, nbOutputs int, inputs ...frontend.Variab
 		res[i] = new(big.Int)
 	}
 
-	err := f(e.Field(), in, res)
+	err := hintFn(e.Field(), in, res)
 
 	if err != nil {
 		panic("NewHint: " + err.Error())

test/engine_test.go

@@ -136,6 +136,59 @@ const (
 	divUncheckedConstConst
 )
 
+// squareHint returns x^2 for the first input.
+func squareHint(_ *big.Int, inputs []*big.Int, outputs []*big.Int) error {
+	outputs[0].Mul(inputs[0], inputs[0])
+	return nil
+}
+
+// zeroHint always returns 0.
+func zeroHint(_ *big.Int, inputs []*big.Int, outputs []*big.Int) error {
+	outputs[0].SetUint64(0)
+	return nil
+}
+
+type squareHintCircuit struct {
+	X       frontend.Variable
+	XSquare frontend.Variable
+}
+
+func (c *squareHintCircuit) Define(api frontend.API) error {
+	res, err := api.Compiler().NewHint(squareHint, 1, c.X)
+	if err != nil {
+		return err
+	}
+	api.AssertIsEqual(res[0], c.XSquare)
+	return nil
+}
+
+func TestHintReplacement(t *testing.T) {
+	field := ecc.BN254.ScalarField()
+
+	t.Run("without replacement", func(t *testing.T) {
+		err := IsSolved(
+			&squareHintCircuit{},
+			&squareHintCircuit{X: 3, XSquare: 9},
+			field,
+		)
+		if err != nil {
+			t.Fatal(err)
+		}
+	})
+
+	t.Run("with replacement", func(t *testing.T) {
+		err := IsSolved(
+			&squareHintCircuit{},
+			&squareHintCircuit{X: 3, XSquare: 0},
+			field,
+			WithReplacementHint(solver.GetHintID(squareHint), zeroHint),
+		)
+		if err != nil {
+			t.Fatal(err)
+		}
+	})
+}
+
 func TestDivUncheckedZeroPanicsInEngine(t *testing.T) {
 	tests := []struct {
 		name string