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 guide walks you through installing the solver rewards pipeline, configuring your credentials, and generating your first payout transfer file.
The pipeline requires Python >= 3.10 . If your system Python is older, use the Docker workflow instead. Prerequisites Before you start, make sure you have:
Python >= 3.10 installed
A Dune Analytics account with an API key
Access to the CoW Protocol analytics database (ANALYTICS_DB_URL)
An Ethereum node URL (and a mainnet node URL if running on L2)
Installation
Clone the repository
git clone https://github.com/cowprotocol/solver-rewards.git cd solver-rewards
Install dependencies
Run make install to create a virtual environment and install all requirements: This creates a venv/ directory and installs everything from requirements.txt.
Configure environment variables
Copy the sample environment file and fill in your credentials: Open .env and set at minimum: # Which network to run accounting for NETWORK = mainnet # Ethereum node URLs NODE_URL = https://your-mainnet-node.example.com NODE_URL_MAINNET = https://your-mainnet-node.example.com # Dune Analytics DUNE_API_KEY = your_dune_api_key_here # Gnosis Safe payment addresses PAYOUTS_SAFE_ADDRESS = 0xA03be496e67Ec29bC62F01a428683D7F9c204930 PAYOUTS_SAFE_ADDRESS_MAINNET = 0xA03be496e67Ec29bC62F01a428683D7F9c204930 # Database ANALYTICS_DB_URL = your_analytics_db_connection_string
See Configuration for the full list of environment variables.
Run the payout script
Generate transfer files for the default accounting period (last 7 days): python -m src.fetch.transfer_file
The script will:
Query Dune Analytics for the block interval
Fetch solver and partner data from the analytics database
Compute rewards, reimbursements, and fees
Write two CSV files to the out/ directory
Print a summary to the console
Review the output
On success, you’ll find two transfer files in out/: out/transfers-mainnet-2024-01-09-to-2024-01-16-COW.csv out/transfers-mainnet-2024-01-09-to-2024-01-16-NATIVE.csv
The console will show a summary like: Total Native Token Funds needed: 1.2345 Total COW Funds needed: 45678.9000
Cross-check these numbers against the Dune dashboard link printed to the console before proceeding. CLI options The full list of options for the main payout script:
python -m src.fetch.transfer_file --help usage: Fetch Complete Reimbursement [-h] [--start START] [--post-tx] [--dry-run] [--send-to-slack] options: -h, --help show this help message and exit --start START Accounting Period Start. Defaults to previous Tuesday --post-tx Flag indicating whether multisend should be posted to safe ( requires valid env var ` PROPOSER_PK ` ) --dry-run Flag indicating whether script should not post alerts or transactions. --send-to-slack Flag indicating whether the script should send results to a Slack channel
Common workflows Default (last 7 days, CSV output)
Specific accounting period
Auto-post to Gnosis Safe
Dry-run with Slack notification
python -m src.fetch.transfer_file
The pipeline should not be run immediately after an accounting period ends. Wait for on-chain data to finalize — including prices.usd, ethereum.transactions, and CoW Protocol event data — before executing the script.
Using Docker If you don’t have Python 3.10+, use the Docker image:
cp .env.sample .env # fill in your credentials docker run --pull=always -it --rm \ --env-file .env \ -v $PWD :/app/out \ ghcr.io/cowprotocol/solver-rewards:main \ src.fetch.transfer_file \ --start 'YYYY-MM-DD'
The transfer file will appear in your current directory after about 30 seconds.
See the Docker guide for more details.
Next steps
Configuration Full reference for all environment variables and network-specific settings.
Generating payouts Detailed guide to all payout modes: CSV, auto-propose, and dry-run.
Validating payouts Steps to verify payout results before Safe execution.
Reward mechanism How rewards, fees, and slippage are calculated.
