Create baseline solver by jeffersonBastos · Pull Request #37 · cowprotocol/solver-template-py

jeffersonBastos · 2025-10-02T18:03:55Z

Overview

This PR introduces the baseline solver implementation in Python, ported from the Rust version, and refactors the template into a multi-engine architecture.
The goal is to provide Python developers with:

A ready-to-use baseline solver for comparison and testing,
A mysolver/solve endpoint as a clean starting point for new solver implementations,
A modernized, modular, and testable project structure.
Improved documentation with a Quick Start guide on integrating and extending this solver.

Key Changes

🆕 New Features

Baseline Solver Engine
- Added BaselineEngine (/baseline/solve) implementing a contract-correct, minimal solver.
- Includes core modules: matcher, pathfinding, pool management, solution builder, contract interactions.
Multi-Engine System
- Introduced SolverEngine base class for pluggable engines.
- Added mysolver/solve endpoint (stubbed for user implementations).
New Domain & Utility Modules
- Domain: auction, order, solution, liquidity, common.
- Utilities: AMM math, bytes/hex conversion, serialization.
Infrastructure Improvements
- Pydantic v2 models with Rust-aligned DTOs.
- Structured logging, Prometheus metrics, and health checks.
- CLI entrypoints for local development.

🔄 Refactors & Migrations

Single App: Consolidated legacy server into one FastAPI app.
Routers: Modular API routing (/baseline, /mysolver).
Project Structure: Full reorganization to domain-driven architecture.
Removed Legacy Models & Utils: Old src/models and src/util replaced with domain + utils modules.

🗑️ Deletions

Removed outdated legacy models (batch_auction, order, token, etc.).
Removed old test files, replaced with comprehensive new suite.
Dropped unused Docker setup (development now CLI-based).

Motivation

Provide Python developers with the same onboarding experience Rust solvers already have.
Allow baseline vs custom solver races locally, without requiring Rust knowledge.
Improve maintainability, modularity, and testability for long-term growth.

Next Steps

Add more comprehensive validation tests with complete auctions, similar to Rust’s coverage.
Ensure parity validation with the Rust baseline solver.
Explore performance improvements.
We are open to feedback and suggestions — this is just the first version.

- Fix fundamental schema incompatibility with current CoW infrastructure - Update models to use snake_case with Pydantic aliases for camelCase JSON - Replace legacy BatchAuction with CowAuction matching solvers_dto - Add proper field aliases (sellToken -> sell_token, etc.) - Remove incompatible legacy models and utilities - Update server endpoint to use new schema structure - Organize template structure with examples and reference materials Resolves schema validation errors (422) when receiving auctions from driver. Template now works seamlessly with current CoW Protocol infrastructure.

- Add typer for CLI support - Add prometheus-client for metrics - Update version constraints for better compatibility - Organize dependencies by category (core, dev, optional)

- Add multi-engine solver architecture with baseline and mysolver engines - Implement FastAPI application with health, metrics, and solve endpoints - Add comprehensive model definitions for auction, order, liquidity, and solution - Include utility modules for serialization, math operations, and byte conversion - Add CLI interface with typer for running the solver server - Implement dependency injection and settings management - Add comprehensive test suite for API, models, and multi-engine functionality - Include logging and metrics infrastructure with Prometheus support

- Replace custom FastAPI implementation with python_baseline.api.app - Remove duplicate endpoint definitions and middleware setup - Simplify server configuration by delegating to main solver application - Maintain backward compatibility for existing server startup process

- Add comprehensive documentation for new multi-engine architecture - Include examples for baseline, mysolver, and default engine endpoints - Update health check endpoint from /health to /healthz - Add Prometheus metrics endpoint documentation - Update driver configuration examples with new port (11088) - Add autopilot configuration examples for different solver engines - Maintain backward compatibility documentation for legacy server

- Move python_baseline/ to src/ with clean structure - Separate API routers (baseline, mysolver) - Move models to domain/ - Update all imports from python_baseline.* to src.* - Remove legacy files and duplicates - Improve project organization and maintainability

- Add Web3 and blockchain dependencies (web3, eth-typing, eth-utils, eth-abi, hexbytes) - Add optimization libraries (networkx for pathfinding, scipy for math) - Implement baseline solver engine with two-phase approach: * CoW (Coincidence of Wants) matching for direct order settlement * AMM routing through liquidity pools using NetworkX pathfinding - Add comprehensive AMM math utilities for Uniswap V2, Balancer, and Curve pools - Create solution builder for transaction construction and settlement - Add partial fill optimization framework and gas estimation utilities - Add comprehensive test coverage for baseline engine - Remove obsolete test files and update domain models - Fix pydantic field_validator imports and type annotations

- Simplify domain models by removing custom U256/Address types - Migrate to Pydantic v2 field validators - Add centralized fee conversion utilities - Update solver configurations with Python and baseline endpoints - Expand base token list with popular tokens (WETH, DAI, USDC, USDT, etc.) - Add Uniswap V2 configuration support - Integrate Web3 for robust Ethereum address validation - Remove deprecated utility modules (hexbytes, u256) - Update interaction encoding to use HexBytes - Improve type safety with proper address validation

…ver-on-python-template Add Python Baseline Solver & Multi-Engine Architecture

…ests Update README and create QUICKSTART doc

socket-security · 2025-10-02T18:04:24Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Package	Supply Chain Security	Vulnerability	License
poetry-core@2.3.1
mypy@0.942 ⏵ 1.19.1	⁺¹
scipy@1.17.1
black@22.3.0 ⏵ 26.1.0	^-3	⁺²
pytest@7.1.1 ⏵ 9.0.2	^-8
pylint@2.13.5 ⏵ 4.0.5	^-1
web3@7.14.1
networkx@3.6.1
uvicorn@0.17.6 ⏵ 0.41.0
prometheus-client@0.24.1
python-dotenv@0.20.0 ⏵ 1.2.1			⁺³¹
typer@0.24.1
pydantic@1.9.0 ⏵ 2.12.5	⁺⁸	⁺²
eth-utils@5.3.1
makefun@1.13.1 ⏵ 1.16.0	⁺¹
eth-typing@5.2.1
eth-abi@5.2.0
pydantic-settings@2.13.1
httpx@0.28.1
hexbytes@1.3.1
fastapi@0.65.2 ⏵ 0.133.0	⁺¹

View full report

jeffersonBastos · 2025-10-08T12:10:33Z

I have read the CLA Document and I hereby sign the CLA

…eline - solution: Trade as fulfillment (kind, order, executedAmount), camelCase aliases and field_serializer for callData; Interaction/Allowance/Asset; JitTrade, LiquidityInteraction, Solution alias and populate_by_name - api: return JSONResponse with model_dump(by_alias=True) for correct serialization; simplify notify handler - engine: pass orders dict to PriceFinder; Trade creation with fulfillment format; matched_uids from trade.order - cow_matcher: build Trade with kind/order/executed_amount - price_finder: accept orders dict, resolve sell/buy token and amounts from Order for price graph; TYPE_CHECKING for Order - path_finder: liquidity kind constantProduct/weightedProduct (lowercase) - solution_builder: drop per-trade price backfill; validate order UID and executed_amount instead of sell/buy token prices - domain: Order.fee_amount (optional); auction/solution model_config and aliases - data: large_example.json numeric and trailing newline fixes

jeffersonBastos added 30 commits September 10, 2025 15:39

feat: update requirements (pydantic, fastapi and uvicorn)

463415f

feat: update README and remove Docker initialization option

679ec9b

chore: add .tool-versions for development environment setup

15e74a5

chore: update requirements.txt with new dependencies and structure

cceb62c

- Add typer for CLI support - Add prometheus-client for metrics - Update version constraints for better compatibility - Organize dependencies by category (core, dev, optional)

feat: add solver configuration system with pydantic

23d8d34

fix: add log_format at settings

7b36934

fix: move validate_auction to shared folder

376cdfc

fix: adjust _generate_solution_id function to follow Rust implementation

de7a0dd

chore: rename pathfinder to path_finder

f18eb6a

feat: implement AMM integration for baseline solver

b06289b

fix: change solution id from string to integer

ead33cc

feat: add notify route

a9c8243

fix: update to Pydantic v2 syntax

43511c6

fix: remove unused functions and file

c4e5dd9

chore: format code

7a82660

chore: remove legacy test

acd0f5d

feat: create Makefile

cbf6b04

fix: adjust tests

c86b649

chore: update README

5ea6be0

fix: delete unused files

c01839f

fix: remove web3 and networkx fallback

4a53324

chore: remove dockerignore file

71ab5d2

fix: pydantic_settings import

3681406

refactor: consolidate metrics and remove redundant code

56780cc

jeffersonBastos and others added 10 commits September 29, 2025 10:57

feat: add TODO tags for non-production ready parts

dc4e439

feat: migrate from venv/pip to Poetry for dependency management

47b08bb

feat: update github workdlow to use Poetry and create DockerFile

bc52136

fix: adjust readme and MakeFile

37d1f64

fix: adjust pull-request.yaml

29b40af

Merge pull request #4 from bleu/jefferson/cow-523-create-baseline-sol…

67f3009

…ver-on-python-template Add Python Baseline Solver & Multi-Engine Architecture

chore: remove unused files and update README

0841a70

feat: add QUICKSTART docs and update README.

a0cb97d

Merge pull request #5 from bleu/jefferson/cow-526-baseline-docs-and-t…

0ee38f6

…ests Update README and create QUICKSTART doc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Create baseline solver#37

Create baseline solver#37
jeffersonBastos wants to merge 41 commits intocowprotocol:mainfrom
bleu:refactor/create-baseline

jeffersonBastos commented Oct 2, 2025

Uh oh!

socket-security bot commented Oct 2, 2025 •

edited

Loading

Uh oh!

jeffersonBastos commented Oct 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

jeffersonBastos commented Oct 2, 2025

Overview

Key Changes

🆕 New Features

🔄 Refactors & Migrations

🗑️ Deletions

Motivation

Next Steps

Uh oh!

socket-security bot commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeffersonBastos commented Oct 8, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

socket-security bot commented Oct 2, 2025 •

edited

Loading