Package: eth-keys
eth-keysCommon API for Ethereum key operationsThis library and repository was previously located athttps://github.com/pipermerriam/ethereum-keys.  It was transferred to the Ethereum foundation github in November 2017 and renamed toeth-keys.  The PyPi package was also renamed fromethereum-keystoeth-keys.Read more in the documentation below.View the change log.Quickstartpython-mpipinstalleth-keys>>>frometh_keysimportkeys>>>pk=keys.PrivateKey(b'\x01'*32)>>>signature=pk.sign_msg(b'a message')>>>pk'0x0101010101010101010101010101010101010101010101010101010101010101'>>>pk.public_key'0x1b84c5567b126440995d3ed5aaba0565d71e1834604819ff9c17f5e9d5dd078f70beaf8f588b541507fed6a642c5ab42dfdf8120a7f639de5122d47a69a8e8d1'>>>signature'0xccda990dba7864b79dc49158fea269338a1cf5747bc4c4bf1b96823e31a0997e7d1e65c06c5bf128b7109e1b4b9ba8d1305dc33f32f624695b2fa8e02c12c1e000'>>>pk.public_key.to_checksum_address()'0x1a642f0E3c3aF545E7AcBD38b07251B3990914F1'>>>signature.verify_msg(b'a message',pk.public_key)True>>>signature.recover_public_key_from_msg(b'a message')==pk.public_keyTrueDocumentationKeyAPI(backend=None)TheKeyAPIobject is the primary API for interacting with theeth-keyslibary.  The object takes a single optional argument in its constructor which
designates what backend will be used for eliptical curve cryptography
operations.  The built-in backends are:eth_keys.backends.NativeECCBackend: A pure python implementation of the ECC operations.eth_keys.backends.CoinCurveECCBackend: Uses thecoincurvelibrary for ECC operations.By default,eth-keyswilltryto use theCoinCurveECCBackend,
falling back to theNativeECCBackendif thecoincurvelibrary is not
available.Note: Thecoincurvelibrary is not automatically installed witheth-keysand must be installed separately.Thebackendargument can be given in any of the following forms.Instance of the backend classThe backend classString with the dot-separated import path for the backend class.>>>frometh_keysimportKeyAPI>>>frometh_keys.backendsimportNativeECCBackend# These are all the same>>>keys=KeyAPI(NativeECCBackend)>>>keys=KeyAPI(NativeECCBackend())>>>keys=KeyAPI('eth_keys.backends.NativeECCBackend')# Or for the coincurve base backend>>>keys=KeyAPI('eth_keys.backends.CoinCurveECCBackend')The backend can also be configured using the environment variableECC_BACKEND_CLASSwhich should be set to the dot-separated python import path
to the desired backend.>>>importos>>>os.environ['ECC_BACKEND_CLASS']='eth_keys.backends.CoinCurveECCBackend'KeyAPI.ecdsa_sign(message_hash, private_key) -> SignatureThis method returns a signature for the givenmessage_hash, signed by the
providedprivate_key.message_hash:mustbe a byte string of length 32private_key:mustbe an instance ofPrivateKeyKeyAPI.ecdsa_verify(message_hash, signature, public_key) -> boolReturnsTrueorFalsebased on whether the providedsignatureis a valid
signature for the providedmessage_hashandpublic_key.message_hash:mustbe a byte string of length 32signature:mustbe an instance ofSignaturepublic_key:mustbe an instance ofPublicKeyKeyAPI.ecdsa_recover(message_hash, signature) -> PublicKeyReturns thePublicKeyinstances recovered from the givensignatureandmessage_hash.message_hash:mustbe a byte string of length 32signature:mustbe an instance ofSignatureKeyAPI.private_key_to_public_key(private_key) -> PublicKeyReturns thePublicKeyinstances computed from the givenprivate_keyinstance.private_key:mustbe an instance ofPublicKeyCommon APIs forPublicKey,PrivateKeyandSignatureThere is a common API for the following objects.PublicKeyPrivateKeySignatureEach of these objects has all of the following APIs.obj.to_bytes(): Returns the object in it's canonicalbytesserialization.obj.to_hex(): Returns a text string of the hex encoded canonical representation.KeyAPI.PublicKey(public_key_bytes)ThePublicKeyclass takes a single argument which must be a bytes string with length 64.Note that there are two other common formats for public keys: 65 bytes with a leading\x04byte
and 33 bytes starting with either\x02or\x03. To use the former with thePublicKeyobject,
remove the first byte. For the latter, refer toPublicKey.from_compressed_bytes.The following methods are available:PublicKey.from_compressed_bytes(compressed_bytes) -> PublicKeyThisclassmethodreturns a newPublicKeyinstance computed from its compressed representation.compressed_bytesmustbe a byte string of length 33 starting with\x02or\x03.PublicKey.from_private(private_key) -> PublicKeyThisclassmethodreturns a newPublicKeyinstance computed from the
givenprivate_key.private_keymay either be a byte string of length 32 or an instance of theKeyAPI.PrivateKeyclass.PublicKey.recover_from_msg(message, signature) -> PublicKeyThisclassmethodreturns a newPublicKeyinstance computed from the
providedmessageandsignature.messagemustbe a byte stringsignaturemustbe an instance ofKeyAPI.SignaturePublicKey.recover_from_msg_hash(message_hash, signature) -> PublicKeySame asPublicKey.recover_from_msgexcept thatmessage_hashshould be the Keccak
hash of themessage.PublicKey.verify_msg(message, signature) -> boolThis method returnsTrueorFalsebased on whether the signature is a valid
for the given message.PublicKey.verify_msg_hash(message_hash, signature) -> boolSame asPublicKey.verify_msgexcept thatmessage_hashshould be the Keccak
hash of themessage.PublicKey.to_compressed_bytes() -> bytesReturns the compressed representation of this public key.PublicKey.to_address() -> textReturns the hex encoded ethereum address for this public key.PublicKey.to_checksum_address() -> textReturns the ERC55 checksum formatted ethereum address for this public key.PublicKey.to_canonical_address() -> bytesReturns the 20-byte representation of the ethereum address for this public key.KeyAPI.PrivateKey(private_key_bytes)ThePrivateKeyclass takes a single argument which must be a bytes string with length 32.The following methods and properties are availablePrivateKey.public_keyThispropertyholds thePublicKeyinstance coresponding to this private key.PrivateKey.sign_msg(message) -> SignatureThis method returns a signature for the givenmessagein the form of aSignatureinstancemessagemustbe a byte string.PrivateKey.sign_msg_hash(message_hash) -> SignatureSame asPrivateKey.signexcept thatmessage_hashshould be the Keccak
hash of themessage.KeyAPI.Signature(signature_bytes=None, vrs=None)TheSignatureclass can be instantiated in one of two ways.signature_bytes: a bytes string with length 65.vrs: a 3-tuple composed of the integersv,r, ands.Note: If using thesignature_bytesto instantiate, the byte string should be encoded asr_bytes | s_bytes | v_byteswhere|represents concatenation.r_bytesands_bytesshould be 32 bytes in length.v_bytesshould be a single byte\x00or\x01.Signatures are expected to use1or0for theirvvalue.The following methods and properties are availableSignature.vThis property returns thevvalue from the signature as an integer.Signature.rThis property returns thervalue from the signature as an integer.Signature.sThis property returns thesvalue from the signature as an integer.Signature.vrsThis property returns a 3-tuple of(v, r, s).Signature.verify_msg(message, public_key) -> boolThis method returnsTrueorFalsebased on whether the signature is a valid
for the given public key.message:mustbe a byte string.public_key:mustbe an instance ofPublicKeySignature.verify_msg_hash(message_hash, public_key) -> boolSame asSignature.verify_msgexcept thatmessage_hashshould be the Keccak
hash of themessage.Signature.recover_public_key_from_msg(message) -> PublicKeyThis method returns aPublicKeyinstance recovered from the signature.message:mustbe a byte string.Signature.recover_public_key_from_msg_hash(message_hash) -> PublicKeySame asSignature.recover_public_key_from_msgexcept thatmessage_hashshould be the Keccak hash of themessage.Exceptionseth_api.exceptions.ValidationErrorThis error is raised during instantaition of any of thePublicKey,PrivateKeyorSignatureclasses if their constructor parameters are
invalid.eth_api.exceptions.BadSignatureThis error is raised from any of therecoverorverifymethods involving
signatures if the signature is invalid.Developer SetupIf you would like to hack on eth-keys, please check out theSnake Charmers
Tactical Manualfor information on how we do:TestingPull RequestsDocumentationWe usepre-committo maintain consistent code style. Once
installed, it will run automatically with every commit. You can also run it manually
withmake lint. If you need to make a commit that skips thepre-commitchecks, you
can do so withgit commit --no-verify.Development Environment SetupYou can set up your dev environment with:gitclonegit@github.com:ethereum/eth-keys.gitcdeth-keys
virtualenv-ppython3venv
.venv/bin/activate
python-mpipinstall-e".[dev]"pre-commitinstallRelease setupTo release a new version:makereleasebump=$$VERSION_PART_TO_BUMP$$How to bumpversionThe version format for this repo is{major}.{minor}.{patch}for stable, and{major}.{minor}.{patch}-{stage}.{devnum}for unstable (stagecan be alpha or beta).To issue the next version in line, specify which part to bump,
likemake release bump=minorormake release bump=devnum. This is typically done from the
main branch, except when releasing a beta (in which case the beta is released from main,
and the previous stable branch is released from said branch).If you are in a beta version,make release bump=stagewill switch to a stable.To issue an unstable version when the current version is stable, specify the
new version explicitly, likemake release bump="--new-version 4.0.0-alpha.1 devnum"