Development setup

Setting up a local development environment for contributing to solver rewards.

This project requires Python >= 3.10 strictly. The codebase uses syntax and standard-library features introduced in 3.10. Running an older Python version will produce import errors at startup.

Prerequisites

Before cloning the repository, make sure you have the following installed:

• Python >= 3.10 — check with python3 --version
• Git — check with git --version
• pip-tools (optional, for dependency management) — pip install pip-tools

Installation

1. Clone the repository

   git clone https://github.com/cowprotocol/solver-rewards.git
   cd solver-rewards
   
2. Install dependencies

   Run the install target. It creates a venv/ virtualenv, upgrades pip, and installs all packages from requirements.txt.

   make install
   

   The Makefile uses a sentinel file venv/.install so subsequent make invocations skip reinstalling unless requirements.txt changes.

3. Configure environment variables

   Copy the sample environment file and fill in your Dune Analytics and orderbook credentials.

   cp .env.sample .env
   

   Open .env and populate the required API keys before running any pipeline scripts.

Code style

The project follows the Black code formatter with no custom configuration — Black’s defaults apply.

# Auto-format the entire project
make fmt

# Equivalent direct command
black ./

Many editors (VS Code, PyCharm, Neovim) can be configured to run Black on save, which avoids formatting-only CI failures.

Linting

Pylint is used to lint the src/ package. The project ships a minimal .pylintrc that disables two checks:

• fixme — allows TODO/FIXME comments in source
• logging-fstring-interpolation — allows f-strings in log calls

make lint

This runs:

pylint src/

Type checking

Mypy runs in --strict mode against the src/ package. The mypy.ini targets Python 3.12 and sets two relaxations for the src.* namespace:

Option	Value	Reason
ignore_missing_imports	True	Several third-party stubs are absent
allow_untyped_calls	True	Calls into untyped third-party code
allow_any_generics	True	Generic aliases without type parameters

make types

This runs:

mypy src/ --strict

Running all checks

make check chains formatting, linting, and type checking in a single command. Run this before opening a pull request.

make check

Internally this is equivalent to:

make fmt && make lint && make types

Makefile reference

install

# Creates venv/, upgrades pip, installs requirements.txt
$(PYTHON) -m venv $(VENV)
$(ACTIVATE); pip install --upgrade pip
$(ACTIVATE); pip install -r requirements.txt

Managing dependencies

Direct dependencies are declared in requirements.in. The fully-pinned requirements.txt is generated from it using pip-tools.

To add or update a dependency:

1. Edit requirements.in

   Add the package (with an optional version constraint) to requirements.in:

   # requirements.in
   some-new-package>=1.2.0
   

   Current direct dependencies include: dune-client, duneapi, web3, safe-eth-py, pandas, numpy, psycopg2-binary, SQLAlchemy, python-dotenv, requests, and dev tools black, mypy, pylint, pytest.

2. Compile the lockfile

   pip-compile requirements.in
   # or
   python -m piptools compile requirements.in
   

   Compilation can take several minutes for large dependency trees or on first run. Add -v to watch progress:

   pip-compile -v requirements.in
   
3. Reinstall from the updated lockfile

   make install
   

   The sentinel file venv/.install is keyed on requirements.txt, so Make will detect the change and re-run pip.

Commit both requirements.in and requirements.txt. The .in file records intent; the .txt file ensures reproducible installs for every contributor and CI run.