0
# BLS12-381 Curve
1
2
Reference implementation of BLS12-381 elliptic curve operations including point arithmetic and bilinear pairings. This curve is used in Ethereum 2.0 and other modern blockchain applications for its security properties and efficient pairing operations.
3
4
## Constants and Generator Points
5
6
```python { .api }
7
# Generator points
8
G1 # Generator point on G1 (base curve)
9
G2 # Generator point on G2 (twist curve)
10
G12 # Identity element in GT (target group)
11
12
# Points at infinity
13
Z1 # Point at infinity for G1
14
Z2 # Point at infinity for G2
15
16
# Curve parameters
17
b: int # Curve coefficient for G1: y^2 = x^3 + b
18
b2 # Curve coefficient for G2 (quadratic extension)
19
b12 # Curve coefficient for G12 (degree 12 extension)
20
curve_order: int # Order of the curve
21
field_modulus: int # Prime modulus of the base field
22
twist # Twist parameter for G2
23
```
24
25
## Capabilities
26
27
### Point Arithmetic
28
29
Basic elliptic curve point operations for both G1 and G2 groups.
30
31
```python { .api }
32
def add(p1, p2):
33
"""
34
Add two elliptic curve points.
35
36
Args:
37
p1: First point (G1 or G2)
38
p2: Second point (G1 or G2, same type as p1)
39
40
Returns:
41
Point of same type as inputs representing p1 + p2
42
"""
43
44
def double(p):
45
"""
46
Double an elliptic curve point.
47
48
Args:
49
p: Point to double (G1 or G2)
50
51
Returns:
52
Point of same type representing 2 * p
53
"""
54
55
def multiply(p, n):
56
"""
57
Multiply a point by a scalar.
58
59
Args:
60
p: Point to multiply (G1 or G2)
61
n (int): Scalar multiplier
62
63
Returns:
64
Point of same type representing n * p
65
"""
66
67
def neg(p):
68
"""
69
Negate a point.
70
71
Args:
72
p: Point to negate (G1 or G2)
73
74
Returns:
75
Point of same type representing -p
76
"""
77
```
78
79
### Point Properties and Validation
80
81
Functions to check point properties and validate curve membership.
82
83
```python { .api }
84
def eq(p1, p2) -> bool:
85
"""
86
Test if two points are equal.
87
88
Args:
89
p1: First point
90
p2: Second point
91
92
Returns:
93
bool: True if points are equal, False otherwise
94
"""
95
96
def is_inf(p) -> bool:
97
"""
98
Check if a point is the point at infinity.
99
100
Args:
101
p: Point to check
102
103
Returns:
104
bool: True if point is at infinity, False otherwise
105
"""
106
107
def is_on_curve(p) -> bool:
108
"""
109
Verify that a point lies on the curve.
110
111
Args:
112
p: Point to validate
113
114
Returns:
115
bool: True if point is on curve, False otherwise
116
"""
117
```
118
119
### Bilinear Pairing Operations
120
121
Pairing functions that map pairs of points to elements in the target group GT.
122
123
```python { .api }
124
def pairing(p1, p2):
125
"""
126
Compute the bilinear pairing e(p1, p2).
127
128
Args:
129
p1: Point in G1
130
p2: Point in G2
131
132
Returns:
133
Element in GT (degree 12 extension field)
134
"""
135
136
def final_exponentiate(p):
137
"""
138
Perform the final exponentiation step of pairing computation.
139
140
Args:
141
p: Element from the Miller loop computation
142
143
Returns:
144
Final pairing result in GT
145
"""
146
```
147
148
## Field Elements
149
150
The BLS12-381 curve operations work with various field elements:
151
152
```python { .api }
153
# Field element types (imported from py_ecc.fields)
154
FQ # Base field element (Fp)
155
FQ2 # Quadratic extension field element (Fp2)
156
FQ12 # Degree 12 extension field element (Fp12, target group GT)
157
FQP # General polynomial field element
158
```
159
160
## Usage Examples
161
162
### Basic Point Operations
163
164
```python
165
from py_ecc.bls12_381 import G1, G2, multiply, add, is_on_curve
166
167
# Scalar multiplication
168
point1 = multiply(G1, 123)
169
point2 = multiply(G1, 456)
170
171
# Point addition
172
sum_point = add(point1, point2)
173
174
# Verify points are on curve
175
assert is_on_curve(point1)
176
assert is_on_curve(point2)
177
assert is_on_curve(sum_point)
178
179
# This should equal (123 + 456) * G1
180
expected = multiply(G1, 123 + 456)
181
assert eq(sum_point, expected)
182
```
183
184
### Pairing Computation
185
186
```python
187
from py_ecc.bls12_381 import G1, G2, multiply, pairing
188
189
# Create some points
190
p1 = multiply(G1, 123)
191
q1 = multiply(G2, 456)
192
p2 = multiply(G1, 789)
193
q2 = multiply(G2, 321)
194
195
# Compute pairings
196
pairing1 = pairing(p1, q1)
197
pairing2 = pairing(p2, q2)
198
199
# Pairing is bilinear: e(a*P, Q) = e(P, a*Q) = e(P, Q)^a
200
a = 42
201
pa_q = pairing(multiply(p1, a), q1)
202
p_aq = pairing(p1, multiply(q1, a))
203
p_q_a = pairing1 ** a
204
205
# All should be equal (up to field arithmetic precision)
206
print("Bilinearity verified")
207
```
208
209
### Multi-Pairing (Product of Pairings)
210
211
```python
212
from py_ecc.bls12_381 import G1, G2, multiply, pairing
213
from py_ecc.fields import bls12_381_FQ12 as FQ12
214
215
# Multiple pairing computation
216
points_g1 = [multiply(G1, i) for i in [1, 2, 3]]
217
points_g2 = [multiply(G2, i) for i in [4, 5, 6]]
218
219
# Compute individual pairings
220
pairings = [pairing(p1, p2) for p1, p2 in zip(points_g1, points_g2)]
221
222
# Product of pairings
223
result = FQ12.one()
224
for p in pairings:
225
result = result * p
226
227
print(f"Multi-pairing result computed")
228
```
229
230
### Point Validation
231
232
```python
233
from py_ecc.bls12_381 import G1, G2, is_on_curve, is_inf, multiply
234
from py_ecc.fields import bls12_381_FQ as FQ
235
236
# Validate generator points
237
assert is_on_curve(G1)
238
assert is_on_curve(G2)
239
assert not is_inf(G1)
240
assert not is_inf(G2)
241
242
# Create and validate random points
243
random_point = multiply(G1, 12345)
244
assert is_on_curve(random_point)
245
assert not is_inf(random_point)
246
247
# Check point at infinity
248
zero_point = multiply(G1, 0) # Should be point at infinity
249
assert is_inf(zero_point)
250
251
print("Point validation complete")
252
```
253
254
### Custom Field Operations
255
256
```python
257
from py_ecc.fields import bls12_381_FQ as FQ, bls12_381_FQ2 as FQ2
258
259
# Work with field elements directly
260
a = FQ(123)
261
b = FQ(456)
262
c = a + b
263
d = a * b
264
e = a ** 3
265
266
# Quadratic extension field
267
f = FQ2([1, 2]) # 1 + 2*i where i^2 = -1
268
g = FQ2([3, 4]) # 3 + 4*i
269
h = f * g
270
271
print(f"Field arithmetic results: {c}, {d}, {e}")
272
print(f"Extension field result: {h}")
273
```
274
275
## Types
276
277
```python { .api }
278
from typing import Optional, Tuple
279
from py_ecc.fields import bls12_381_FQ, bls12_381_FQ2
280
281
# Point types (None represents point at infinity)
282
Point2D = Optional[Tuple[bls12_381_FQ, bls12_381_FQ]]
283
Point2D_FQ2 = Optional[Tuple[bls12_381_FQ2, bls12_381_FQ2]] # For G2 points
284
285
# Field element types
286
Field = bls12_381_FQ
287
ExtensionField2 = bls12_381_FQ2
288
ExtensionField12 = bls12_381_FQ12
289
```
290
291
## Error Handling
292
293
BLS12-381 operations may raise various exceptions:
294
295
- Field arithmetic errors for invalid operations
296
- Curve validation errors for points not on the curve
297
- Pairing computation errors for invalid inputs
298
299
```python
300
from py_ecc.bls12_381 import is_on_curve, pairing, multiply, G1, G2
301
302
try:
303
# Validate points before pairing
304
p1 = multiply(G1, some_scalar)
305
p2 = multiply(G2, some_other_scalar)
306
307
if is_on_curve(p1) and is_on_curve(p2):
308
result = pairing(p1, p2)
309
else:
310
raise ValueError("Invalid curve points")
311
312
except Exception as e:
313
print(f"Curve operation error: {e}")
314
```