BYOS Contracts

Solidity contracts for the Bring Your Own Solver (BYOS) project — a bonded CoW Protocol solver that sources proposed solutions from a permissionless set of external sub-solvers. Source RFP: Bring Your Own Solver (BYOS).

Contracts

Contract	Status	Description
Escrow	implemented	Per-chain, native-token collateral keyed by sub-solver address. Deposits, debits (Track A revert penalties / Track B EBBO passthrough), freeze/unfreeze, and all-or-nothing withdrawal with cooldown. First deposit for a sub-solver deploys its Trampoline.
Trampoline	implemented	Per-sub-solver execution sandbox: verifies the sub-solver's EIP-712 proposal signature (including the route hash and expiry), runs the signed route in a fund-less context, and settles back exactly buyAmount to GPv2Settlement (native ETH via the 0xeee… marker). Immutable, no admin key.
TrampolineFactory	implemented	CREATE2 deployer for Trampoline instances (salt = sub-solver address) and the EIP-712 domain anchor for proposal signatures. ensureDeployed is idempotent and permissionless.

Architecture

Sub-solvers submit EIP-712-signed routing proposals to BYOS, collateralized by their escrow balance. BYOS retains exclusive control over on-chain settlement. The Escrow contract is the only sub-solver capital BYOS touches — trade capital flows atomically through GPv2Settlement.

Domain language and the architecture map live in CONTEXT.md. CoW protocol background (slashing framework, auction mechanics, solver CIPs) is under docs/reference/.

See docs/adr/ for architecture decision records:

• ADR-0001 — Trampoline topology (one instance per sub-solver)
• ADR-0002 — Escrow contract design
• ADR-0003 — Trampoline deployment & settlement integration
• ADR-0004 — Penalty schedule & attribution
• ADR-0005 — Trampoline execution authority & proposal signature

Development

Prerequisites

• Foundry

Build

forge build

Test

forge test

The fork suite (test/fork/) drives a real GPv2Settlement.settle() on mainnet state. It uses a public RPC endpoint by default; set MAINNET_RPC_URL to use your own, or set it to an empty string to skip the suite (e.g. offline):

forge test --match-path 'test/fork/*'          # public endpoint
MAINNET_RPC_URL=<url> forge test               # custom endpoint
MAINNET_RPC_URL= forge test                    # skip fork tests

Deploy

ESCROW_ADMIN=<address> ESCROW_OPERATOR=<address> BYOS_SUBMITTERS=<addr1>,<addr2> \
  forge script script/Deploy.s.sol --broadcast

Deploys the TrampolineFactory and the Escrow wired to it. See script/Deploy.s.sol for the optional parameters and their defaults.

License

LGPL-3.0-or-later