Skip to main content
This guide walks you through setting up a complete development environment for CoW Protocol Services.

​
Prerequisites

Before you begin, ensure you have the following installed:
1

Rust 2024 Edition

Install Rust using rustup. The project uses Rust 2024 Edition.
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup toolchain install stable --profile minimal
rustup toolchain install nightly --profile minimal
Verify your installation:
rustup --version
rustc --version
cargo --version
2

Docker & Docker Compose

Required for running PostgreSQL and the playground environment.Verify installation:
docker --version
docker compose version
3

Foundry (anvil)

Required for running forked network tests. Install Foundry which includes anvil:
curl -L https://foundry.paradigm.xyz | bash
foundryup
Verify anvil is available:
anvil --version
The anvil binary path is configurable via the ANVIL_COMMAND environment variable. It defaults to "anvil" and must be in your PATH.
4

cargo-nextest

The project uses cargo-nextest for running tests (CI requirement).
cargo install cargo-nextest --locked
Do not use cargo test - always use cargo nextest run. The CI uses nextest and handles global state differently, which can cause tests to fail with cargo test.
5

Just (Optional but Recommended)

The project includes a Justfile with convenient commands.
cargo install just
View available commands:
just --list
6

Tombi (Optional)

For TOML file formatting:
cargo install tombi
Editor extensions available for VS Code, Zed, and JetBrains.

​
Clone the Repository

git clone https://github.com/cowprotocol/services.git
cd services

​
Install Dependencies

Rust dependencies are managed through Cargo.toml. They’ll be downloaded automatically during the first build: 
cargo build
The first build will take some time as it downloads and compiles all dependencies. Subsequent builds will be much faster thanks to cargo’s incremental compilation.

​
Database Setup

Many tests and local development require PostgreSQL.
1

Start PostgreSQL with Docker Compose

docker compose up -d
This will:
  • Start a PostgreSQL container on port 5432
  • Automatically run database migrations
2

Verify Database Connection

docker compose ps
You should see the db container running.
3

Access Database (Optional)

Using the included Adminer web interface:
docker compose up -d adminer
Then visit: http://localhost:8082

​
Environment Variables

​
For Forked Network Tests

To run E2E tests against forked networks, you need RPC endpoints:
.env
export FORK_URL_MAINNET="https://mainnet.infura.io/v3/YOUR_KEY"
export FORK_URL_GNOSIS="https://rpc.gnosischain.com"
Refer to Chainlist for Mainnet RPCs and Gnosis RPC Providers for Gnosis RPCs.

​
For Playground Development

See the Playground guide for playground-specific environment configuration.

​
Building the Services

cargo build
The workspace includes 25+ crates. Main binaries:
  • orderbook - HTTP API for orders
  • autopilot - Auction manager
  • driver - Solution execution
  • solvers - Internal solver engine
  • refunder - Handles refunds

​
IDE Setup Recommendations

​
Visual Studio Code

Recommended Extensions: Settings (.vscode/settings.json): 
{
  "rust-analyzer.cargo.features": "all",
  "rust-analyzer.checkOnSave.command": "clippy",
  "rust-analyzer.rustfmt.extraArgs": ["+nightly"],
  "[rust]": {
    "editor.defaultFormatter": "rust-lang.rust-analyzer",
    "editor.formatOnSave": true
  }
}

​
JetBrains IDEs (IntelliJ IDEA, RustRover, CLion)

Plugins:
  • Rust - Official Rust plugin
  • Tombi - TOML formatting
Configure rustfmt:
  1. Go to Settings → Languages & Frameworks → Rust → Rustfmt
  2. Set Toolchain to nightly
  3. Enable Run rustfmt on Save

​
Zed

Extensions: Settings: 
{
  "languages": {
    "Rust": {
      "format_on_save": "on",
      "formatter": "language_server"
    }
  }
}

​
Verify Your Setup

Run these commands to ensure everything is working:
1

Run unit tests

cargo nextest run
or
just test-unit
2

Run database tests

Ensure PostgreSQL is running:
docker compose up -d
Then run:
just test-db
3

Check code formatting

just fmt --check
4

Run clippy linter

just clippy

​
Next Steps

Testing Guide

Learn how to write and run tests

Playground

Set up the full local development stack

Contributing

Guidelines for contributing code

Architecture

Understand the system architecture

​
Troubleshooting

​
Compilation Errors

Install build essentials:
sudo apt-get install build-essential pkg-config libssl-dev
Install Xcode command line tools:
xcode-select --install
Reduce parallel compilation:
cargo build -j 2

​
Database Connection Issues

Stop any existing PostgreSQL instance:
# macOS
brew services stop postgresql

# Linux
sudo systemctl stop postgresql
Reset Docker volumes:
docker compose down --volumes
docker compose up -d

Build docs developers (and LLMs) love

Get started for freeTalk to us