py-ecc

Warnings

• breaking BLS (Boneh-Lynn-Shacham) signature scheme implementations have undergone significant breaking changes across major versions (e.g., v3.0.0, v5.0.0). These changes reflect updates to IETF BLS drafts (e.g., v2, draft 04).
  Fix: Review the specific IETF BLS draft version implemented in your `py-ecc` version. Existing BLS keys or signatures from older versions may be incompatible. Migrate data or adapt code to the new specification, particularly for hash-to-curve functions and signature aggregation.
• gotcha The `v` (recovery identifier) value returned by `py_ecc.secp256k1.ecsign` is strictly 0 or 1. This differs from Ethereum's typical `v` values (27 or 28, or Chain ID-dependent 35/36+Chain ID), which are often used in transactions.
  Fix: When interfacing with other libraries or blockchain protocols, be aware that you might need to convert `py-ecc`'s `v` (0 or 1) to the expected format, e.g., by adding 27, or handling chain_id logic, before broadcasting. Conversely, `ecrecover` expects `v` to be in `(0, 1)` range, not `(27, 28)`.
• gotcha BLS hash-to-curve functions are highly sensitive to the exact IETF draft specification. Using a function from one version with data generated by another can lead to silent failures or invalid results due to differing parameters or algorithms.
  Fix: Always ensure consistency between the `py-ecc` BLS implementation version and the specification used by the counterparty system. Consult the `py-ecc` source or documentation for the precise BLS draft version supported by your installed library version.

Install

• pip install py-ecc Install stable version

Imports

• secp256k1 functions

  from py_ecc.secp256k1 import privtopub, ecsign, ecrecover, N

  Common functions for secp256k1 curve operations.
• bls_basic_scheme

  from py_ecc.bls.basic_scheme import KeyGen, Sign, Verify

  Functions for the basic BLS signature scheme (check documentation for specific IETF draft version).
• bn128 functions

  from py_ecc.bn128 import G1, G2, multiply, add, pairing

  Functions for BN128 curve operations, commonly used for SNARKs and pairing-based cryptography.

Quickstart

This quickstart demonstrates how to generate a secp256k1 private key, derive its public key, sign a message hash, and then verify the signature by recovering the public key.

import os
from py_ecc.secp256k1 import privtopub, ecsign, ecrecover, N

# 1. Generate a private key
# In a real application, use a cryptographically secure random source (e.g., from a KDF or secure RNG)
privkey = int(os.urandom(32).hex(), 16) % N
print(f"Private Key: {hex(privkey)}")

# 2. Derive the public key
pubkey = privtopub(privkey)
print(f"Public Key (uncompressed, X, Y tuple): {pubkey}")

# 3. Create a message hash (must be 32 bytes)
msg_hash = int.from_bytes(os.urandom(32), 'big')
print(f"Message Hash: {hex(msg_hash)}")

# 4. Sign the message
v, r, s = ecsign(msg_hash, privkey)
print(f"Signature: v={v}, r={hex(r)}, s={hex(s)}")

# 5. Recover the public key from the signature
recovered_pubkey = ecrecover(msg_hash, v, r, s)
print(f"Recovered Public Key: {recovered_pubkey}")

# 6. Verify the signature
assert recovered_pubkey == pubkey, "Signature verification failed!"
print("Signature verification successful!")