@cowprotocol/contracts

CoW Protocol

This repository contains the Solidity smart contract code for the CoW Protocol (formerly known as Gnosis Protocol).

For more documentation on how the protocol works on a smart contract level, see the documentation pages.

Getting Started

Building the Project

yarn
yarn build

Running Tests

yarn test

The tests can be run in "debug mode" as follows:

DEBUG=* yarn test

Gas Reporter

Gas consumption can be reported by setting the REPORT_GAS flag when running tests as

REPORT_GAS=1 yarn test

Benchmarking

This repository additionally includes tools for gas benchmarking and tracing.

In order to run a gas benchmark on a whole bunch of settlement scenarios:

yarn bench

These gas benchmarks can be compared against any other git reference and will default to the merge-base if omitted:

yarn bench:compare [<ref>]

In order to get a detailed trace of a settlement to identify how much gas is being spent where:

yarn bench:trace

Deployment

Deploying Contracts

Choose the network and gas price in wei for the deployment. After replacing these values, run:

NETWORK='rinkeby'
GAS_PRICE_WEI='1000000000'
yarn deploy --network $NETWORK --gasprice $GAS_PRICE_WEI

New files containing details of this deployment will be created in the deployment folder. These files should be committed to this repository.

Verify Deployed Contracts

Etherscan

For verifying all deployed contracts:

export ETHERSCAN_API_KEY=<Your Key>
yarn verify:etherscan --network $NETWORK

Single contracts can be verified as well, but the constructor arguments must be explicitly given to the command. A common example is the vault relayer contract, which is not automatically verified with the command above since it is only deployed indirectly during initialization. This contract can be manually verified with:

npx hardhat verify --network $NETWORK 0xC92E8bdf79f0507f65a392b0ab4667716BFE0110  0xBA12222222228d8Ba445958a75a0704d566BF2C8

The first address is the vault relayer address, the second is the deployment input (usually, the Balancer vault).

Tenderly

For verifying all deployed contracts:

yarn verify:tenderly --network $NETWORK

For a single contract, named GPv2Contract and located at address 0xFeDbc87123caF3925145e1bD1Be844c03b36722f in the example:

npx hardhat tenderly:verify --network $NETWORK GPv2Contract=0xFeDbc87123caF3925145e1bD1Be844c03b36722f

Deployed Contract Addresses

This package additionally contains a networks.json file at the root with the address of each deployed contract as well the hash of the Ethereum transaction used to create the contract.

Test coverage

Test coverage can be checked with the command

yarn coverage

A summary of coverage results are printed out to console. More detailed information is presented in the generated file coverage/index.html.

Known issues

If a user creates an order with:

• zero sell amount
• zero buy amount
• partially fillable set to false

then this order could be executed an arbitrary amount of times instead of just a single time. This means that any solver could drain the fee amount from the user until not enough funds are available anymore.

We recommend to never sign orders of this form and, if developing a contract that creates orders on behalf of other users, make sure at a contract level that such orders cannot be created.

Helper scripts

A collection of tools for interacting with the CoW Swap contracts.

Solver Authentication

This repo contains scripts to manage the list of authenticated solvers in all networks the contract has been deployed.

The scripts are called with:

yarn solvers command [arg ...]

Here is a list of available commands. The commands flagged with [**] require exporting the private key of the authentication contract owner, while those flagged with [*] require the address of either the owner or the manager. The private key can be exported with export PK=<private key>.

1. add $ADDRESS [*]. Adds the address to the list of registered solvers.
2. remove $ADDRESS [*]. Removes the address from the list of registered solvers.
3. check $ADDRESS. Checks if the given address is in the list of registered solvers.
4. list. Lists all registered solvers.
5. setManager $ADDRESS [**]. Sets the manager of the authenticator to the input address.

For example, adding the address 0x0000000000000000000000000000000000000042 to the solver list:

export PK=<private key>
yarn solvers add 0x0000000000000000000000000000000000000042

Transfer Ownership

There is a dedicated script to change the owner of the authenticator proxy.

Usage and parameters can be seen by running:

yarn hardhat transfer-ownership --help

Fee Withdrawals

Script to withdraw all balances of the Settlement contract. Allows to specify what minimum value the contract must have for a token to be considered (breadcrumbs might not be worth the gas costs) and how much remaining value should be left in the contract (e.g. to feed token buffers).

If no token list is passed in all traded token balances will be fetched from chain (can take a long time...)

export PK=<private key>
yarn hardhat withdraw --receiver 0x6C2999B6B1fAD608ECEA71B926D68Ee6c62BeEf8 --min-value 10000 --leftover 500 0x038a68ff68c393373ec894015816e33ad41bd564 0x913d8adf7ce6986a8cbfee5a54725d9eea4f0729

Decoding Settlement CallData

This project exposes some handy scripts for parsing settlement calldata into human readable format.

The decode script can be used in two ways:

1. By specifying the transaction hash of an existing settlement transaction --txhash 0x...

npx hardhat decode --txhash 0xc12e5bc2ef9c116932301495738d555ea1d658977dacd6c7989a6d77125a17d2 --network mainnet

2. When no txhash is specified, by reading the calldata from stdin (< calldata.txt). If stdin is a terminal, the user is prompted to paste the calldata into the terminal.

> npx hardhat decode --network mainnet
# Paste in the calldata to decode

Note that you will be expected to have your INFURA_KEY exported to your environment variables.

Releases

The content of this repo is published on NPM as @cowprotocol/contracts.

Maintainers this repository can manually trigger a new release. The steps are as follows:

1. Update the package version number in ./package.json on branch main.

2. On GitHub, visit the "Actions" tab, "Publish package to NPM", "Run workflow" with main as the target branch.

Once the workflow has been executed successfully, a new NPM package version should be available as well as a new git tag named after the released version.