evmprecompiles

func ECAdd ¶

func ECAdd(api frontend.API, P, Q *sw_emulated.AffinePoint[emulated.BN254Fp]) *sw_emulated.AffinePoint[emulated.BN254Fp]

ECAdd implements ALT_BN128_ADD precompile contract at address 0x06.

func ECAddG1BLS ¶ added in v0.13.0

func ECAddG1BLS(api frontend.API, P, Q, expected *sw_emulated.AffinePoint[emulated.BLS12381Fp])

ECAddG1BLS implements BLS12_G1ADD precompile contract at address 0x0b.

func ECAddG2BLS ¶ added in v0.13.0

func ECAddG2BLS(api frontend.API, P, Q, expected *sw_bls12381.G2Affine)

ECAddG2BLS implements BLS12_G2ADD precompile contract at address 0x0d.

func ECG1ScalarMulSumBLS ¶ added in v0.14.0

func ECG1ScalarMulSumBLS(api frontend.API, prev, P *sw_bls12381.G1Affine, s *emulated.Element[sw_bls12381.ScalarField], expected *sw_bls12381.G1Affine) error

ECG1ScalarMulSumBLS computes the scalar multiplication of a point P by a scalar s, adds it to a previous point prev, and checks that the result is equal to expected. It is used to implement the BLS12_G1MSM precompile contract at address 0x0c.

func ECG2ScalarMulSumBLS ¶ added in v0.14.0

func ECG2ScalarMulSumBLS(api frontend.API, prev, Q *sw_bls12381.G2Affine, s *emulated.Element[sw_bls12381.ScalarField], expected *sw_bls12381.G2Affine) error

ECG2ScalarMulSumBLS computes the scalar multiplication of a point P by a scalar s in G2, adds it to a previous point prev, and checks that the result is equal to expected. It is used to implement the [BLS12_G2MSM] precompile contract at address 0x0e.

func ECMapToG1BLS ¶ added in v0.13.0

func ECMapToG1BLS(api frontend.API, P *emulated.Element[emulated.BLS12381Fp], expected *sw_emulated.AffinePoint[emulated.BLS12381Fp]) error

ECMapToG1BLS implements [BLS12_MAP_FP_TO_G1] precompile contract at address 0x10.

func ECMapToG2BLS ¶ added in v0.13.0

func ECMapToG2BLS(api frontend.API, u *fields_bls12381.E2, expected *sw_bls12381.G2Affine) error

ECMapToG2BLS implements [BLS12_MAP_FP2_TO_G2] precompile contract at address 0x11.

func ECMul ¶

func ECMul(api frontend.API, P *sw_emulated.AffinePoint[emulated.BN254Fp], u *emulated.Element[emulated.BN254Fr]) *sw_emulated.AffinePoint[emulated.BN254Fp]

ECMul implements ALT_BN128_MUL precompile contract at address 0x07.

func ECPair ¶

func ECPair(api frontend.API, P []*sw_bn254.G1Affine, Q []*sw_bn254.G2Affine)

ECPair implements ALT_BN128_PAIRING_CHECK precompile contract at address 0x08.

To have a fixed-circuit regardless of the number of inputs, we need 2 fixed circuits:

• MillerLoopAndMul: A Miller loop of fixed size 1 followed by a multiplication in 𝔽p¹².
• MillerLoopAndFinalExpCheck: A Miller loop of fixed size 1 followed by a multiplication in 𝔽p¹², and a check that the result lies in the same equivalence class as the reduced pairing purported to be 1. This check replaces the final exponentiation step in-circuit and follows Section 4 of On Proving Pairings paper by A. Novakovic and L. Eagen.

N.B.: This is a sub-optimal routine but defines a fixed circuit regardless of the number of inputs. We can extend this routine to handle a 2-by-2 logic but we prefer a minimal number of circuits (2).

See the methods ECPairMillerLoopAndMul and ECPairMillerLoopAndFinalExpCheck for the fixed circuits. See the method ECPairIsOnG2 for the check that Qᵢ are on G2.

func ECPairBLS ¶ added in v0.13.0

func ECPairBLS(api frontend.API, P []*sw_bls12381.G1Affine, Q []*sw_bls12381.G2Affine)

ECPairBLS implements BLS12_PAIRING_CHECK precompile contract at address 0x0f.

To have a fixed-circuit regardless of the number of inputs, we need 2 fixed circuits:

• MillerLoopAndMul: A Miller loop of fixed size 1 followed by a multiplication in 𝔽p¹².
• MillerLoopAndFinalExpCheck: A Miller loop of fixed size 1 followed by a multiplication in 𝔽p¹², and a check that the result lies in the same equivalence class as the reduced pairing purported to be 1. This check replaces the final exponentiation step in-circuit and follows Section 4 of On Proving Pairings paper by A. Novakovic and L. Eagen.

N.B.: This is a sub-optimal routine but defines a fixed circuit regardless of the number of inputs. We can extend this routine to handle a 2-by-2 logic but we prefer a minimal number of circuits (2).

See the methods ECPairMillerLoopAndMul and ECPairMillerLoopAndFinalExpCheck for the fixed circuits. See the methods ECPairBLSIsOnG1 and ECPairBLSIsOnG2 for the check that Pᵢ and Qᵢ are on G1 and resp. G2.

func ECPairBLSIsOnG1 ¶ added in v0.13.0

func ECPairBLSIsOnG1(api frontend.API, Q *sw_bls12381.G1Affine, expectedIsOnG1 frontend.Variable) error

ECPairBLSIsOnG1 implements the fixed circuit for checking G1 membership and non-membership.

func ECPairBLSIsOnG2 ¶ added in v0.13.0

func ECPairBLSIsOnG2(api frontend.API, Q *sw_bls12381.G2Affine, expectedIsOnG2 frontend.Variable) error

ECPairBLSIsOnG2 implements the fixed circuit for checking G2 membership and non-membership.

func ECPairBLSMillerLoopAndFinalExpCheck ¶ added in v0.13.0

func ECPairBLSMillerLoopAndFinalExpCheck(api frontend.API, accumulator *sw_bls12381.GTEl, P *sw_bls12381.G1Affine, Q *sw_bls12381.G2Affine, expectedIsSuccess frontend.Variable) error

ECPairMillerLoopAndFinalExpCheck implements the fixed circuit for a Miller loop of fixed size 1 followed by a multiplication with an accumulator in 𝔽p¹², and a check that the result corresponds to the expected result.

func ECPairBLSMillerLoopAndMul ¶ added in v0.13.0

func ECPairBLSMillerLoopAndMul(api frontend.API, accumulator *sw_bls12381.GTEl, P *sw_bls12381.G1Affine, Q *sw_bls12381.G2Affine, expected *sw_bls12381.GTEl) error

ECPairMillerLoopAndMul implements the fixed circuit for a Miller loop of fixed size 1 followed by a multiplication with an accumulator in 𝔽p¹². It asserts that the result corresponds to the expected result.

func ECPairIsOnG2 ¶ added in v0.11.0

func ECPairIsOnG2(api frontend.API, Q *sw_bn254.G2Affine, expectedIsOnG2 frontend.Variable) error

ECPairIsOnG2 implements the fixed circuit for checking G2 membership and non-membership.

func ECPairMillerLoopAndFinalExpCheck ¶ added in v0.11.0

func ECPairMillerLoopAndFinalExpCheck(api frontend.API, accumulator *sw_bn254.GTEl, P *sw_bn254.G1Affine, Q *sw_bn254.G2Affine, expectedIsSuccess frontend.Variable) error

ECPairMillerLoopAndFinalExpCheck implements the fixed circuit for a Miller loop of fixed size 1 followed by a multiplication with an accumulator in 𝔽p¹², and a check that the result corresponds to the expected result.

func ECPairMillerLoopAndMul ¶ added in v0.11.0

func ECPairMillerLoopAndMul(api frontend.API, accumulator *sw_bn254.GTEl, P *sw_bn254.G1Affine, Q *sw_bn254.G2Affine, expected *sw_bn254.GTEl) error

ECPairMillerLoopAndMul implements the fixed circuit for a Miller loop of fixed size 1 followed by a multiplication with an accumulator in 𝔽p¹². It asserts that the result corresponds to the expected result.

func ECRecover ¶

func ECRecover(api frontend.API, msg emulated.Element[emulated.Secp256k1Fr],
	v frontend.Variable, r, s emulated.Element[emulated.Secp256k1Fr],
	strictRange frontend.Variable, isFailure frontend.Variable) *sw_emulated.AffinePoint[emulated.Secp256k1Fp]

ECRecover implements ECRECOVER precompile contract at address 0x01.

The method allows checking both the transaction signatures and ECRecover precompile calls. The difference between TX signature verification and ECRecover precompile call is that there is additional check for s <= (Fr-1)/2 in the former case. To enforce this check, the strictRange variable should be set to 1.

The isFailure variable is set to 1 when the inputs are expected to be invalid in the context of ECRecover. The failure cases are:

1. The public key is zero.
2. The value r^3 + 7 is not a quadratic residue.

func Expmod ¶ added in v0.10.0

func Expmod[P emulated.FieldParams](api frontend.API, base, exp, modulus *emulated.Element[P]) *emulated.Element[P]

Expmod implements MODEXP precompile contract at address 0x05.

Internally, uses 4k elements for representing the base, exponent and modulus, upper bounding the sizes of the inputs. The runtime is constant regardless of the actual length of the inputs.

func GetHints ¶

func GetHints() []solver.Hint

GetHints returns all the hints used in this package.

func KzgPointEvaluation ¶ added in v0.14.0

func KzgPointEvaluation(
	api frontend.API,
	versionedHash [2]frontend.Variable,
	evaluationPoint emulated.Element[sw_bls12381.ScalarField],
	claimedValue emulated.Element[sw_bls12381.ScalarField],
	commitmentCompressed [3]frontend.Variable,
	proofCompressed [3]frontend.Variable,
	expectedSuccess frontend.Variable,
	expectedBlobSize [2]frontend.Variable,
	expectedBlsModulus [2]frontend.Variable,
) error

KzgPointEvaluation implements the [KZG_POINT_EVALUATION] precompile at address 0xa.

The data is encoded as follows:

[ versioned_hash | point |  claim  | commitment |   proof   ]
 <---- 32b -----> <-32b-> <- 32b -> <-- 48b  --> <-- 48b -->

Values point and claim are the evaluation point and the claimed value, they are represented as 32-byte scalar field elements. We use [2]frontend.Variable as the arithmetization provides them as 16-byte words.

Values commitment and proof are the KZG commitment and proof respectively. They are given as compressed points, for which we use 3 native elements to represent. The method performs decompression and all necessary checks. The encoding is given by Appendix C of [PAIRING_FRIENDLY_CURVES].

[KZG_POINT_EVALUATION] https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md [PAIRING_FRIENDLY_CURVES] https://datatracker.ietf.org/doc/draft-irtf-cfrg-pairing-friendly-curves/