Developer Notes

Installation:

git clone https://github.com/ethereum/pyethereum.git
virtualenv -p python3.6 pyethereum

Only Python versions 2.7, 3.4, 3.5 or 3.6 are supported.

cd pyethereum
pip install -r requirements.txt

That will try to install the requirements in your current environment.

NOTE: If you have not setup a virtualenv this will most likely try to install dependencies globally and might require more privileges.

If you get the following error:

scrypt-1.1.6/lib/crypto/crypto_aesctr.c:38:25: fatal error: openssl/aes.h: No such file or directory

then you need the SSL development libraries. To install them:

On Debian, Ubuntu, Linux Mint and other Ubuntu descendants:

sudo apt-get install libssl-dev

On Fedora, CentOS and RedHat:

sudo yum install openssl-devel

Installing dependencies for OS X

If you are trying to run pyethereum on OS X, please make sure you have the following dependencies installed:

brew install pkg-config libffi autoconf automake libtool openssl

How to contribute

We accept pull requests. Fork the repository and send your PR!

dev_requirements

To install the dependencies necessary for development (testing, ...), run:

pip install -r dev_requirements.txt

Coding

• You should try to write code compatible with Python3 (see http://www.diveintopython3.net/porting-code-to-python-3-with-2to3.html).
• Your code should pass PEP8 check.
• Use absolute path for import (eg. from pyethereum import utils)
• Use rlp.utils.decode_hex and rlp.utils.encode_hex instead of .decode('hex') and .encode('hex')
• Use utils.is_numeric() and utils.is_string() instead of isinstance()
• Use utils.to_string() instead str()
• Use rlp.utils.ascii_chr() instead chr()
• Use utils.safe_ord() instead ord()
• Use // instead / to divide integer
• Use bytes for every hard coded string. It is not enough to add b before every string, because in Py2, 'foo'[0] == 'f' and in Py3, b'foo'[0] == 102, so everywhere use in_to_bytes(data[i]) instead of data[i] (see https://github.com/ethereum/pyethereum/commit/72331f81e42e11e8c3d2f584f5d49befb4ec3722#diff-a353fb065c72ecea2d0526509dd51d41L7)

Testing

pytest is used for testing

In order to run tests, you need to prepare the fixtures-submodule:

git submodule init
git submodule update --recursive

then run the tests either by calling py.test (or behave for a set of older tests) consecutively or by calling tox (which will do both).

In order to update the fixtures-submodule:

git submodule status
cd fixtures/
git pull origin develop
cd ..
git commit -m 'updated fixtures submodule'

Tips for testing with the VM:

1. You can get traces for a transaction using the API and ethclient, e.g.: bin/pyethclient trace 522f583b94cb3a16deca41404ef404c2c1b3484070af2ec7971bc4e1a17c556e
2. Use the -s modifier to see the log output of tests, e.g. py.test -s tests/test_vm.py
3. You can customize the level of VM logging detail by modifying PBLogger in processblock.py

Logging:

Please use the logging module for logging.

For basic, verbose logging functionality, the following is sufficient (adjust level to your needs)::

import logging

logging.basicConfig(format='[%(asctime)s] %(name)s %(levelname)s %(message)s', level=logging.DEBUG)
logger = logging.getLogger(__name__)

If you need a more advanced setup, have a look at the python docs

Pretty printed json logging

The json log can be hard to read. Here is, how you can redirect it through pretty printing (while still being able to grep for keywords):

tail -f logfile.json|cut -b25-|while IFS=$'\n' read -r line; do python -mjson.tool <<<"$line"; done

Easy Debugging:

The eth.py script, understands a command line flag for easy debugging, e.g.:

pyethereum/eth.py -L pyethereum.wire:DEBUG,:INFO ...<other args>

will set the log-level for wire to DEBUG and the root logger to INFO.

pyethereum/eth.py -L :DEBUG ...<other args>

logs everything to the console.

Furthermore, the log handler supports a special log level, log.DEV(msg, **kwargs), that will be highlighted in the log. Use this, if you want some temporary debug logging to stand out. The internal loglevel is CRITICAL, so it should always appear, even if you go with the default log settings (i.e. don't define -l...).

Monkey patching

bin/pyeth tries to import a module named pyethereum/monkeypatch.py. You can use monkey patching to temporarily introduce alternate control flow e.g.

"Monkey Patch Example"

import pyethereum.packeter
pyethereum.packeter.Packeter.CLIENT_VERSION += '/YourName'

# set processblock log details
import pyethereum.processblock as pb
pb.pblogger.log_state_delta = True
pb.pblogger.log_ops = True

# write failed blocks to disc
import pyethereum.utils as utils
orig_verify = pb.verify

def log_verify(block, parent):
   res = orig_verify(block, parent)
   if not res:
        pb.logger.debug('### VERIFICATION FAILED ### %r', e)
        f = os.path.join(utils.data_dir, 'badblock.log')
        open(f, 'w').write(str(block.hex_serialize()))
        print block.hex_serialize()
    return res
pb.verify = log_verify

# import other patches
import blockfetcherpatch