diff --git a/EIPS/eip-2537.md b/EIPS/eip-2537.md index 9a80865676204..14b9858c8eb21 100644 --- a/EIPS/eip-2537.md +++ b/EIPS/eip-2537.md @@ -1,7 +1,7 @@ --- eip: 2537 title: Precompile for BLS12-381 curve operations -author: Alex Vlasov (@shamatar), Kelly Olson (@ineffectualproperty) +author: Alex Vlasov (@shamatar), Kelly Olson (@ineffectualproperty), Alex Stokes (@ralexstokes) discussions-to: https://ethereum-magicians.org/t/eip2537-bls12-precompile-discussion-thread/4187 status: Stagnant type: Standards Track @@ -35,15 +35,15 @@ Multiexponentiation operation is included to efficiently aggregate public keys o |Precompile |Address | |---|---| -|BLS12_G1ADD | 0x0a | -|BLS12_G1MUL | 0x0b | -|BLS12_G1MULTIEXP | 0x0c | -|BLS12_G2ADD | 0x0d | -|BLS12_G2MUL | 0x0e | -|BLS12_G2MULTIEXP | 0x0f | -|BLS12_PAIRING | 0x10 | -|BLS12_MAP_FP_TO_G1 | 0x11 | -|BLS12_MAP_FP2_TO_G2 | 0x12 | +|BLS12_G1ADD | 0x0c | +|BLS12_G1MUL | 0x0d | +|BLS12_G1MULTIEXP | 0x0e | +|BLS12_G2ADD | 0x0f | +|BLS12_G2MUL | 0x10 | +|BLS12_G2MULTIEXP | 0x11 | +|BLS12_PAIRING | 0x12 | +|BLS12_MAP_FP_TO_G1 | 0x13 | +|BLS12_MAP_FP2_TO_G2 | 0x14 | ## Motivation @@ -122,6 +122,7 @@ Certain operations have variable length input, such as multiexponentiations (tak G1 addition call expects `256` bytes as an input that is interpreted as byte concatenation of two G1 points (`128` bytes each). Output is an encoding of addition operation result - single G1 point (`128` bytes). Error cases: + - Either of points being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -131,6 +132,7 @@ Error cases: G1 multiplication call expects `160` bytes as an input that is interpreted as byte concatenation of encoding of G1 point (`128` bytes) and encoding of a scalar value (`32` bytes). Output is an encoding of multiplication operation result - single G1 point (`128` bytes). Error cases: + - Point being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -140,6 +142,7 @@ Error cases: G1 multiexponentiation call expects `160*k` bytes as an input that is interpreted as byte concatenation of `k` slices each of them being a byte concatenation of encoding of G1 point (`128` bytes) and encoding of a scalar value (`32` bytes). Output is an encoding of multiexponentiation operation result - single G1 point (`128` bytes). Error cases: + - Any of G1 points being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -150,6 +153,7 @@ Error cases: G2 addition call expects `512` bytes as an input that is interpreted as byte concatenation of two G2 points (`256` bytes each). Output is an encoding of addition operation result - single G2 point (`256` bytes). Error cases: + - Either of points being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -159,6 +163,7 @@ Error cases: G2 multiplication call expects `288` bytes as an input that is interpreted as byte concatenation of encoding of G2 point (`256` bytes) and encoding of a scalar value (`32` bytes). Output is an encoding of multiplication operation result - single G2 point (`256` bytes). Error cases: + - Point being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -168,6 +173,7 @@ Error cases: G2 multiexponentiation call expects `288*k` bytes as an input that is interpreted as byte concatenation of `k` slices each of them being a byte concatenation of encoding of G2 point (`256` bytes) and encoding of a scalar value (`32` bytes). Output is an encoding of multiexponentiation operation result - single G2 point (`256` bytes). Error cases: + - Any of G2 points being not on the curve must result in error - Field elements encoding rules apply (obviously) - Input has invalid length @@ -176,12 +182,14 @@ Error cases: #### ABI for pairing Pairing call expects `384*k` bytes as an inputs that is interpreted as byte concatenation of `k` slices. Each slice has the following structure: + - `128` bytes of G1 point encoding - `256` bytes of G2 point encoding Output is a `32` bytes where first `31` bytes are equal to `0x00` and the last byte is `0x01` if pairing result is equal to multiplicative identity in a pairing target field and `0x00` otherwise. Error cases: + - Any of G1 or G2 points being not on the curve must result in error - Any of G1 or G2 points are not in the correct subgroup - Field elements encoding rules apply (obviously) @@ -193,6 +201,7 @@ Error cases: Field-to-curve call expects `64` bytes an an input that is interpreted as a an element of the base field. Output of this call is `128` bytes and is G1 point following respective encoding rules. Error cases: + - Input has invalid length - Input is not a valid field element @@ -201,6 +210,7 @@ Error cases: Field-to-curve call expects `128` bytes an an input that is interpreted as a an element of the quadratic extension field. Output of this call is `256` bytes and is G2 point following respective encoding rules. Error cases: + - Input has invalid length - Input is not a valid field element @@ -267,6 +277,7 @@ For multiexponentiation and pairing functions gas cost depends on the input leng Define a constant `LEN_PER_PAIR` that is equal to `160` for G1 operation and to `288` for G2 operation. Define a function `discount(k)` following the rules in the corresponding section, where `k` is number of pairs. The following pseudofunction reflects how gas should be calculated: + ``` k = floor(len(input) / LEN_PER_PAIR); if k == 0 { @@ -286,6 +297,7 @@ We use floor division to get number of pairs. If length of the input is not divi Define a constant `LEN_PER_PAIR = 384`; The following pseudofunction reflects how gas should be calculated: + ``` k = floor(len(input) / LEN_PER_PAIR); @@ -317,13 +329,13 @@ Subgroup check **is mandatory** during the pairing call. Implementations *should ### Field to curve mapping -Algorithms and set of parameters for SWU mapping method is provided by a separate [document](../assets/eip-2537/field_to_curve.md) +Algorithms and set of parameters for SWU mapping method is provided by a separate [document](../assets/eip-2537/field_to_curve.md) ## Test Cases -Due to the large test parameters space we first provide properties that various operations must satisfy. We use additive notation for point operations, capital letters (`P`, `Q`) for points, small letters (`a`, `b`) for scalars. Generator for G1 is labeled as `G`, generator for G2 is labeled as `H`, otherwise we assume random point on a curve in a correct subgroup. `0` means either scalar zero or point of infinity. `1` means either scalar one or multiplicative identity. `group_order` is a main subgroup order. `e(P, Q)` means pairing operation where `P` is in G1, `Q` is in G2. +Due to the large test parameters space we first provide properties that various operations must satisfy. We use additive notation for point operations, capital letters (`P`, `Q`) for points, small letters (`a`, `b`) for scalars. Generator for G1 is labeled as `G`, generator for G2 is labeled as `H`, otherwise we assume random point on a curve in a correct subgroup. `0` means either scalar zero or point of infinity. `1` means either scalar one or multiplicative identity. `group_order` is a main subgroup order. `e(P, Q)` means pairing operation where `P` is in G1, `Q` is in G2. -Requeired properties for basic ops (add/multiply): +Required properties for basic ops (add/multiply): - Commutativity: `P + Q = Q + P` - Additive negation: `P + (-P) = 0` @@ -334,7 +346,8 @@ Requeired properties for basic ops (add/multiply): - Multiplication by the unnormalized scalar `(scalar + group_order) * P = scalar * P` Required properties for pairing operation: -- Degeneracy `e(P, 0*Q) = e(0*P, Q) = 1` + +- Degeneracy `e(P, 0*Q) = e(0*P, Q) = 1` - Bilinearity `e(a*P, b*Q) = e(a*b*P, Q) = e(P, a*b*Q)` (internal test, not visible through ABI) ### Benchmarking test cases @@ -344,6 +357,7 @@ A set of test vectors for quick benchmarking on new implementations is located i ## Reference Implementation There are two fully spec compatible implementations on the day of writing: + - One in Rust language that is based on the EIP1962 code and integrated with OpenEthereum for this library - One implemented specifically for Geth as a part of the current codebase @@ -354,4 +368,5 @@ Strictly following the spec will eliminate security implications or consensus im Important topic is a "constant time" property for performed operations. We explicitly state that this precompile **IS NOT REQUIRED** to perform all the operations using constant time algorithms. ## Copyright + Copyright and related rights waived via [CC0](../LICENSE.md).