This is the Python core library of the Ethereum project.

For the python based command line client see:
https://github.com/ethereum/pyethapp

Installation:
-------------

``sudo apt-get install libssl-dev build-essential automake pkg-config libtool libffi-dev libgmp-dev``

``git clone https://github.com/ethereum/pyethereum/``

``cd pyethereum``

``python setup.py install``

Components
----------

ethereum.pow.chain
~~~~~~~~~~~~~~~~~~

Contains the Chain class, which can be used to manage a blockchain. Main
methods are:

-  ``__init__(genesis=None, env=None, new_head_cb=None, reset_genesis=False, localtime=None)``
   - initializes with the given genesis. ``env`` specifies the
   *environment* (including chain config and database), ``new_head_cb``
   is a callback called when a new head is added, and ``localtime`` is
   what the chain assumes is the current timestamp. The genesis can be:

   -  None - in which case it assumes ``env`` is given, and creates a
      Chain object with the data saved in ``env.db``. If
      ``reset_genesis`` is set, it re-initializes the chain.
   -  A ``State`` object
   -  A genesis declaration
   -  A state snapshot (``State.snapshot()``)
   -  An allocation (ie. dict
      ``{address: {balance: 1, nonce: 2, code: b'\x03\x04\x05', storage: {"0x06": "0x07"}}}``)

-  ``add_block(block)`` - adds a block to the chain
-  ``process_time_queue(timestamp)`` - tells the chain that the current
   time has increased to the new timestamp. The chain will then process
   any blocks that were unprocessed because they appeared too "early"
-  ``get_blockhash_by_number(num)`` - get the block hash of a block at
   the given block number
-  ``get_block(hash)`` - gets the block with the given blockhash
-  ``get_block_by_number(num)`` - equivalent to
   ``get_block(get_blockhash_by_number(num))``
-  ``get_parent(block)`` - gets the parent of a block
-  ``get_children(block)`` - gets the children of a block
-  ``head`` (property) - gets the block at the head of the chain
-  ``state`` (property) - gets the state at the head of the chain
-  ``mk_poststate_of_blockhash(hash)`` - creates a state object after a
   given block
-  ``has_block(block)`` - is that block in the chain? Returns True/False
-  ``get_chain(from, to)`` - roughly equivalent to
   ``[get_block_by_number(i) for i in range(from, to)]``, though
   automatically stops if it reaches the head. ``from`` can be elided to
   start from genesis, ``to`` can be elided to go up to the head.
-  ``get_tx_position(tx)`` - if the transaction is in the chain, returns
   ``(blknum, index)`` where ``blknum`` is the block number of the block
   that contains the transaction and ``index`` is its position in the
   block

ethereum.state
~~~~~~~~~~~~~~

Contains the State class, which is used to manage a state. Main methods
are:

-  ``__init__(root_hash, env, **kwargs)`` - initializes a state with the
   given root hash, the given env (which includes a config and database)
   and the given auxiliary arguments. These include:

   -  ``txindex`` - the transaction index
   -  ``gas_used`` - amount of gas used
   -  ``gas_limit`` - block gas limit
   -  ``block_number`` - block number
   -  ``block_coinbase`` - block coinbase address
   -  ``block_difficulty`` - block difficulty
   -  ``timestamp`` - timestamp
   -  ``logs`` - logs created so far
   -  ``receipts`` - receipts created so far (from previous transactions
      in the current block)
   -  ``bloom`` - the bloom filter
   -  ``suicides`` - suicides (or selfdestructs, the newer more
      politically correct synonym)
   -  ``recent_uncles`` - recent uncle blocks in the chain
   -  ``prev_headers`` - previous block headers
   -  ``refunds`` - suicide/selfdestruct refund counter

Pyethereum follows a **maximally state-centric model**; the ONLY
information needed to process a transaction or a block is located within
the state itself, allowing the actual state transition logic to be a
very clean ``apply_transaction(state, tx)`` and
``apply_block(state, block)``.

-  ``get_balance``- gets the balance of an account
-  ``get_code`` - gets the code of an account
-  ``get_storage_data(addr, k)`` - gets the storage at the given key of
   the given address. Expects a key in **numerical** form (eg. b"cow" or
   "0x636f77" is represented as 6516599).
-  ``to_snapshot(root_only=False, no_prevblocks=False)`` - creates a
   snapshot for the current state. If ``root_only`` is set, only adds
   the state root, not the entire state. If ``no_prevblocks`` is set,
   does not add previous headers and uncles. Setting either of those
   flags means that the same database would be required to recover from
   the snapshot.
-  ``from_snapshot(snapshot, env)`` (classmethod) - creates a state from
   the given snapshot with the given ``env``.
-  ``ephemeral_clone()`` - creates a clone of the state that you can
   work with without affecting the original

There are also many methods that modify the state, eg. ``set_code``,
``set_storage_data``, but it is generally recommended to avoid using
these, and instead modify the state ONLY through ``apply_transaction``
and ``apply_block``.

ethereum.meta
~~~~~~~~~~~~~

This file contains two functions:

-  ``apply_block(state, block)`` - takes a state and processes a block
   onto that state
-  ``make_head_candidate(chain, txqueue=None, parent=None, timestamp, coinbase, extra_data, min_gasprice=0)``
   - creates a candidate block for the chain on top of the given parent
   block (default: head of the chain). Gets transactions from the given
   ``txqueue`` object with the given ``mingasprice`` (otherwise does not
   add transactions). ``timestamp``, ``coinbase`` and ``extra_data`` can
   be used to specify those parameters in the block; otherwise defaults
   are used

ethereum.messages
~~~~~~~~~~~~~~~~~

The main function that should be called from here is
``apply_transaction(state, tx)``.

ethereum.utils
~~~~~~~~~~~~~~

Contains a bunch of utility functions, including:

Numerical and hex conversions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  ``encode_int(i)`` - converts an integer into big-endian binary
   representation
-  ``zpad(data, length)`` - pads the data up to the desired length by
   adding zero bytes on the left
-  ``encode_int32(i)`` - equivalent to ``zpad(encode_int(i), 32)`` but
   faster
-  ``big_endian_to_int(d)`` - converts binary data into an integer
-  ``encode_hex(b)`` - converts bytes to hex
-  ``decode_hex(h)`` - converts hex to bytes
-  ``int_to_addr(i)`` - converts integer to address
-  ``is_numeric(i)`` - returns True if the value is int or long,
   otherwise False

Cryptography
^^^^^^^^^^^^

-  ``sha3(data)`` - computes the SHA3 (or more precisely, keccak256)
   hash
-  ``ecrecover_to_pub(hash, v, r, s)`` - recovers the public key that
   made the signature as a 64-byte binary blob of
   ``encode_int32(x) + encode_int32(y)``. Hashing this and taking the
   last 20 bytes gives the *address* that signed a message.
-  ``ecsign(hash, key)`` - returns the v, r, s values of a signature
-  ``normalize_key(key)`` - converts a key from many formats into
   32-byte binary
-  ``privtoaddr(key)`` - converts a key to an address

Addresses
^^^^^^^^^

-  ``normalize_address(addr)`` - converts an address into 20-byte binary
   form
-  ``check_checksum(addr)`` - returns True if the address checksum
   passes, otherwise False
-  ``checksum_encode(addr)`` - converts an address into hex form with a
   checksum
-  ``mk_contract_address(addr, nonce)`` - creates the address of a
   contract created by the given address with the given nonce

Miscellaneous
^^^^^^^^^^^^^

-  ``denoms`` - contains the denominations of ether, eg.
   ``denoms.finney = 10**15``, ``denoms.shannon = 10**9``,
   ``denoms.gwei = 10**9``

ethereum.block
~~~~~~~~~~~~~~

Contains the ``Block`` and ``BlockHeader`` classes. Generally
recommended to avoid creating blocks and block headers directly, instead
using ``mk_head_candidate``. The member variables are straightforward:

-  ``block.transactions`` - transactions in a block
-  ``block.uncles`` - uncles in a block
-  ``block.header`` - header of a block

And in the header:

-  ``header.hash`` - the hash (also the block hash)
-  ``header.mining_hash`` - the hash used for proof of work mining
-  ``header.to_dict()`` - serializes into a human-readable dict
-  ``header.prevhash`` - previous block hash
-  ``header.uncles_hash`` - hash of the uncle list
-  ``header.coinbase`` - coinbase (miner) address
-  ``header.state_root`` - root hash of the post-state
-  ``header.tx_list_root`` - hash of the transactions in the block
-  ``header.receipts_root`` - hash of the receipt trie
-  ``header.bloom`` - bloom filter
-  ``header.difficulty`` - block difficulty
-  ``header.number`` - block number
-  ``header.gas_limit`` - gas limit
-  ``header.gas_used`` - gas used
-  ``header.timestamp`` - timestamp
-  ``header.extra_data`` - block extra data
-  ``header.mixhash`` and ``header.nonce`` - Ethash proof of work values

ethereum.transactions
~~~~~~~~~~~~~~~~~~~~~

Contains the Transaction class, with the following methods and values:

-  ``__init__(nonce, gasprice, startgas, to, value, data, (v, r, s optional))``
   - constructor
-  ``sign(key, network_id=None)`` - signs the transaction with the given
   key, and with the given EIP155 chain ID (leaving as None will create
   a pre-EIP155 tx, be warned of replay attacks if you do this!)
-  ``sender`` - the sender address of the transaction
-  ``network_id`` - the EIP155 chain ID of the transaction
-  ``hash`` - the hash of the transaction
-  ``to_dict()`` - serializes into a human-readable dict
-  ``intrinsic_gas_used`` - the amount of gas consumed by the
   transaction, including the cost of the tx data
-  ``creates`` - if the transaction creates a contract, returns the
   contract address
-  ``nonce``, ``gasprice``, ``startgas``, ``to``, ``value``, ``data``,
   ``v``, ``r``, ``s`` - parameters in the transaction

ethereum.tools.keys
~~~~~~~~~~~~~~~~~~~

Creates encrypted private key storaes

-  ``decode_keystore_json(jsondata, password)`` - returns the private
   key from an encrypted keystore object. NOTE: if you are loading from
   a file, the most convenient way to do this is
   ``import json; key = decode_keystore_json(json.load(open('filename.json')), 'password')``
-  ``make_keystore_json(key, pw, kdf='pbkdf2', cipher='aes-128-ctr')`` -
   creates an encrypted keystore object for the key. Keeping ``kdf`` and
   ``cipher`` at their default values is recommended.

ethereum.abi
~~~~~~~~~~~~

Most compilers for HLLs (solidity, serpent, viper, etc) on top of
Ethereum have the option to output an ABI declaration for a program.
This is a json object that looks something like this:

::

    [{"name": "ecrecover(uint256,uint256,uint256,uint256)", "type": "function", "constant": false,
     "inputs": [{"name": "h", "type": "uint256"}, {"name": "v", "type": "uint256"}, {"name": "r", "type": "uint256"}, {"name": "s", "type": "uint256"}],
     "outputs": [{"name": "out", "type": "int256[]"}]},
     {"name": "PubkeyTripleLogEvent(uint256,uint256,uint256)", "type": "event",
     "inputs": [{"name": "x", "type": "uint256", "indexed": false}, {"name": "y", "type": "uint256", "indexed": false}, {"name": "z", "type": "uint256", "indexed": false}]}]

You can initialize an ``abi.ContractTranslator`` object to encode and
decode data for contracts as follows:

::

    true, false = True, False  
    ct = abi.ContractTranslator(<json here>)  
    txdata = ct.encode('function_name', [arg1, arg2, arg3])  

You can also call ``ct.decode_event([topic1, topic2...], logdata)`` to
decode a log.

RLP encoding and decoding
~~~~~~~~~~~~~~~~~~~~~~~~~

For any transaction or block, you can simply do:

::

    import rlp  
    bindata = rlp.encode(<tx or block>)  

To decode:

::

    import rlp  
    from ethereum.transactions import Transaction  
    rlp.decode(blob, Transaction)  

Or:

::

    import rlp  
    from ethereum.blocks import Block  
    rlp.decode(blob, Block)  

Consensus abstraction
~~~~~~~~~~~~~~~~~~~~~

The pyethereum codebase is designed to be maximally friendly for use
across many different consensus algorithms. If you want to add a new
consensus algo, you'll need to take the following steps:

-  Add a directory alongside ``pow``, and in it create a ``chain.py``
   class that implements a ``Chain`` module. This may have a totally
   different fork choice rule for proof of work (GHOST, signature
   counting, Casper, etc).
-  Add an entry to ``consensus_strategy.py``. You will need to
   implement:

   -  ``check_seal`` - check that a block is correctly "sealed" (mined,
      signed, etc)
   -  ``validate_uncles(state, block)`` - check that uncles are valid
   -  ``initialize(state, block)`` - called in ``apply_block`` before
      transactions are processed
   -  ``finalize(state, block)`` - called in ``apply_block`` after
      transactions are processed
   -  ``get_uncle_candidates(chain, state)`` - called in
      ``mk_head_candidate`` to include uncles in a block

-  Create a chain config with the ``CONSENSUS_STRATEGY`` set to whatever
   you named your new consensus strategy

Tester module
-------------

See https://github.com/ethereum/pyethereum/wiki/Using-pyethereum.tester

Tests
-----

Run ``python3.6 -m pytest ethereum/tests/<filename>`` for any .py file
in that directory. Currently all tests are passing except for a few
Metropolis-specific state tests and block tests.

To make your own state tests, use the tester module as follows:

::

    from ethereum.tools import tester as t  
    import json  
    c = t.Chain()  
    x = c.contract(<code>, language=<language>)  
    pre = t.mk_state_test_prefill(c)  
    x.foo(<args>)  
    post = t.mk_state_test_postfill(c, pre)  
    open('output.json', 'w').write(json.dumps(post, indent=4))  

To make a test filler file instead, do
``post = t.mk_state_test_postfill(c, pre, True)``.

License
-------

See `LICENSE <LICENSE>`_
