0
# py-ecc
1
2
A comprehensive elliptic curve cryptography library for Python that implements multiple elliptic curve algorithms including secp256k1 (used in Bitcoin), alt_bn128/bn128 (used in Ethereum), and bls12_381 (used in Ethereum 2.0). The library provides both reference implementations and optimized versions of cryptographic operations, making it essential for blockchain and cryptocurrency applications.
3
4
## Package Information
5
6
- **Package Name**: py-ecc
7
- **Language**: Python
8
- **Installation**: `pip install py_ecc`
9
10
## Core Imports
11
12
```python
13
import py_ecc
14
```
15
16
Common imports for specific functionality:
17
18
```python
19
# BLS signatures
20
from py_ecc.bls import G2Basic, G2MessageAugmentation, G2ProofOfPossession
21
22
# secp256k1 operations
23
from py_ecc.secp256k1 import privtopub, ecdsa_raw_sign, ecdsa_raw_recover
24
25
# BLS12-381 curve operations
26
from py_ecc.bls12_381 import G1, G2, multiply, pairing
27
28
# Optimized implementations
29
from py_ecc.optimized_bls12_381 import pairing as fast_pairing
30
```
31
32
## Basic Usage
33
34
```python
35
import py_ecc
36
from py_ecc.bls import G2Basic
37
from py_ecc.secp256k1 import privtopub, ecdsa_raw_sign
38
39
# BLS signature example
40
private_key = 42
41
message = b"Hello, world!"
42
43
# Generate public key and sign message
44
public_key = G2Basic.SkToPk(private_key)
45
signature = G2Basic.Sign(private_key, message)
46
47
# Verify signature
48
is_valid = G2Basic.Verify(public_key, message, signature)
49
print(f"Signature valid: {is_valid}")
50
51
# secp256k1 example
52
secp_privkey = b'\x79\x2e\xca\x68\x2b\x89\x0b\x31\x35\x62\x47\xf2\xb0\x46\x62\xbf\xf4\x48\xb6\xbb\x19\xea\x1c\x8a\xb4\x8d\xa2\x22\xc8\x94\xef\x9b'
53
secp_pubkey = privtopub(secp_privkey)
54
v, r, s = ecdsa_raw_sign(b'\x35' * 32, secp_privkey)
55
```
56
57
## Architecture
58
59
py-ecc is organized around different elliptic curves and their implementations:
60
61
- **Curve Modules**: Each curve (secp256k1, bn128, bls12_381) has its own module with curve-specific operations
62
- **Field Arithmetic**: Underlying finite field operations supporting all curves
63
- **BLS Signatures**: High-level BLS signature schemes built on top of BLS12-381
64
- **Optimization Layers**: Both reference and optimized implementations for performance-critical operations
65
66
The library provides both educational reference implementations and production-ready optimized versions, allowing developers to choose between clarity and performance based on their needs.
67
68
## Capabilities
69
70
### BLS Signature Schemes
71
72
High-level BLS signature schemes according to IETF standards, providing digital signatures with aggregation capabilities for blockchain applications.
73
74
```python { .api }
75
class G2Basic:
76
@staticmethod
77
def SkToPk(sk: int) -> bytes: ...
78
@staticmethod
79
def KeyValidate(pk: bytes) -> bool: ...
80
@staticmethod
81
def Sign(sk: int, message: bytes) -> bytes: ...
82
@staticmethod
83
def Verify(pk: bytes, message: bytes, signature: bytes) -> bool: ...
84
@staticmethod
85
def Aggregate(signatures: Sequence[bytes]) -> bytes: ...
86
@staticmethod
87
def AggregateVerify(pks: Sequence[bytes], messages: Sequence[bytes], signature: bytes) -> bool: ...
88
@staticmethod
89
def FastAggregateVerify(pks: Sequence[bytes], message: bytes, signature: bytes) -> bool: ...
90
```
91
92
[BLS Signatures](./bls-signatures.md)
93
94
### secp256k1 Operations
95
96
Bitcoin's elliptic curve operations including key generation, ECDSA signing, and signature recovery.
97
98
```python { .api }
99
def privtopub(privkey: bytes) -> Tuple[int, int]: ...
100
def ecdsa_raw_sign(msghash: bytes, priv: bytes) -> Tuple[int, int, int]: ...
101
def ecdsa_raw_recover(msghash: bytes, vrs: Tuple[int, int, int]) -> Tuple[int, int]: ...
102
def multiply(a: Tuple[int, int], n: int) -> Tuple[int, int]: ...
103
def add(a: Tuple[int, int], b: Tuple[int, int]) -> Tuple[int, int]: ...
104
```
105
106
[secp256k1](./secp256k1.md)
107
108
### BLS12-381 Curve Operations
109
110
Reference implementation of BLS12-381 elliptic curve operations including point arithmetic and bilinear pairings.
111
112
```python { .api }
113
def multiply(p, n): ...
114
def add(p1, p2): ...
115
def pairing(p1, p2): ...
116
def is_on_curve(p) -> bool: ...
117
def final_exponentiate(p): ...
118
```
119
120
[BLS12-381 Curve](./bls12-381.md)
121
122
### BN128 Curve Operations
123
124
Reference implementation of BN128 (alt_bn128) elliptic curve operations used in Ethereum's precompiled contracts.
125
126
```python { .api }
127
def multiply(p, n): ...
128
def add(p1, p2): ...
129
def pairing(p1, p2): ...
130
def is_on_curve(p) -> bool: ...
131
def final_exponentiate(p): ...
132
```
133
134
[BN128 Curve](./bn128.md)
135
136
### Optimized Implementations
137
138
High-performance versions of BLS12-381 and BN128 operations with additional specialized functions for production use.
139
140
```python { .api }
141
# Optimized BLS12-381
142
def pairing(p1, p2): ...
143
def multiply_clear_cofactor_G1(p): ...
144
def multiply_clear_cofactor_G2(p): ...
145
def optimized_swu_G1(t): ...
146
def optimized_swu_G2(t): ...
147
```
148
149
[Optimized Operations](./optimized.md)
150
151
### Field Arithmetic
152
153
Finite field arithmetic supporting all implemented curves with both basic and extension field operations.
154
155
```python { .api }
156
class FQ:
157
def __init__(self, val: int): ...
158
def __add__(self, other): ...
159
def __mul__(self, other): ...
160
def __pow__(self, other): ...
161
162
class FQ2:
163
def __init__(self, coeffs: Sequence): ...
164
165
class FQ12:
166
def __init__(self, coeffs: Sequence): ...
167
```
168
169
[Field Arithmetic](./fields.md)
170
171
## Types
172
173
```python { .api }
174
from typing import Tuple, Optional, Sequence
175
176
# Point representations
177
PlainPoint2D = Tuple[int, int]
178
PlainPoint3D = Tuple[int, int, int]
179
180
# Generic field element types
181
Point2D = Optional[Tuple[Field, Field]]
182
Point3D = Optional[Tuple[Field, Field, Field]]
183
184
# BLS types (from eth-typing)
185
BLSPubkey = bytes
186
BLSSignature = bytes
187
```