eth_account

Account

class eth_account.account.Account

This is the primary entry point for working with Ethereum private keys.

It does not require a connection to an Ethereum node.

create(extra_entropy='')

Creates a new private key, and returns it as a LocalAccount.

Parameters:extra_entropy (str or bytes or int) – Add extra randomness to whatever randomness your OS can provide
Returns:an object with private key and convenience methods
>>> from eth_account import Account
>>> acct = Account.create('KEYSMASH FJAFJKLDSKF7JKFDJ 1530')
>>> acct.address
'0x5ce9454909639D2D17A3F753ce7d93fa0b9aB12E'
>>> acct.privateKey
b"\xb2\}\xb3\x1f\xee\xd9\x12''\xbf\t9\xdcv\x9a\x96VK-\xe4\xc4rm\x03[6\xec\xf1\xe5\xb3d"

# These methods are also available: signHash(), signTransaction(), encrypt()
# They correspond to the same-named methods in Account.*
# but without the private key argument
static decrypt(keyfile_json, password)

Decrypts a private key that was encrypted using an Ethereum client or encrypt().

Parameters:
  • keyfile_json (dict or str) – The encrypted key
  • password (str) – The password that was used to encrypt the key
Returns:

the raw private key

Return type:

HexBytes

>>> encrypted = {
 'address': '5ce9454909639d2d17a3f753ce7d93fa0b9ab12e',
 'crypto': {'cipher': 'aes-128-ctr',
  'cipherparams': {'iv': '78f214584844e0b241b433d7c3bb8d5f'},
  'ciphertext': 'd6dbb56e4f54ba6db2e8dc14df17cb7352fdce03681dd3f90ce4b6c1d5af2c4f',
  'kdf': 'pbkdf2',
  'kdfparams': {'c': 1000000,
   'dklen': 32,
   'prf': 'hmac-sha256',
   'salt': '45cf943b4de2c05c2c440ef96af914a2'},
  'mac': 'f5e1af09df5ded25c96fcf075ada313fb6f79735a914adc8cb02e8ddee7813c3'},
 'id': 'b812f3f9-78cc-462a-9e89-74418aa27cb0',
 'version': 3}

>>> import getpass
>>> Account.decrypt(encrypted, getpass.getpass())
HexBytes('0xb25c7db31feed9122727bf0939dc769a96564b2de4c4726d035b36ecf1e5b364')
static encrypt(private_key, password)

Creates a dictionary with an encrypted version of your private key. To import this keyfile into Ethereum clients like geth and parity: encode this dictionary with json.dumps() and save it to disk where your client keeps key files.

Parameters:
  • private_key (hex str, bytes, int or eth_keys.datatypes.PrivateKey) – The raw private key
  • password (str) – The password which you will need to unlock the account in your client
Returns:

The data to use in your encrypted file

Return type:

dict

>>> import getpass
>>> encrypted = Account.encrypt(
    0xb25c7db31feed9122727bf0939dc769a96564b2de4c4726d035b36ecf1e5b364,
    getpass.getpass()
)

{'address': '5ce9454909639d2d17a3f753ce7d93fa0b9ab12e',
 'crypto': {'cipher': 'aes-128-ctr',
  'cipherparams': {'iv': '78f214584844e0b241b433d7c3bb8d5f'},
  'ciphertext': 'd6dbb56e4f54ba6db2e8dc14df17cb7352fdce03681dd3f90ce4b6c1d5af2c4f',
  'kdf': 'pbkdf2',
  'kdfparams': {'c': 1000000,
   'dklen': 32,
   'prf': 'hmac-sha256',
   'salt': '45cf943b4de2c05c2c440ef96af914a2'},
  'mac': 'f5e1af09df5ded25c96fcf075ada313fb6f79735a914adc8cb02e8ddee7813c3'},
 'id': 'b812f3f9-78cc-462a-9e89-74418aa27cb0',
 'version': 3}

 >>> with open('my-keyfile', 'w') as f:
     f.write(json.dumps(encrypted))
privateKeyToAccount(private_key)

Returns a convenient object for working with the given private key.

Parameters:private_key (hex str, bytes, int or eth_keys.datatypes.PrivateKey) – The raw private key
Returns:object with methods for signing and encrypting
Return type:LocalAccount
>>> acct = Account.privateKeyToAccount(
  0xb25c7db31feed9122727bf0939dc769a96564b2de4c4726d035b36ecf1e5b364)
>>> acct.address
'0x5ce9454909639D2D17A3F753ce7d93fa0b9aB12E'
>>> acct.privateKey
b"\xb2\}\xb3\x1f\xee\xd9\x12''\xbf\t9\xdcv\x9a\x96VK-\xe4\xc4rm\x03[6\xec\xf1\xe5\xb3d"

# These methods are also available: signHash(), signTransaction(), encrypt()
# They correspond to the same-named methods in Account.*
# but without the private key argument
recoverHash(message_hash, vrs=None, signature=None)

Get the address of the account that signed the message with the given hash. You must specify exactly one of: vrs or signature

Parameters:
  • message_hash (hex str or bytes or int) – the hash of the message that you want to verify
  • vrs (tuple(v, r, s), each element is hex str, bytes or int) – the three pieces generated by an elliptic curve signature
  • signature (hex str or bytes or int) – signature bytes concatenated as r+s+v
Returns:

address of signer, hex-encoded & checksummed

Return type:

str

>>> msg = "I♥SF"
>>> msghash = '0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750'
>>> vrs = (
      28,
      '0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb3',
      '0x3e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce')
>>> Account.recoverHash(msghash, vrs=vrs)
'0x5ce9454909639D2D17A3F753ce7d93fa0b9aB12E'

# All of these recover calls are equivalent:

# variations on msghash
>>> msghash = b"\x14v\xab\xb7E\xd4#\xbf\t'?\x1a\xfd\x88}\x95\x11\x81\xd2Z\xdcf\xc4\x83JpI\x19\x11\xb7\xf7P"  # noqa: E501
>>> Account.recoverHash(msghash, vrs=vrs)
>>> msghash = 0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750
>>> Account.recoverHash(msghash, vrs=vrs)

# variations on vrs
>>> vrs = (
      '0x1c',
      '0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb3',
      '0x3e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce')
>>> Account.recoverHash(msghash, vrs=vrs)
>>> vrs = (
      b'\x1c',
      b'\xe6\xca\x9b\xbaX\xc8\x86\x11\xfa\xd6jl\xe8\xf9\x96\x90\x81\x95Y8\x07\xc4\xb3\x8b\xd5(\xd2\xcf\xf0\x9dN\xb3',  # noqa: E501
      b'>[\xfb\xbfM>9\xb1\xa2\xfd\x81jv\x80\xc1\x9e\xbe\xba\xf3\xa1A\xb29\x93J\xd4<\xb3?\xce\xc8\xce')  # noqa: E501
>>> Account.recoverHash(msghash, vrs=vrs)
>>> vrs = (
      0x1c,
      0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb3,
      0x3e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce)
>>> Account.recoverHash(msghash, vrs=vrs)

# variations on signature
>>> signature = '0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb33e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce1c'  # noqa: E501
>>> Account.recoverHash(msghash, signature=signature)
>>> signature = b'\xe6\xca\x9b\xbaX\xc8\x86\x11\xfa\xd6jl\xe8\xf9\x96\x90\x81\x95Y8\x07\xc4\xb3\x8b\xd5(\xd2\xcf\xf0\x9dN\xb3>[\xfb\xbfM>9\xb1\xa2\xfd\x81jv\x80\xc1\x9e\xbe\xba\xf3\xa1A\xb29\x93J\xd4<\xb3?\xce\xc8\xce\x1c'  # noqa: E501
>>> Account.recoverHash(msghash, signature=signature)
>>> signature = 0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb33e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce1c  # noqa: E501
>>> Account.recoverHash(msghash, signature=signature)
recoverTransaction(serialized_transaction)

Get the address of the account that signed this transaction.

Parameters:serialized_transaction (hex str, bytes or int) – the complete signed transaction
Returns:address of signer, hex-encoded & checksummed
Return type:str
>>> raw_transaction = '0xf86a8086d55698372431831e848094f0109fc8df283027b6285cc889f5aa624eac1f55843b9aca008025a009ebb6ca057a0535d6186462bc0b465b561c94a295bdb0621fc19208ab149a9ca0440ffd775ce91a833ab410777204d5341a6f9fa91216a6f3ee2c051fea6a0428',  # noqa: E501
>>> Account.recoverTransaction(raw_transaction)
'0x2c7536E3605D9C16a7a3D7b1898e529396a65c23'
setKeyBackend(backend)

Change the backend used by the underlying eth-keys library.

(The default is fine for most users)

Parameters:backend – any backend that works in eth_keys.KeyApi(backend)
signHash(message_hash, private_key)

Sign the hash provided.

Warning

Never sign a hash that you didn’t generate, it can be an arbitrary transaction. For example, it might send all of your account’s ether to an attacker.

If you would like compatibility with w3.eth.sign() you can use defunct_hash_message().

Several other message standards are proposed, but none have a clear consensus. You’ll need to manually comply with any of those message standards manually.

Parameters:
  • message_hash (hex str, bytes or int) – the 32-byte message hash to be signed
  • private_key (hex str, bytes, int or eth_keys.datatypes.PrivateKey) – the key to sign the message with
Returns:

Various details about the signature - most importantly the fields: v, r, and s

Return type:

AttributeDict

>>> msg = "I♥SF"
>>> from eth_account.messages import defunct_hash_message
>>> msghash = defunct_hash_message(text=msg)
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')
>>> key = "0xb25c7db31feed9122727bf0939dc769a96564b2de4c4726d035b36ecf1e5b364"
>>> Account.signHash(msghash, key)
{'messageHash': HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750'),  # noqa: E501
 'r': 104389933075820307925104709181714897380569894203213074526835978196648170704563,
 's': 28205917190874851400050446352651915501321657673772411533993420917949420456142,
 'signature': HexBytes('0xe6ca9bba58c88611fad66a6ce8f996908195593807c4b38bd528d2cff09d4eb33e5bfbbf4d3e39b1a2fd816a7680c19ebebaf3a141b239934ad43cb33fcec8ce1c'),  # noqa: E501
 'v': 28}

# these are equivalent:
>>> Account.signHash(
    0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750,
    key
)
>>> Account.signHash(
    "0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750",
    key
)
signTransaction(transaction_dict, private_key)

Sign a transaction using a local private key. Produces signature details and the hex-encoded transaction suitable for broadcast using w3.eth.sendRawTransaction().

Create the transaction dict for a contract method with my_contract.functions.my_function().buildTransaction()

Parameters:
  • transaction_dict (dict) – the transaction with keys: nonce, chainId, to, data, value, gas, and gasPrice.
  • private_key (hex str, bytes, int or eth_keys.datatypes.PrivateKey) – the private key to sign the data with
Returns:

Various details about the signature - most importantly the fields: v, r, and s

Return type:

AttributeDict

>>> transaction = {
        # Note that the address must be in checksum format:
        'to': '0xF0109fC8DF283027b6285cc889F5aA624EaC1F55',
        'value': 1000000000,
        'gas': 2000000,
        'gasPrice': 234567897654321,
        'nonce': 0,
        'chainId': 1
    }
>>> key = '0x4c0883a69102937d6231471b5dbb6204fe5129617082792ae468d01a3f362318'
>>> signed = Account.signTransaction(transaction, key)
{'hash': HexBytes('0x6893a6ee8df79b0f5d64a180cd1ef35d030f3e296a5361cf04d02ce720d32ec5'),
 'r': 4487286261793418179817841024889747115779324305375823110249149479905075174044,
 'rawTransaction': HexBytes('0xf86a8086d55698372431831e848094f0109fc8df283027b6285cc889f5aa624eac1f55843b9aca008025a009ebb6ca057a0535d6186462bc0b465b561c94a295bdb0621fc19208ab149a9ca0440ffd775ce91a833ab410777204d5341a6f9fa91216a6f3ee2c051fea6a0428'),  # noqa: E501
 's': 30785525769477805655994251009256770582792548537338581640010273753578382951464,
 'v': 37}
>>> w3.eth.sendRawTransaction(signed.rawTransaction)

See Signers for alternative signers.

AttributeDict

class eth_account.datastructures.AttributeDict(*args, **kwargs)

Bases: attrdict.dictionary.AttrDict

See AttrDict docs

This class differs only in that it is made immutable. This immutability is not a security guarantee. It is only a style-check convenience.

Messages

eth_account.messages.defunct_hash_message(primitive=None, hexstr=None, text=None)

Convert the provided message into a message hash, to be signed. This provides the same prefix and hashing approach as w3.eth.sign(). That means that the message will automatically be prepended with text defined in EIP-191 as version ‘E’: b'\x19Ethereum Signed Message:\n' concatenated with the number of bytes in the message.

Awkwardly, the number of bytes in the message is encoded in decimal ascii. So if the message is ‘abcde’, then the length is encoded as the ascii character ‘5’. This is one of the reasons that this message format is not preferred. There is ambiguity when the message ‘00’ is encoded, for example. Only use this method if you must have compatibility with w3.eth.sign().

Supply exactly one of the three arguments: bytes, a hex string, or a unicode string.

Parameters:
  • primitive (bytes or int) – the binary message to be signed
  • hexstr (str) – the message encoded as hex
  • text (str) – the message as a series of unicode characters (a normal Py3 str)
Returns:

The hash of the message, after adding the prefix

Return type:

HexBytes

>>> from eth_account.messages import defunct_hash_message

>>> msg = "I♥SF"
>>> defunct_hash_message(text=msg)
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')

# these four also produce the same hash:
>>> defunct_hash_message(w3.toBytes(text=msg))
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')

>>> defunct_hash_message(bytes(msg, encoding='utf-8'))
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')

>>> Web3.toHex(text=msg)
'0x49e299a55346'
>>> defunct_hash_message(hexstr='0x49e299a55346')
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')

>>> defunct_hash_message(0x49e299a55346)
HexBytes('0x1476abb745d423bf09273f1afd887d951181d25adc66c4834a70491911b7f750')