Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cowprotocol/solver-rewards/llms.txt

Use this file to discover all available pages before exploring further.

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:
OptionValueReason
ignore_missing_importsTrueSeveral third-party stubs are absent
allow_untyped_callsTrueCalls into untyped third-party code
allow_any_genericsTrueGeneric 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

# 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us