Developer guide

Here are instructions for new developers how to get started with the development of web3-ethereum-defi package. This concerns you only if you indent to contribute to the package code itself - if you use the package as a dependency then this might not be relevant for oyu.

Prerequisites

You can program in Python
You now how Git and Github work
Linux or Mac recommended (We might not be able to support Windows users)

Checkout

Check out the project locally:

git clone git@github.com:tradingstrategy-ai/web3-ethereum-defi.git

We assume you use SSH keys with Github, but HTTPS checkout works as well.

Make sure you checkout the submodules, as we include Uniswap, Sushiswap and others as Git submodules:

cd web3-ethereum-defi
git submodule update --init --recursive

Prerequisites

Pandoc (to build docs):

brew install pandoc

Install with Poetry

Install Poetry.

Install the project with Poetry in development mode:

cd web3-ethereum-defi
poetry shell  # Enter to Poetry/virtualenv enabled shell
poetry install -E docs -E data

Note that -E docs is important, otherwise Sphinx package won’t be installed and you cannot build docs.

Check instructions here if you need to change Python version from your default to Python 3.8+.

Ganache

Some features require ganache, to install it.

First install Node / NPM:

brew install node  # For macOS

Then install Ganache itself:

npm install -g ganache

Make sure your Ganache is version 7+:

ganache --version

ganache v7.0.3 (@ganache/cli: 0.1.4, @ganache/core: 0.1.4)

Smoke test

Check that the tests of unmodified master branch pass:

pytest

For fast parallel test execution run with pytest-xdist across all of your CPUs:

pytest -n auto --dist loadscope

You should get all green.

Some tests will be skipped, because they require full EVM nodes. JSON-RPC needs to be configured through environment variables.

You can also run tests with logging enabled to get more information:

pytest --tb=native --log-cli-level=info -x

This will

Use native tracebacks
Set console logging level to INFO
Stop on the first failure

Formatting code

The code uses Python black formatting with unlimited line length.

To format any of your code:

# Black comes in dev dependencies
poetry shell
black eth_defi tests scripts

Pull requests

For new feature requests, make sure your pull request satisfies the checklist below and enjoy merge party.

Documentation dependencies

This repository uses poetry to manage dependencies, but Read The Docs, where docs are continuously build, only supports pip. You need to update Read the Docs dependencies manually if you update pyproject.toml.

To update dependencies for Read the Docs run:

poetry update
poetry export \
    --with=dev \
    --extras=data \
    --extras=docs \
    --without-hashes \
    --format=requirements.txt > docs/requirements.txt

# Include self
echo "-e ." >> docs/requirements.txt

# Check we generated a good file
head docs/requirements.txt

See .readthedocs.yml for further details.
See Generating requirements.txt with Poetry.
See including your own package in pip requirements.txt list

Pull request quality checklist

✅ The Python code passes flake8 formatting conventions. Run poetry run flake8 and you should get a clean output. Note that Github Action will complain on these when you open a pull request.
✅ Every Python module has a sensible docstring in the format single line description + long description. See existing modules for examples.
✅ Every Python function has a sensible docstring in the format single line description + long description. See existing modules for examples.
✅ Every Python function that library users call have their parameters documented.
✅ Every Python function that library users call has a code example in the docstring.
✅ Every Python function has a unit test and unit test comes with a proper docstring.
✅ Any new functions are added to the documentation. Run cd docs && make clean html and then open docs/build/html/index.html to view documentation locally. See existing Sphinx documentation for examples how to include your module in the autogenerated documentation.
✅ CHANGELOG.md contains a line for the change if it is a library user facing feature.

Rebuilding smart contract compilation artifacts

All smart contracts should be precompiled in the Github repository. If you need to recompile them, you need to have Gnu make.

You will need yarn in the additional to npm:

npm install -g yarn

Get make:

brew install make

Then you can run the command to recompile all the smart contracts:

make all