Skip to content

fix: replace barn.cow.fi with dev.cow.fi #606

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alfetopito wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: replace barn.cow.fi with dev.cow.fi #606

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 44 additions & 19 deletions docs/cow-protocol/tutorials/solvers/onboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,15 @@ sidebar_position: 1
---

# Joining The CoW Protocol Solver Competition

> **_NOTE:_** In order to get connected to the shadow competition, feel free to reach out to an admin of the ["CoW Swap Solvers"](https://t.me/+2Z_-DW57meA1MDlh) group on Telegram.

> **_NOTE:_** Most of this document assumes that you will be joining the solver competition under the CoW DAO bonding pool. If you were to set up your own bonding pool then most of the information in this document is either optional or irrelevant. To join the solver competition under your own bonding pool refer to [this document](https://docs.cow.fi/cow-protocol/reference/core/auctions/bonding-pools) and reach out to help set up the bonding pool and whitelist your solver's address.

![General process for joining the solver competition](solver_onboarding_process.jpg)

## Index

1. Essential information
2. Locally developing your solver
3. Joining the shadow competition
Expand All @@ -25,25 +27,30 @@ sidebar_position: 1
## 1. Essential information for joining the solver competition

### Requirements for joining the CoW DAO bonding pool

The general KYC requirements are to send us documentation proving that you are the beneficial owners of the company behind the solver and 1-2 passports of some of the main developers of the solver. Do not send this before the meeting, we will explain the process during the meeting so that you can send the documents afterwards.

Given the risk that will be carried by the CoW DAO bonding pool we also ask that solvers who join the solver competition through the CoW DAO bonding pool start solving on Arbitrum first. After being in production on Arbitrum solvers can move to other L2's relatively easily. But joining the mainnet competition will require further evaluation after some time of solving on L2's.

### Service fees

As specified in [CIP-48](https://snapshot.box/#/s:cow.eth/proposal/0x563ab9a66265ad72c47a8e55f620f927685dd07d4d49f6d1812905c683f05805) solvers that are part of the CoW DAO bonding pool will be charged a service fee that is withheld from their weekly rewards. This fee will begin six months after the solver has joined the CoW Bonding pool and will encompass 15% of the weekly COW rewards that the solver would have received.

## 2. Locally developing your solver

The first step to joining the solver competition is to set up a solver. We have a [local set up guide](https://docs.cow.fi/cow-protocol/tutorials/solvers/local_test) that can help you set up a solver locally. There are also open-source example solvers available in the [solvers crate](https://github.com/cowprotocol/services/tree/main/crates/solvers) that you can use as a starting point for developing your solver.

API specification: https://github.com/cowprotocol/services/blob/main/crates/solvers/openapi.yml
API specification: <https://github.com/cowprotocol/services/blob/main/crates/solvers/openapi.yml>

## 3. Joining the shadow (test) competition
Once you have a solver running locally you can join the shadow competition to start testing your solver using CoW Protocol's order flow.

Once you have a solver running locally you can join the shadow competition to start testing your solver using CoW Protocol's order flow.

If you would like to secure your solver, you can set up a firewall and only accept requests from IP addresses that you whitelist beforehand. Contact us for the IP addresses that we use to send requests to your solver that you can whitelist.

### Exposed Endpoint
The exposed endpoint provided must be of the following format: {base_url}/\${envName}/\${network} - for example: https://api.mysolver.io/staging/mainnet

The exposed endpoint provided must be of the following format: {base_url}/\${envName}/\${network} - for example: <https://api.mysolver.io/staging/mainnet>
envName values: shadow, staging, prod
supported networks: arbitrum-one, avalanche, base, bnb, mainnet, xdai (gnosis), ink, linea, plasma, optimism, polygon, sepolia, and more are coming out!

Expand All @@ -52,23 +59,29 @@ The `/solve` response sent to your solver is quite large. If you are using Nginx
:::

### Driver configuration for your solver
There are various configurations for your solver in the driver to help you optimize your solver:

There are various configurations for your solver in the driver to help you optimize your solver:

#### - Wrapping / unwrapping native tokens

The default behavior for the driver is to set the native token address to `0xeee` and to insert interactions into your solution to unwrap the native token. It's also possible to configure this to either send the wrapped token address (WETH) and unwrap the native token, or send the wrapped token address and not unwrap the native token.

#### - Liquidity fetching

It is possible to enable or disable liquidity fetching for your solver. If this is enabled, the driver will search for on-chain liquidity sources for your solver to use and send them to your solver. [Docs](https://docs.cow.fi/cow-protocol/tutorials/arbitrate/solver/driver#fetching-liquidity)

#### - Fairness checks for EBBO
To ensure a fair execution for the users there are several EBBO rules that are maintained in the auction. Usually, an EBBO violation means that a reference pool from the base protocol would have given the user a better price than what they ended up receiving.

To ensure a fair execution for the users there are several EBBO rules that are maintained in the auction. Usually, an EBBO violation means that a reference pool from the base protocol would have given the user a better price than what they ended up receiving.

In the event of an EBBO violation the team will reach out and ask you to reimburse the user. [Docs](https://docs.cow.fi/cow-protocol/reference/core/auctions/ebbo-rules)

#### - Merging disjoint solutions

It is possible for your solver to submit multiple solutions for a single auction and let the driver select the solution with the highest score to submit to the auction. It is possible to enable the driver to merge disjoint solutions into a single solution for the auction. [Docs](https://docs.cow.fi/cow-protocol/tutorials/arbitrate/solver/driver#postprocessing-solutions)

## 4. KYC checks and onboarding call

Once your solver is tested and ready to join the solver competition, it is time to start the onboarding process. At this point, it would be best to reach out to the team on Telegram to schedule an onboarding call. During this call the team will go over the onboarding process and discuss the next steps.

The main goal of the onboarding call is to both make sure that your team understands everything they need to know related to the solver competition, and for everyone to get to know each other. The main structure of these calls is:
Expand All @@ -86,62 +99,73 @@ The main goal of the onboarding call is to both make sure that your team underst
- The slippage accounting process and weekly rewards

## 5. Joining the staging (barn) competition
After the onboarding call, the CoW team will begin preparing the required infrastructure for your solver to join the solver competition. If you are joining the solver competition under the CoW DAO bonding pool, then this will involve setting up and managing the driver on your behalf and setting up and managing the submission keys on your behalf.

After the onboarding call, the CoW team will begin preparing the required infrastructure for your solver to join the solver competition. If you are joining the solver competition under the CoW DAO bonding pool, then this will involve setting up and managing the driver on your behalf and setting up and managing the submission keys on your behalf.

To do this, the team will generate keys for your solver to use for settling auctions on-chain and whitelisting those for the solver competition. In order to do this you will need to send a `rewards address` that you would like to use to receive weekly rewards on the chain that you are solving on. Specifically, the rewards address needs to be controlled by the relevant solver team on both the chain it is currently solving and on mainnet, as we send native token transfers to the chain the solver is active while we send COW rewards to the mainnet address always.

After this process is done, the team will send you the submission addresses that your solver will use to settle auctions on-chain. While this is managed by the CoW team, it will be your responsibility to monitor this and make sure that is holds enough funds to cover gas fees. The driver has a minimum threshold for gas that it applies to make sure that the address holds (more than) enough funds to pay the required gas fees. Therefore we recommend these balances:

| Network | Environment | Recommended initial balance |
|---|---|---|
| Mainnet | Staging | 0.2 ETH |
| Mainnet | Production | 1 ETH |
| Arbitrum | Staging | 0.05 ETH |
| Arbitrum | Production | 0.2 ETH |
| Base | Staging | 0.05 ETH |
| Base | Production | 0.2 ETH |
| Gnosis | Staging | 15 xDAI |
| Gnosis | Production | 100 xDAI |
| Network | Environment | Recommended initial balance |
| -------- | ----------- | --------------------------- |
| Mainnet | Staging | 0.2 ETH |
| Mainnet | Production | 1 ETH |
| Arbitrum | Staging | 0.05 ETH |
| Arbitrum | Production | 0.2 ETH |
| Base | Staging | 0.05 ETH |
| Base | Production | 0.2 ETH |
| Gnosis | Staging | 15 xDAI |
| Gnosis | Production | 100 xDAI |

> **_NOTE:_** Please send the funds in the native currency of the chain that these addresses will be solving on. So for a submission address generated for your solver on Arbitrum, send the funds in ETH on the Arbitrum network.

After your solver is live and begins settling transactions, it will be your responsibility to monitor these addresses and to make sure that they hold enough funds to settle transactions for winning auctions.

In order to create some volume to test your solver, you can create orders on staging by using our barn swap interface ([https://barn.cow.fi](https://barn.cow.fi)).
In order to create some volume to test your solver, you can create orders on staging by using our dev swap interface ([https://dev.cow.fi](https://dev.cow.fi)).
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Find all barn subdomain references in documentation

# Search for barn.cow.fi and barn.api.cow.fi references
echo "=== References to barn.cow.fi ==="
rg -n "barn\.cow\.fi" docs/

echo -e "\n=== References to barn.api.cow.fi ==="
rg -n "barn\.api\.cow\.fi" docs/

Repository: cowprotocol/docs

Length of output: 2417

🏁 Script executed:

#!/bin/bash
# Check for references to dev.cow.fi
echo "=== References to dev.cow.fi ==="
rg -n "dev\.cow\.fi" docs/

# Get context around the onboard.md reference
echo -e "\n=== Context around onboard.md line 124 ==="
sed -n '120,130p' docs/cow-protocol/tutorials/solvers/onboard.md

# Get context around the local_test.md table
echo -e "\n=== Context around local_test.md table ==="
sed -n '45,75p' docs/cow-protocol/tutorials/solvers/local_test.md

Repository: cowprotocol/docs

Length of output: 3335

🏁 Script executed:

#!/bin/bash
# Check for references to staging environment across all docs
echo "=== References to 'staging' ==="
rg -n "staging" docs/cow-protocol/tutorials/solvers/ | head -20

# Check for 'barn' references with more context
echo -e "\n=== barn references with context ==="
rg -n "barn" docs/cow-protocol/tutorials/solvers/ -B 2 -A 2

# Check for other swap interface references
echo -e "\n=== Other references to swap interface ==="
rg -n "swap interface\|swap UI" docs/ -i

Repository: cowprotocol/docs

Length of output: 10985

Update swap interface reference to match staging (barn) naming convention.

Line 124 uses dev.cow.fi for the staging swap interface, but this breaks the established naming convention used throughout the documentation. The staging environment is consistently referred to as "barn" elsewhere in this file (line 101: "staging (barn) competition") and across the solver documentation, where all staging endpoints use the barn.* subdomain pattern (barn.api.cow.fi, barn.gnosis-protocol.io, etc.).

Update dev.cow.fi to align with the barn naming convention for consistency.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/cow-protocol/tutorials/solvers/onboard.md` at line 124, Replace the
staging swap interface URL that currently points to "https://dev.cow.fi" with
the barn staging domain "https://barn.cow.fi" in the onboarding doc; locate the
occurrence of the dev.cow.fi link in the "onboard.md" content (the line that
instructs using the dev swap interface) and update the hyperlink and any
plain-text references to follow the barn.* naming convention used elsewhere
(e.g., barn.cow.fi).

Copy link
Copy Markdown
Contributor Author

@alfetopito alfetopito Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a backend staging env called barn (barn.api.cow.fi), and a frontend semi-stating env called barn (barn.cow.fi).
The frontend one is being removed, and instead the dev (dev.swap.cow.fi) should be used instead.
That's the point of this change.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alfetopito, thanks for the clarification! I misidentified the two distinct barn environments. The backend staging API (barn.api.cow.fi) is separate from the frontend swap interface (barn.cow.fi), and since the frontend one is being decommissioned in favour of dev.cow.fi, the change in this PR is correct. I'll withdraw my concern.

✏️ Learnings added 
Learnt from: alfetopito
Repo: cowprotocol/docs PR: 606
File: docs/cow-protocol/tutorials/solvers/onboard.md:124-124
Timestamp: 2026-03-26T09:21:38.746Z
Learning: In the CoW Protocol docs (cowprotocol/docs), there are two distinct "barn" environments:
1. Backend staging API: `barn.api.cow.fi` — this continues to exist and should remain referenced as `barn`.
2. Frontend semi-staging swap interface: `barn.cow.fi` — this is being removed/decommissioned and replaced with `dev.cow.fi` (also known as `dev.swap.cow.fi`).
When reviewing docs that reference `barn.cow.fi` vs `dev.cow.fi`, do NOT flag replacement of `barn.cow.fi` → `dev.cow.fi` as inconsistent; it is intentional and correct.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

🧠 Learnings used 
Learnt from: MarcusWentz
Repo: cowprotocol/docs PR: 586
File: docs/cow-protocol/tutorials/solvers/local_test.md:26-31
Timestamp: 2026-01-21T21:57:26.174Z
Learning: Document that the --native-price-estimators argument for the CoW Protocol autopilot CLI must use the Driver|name|url format (e.g., 'Driver|baseline|http://driver/baseline'), not just 'name|url'. Apply this guidance broadly in docs under the docs directory and include explicit examples to avoid ambiguity.


## 6. Moving to production

Once your solver has moved to staging we can deploy your solver on production. Usually the team will schedule your solver to go live with the next release (on Tuesday) after you are deployed on staging. This gives your team a few days to test your solver by settling some transactions on-chain before going live on production.

## 7. Weekly rewards and accounting

Every week on Tuesday your solver will receive payments and rewards for settling auctions. Rewards in COW will be sent to the rewards address on mainnet, and reimbursements for network fees and slippage will be distributed on the same network as where the solving took place.

We advise using a single rewards address that is available on all networks.

[You can find more information about how we calculate and distribute rewards here.](https://docs.cow.fi/cow-protocol/reference/core/auctions/rewards). The accounting process is documented in detail [here](https://docs.cow.fi/cow-protocol/reference/core/auctions/accounting).

## 8. Moving to other networks

After joining the solver competition on Arbitrum we can enable your solver on other chains relatively soon. For this we will go through the same process of generating addresses, vouching for them, and whitelisting them. For each new chain that we deploy your solver on we will need:

- A rewards address for receiving the weekly COW rewards associated with that network;
- An endpoint that you would like to use for staging amd production.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Fix typo: "amd" should be "and".

There's a spelling error in this line.

📝 Proposed fix 
-- An endpoint that you would like to use for staging amd production.
+- An endpoint that you would like to use for staging and production.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- An endpoint that you would like to use for staging amd production.
- An endpoint that you would like to use for staging and production.
🧰 Tools
🪛 LanguageTool

[grammar] ~143-~143: Ensure spelling is correct
Context: ... that you would like to use for staging amd production. ## 9. Joining the mainnet ...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/cow-protocol/tutorials/solvers/onboard.md` at line 143, Fix the typo in
the sentence "An endpoint that you would like to use for staging amd
production." by replacing "amd" with "and" so it reads "An endpoint that you
would like to use for staging and production." Locate this line in
docs/cow-protocol/tutorials/solvers/onboard.md (the sentence text above) and
update the wording accordingly.


## 9. Joining the mainnet competition
We usually wait a bit before migrating solvers to mainnet. After your solver has been active on other networks for some time the team can enable your solver on mainnet.

We usually wait a bit before migrating solvers to mainnet. After your solver has been active on other networks for some time the team can enable your solver on mainnet.

## 10. Joining the quoting competition

Besides the solving competition, there is also a quoting competition. More information about the quoting competition can be found [here](https://docs.cow.fi/cow-protocol/reference/core/auctions/rewards#price-estimation-competition-rewards-cips-27-57-72).

## 11. F.A.Q.
## 11. F.A.Q

### Can we get access to the orderbook API?

Yes, we can whitelist solvers so that they can have access to the orderbook API. Although we generally wait with this until your solver is live and settling orders on-chain.

### How do we integrate CoW AMMs?

[We have a section in the documentation about integrating CoW AMMs.](https://docs.cow.fi/cow-amm/tutorials/cow-amm-for-solvers)

### Is there a way to find out the COW reward in real time immediately after the trade?

[This table](https://dune.com/queries/5270914) contains reward data per solver and per auction (denominated in the native token of the chain). Note that data is updated every 2 hours.

### What are the environments?

There are three environments: shadow, staging, and production.
In the shadow competition (only arbitrum and mainnet now) the solver is tested using production order flow but without settling any orders. This is for testing the integration of the solver. It is possible to simulate the solver's solutions and see how it does.

Expand All @@ -150,4 +174,5 @@ In the staging (barn) competition settling happens on-chain but the volume is mu
Finally, production is where the solver is participating in the main solver competition.

### Are there any prerequisites in the shadow environment that we must meet before being allowed to join staging?

No, there are no prerequisites (other than KYC if joining the CoW DAO bonding pool) but it is recommended that the solver manages to submit and win solutions on shadow before staging.
Loading