README.md

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 storages

• 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