Metadata-Version: 1.1
Name: ethereum
Version: 2.0.1
Summary: Next generation cryptocurrency network
Home-page: https://github.com/ethereum/pyethereum/
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: 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
        
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
