Aah, I get it

Author: vbuterin

README.md

@@ -0,0 +1,241 @@
+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'\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)`.
+
+## Licence
+
+See LICENCE

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-with open('README.md') as readme_file:
+with open('README.rst') as readme_file:
     readme = readme_file.read()
 
 # requirements