{"id":4696,"library":"py-ecc","title":"py-ecc","description":"py-ecc is a pure-Python library for elliptic curve cryptography, offering implementations for curves like secp256k1 (used in Bitcoin and Ethereum), alt_bn128, and bls12_381. Currently at version 8.0.0, the library is actively maintained with releases tied to evolving cryptographic standards, especially for BLS.","status":"active","version":"8.0.0","language":"en","source_language":"en","source_url":"https://github.com/ethereum/py_ecc","tags":["cryptography","elliptic-curve","ethereum","bls","secp256k1","alt_bn128","bls12_381","signing","verification"],"install":[{"cmd":"pip install py-ecc","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides cryptographic hashing functionalities, often including Keccak-256 which is critical for Ethereum-related operations.","package":"eth-hash","optional":false}],"imports":[{"note":"Common functions for secp256k1 curve operations.","symbol":"secp256k1 functions","correct":"from py_ecc.secp256k1 import privtopub, ecsign, ecrecover, N"},{"note":"Functions for the basic BLS signature scheme (check documentation for specific IETF draft version).","symbol":"bls_basic_scheme","correct":"from py_ecc.bls.basic_scheme import KeyGen, Sign, Verify"},{"note":"Functions for BN128 curve operations, commonly used for SNARKs and pairing-based cryptography.","symbol":"bn128 functions","correct":"from py_ecc.bn128 import G1, G2, multiply, add, pairing"}],"quickstart":{"code":"import os\nfrom py_ecc.secp256k1 import privtopub, ecsign, ecrecover, N\n\n# 1. Generate a private key\n# In a real application, use a cryptographically secure random source (e.g., from a KDF or secure RNG)\nprivkey = int(os.urandom(32).hex(), 16) % N\nprint(f\"Private Key: {hex(privkey)}\")\n\n# 2. Derive the public key\npubkey = privtopub(privkey)\nprint(f\"Public Key (uncompressed, X, Y tuple): {pubkey}\")\n\n# 3. Create a message hash (must be 32 bytes)\nmsg_hash = int.from_bytes(os.urandom(32), 'big')\nprint(f\"Message Hash: {hex(msg_hash)}\")\n\n# 4. Sign the message\nv, r, s = ecsign(msg_hash, privkey)\nprint(f\"Signature: v={v}, r={hex(r)}, s={hex(s)}\")\n\n# 5. Recover the public key from the signature\nrecovered_pubkey = ecrecover(msg_hash, v, r, s)\nprint(f\"Recovered Public Key: {recovered_pubkey}\")\n\n# 6. Verify the signature\nassert recovered_pubkey == pubkey, \"Signature verification failed!\"\nprint(\"Signature verification successful!\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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).","severity":"breaking","affected_versions":">=3.0.0"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All BLS-enabled versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}