{"id":14958556,"url":"https://github.com/ethereum/eth-keys","last_synced_at":"2025-05-14T21:04:35.364Z","repository":{"id":41812213,"uuid":"104133488","full_name":"ethereum/eth-keys","owner":"ethereum","description":"A common API for Ethereum key operations.","archived":false,"fork":false,"pushed_at":"2025-04-03T21:56:35.000Z","size":486,"stargazers_count":164,"open_issues_count":7,"forks_count":67,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-06T13:06:19.282Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ethereum.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-19T21:58:38.000Z","updated_at":"2025-04-03T21:56:40.000Z","dependencies_parsed_at":"2024-06-18T13:33:50.046Z","dependency_job_id":"03c6de1f-4bfa-47d0-877c-71d89e93da75","html_url":"https://github.com/ethereum/eth-keys","commit_stats":{"total_commits":345,"total_committers":22,"mean_commits":"15.681818181818182","dds":0.7275362318840579,"last_synced_commit":"1cbc4ff4f6f5b06a63f268003f4a219bf8657575"},"previous_names":["ethereum/ethereum-keys"],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum%2Feth-keys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum%2Feth-keys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum%2Feth-keys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ethereum%2Feth-keys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ethereum","download_url":"https://codeload.github.com/ethereum/eth-keys/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248741206,"owners_count":21154255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T13:17:22.640Z","updated_at":"2025-04-13T16:07:45.608Z","avatar_url":"https://github.com/ethereum.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# eth-keys\n\n[![Join the conversation on Discord](https://img.shields.io/discord/809793915578089484?color=blue\u0026label=chat\u0026logo=discord\u0026logoColor=white)](https://discord.gg/GHryRvPB84)\n[![Build Status](https://circleci.com/gh/ethereum/eth-keys.svg?style=shield)](https://circleci.com/gh/ethereum/eth-keys)\n[![PyPI version](https://badge.fury.io/py/eth-keys.svg)](https://badge.fury.io/py/eth-keys)\n[![Python versions](https://img.shields.io/pypi/pyversions/eth-keys.svg)](https://pypi.python.org/pypi/eth-keys)\n\nCommon API for Ethereum key operations\n\n\u003e This library and repository was previously located at https://github.com/pipermerriam/ethereum-keys.  It was transferred to the Ethereum foundation github in November 2017 and renamed to `eth-keys`.  The PyPi package was also renamed from `ethereum-keys` to `eth-keys`.\n\nRead more in the documentation below. [View the change log](https://github.com/ethereum/eth-keys/blob/main/CHANGELOG.rst).\n\n## Installation\n\n```sh\npython -m pip install eth-keys\n```\n\n```python\n\u003e\u003e\u003e from eth_keys import keys\n\u003e\u003e\u003e pk = keys.PrivateKey(b'\\x01' * 32)\n\u003e\u003e\u003e signature = pk.sign_msg(b'a message')\n\u003e\u003e\u003e pk\n'0x0101010101010101010101010101010101010101010101010101010101010101'\n\u003e\u003e\u003e pk.public_key\n'0x1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1'\n\u003e\u003e\u003e signature\n'0xccda990dba7864b79dc49158fea269338a1cf5747bc4c4bf1b96823e31a0997e7d1e65c06c5bf128b7109e1b4b9ba8d1305dc33f32f624695b2fa8e02c12c1e000'\n\u003e\u003e\u003e pk.public_key.to_checksum_address()\n'0x1a642f0E3c3aF545E7AcBD38b07251B3990914F1'\n\u003e\u003e\u003e signature.verify_msg(b'a message', pk.public_key)\nTrue\n\u003e\u003e\u003e signature.recover_public_key_from_msg(b'a message') == pk.public_key\nTrue\n```\n\n## Documentation\n\n### `KeyAPI(backend=None)`\n\nThe `KeyAPI` object is the primary API for interacting with the `eth-keys`\nlibary.  The object takes a single optional argument in its constructor which\ndesignates what backend will be used for eliptical curve cryptography\noperations.  The built-in backends are:\n\n- `eth_keys.backends.NativeECCBackend`: A pure python implementation of the ECC operations.\n- `eth_keys.backends.CoinCurveECCBackend`: Uses the [`coincurve`](https://github.com/ofek/coincurve) library for ECC operations.\n\nBy default, `eth-keys` will *try* to use the `CoinCurveECCBackend`,\nfalling back to the `NativeECCBackend` if the `coincurve` library is not\navailable.\n\n\u003e Note: The `coincurve` library is not automatically installed with `eth-keys` and must be installed separately.\n\nThe `backend` argument can be given in any of the following forms.\n\n- Instance of the backend class\n- The backend class\n- String with the dot-separated import path for the backend class.\n\n```python\n\u003e\u003e\u003e from eth_keys import KeyAPI\n\u003e\u003e\u003e from eth_keys.backends import NativeECCBackend\n# These are all the same\n\u003e\u003e\u003e keys = KeyAPI(NativeECCBackend)\n\u003e\u003e\u003e keys = KeyAPI(NativeECCBackend())\n\u003e\u003e\u003e keys = KeyAPI('eth_keys.backends.NativeECCBackend')\n# Or for the coincurve base backend\n\u003e\u003e\u003e keys = KeyAPI('eth_keys.backends.CoinCurveECCBackend')\n```\n\nThe backend can also be configured using the environment variable\n`ECC_BACKEND_CLASS` which should be set to the dot-separated python import path\nto the desired backend.\n\n```python\n\u003e\u003e\u003e import os\n\u003e\u003e\u003e os.environ['ECC_BACKEND_CLASS'] = 'eth_keys.backends.CoinCurveECCBackend'\n```\n\n### `KeyAPI.ecdsa_sign(message_hash, private_key) -\u003e Signature`\n\nThis method returns a signature for the given `message_hash`, signed by the\nprovided `private_key`.\n\n- `message_hash`: **must** be a byte string of length 32\n- `private_key`: **must** be an instance of `PrivateKey`\n\n### `KeyAPI.ecdsa_verify(message_hash, signature, public_key) -\u003e bool`\n\nReturns `True` or `False` based on whether the provided `signature` is a valid\nsignature for the provided `message_hash` and `public_key`.\n\n- `message_hash`: **must** be a byte string of length 32\n- `signature`: **must** be an instance of `Signature`\n- `public_key`: **must** be an instance of `PublicKey`\n\n### `KeyAPI.ecdsa_recover(message_hash, signature) -\u003e PublicKey`\n\nReturns the `PublicKey` instances recovered from the given `signature` and\n`message_hash`.\n\n- `message_hash`: **must** be a byte string of length 32\n- `signature`: **must** be an instance of `Signature`\n\n### `KeyAPI.private_key_to_public_key(private_key) -\u003e PublicKey`\n\nReturns the `PublicKey` instances computed from the given `private_key`\ninstance.\n\n- `private_key`: **must** be an instance of `PublicKey`\n\n### Common APIs for `PublicKey`, `PrivateKey` and `Signature`\n\nThere is a common API for the following objects.\n\n- `PublicKey`\n- `PrivateKey`\n- `Signature`\n\nEach of these objects has all of the following APIs.\n\n- `obj.to_bytes()`: Returns the object in it's canonical `bytes` serialization.\n- `obj.to_hex()`: Returns a text string of the hex encoded canonical representation.\n\n### `KeyAPI.PublicKey(public_key_bytes)`\n\nThe `PublicKey` class takes a single argument which must be a bytes string with length 64.\n\n\u003e Note that there are two other common formats for public keys: 65 bytes with a leading `\\x04` byte\n\u003e and 33 bytes starting with either `\\x02` or `\\x03`. To use the former with the `PublicKey` object,\n\u003e remove the first byte. For the latter, refer to `PublicKey.from_compressed_bytes`.\n\nThe following methods are available:\n\n#### `PublicKey.from_compressed_bytes(compressed_bytes) -\u003e PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from its compressed representation.\n\n- `compressed_bytes` **must** be a byte string of length 33 starting with `\\x02` or `\\x03`.\n\n#### `PublicKey.from_private(private_key) -\u003e PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from the\ngiven `private_key`.\n\n- `private_key` may either be a byte string of length 32 or an instance of the `KeyAPI.PrivateKey` class.\n\n#### `PublicKey.recover_from_msg(message, signature) -\u003e PublicKey`\n\nThis `classmethod` returns a new `PublicKey` instance computed from the\nprovided `message` and `signature`.\n\n- `message` **must** be a byte string\n- `signature` **must** be an instance of `KeyAPI.Signature`\n\n#### `PublicKey.recover_from_msg_hash(message_hash, signature) -\u003e PublicKey`\n\nSame as `PublicKey.recover_from_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n#### `PublicKey.verify_msg(message, signature) -\u003e bool`\n\nThis method returns `True` or `False` based on whether the signature is a valid\nfor the given message.\n\n#### `PublicKey.verify_msg_hash(message_hash, signature) -\u003e bool`\n\nSame as `PublicKey.verify_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n#### `PublicKey.to_compressed_bytes() -\u003e bytes`\n\nReturns the compressed representation of this public key.\n\n#### `PublicKey.to_address() -\u003e text`\n\nReturns the hex encoded ethereum address for this public key.\n\n#### `PublicKey.to_checksum_address() -\u003e text`\n\nReturns the ERC55 checksum formatted ethereum address for this public key.\n\n#### `PublicKey.to_canonical_address() -\u003e bytes`\n\nReturns the 20-byte representation of the ethereum address for this public key.\n\n### `KeyAPI.PrivateKey(private_key_bytes)`\n\nThe `PrivateKey` class takes a single argument which must be a bytes string with length 32.\n\nThe following methods and properties are available\n\n#### `PrivateKey.public_key`\n\nThis *property* holds the `PublicKey` instance coresponding to this private key.\n\n#### `PrivateKey.sign_msg(message) -\u003e Signature`\n\nThis method returns a signature for the given `message` in the form of a\n`Signature` instance\n\n- `message` **must** be a byte string.\n\n#### `PrivateKey.sign_msg_hash(message_hash) -\u003e Signature`\n\nSame as `PrivateKey.sign` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n### `KeyAPI.Signature(signature_bytes=None, vrs=None)`\n\nThe `Signature` class can be instantiated in one of two ways.\n\n- `signature_bytes`: a bytes string with length 65.\n- `vrs`: a 3-tuple composed of the integers `v`, `r`, and `s`.\n\n\u003e Note: If using the `signature_bytes` to instantiate, the byte string should be encoded as `r_bytes | s_bytes | v_bytes` where `|` represents concatenation.  `r_bytes` and `s_bytes` should be 32 bytes in length.  `v_bytes` should be a single byte `\\x00` or `\\x01`.\n\nSignatures are expected to use `1` or `0` for their `v` value.\n\nThe following methods and properties are available\n\n#### `Signature.v`\n\nThis property returns the `v` value from the signature as an integer.\n\n#### `Signature.r`\n\nThis property returns the `r` value from the signature as an integer.\n\n#### `Signature.s`\n\nThis property returns the `s` value from the signature as an integer.\n\n#### `Signature.vrs`\n\nThis property returns a 3-tuple of `(v, r, s)`.\n\n#### `Signature.verify_msg(message, public_key) -\u003e bool`\n\nThis method returns `True` or `False` based on whether the signature is a valid\nfor the given public key.\n\n- `message`: **must** be a byte string.\n- `public_key`: **must** be an instance of `PublicKey`\n\n#### `Signature.verify_msg_hash(message_hash, public_key) -\u003e bool`\n\nSame as `Signature.verify_msg` except that `message_hash` should be the Keccak\nhash of the `message`.\n\n#### `Signature.recover_public_key_from_msg(message) -\u003e PublicKey`\n\nThis method returns a `PublicKey` instance recovered from the signature.\n\n- `message`: **must** be a byte string.\n\n#### `Signature.recover_public_key_from_msg_hash(message_hash) -\u003e PublicKey`\n\nSame as `Signature.recover_public_key_from_msg` except that `message_hash`\nshould be the Keccak hash of the `message`.\n\n### Exceptions\n\n#### `eth_api.exceptions.ValidationError`\n\nThis error is raised during instantaition of any of the `PublicKey`,\n`PrivateKey` or `Signature` classes if their constructor parameters are\ninvalid.\n\n#### `eth_api.exceptions.BadSignature`\n\nThis error is raised from any of the `recover` or `verify` methods involving\nsignatures if the signature is invalid.\n\n## Developer Setup\n\nIf you would like to hack on eth-keys, please check out the [Snake Charmers\nTactical Manual](https://github.com/ethereum/snake-charmers-tactical-manual)\nfor information on how we do:\n\n- Testing\n- Pull Requests\n- Documentation\n\nWe use [pre-commit](https://pre-commit.com/) to maintain consistent code style. Once\ninstalled, it will run automatically with every commit. You can also run it manually\nwith `make lint`. If you need to make a commit that skips the `pre-commit` checks, you\ncan do so with `git commit --no-verify`.\n\n### Development Environment Setup\n\nYou can set up your dev environment with:\n\n```sh\ngit clone git@github.com:ethereum/eth-keys.git\ncd eth-keys\nvirtualenv -p python3 venv\n. venv/bin/activate\npython -m pip install -e \".[dev]\"\npre-commit install\n```\n\n### Release setup\n\nTo release a new version:\n\n```sh\nmake release bump=$$VERSION_PART_TO_BUMP$$\n```\n\n#### How to bumpversion\n\nThe version format for this repo is `{major}.{minor}.{patch}` for stable, and\n`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).\n\nTo issue the next version in line, specify which part to bump,\nlike `make release bump=minor` or `make release bump=devnum`. This is typically done from the\nmain branch, except when releasing a beta (in which case the beta is released from main,\nand the previous stable branch is released from said branch).\n\nIf you are in a beta version, `make release bump=stage` will switch to a stable.\n\nTo issue an unstable version when the current version is stable, specify the\nnew version explicitly, like `make release bump=\"--new-version 4.0.0-alpha.1 devnum\"`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereum%2Feth-keys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethereum%2Feth-keys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethereum%2Feth-keys/lists"}