evmprecompiles

Documentation

Overview

Package evmprecompiles implements the Ethereum VM precompile contracts.

This package collects all the precompile functions into a single location for easier integration. The main functionality is implemented elsewhere. This package right now implements:

1. ECRECOVER ✅ -- function ECRecover
2. SHA256 ❌ -- in progress
3. RIPEMD160 ❌ -- postponed
4. ID ❌ -- trivial to implement without function
5. EXPMOD ✅ -- function Expmod
6. BN_ADD ✅ -- function ECAdd
7. BN_MUL ✅ -- function ECMul
8. SNARKV ✅ -- function ECPair
9. BLAKE2F ❌ -- postponed

This package uses local representation for the arguments. It is up to the user to instantiate corresponding types from their application-specific data.

Index

• func ECAdd(api frontend.API, P, Q *sw_emulated.AffinePoint[emulated.BN254Fp]) *sw_emulated.AffinePoint[emulated.BN254Fp]
• func ECMul(api frontend.API, P *sw_emulated.AffinePoint[emulated.BN254Fp], ...) *sw_emulated.AffinePoint[emulated.BN254Fp]
• func ECPair(api frontend.API, P []*sw_bn254.G1Affine, Q []*sw_bn254.G2Affine)
• func ECPairIsOnG2(api frontend.API, Q *sw_bn254.G2Affine, expectedIsOnG2 frontend.Variable) error
• func ECPairMillerLoopAndFinalExpCheck(api frontend.API, accumulator *sw_bn254.GTEl, P *sw_bn254.G1Affine, ...) error
• func ECPairMillerLoopAndMul(api frontend.API, accumulator *sw_bn254.GTEl, P *sw_bn254.G1Affine, ...) error
• func ECRecover(api frontend.API, msg emulated.Element[emulated.Secp256k1Fr], ...) *sw_emulated.AffinePoint[emulated.Secp256k1Fp]
• func Expmod[P emulated.FieldParams](api frontend.API, base, exp, modulus *emulated.Element[P]) *emulated.Element[P]
• func GetHints() []solver.Hint

Functions

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 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 ECPairIsOnG2

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

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

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

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.