Skip to content

Commit 0ee38f6

Browse files
jeffersonBastosjeffersonBastos
authored
Merge pull request #5 from bleu/jefferson/cow-526-baseline-docs-and-tests
Update README and create QUICKSTART doc
2 parents 67f3009 + a0cb97d commit 0ee38f6

File tree

5 files changed

+402
-260
lines changed

5 files changed

+402
-260
lines changed

‎QUICKSTART.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Quick Start: Running Python Solvers Against Barn API
2+
3+
This guide walks you through setting up and running Python-based solvers against CoW Protocol's staging environment (Barn API).
4+
5+
## What You'll Build
6+
7+
A complete solver stack running locally:
8+
- **Autopilot**: Fetches live auctions from Barn API
9+
- **Driver**: Routes auction data to your solver and manages solution submission
10+
- **Python Solver**: Your custom solving logic
11+
12+
## Prerequisites
13+
14+
Before starting, ensure you have:
15+
16+
- **Rust & Cargo** — [Installation guide](https://www.rust-lang.org/tools/install)
17+
- **Python 3.11+** — [Installation guide](https://www.python.org/downloads/)
18+
- **Poetry** — [Installation guide](https://python-poetry.org/docs/#installation) (Python dependency management)
19+
- **PostgreSQL** — Running instance (setup instructions in [services repo](https://github.com/cowprotocol/services?tab=readme-ov-file#postgres))
20+
- **Ethereum RPC endpoint** — Required for blockchain access
21+
- Get a public endpoint from [Chainlist](https://chainlist.org/) (rate-limited)
22+
- **Alternative**: Use the [services playground setup](https://github.com/cowprotocol/services#playground) for a fully local environment
23+
24+
## Architecture Overview
25+
26+
```mermaid
27+
sequenceDiagram
28+
box cowprotocol/services - Rust
29+
participant autopilot
30+
participant driver
31+
end
32+
box solver
33+
participant solver engine
34+
end
35+
autopilot->>driver: auction
36+
driver->>solver engine: auction
37+
solver engine->>driver: set of solutions
38+
driver->>autopilot: the best solution or quote,<br> depending on the request
39+
autopilot->>driver: request to publish a settlement,<br>in case this solver won
40+
driver->>driver: encode and publish the settlement
41+
autopilot->>autopilot: detect when the settlement is published<br>by monitoring the blockchain
42+
```
43+
44+
## Setup Steps
45+
46+
### 1. Clone Required Repositories
47+
48+
```bash
49+
# Clone the CoW Protocol services (contains autopilot & driver)
50+
git clone https://github.com/cowprotocol/services.git
51+
52+
# Clone the Python solver template (in a separate directory)
53+
git clone https://github.com/cowprotocol/solver-template-py.git
54+
```
55+
56+
### 2. Install Python Solver Dependencies
57+
58+
Navigate to the solver template directory and install dependencies:
59+
60+
```bash
61+
cd solver-template-py
62+
63+
# Install dependencies with Poetry
64+
poetry install
65+
66+
# Verify installation
67+
poetry run python -c "from src.infra.settings import settings; print('✅ Config OK:', settings.solver.chain_id)"
68+
```
69+
70+
### 3. Test the Solver Setup
71+
72+
```bash
73+
# Test configuration system
74+
poetry run python -m pytest src/tests/test_config.py -v
75+
76+
# Show current configuration
77+
poetry run python -m src.infra.cli config
78+
```
79+
80+
### 4. Start Your Python Solver
81+
82+
The solver supports multiple engines in a single FastAPI application:
83+
84+
```bash
85+
# Using Makefile (Recommended)
86+
make run
87+
88+
# Or manually
89+
poetry run python -m src.infra.cli run
90+
91+
# Alternative methods
92+
poetry run python -m src._server
93+
poetry run uvicorn src.api.app:app --host 0.0.0.0 --port 8080
94+
```
95+
96+
The solver will start on `http://localhost:8080` with the following endpoints:
97+
- `GET /` - Root endpoint with service information
98+
- `GET /healthz` - Health check
99+
- `GET /metrics` - Prometheus metrics
100+
- `POST /baseline/solve` - Baseline solver engine
101+
- `POST /mysolver/solve` - MySolver engine (stub implementation)
102+
- `POST /solve` - Default solver (configurable via DEFAULT_SOLVER_ROUTE)
103+
104+
### 5. Test the Solver
105+
106+
```bash
107+
# Health check
108+
curl http://localhost:8080/healthz
109+
110+
# Test baseline solver
111+
curl -X POST "http://127.0.0.1:8080/baseline/solve" \
112+
-H "accept: application/json" \
113+
-H "Content-Type: application/json" \
114+
--data "@data/small_example.json"
115+
116+
# Test custom solver
117+
curl -X POST "http://127.0.0.1:8080/mysolver/solve" \
118+
-H "accept: application/json" \
119+
-H "Content-Type: application/json" \
120+
--data "@data/small_example.json"
121+
```
122+
123+
### 6. PostgreSQL Setup
124+
125+
The autopilot requires a PostgreSQL database to track auction state.
126+
Follow the [database setup instructions](https://github.com/cowprotocol/services?tab=readme-ov-file#postgres) in the services repository README.
127+
128+
### 7. Configure the Driver
129+
130+
The driver (services repository) configuration file tells the system where to find your solver and how to interact with it.
131+
Copy the example configuration from the Python solver template located at `examples/driver.toml` to your `services/crates/driver/` directory as `driver.toml`.
132+
133+
#### Key Configuration Changes from Default
134+
135+
The main modifications for Barn API setup:
136+
137+
- `orderbook-url`: Changed to `https://barn.api.cow.fi/mainnet/api` (staging environment)
138+
- `[[solver]]` blocks: Added Python solver endpoints pointing to `localhost:8080` (FastAPI default port)
139+
- `base-tokens`: Expanded list for better liquidity coverage
140+
- Test private key: Using a known test key (never use for production!)
141+
142+
### 8. Start the Driver
143+
144+
In a new terminal, from the `services` directory:
145+
146+
```bash
147+
cargo run --bin driver -- \
148+
--ethrpc "YOUR_RPC_ENDPOINT_HERE" \
149+
--config driver.toml
150+
```
151+
152+
Replace `YOUR_RPC_ENDPOINT_HERE` with your Ethereum RPC URL.
153+
154+
Example:
155+
156+
```bash
157+
cargo run --bin driver -- \
158+
--ethrpc "https://eth.llamarpc.com" \
159+
--config driver.toml
160+
```
161+
162+
### 9. Start the Autopilot
163+
164+
In another terminal, from the `services` directory:
165+
166+
```bash
167+
cargo run --bin autopilot -- \
168+
--node-url "YOUR_RPC_ENDPOINT_HERE" \
169+
--db-url "postgresql://postgres:password@localhost:5432/autopilot" \
170+
--drivers "baseline-python|http://localhost:11088/baseline-python|0x0000000000000000000000000000000000000000|0.1" \
171+
--drivers "python-solver|http://localhost:11088/python-solver|0x0000000000000000000000000000000000000000|0.1" \
172+
--native-price-estimators "baseline-python|http://localhost:11088/baseline-python" \
173+
--shadow "https://barn.api.cow.fi/mainnet/"
174+
```
175+
176+
**Command Breakdown:**
177+
178+
- `--node-url`: Your Ethereum RPC endpoint
179+
- `--db-url`: PostgreSQL connection string
180+
- `--drivers`: Solver configurations in format `name|endpoint|address|priority`
181+
- The endpoint uses port `11088` (driver's internal port)
182+
- Address `0x0000...` means using the account from driver config
183+
- Priority `0.1` is a weight factor for solver selection
184+
- `--native-price-estimators`: Required parameter, points to a solver for price estimation
185+
- `--shadow`: Barn API URL for fetching live auction data
186+
187+
Optional: To also run the Rust baseline solver for comparison:
188+
189+
```bash
190+
# Add this line to the autopilot command above
191+
--drivers "baseline|http://localhost:11088/baseline|0x0000000000000000000000000000000000000000|0.1"
192+
```
193+
194+
## Verifying Your Setup
195+
196+
### Check Solver Health
197+
198+
```bash
199+
# Test baseline endpoint
200+
curl http://127.0.0.1:8080/baseline/health
201+
202+
# Test custom solver endpoint
203+
curl http://127.0.0.1:8080/mysolver/health
204+
```
205+
206+
### Understanding the Flow
207+
208+
1. Autopilot fetches new auctions from Barn API periodically.
209+
2. Driver receives auction data and forwards it to all configured solvers.
210+
3. Your Python solver receives the auction, computes a solution, returns it.
211+
4. Driver evaluates all solutions and selects the best one.
212+
5. Autopilot manages solution submission (in staging, solutions aren't actually submitted on-chain).
213+
214+
## Place an Order
215+
216+
Navigate to [barn.cow.fi/](https://barn.cow.fi/) and place a tiny (real) order. You should see your driver pick it up and include it in the next auction being sent to your solver.
217+
218+
## Next Steps
219+
220+
### Development Workflow
221+
222+
- Modify and create your solver logic in `src/engines/mysolver/`
223+
- Use `make format` to format your code with Black
224+
- Run `make test` to execute the test suite
225+
226+
### Advanced Topics
227+
228+
- Multiple solvers: Add more `[[solver]]` blocks to test different strategies.
229+
- Custom liquidity sources: Modify the `[liquidity]` section in `driver.toml`.
230+
- Production deployment: See Orderbook API documentation for production endpoints.
231+
- Rust baseline solver: Full implementation available in the services repository.
232+
233+
### Getting Help
234+
235+
- Check the [CoW Protocol documentation](https://docs.cow.fi/)
236+
- Review the [services repository](https://github.com/cowprotocol/services) for additional context
237+
- Join the [CoW Protocol Discord](https://discord.gg/cowprotocol) for community support
238+
239+
---
240+
241+
**Ready to start developing?** Check out the [main README](README.md) for detailed information about the solver template architecture and development workflow.

0 commit comments

Comments
 (0)