ethereum 2.0.2

This is the Python core library of the Ethereum project.

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

## Installation:

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’x03x04x05’, 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).

## Licence

See LICENCE