Audit and fix frontmatter metadata across 79 pages

bff/development/creating-services.mdx

@@ -1,11 +1,12 @@
 ---
 title: "Creating Services and Libraries"
+sidebarTitle: "Creating services"
 description: "Guide to scaffolding new services, applications, and libraries in the CoW Protocol BFF monorepo using NX generators"
 ---
 
 # Creating Services and Libraries
 
 The CoW Protocol BFF monorepo uses NX generators to scaffold new projects with proper TypeScript, Docker, and configuration setup.
 
 ## Available Generators
 
@@ -17,13 +18,13 @@
 | `yarn new:node`   | Background workers, CLI tools |
 | `yarn new:lib`    | Shared libraries             |
 
 ## Fastify API Services
 
 ```bash
 yarn new:fastify
 ```
 
 Running the Fastify generator creates a complete API structure with:
 
 - App configuration (`src/app/app.ts`)
 - Entry point (`src/main.ts`)

bff/services/api.mdx

@@ -1,17 +1,17 @@
 ---
 title: "API Service"
-description: "Documentation for the BFF API service, a Fastify-based HTTP server that aggregates data from multiple sources to provide unified endpoints for trading, tokens, and balances"
+description: "BFF API service reference — a Fastify-based server providing unified endpoints for CoW Protocol trading, tokens, and balances."
 ---
 
 # API Service
 
 The API service is the main HTTP API server that provides a unified interface for CoW Protocol frontend applications. Built with Fastify, it aggregates data from multiple sources and provides RESTful endpoints for trading, tokens, balances, and more.
 
 ## Purpose and Responsibilities
 
 The API service serves as the Backend For Frontend (BFF) layer with the following responsibilities:
 
 * **Unified API Gateway**: Aggregates data from CoW Protocol APIs, blockchain nodes, and external services
 * **Token Information**: Provides token prices, balances, and metadata
 * **Trading Data**: Exposes yield pool information, market slippage, and trade simulations
 * **Affiliate Program**: Manages affiliate program data and exports
@@ -84,8 +84,8 @@
 | ----------------------- | -------------------------------- |
 | `COINGECKO_API_KEY`     | CoinGecko API key for price data |
 | `GOLD_RUSH_API_KEY`     | Covalent GoldRush API key        |
 | `ETHPLORER_API_KEY`     | Ethplorer API key for token data |
 | `MORALIS_API_KEY`       | Moralis API key                  |
 | `TENDERLY_API_KEY`      | Tenderly API key for simulations |
 | `TENDERLY_PROJECT_NAME` | Tenderly project name            |
 | `TENDERLY_ORG_NAME`     | Tenderly organization name       |
@@ -154,7 +154,7 @@
 
 - **CoW Analytics Database** - PostgreSQL database for analytics data (read-only access). Configuration: `COW_ANALYTICS_DATABASE_*` variables
 
 - **Blockchain RPC Nodes** - HTTP or WebSocket endpoints for supported chains (Ethereum, Gnosis, etc.). Configuration: `RPC_URL_1`, `RPC_URL_100`, etc.
 
 ### External APIs
 
@@ -168,7 +168,7 @@
 
 ### Plugin System
 
 The API uses Fastify's plugin system to organize functionality:
 
 * **env.ts** - Environment variable validation
 * **cors.ts** - CORS configuration
@@ -205,7 +205,7 @@
 
 * **Affiliate Program Export Poller** - Periodically exports affiliate program data
 
 ## Nx Commands
 
 ```bash
 # Development server

changelog.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Changelog"
-description: "Latest updates to CoW DAO documentation."
+description: "Latest updates and changes to the CoW DAO documentation, including new features and migration notes."
 ---
 
 <Update label="Documentation migrated to Mintlify" description="2025-03-04">

composable-cow/introduction.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Introduction"
-description: "ComposableCoW is the contract that implements programmatic orders on CoW Protocol — orders that execute automatically when predefined on-chain conditions are satisfied."
+description: "ComposableCoW implements programmatic orders on CoW Protocol — automated trading when on-chain conditions are met."
 ---
 
 # Introduction to ComposableCoW
@@ -22,7 +22,7 @@
 Two approaches are available:
 
 1. **Individual order creation** via `ComposableCoW.create()` for simpler scenarios
 2. **Merkle tree-based authorization** for efficiently managing numerous programmatic orders with reduced on-chain storage requirements
 
 ## Technical Infrastructure
 
@@ -38,4 +38,4 @@
 
 ## Security Status
 
 The system underwent audits by Ackee Blockchain and Gnosis teams, with reports available in the repository's audit directory.

cow-amm.mdx

@@ -1,23 +1,24 @@
 ---
 title: "CoW AMM: The First MEV-capturing AMM"
-description: "CoW AMM protects LPs from LVR so they can provide liquidity with less risk and more return. CoW AMM achieves close to 5% more in TVL compared to reference pools, protects millions from LVR, and has captured over $100,000 in surplus for LPs to date."
+sidebarTitle: "CoW AMM"
+description: "CoW AMM protects liquidity providers from LVR (loss-versus-rebalancing), delivering more return with less risk than traditional AMMs."
 hidden: true
 ---
 
 ## AMMs don't want you to know about LVR
 
 Liquidity providers expect their tokens to earn yield, but the dirty little secret of AMMs is that most liquidity pools lose money. In fact, hundreds of millions of dollars of LP funds are stolen by arbitrageurs every year. These losses are known as loss-versus-rebalancing (LVR). LVR is a bigger source of MEV than frontrunning and sandwich attacks combined.
 
 ## An AMM designed with LPs in mind
 
 CoW AMM eliminates LVR once and for all by using batch auctions to send surplus to LPs
 
 1. Liquidity providers deposit tokens into protected CoW AMM liquidity pools, where traders can access the liquidity
 2. Solvers bid to rebalance CoW AMM pools whenever there is an arbitrage opportunity
 3. The solver that offers the most surplus to the pool wins the right to rebalance the pool
 4. CoW AMM eliminates LVR by capturing arbitrage value for LPs and shielding it from MEV bots
 
 ## Deploy liquidity on CoW AMM
 
 Thanks to CoW AMM's integration with Balancer, LPs can now [deploy their liquidity or create a brand new pool in just a few clicks](https://balancer.fi/pools/cow).
 

cow-amm/explanation/how-cow-amms-work.mdx

@@ -1,5 +1,6 @@
 ---
 title: "How CoW AMMs Work"
+description: "How CoW AMM uses the Function-Maximizing AMM mechanism to batch trades at uniform clearing prices, eliminating LVR for liquidity providers."
 ---
 
 ## FM-AMMs
@@ -14,27 +15,27 @@
 
 ## Contract architecture
 
 CoW AMM is built as a set of contracts that integrate natively with Balancer's infrastructure and CoW Protocol's solver competition:
 
 - **`BCoWPool`**: The AMM pool contract, which extends Balancer's `BPool`. Each CoW AMM pool is a `BCoWPool` instance that holds liquidity and defines the trading function. It implements the `IConditionalOrder` interface from [ComposableCoW](/cow-protocol/reference/contracts/periphery/composable-cow), which allows the CoW Protocol watchtower to poll the pool for tradeable orders.
 - **`BCoWFactory`**: The factory contract used to deploy new CoW AMM pools. It creates `BCoWPool` instances with the correct configuration for CoW Protocol integration.
 - **`BCoWHelper`**: A helper contract for solvers. Given a pool and the current on-chain state, it generates valid order parameters that solvers can include in their settlement batches.
 
 The end-to-end flow works as follows:
 
 1. **Pool deployment** — An LP deploys a new pool via `BCoWFactory` and adds liquidity.
 2. **Watchtower polling** — The CoW Protocol watchtower periodically calls each pool's `getTradeableOrderWithSignature` (via the `IConditionalOrder` interface) to discover when the pool has a tradeable order.
 3. **Solver queries** — When a solver identifies a CoW AMM order, it can use `BCoWHelper` to compute valid order parameters that move the AMM curve higher.
 4. **Batch settlement** — The solver includes the CoW AMM order in its settlement batch alongside user orders, enabling coincidence of wants.
 5. **Pool rebalances** — After settlement, the pool's reserves are updated and the AMM curve moves to reflect the new balances.
 
 <Note>
   CoW AMMs are **not** based on Safe (the old architecture). They are native Balancer pools with direct CoW Protocol integration via the ComposableCoW programmatic order framework.
 </Note>
 
 ## Getting Started with CoW AMM
 
 To facilitate easy liquidity providing, CoW DAO has partnered with Balancer to implement CoW AMMs into the Balancer ecosystem. LPs can [use the Balancer app](https://balancer.fi/pools/cow) to LP direclty on one of over a dozen liquidity pools.
 
 In the next section, LPs can learn how to create their own CoW AMM pools for brand new assets either on Balancer or outside the platform.
 

cow-amm/explanation/the-problem-of-lvr.mdx

@@ -1,21 +1,22 @@
 ---
 title: "The Problem of LVR (Loss-versus-rebalancing)"
-description: "First coined by a team of researchers from  LVR is a form of arbitrage that occurs whenever an AMM has an outdated (stale) price in comparison to some other trading venue."
+sidebarTitle: "The problem of LVR"
+description: "Loss-versus-rebalancing (LVR) explained — how arbitrageurs exploit stale AMM prices and why CoW AMM solves this problem."
 ---
 
 Arbitrageurs exploit this difference by trading from the AMM to the more liquid exchange (usually a centralized exchange like Binance), correcting the arbitrage and extracting value from LPs in the process.
 
 # How LVR Works
 
 Most AMMs (such as Uniswap) are examples of constant function automated market makers—CF-AMMs. These AMMs take in two assets and automatically re-calculate prices after each trade to ensure ample liquidity at all times. This means the AMMs experience asset price discovery as they are being traded against.
 
 However, since crypto assets trade on various platforms including centralized exchanges, the prices on a CF-AMM may be outdated compared to the more liquid prices on a centralized exchange. This discrepancy allows arbitrageurs to trade between the liquid exchange and the outdated AMM, correcting prices and capturing arbitrage in the process.
 
 "Loss-versus-rebalancing" is the scenario where an LP provides liquidity to a CF-AMM whose prices are stale compared to a more liquid venue like a centralized exchange. By leaving their funds in the liquidity pool, they are not making as much money as they could be if they were to constantly "rebalance" between the AMM and the exchange. Thus, they incur a "loss" compared to what they would have in a "rebalancing" strategy.
 
 # The Impact of LVR on LPs
 
 Many liquidity providers haven’t even heard of LVR, but it costs them 5–7% of their liquidity, resulting in hundreds of millions lost each year. In fact, when accounting for LVR, many of the largest liquidity pools are not profitable for LPs at all.
 
 Due to these losses, LVR is a type of MEV (maximal extractable value) that accounts for more price exploitation than frontrunning and sandwich attacks combined.
 

cow-amm/tutorials/cow-amm-for-solvers.mdx

@@ -1,34 +1,35 @@
 ---
 title: "CoW AMM Liquidity for Solvers"
+description: "How solvers can interact with CoW AMM liquidity in the CoW Protocol orderbook, including custom buy/sell amounts and surplus capturing."
 ---
 
 ## I'm a solver. How do I use CoW AMM liquidity?
 
 CoW AMM orders already appear in the CoW Protocol orderbook, so you're already using its liquidity. However, CoW AMMs allow solvers to specify custom buy and sell amounts, as long as the order preserves or increases the constant product invariant of the token reserves.
 
 CoW AMMs can be treated as a liquidity source akin to Uniswap or Balancer weighted pools with uniform weights. Each CoW AMM is a pair that trades two tokens.
 
 Importantly, surplus for a CoW AMM order is measured differently when computing the solver reward payout.
 
 ### Indexing Balancer CoW AMMs
 
 CoW AMM pairs can be detected by listening to the `COWAMMPoolCreated` events emitted by the `BCowFactory` instance for the current chain (see the [official contract repository](https://github.com/balancer/cow-amm) for the current deployment addresses). All addresses of Balancer CoW AMMs are sent as part of the auction instance as `surplusCapturingJitOrderOwners`.
 
 The AMM reserves are the balance of the two tokens traded by the AMM.
 
 ### Creating CoW AMM orders with the helper contract
 
 Integrating CoW AMM orders requires adding a JitOrder with the CoW AMM. This order should be described from the CoW AMM pool's perspective. So if a user wants to sell token A to buy token B and you would like to settle (part of) this order with a CoW AMM, then you would need to add a JitOrder from the CoW AMM's perspective to match (part of) this order. In other words, you would be adding a JitOrder for the CoW AMM to sell token B to buy token A. You can do this by calling the `orderFromBuyAmount` because the user’s amount is exactly how much you would want the pool to receive, asking for the amount of tokens in exchange.
 
 [The source code for the helper contract can be found here.](https://github.com/balancer/cow-amm/blob/main/src/contracts/BCoWHelper.sol) The `orderFromBuyAmount` and 'orderFromSellAmount' methods return the order, preInteractions, postInteractions, and signature. This can be used to generate the order (JitOrder) and check prices.
 
 This order generated by the BCoWHelper contract will contain the limit prices for which the CoW AMM is willing to trade. Trading at exactly these limit prices will not generate surplus for the CoW AMM, any price improvement from these limit prices will be surplus captured by the CoW AMM.
 
 One thing to keep in mind when using the helper contract to generate these JitOrders is that both the `orderFromSellAmount` and `orderFromBuyAmount` methods return an order where the `partiallyFillable` field is marked as true. However, since the driver does not support partially fillable JitOrders, it replaces the partiallyFillable field with false. This means that the `partiallyFillable` field must be set to false before passing the solution to the driver and the signature of both the JitOrder and the commit hash in the pre-interaction should be updated accordingly.
 
 Doing this will generate additional surplus in the solver competition (assuming you trade at a better price than the provided limit price). For example, if a solver would like to settle a user using outside liquidity that trades a pair for which there is a CoW AMM, then that solver can compare those prices with that of the CoW AMM. This (or part of this) interaction can then be replaced with the CoW AMM to generate additional surplus. This way the solver can integrate CoW AMMs by solving as if these CoW AMM's do not exist, and then check whether some of the outside interactions can be replaced by CoW AMMs (note: UPC and EBBO apply to CoW AMMs as well).
 
 Another way that a solver can use CoW AMM's is by using outside liquidity from the competition/auction to trade with the CoW AMM, thereby re-balancing the AMM and receiving an additional surplus for doing so if the prices of the CoW AMM is off relative to the outside world.
 
 The helper contracts are deployed here:
 
@@ -39,7 +40,7 @@
 * Avalanche N/A
 * Polygon N/A
 * BNB N/A
 * Linea N/A
 * Plasma N/A
 
 ### Settling a custom order

cow-protocol/explanation/architecture/autopilot.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Autopilot"
+description: "The Autopilot orchestrates CoW Protocol's batch auction lifecycle, managing order collection, solver coordination, and on-chain settlement."
 ---
 
 ## Overview
@@ -32,7 +33,7 @@
 
 The autopilot builds an auction that includes all tradable orders. To handle this, it needs to maintain a complete overview of the protocol.
 
 Much of the order data it needs is collected through the database, which is shared with the orderbook. The database stores the vast majority of available order information, including user signatures.
 
 Other information can only be retrieved on-chain and is updated every time a new block is mined. For example, it needs to know from the protocol:
 
@@ -43,13 +44,13 @@
 
 Retrieved information isn't limited to the CoW Protocol itself. The autopilot needs to provide a reference price for each token in an order (a numéraire); the reference price is used to normalize the value of the [surplus](/cow-protocol/reference/core/auctions/the-problem), since the surplus must be comparable for all orders and two orders could use the most disparate `ERC-20` tokens. The reference token is usually the chain's native token, since it's the token used to pay for the gas needed when executing a transaction. Orders whose price can't be fetched are discarded and won't be included in an auction.
 
 Native token price fetching is handled by an integrated price estimator in the autopilot. The price is fetched from multiple sources and may change based on the current configurations. Prices are both queried from a list of selected existing solvers as well as retrieved internally by the autopilot (for example, by querying some external parties like Paraswap and 1inch, but also by reading on-chain pool data as Uniswap).
 
 Orders that can't be settled are filtered out. This is the case if, for example:
 
 * an order is expired
 * for fill-or-kill orders the user's balance isn't enough to settle the order
 * the approval to the vault relayer is missing
 * the involved tokens aren't supported by the protocol
 
 The autopilot also checks that [`ERC-1271`](/cow-protocol/reference/core/signing-schemes#erc-1271) signatures are currently valid.

cow-protocol/explanation/architecture/driver.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Driver"
-description: "People interested in running a solver to participate in CoW Protocol mainly want to focus on implementing the most efficient solver engine. However, there are also many mundane tasks that may not seem like a competitive advantage but have to be done regardless."
+description: "The Driver is a plug-and-play component that handles mundane tasks for CoW Protocol solver teams, from auction processing to settlement."
 ---
 
 ## Overview
@@ -13,7 +13,7 @@
 
 The `driver` sits between the [autopilot](/cow-protocol/explanation/architecture/autopilot) and a [solver engine](/cow-protocol/explanation/architecture/solver-engine) and acts as a intermediary between the two. In case you decide to run the driver for a solver engine the lifecycle of an auction looks like this.
 
 Splitting the driver from the solver engine is just a design decision to keep the barrier of entry for new solvers low. However, there is nothing preventing you from patching, forking or reimplementing the driver. You can even merge the responsibilities of the driver and solver engine into one if you want to build the most optimal solver possible; the only hard requirement is that the component the autopilot interfaces with implements this [interface](/cow-protocol/reference/apis/driver).
 
 ## Methodology
 
@@ -27,9 +27,9 @@
 
 ### Fetching liquidity
 
 Unless you find a perfect CoW you'll need some sort of liquidity to settle an order with. To get your solver started with a good set of base liquidity the driver is able to index and encode a broad range of fundamental AMMs. These include `UniswapV2` and its derivatives, `UniswapV3` as well as several liquidity sources from the `BalancerV2` family. All of these can be individually configured or completely disabled if your solver engine manages liquidity on its own.
 
 ### Postprocessing solutions
 
 The driver expects the solver engine to return a recipe on how to solve a set of orders but the recipe itself could not be submitted on-chain. In the post-processing step the driver applies multiple sanity checks to the solution, encodes it into a transaction that can be executed on-chain and verifies that it actually simulates successfully before it considers the solution valid. All this is done because solvers can get slashed for misbehaving so the reference driver checks all it can to reduce the risk of running a solver as much as possible.
 
@@ -41,22 +41,22 @@
 
 ### Submitting settlements
 
 If a solver provided the best solution the autopilot will tell the driver to actually submit it on-chain. This is not as straight forward as it sounds when the blockchain is congested and liquidity sources are volatile. To protect the solver from losing ETH by submitting solutions that revert the driver continuously verifies that the solution still works while it submits it on-chain. As soon as it would revert the driver cancels the transaction to cut the losses to a minimum.
 
 The driver can be configured to use different submission strategies which it dynamically choses based on the potential of MEV for a settlement. If the settlement does not expose any MEV (e.g. it executes all trades without AMMs) it's safe and most efficient to directly submit to the public mempool. However, if a settlement exposes MEV the driver would submit to an MEV-protected RPC like [MEVBlocker](https://mevblocker.io).
 
 ### Flash Loans
 
 The user is able to create a flash loan order's hint by attaching to the `appData` the specified metadata. The autopilot reads the order and cuts it into a [fair combinatorial batch auction](/cow-protocol/explanation/introduction/fair-combinatorial-auction). Then the driver fetches the `appData` by calling the orderbook with `GET /v1/app_data/<app_data_hash>` for every order and caches them in memory. The driver should include the flash loan information into the batch auction's order before sending it to the solver(s).
 
 #### Flash Loans Encoding
 
 If a solver decides to encode the transaction without the help of the reference driver, the solver must call the `IFlashLoanRouter` contract's [flashLoanAndSettle](/cow-protocol/reference/contracts/periphery/flashloans#flashloanandsettle) function instead of the settlement contract's [settle](/cow-protocol/reference/contracts/core/settlement#settle) function. The solver must provide all necessary flash loan inputs for the settlement, as well as the settle calldata, which will be executed within the same context by the `IFlashLoanRouter` contract. The `IFlashLoanRouter` contract will then request the specified flash loans and, once received, execute the settlement as instructed.
 
 The entry point to the router contract ([IFlashLoanRouter](/cow-protocol/reference/contracts/periphery/flashloans#iflashloanrouter-contract)) is the function `flashLoanAndSettle`. It takes a list of loans with the following entries for each loan:
 
 * The loaned amount and ERC-20 token.
 * The flash-loan lender (e.g., Balancer, Aave, Maker, ...).
 * The *borrower*, which is an adapter contract that makes the specific lender implementation compatible with the router.
 
 Only CoW-Protocol solvers can call this function. It also takes the exact call data for a call to `settle`. The flash-loan router is a solver for CoW Protocol and calls `settle` directly once the flash loans have been obtained.
@@ -81,9 +81,9 @@
 
 As you can see the driver has many responsibilities and discussing all of them in detail would be beyond the scope of this documentation but it's worth mentioning one guiding principle that applies to most of them: make the driver do as *little* work as possible in the hot path when processing an auction.
 
 Because having more time for the solver to compute a solution leads to a more competitive solver every process in the driver should introduce as little latency as possible. Also the blockchain is obviously the single source of truth for a lot of the state in the driver and fetching state from the network can be quite slow.
 
 To reconcile these aspects many internal components listen for new blocks getting appended to the blockchain. Whenever that happens the driver fetches all the relevant information and caches it. When the next auction comes in and the driver actually needs that data it's already up-to-date and ready to be used.
 
 ### Dependencies
 

cow-protocol/explanation/architecture/solver-engine.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Solver Engine"
-description: "The Solver Engine implements the  of the CoW Protocol batch auction. As part of the auction lifecycle, it receives a request from the  containing a potentially pre-processed auction instance and returns information about which order to execute together with instructions on how to achieve the desired execution using on-chain liquidity \"interactions\"."
+description: "The Solver Engine processes CoW Protocol batch auctions, determining which orders to execute and how to route them through on-chain liquidity."
 ---
 
 <Note>
@@ -28,7 +28,7 @@
 
 ### Baseline
 
 For each order in the problem set, this solver implements a greedy single-path output maximization algorithm in a weighted graph where vertices correspond to tokens and edges correspond to AMMs providing liquidity between tokens with their output equal to the exchange rate as defined by AMM function given the input amount. Outputs are adjusted to consider the execution cost of updating the AMM when used, using fixed gas amount estimates but taking into account the gas price provided in the auction input. The graph originates over a set of "base tokens" plus the buy and sell token of the order. It aims to find the single path from buy to sell token that maximizes the output for sell orders and minimizes the input for buy orders. It handles partially fillable attempting to first fill the entire order. If the resulting output doesn't satisfy the limit price, it re-attempts filling the order to 50% and keeps halving its amount until a match is found. It does not produce Coincidences of Wants.
 
 ## Flash Loans
 

cow-protocol/explanation/benefits/trade-any-intent.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Trade any intent"
-description: "CoW Protocol allows users to express any type of trade intent on Ethereum and EVM-compatible chains, leveraging  to execute the transactions through the most optimal route."
+description: "CoW Protocol supports any trade intent on Ethereum — from market orders to TWAP, programmatic orders, and CoW Hooks."
 ---
 
 The protocol supports any order logic which includes standard market and limit orders, but also advanced order types such as [TWAP](/cow-protocol/explanation/order-types/twap-orders). Thanks to `ERC-1271`, smart contracts can also submit intents, paving the way for the [Programmatic Order Framework](/cow-protocol/explanation/order-types/programmatic-orders) and contracts like [Milkman](/cow-protocol/explanation/order-types/milkman-orders).

cow-protocol/explanation/fee-model.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Fee Model"
-description: "How fees work in CoW Protocol — from the quote response to on-chain settlement. Everything you need to understand protocol fees, network costs, partner fees, and how to retrieve fee data for accounting."
+description: "How fees work in CoW Protocol — protocol fees, network costs, partner fees, and how to retrieve fee data for accounting."
 ---
 
 <Note>

cow-protocol/explanation/flash-loans/integrators.mdx

@@ -1,6 +1,7 @@
 ---
 title: "How to specify an order with flash loan"
-description: "The flash loan is encoded into the 's metadata as an optional object. This information serves as a hint for the solver, but the solver ultimately can decide for a different approach in order to make the operation more optimal."
+sidebarTitle: "Flash loan orders"
+description: "How to encode flash loan parameters in CoW Protocol order metadata as hints for solvers to optimize execution."
 ---
 
 It is important to ensure that the flash loan gas overhead is added to the slippage tolerance when creating the order.

cow-protocol/explanation/how-it-works/coincidence-of-wants.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Coincidence of Wants"
-description: "CoW (Coincidence of Wants): An economic phenomenon where two parties - each holding the asset that the other needs - exchange assets directly in an equivalent barter."
+description: "Coincidence of Wants (CoW) enables peer-to-peer swaps in CoW Protocol, saving users LP fees and reducing gas costs."
 ---
 
 Thanks to CoW Protocol's batching mechanism, users can make peer-to-peer swaps in cases where they're trading the same assets.

cow-protocol/explanation/how-it-works/flow-of-an-order.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Flow of an order"
-description: "Rather than creating executable on-chain transactions, CoW Protocol users submit their orders as signed  messages. This allows  to find the optimal execution path for the batch of orders before committing them on-chain."
+description: "End-to-end flow of an order through CoW Protocol — from signed intent submission to solver competition and on-chain settlement."
 ---
 
 Let's bring all of our main concepts together by taking a look at the flow of an order through CoW Protocol.
@@ -24,7 +24,7 @@
 
 Once the winning solver executes the batch's orders on-chain, users receive their tokens.
 
 The competition between solvers in a batch auction ensures that users (including traders, DAOs, smart contracts, and bots) always receive the best prices for their trades.
 
 Letting solvers do the heavy lifting means users don't have to worry about finding the best liquidity pool, setting the right gas price, or picking the optimal slippage tolerance for their trades. Solvers are also experts at avoiding MEV so users can rest assured their orders are protected from MEV bots that exploit their price through frontrunning and sandwich attacks.
 

cow-protocol/explanation/how-it-works/how-intents-are-formed.mdx

@@ -1,6 +1,6 @@
 ---
 title: "How Intents Are Formed"
-description: "An intent in CoW Protocol is a signed message that represents a user's wish to trade. It doesn't execute a trade directly — instead, it delegates execution to solvers who find the optimal path."
+description: "How CoW Protocol intents are formed — signed messages that delegate trade execution to solvers for optimal path finding."
 ---
 
 An [_intent_](/cow-protocol/explanation/introduction/intents) in CoW Protocol is a signed message that represents a user's wish to trade. It doesn't execute a trade directly — instead, it delegates execution to [solvers](/cow-protocol/explanation/introduction/solvers) who find the optimal path.
@@ -8,7 +8,7 @@
 <Warning>
 **This document explains the anatomy of intents at a conceptual level.**
 
 For a step-by-step integration walkthrough, see the **[API Integration Guide](/cow-protocol/howto/integrate/api)**. For higher-level tools, use the **[TypeScript SDK](/cow-sdk/quickstart)** or the **[Python SDK](/cow-py/quickstart)**.
 </Warning>
 
 Forming an intent follows three stages:

cow-protocol/explanation/introduction/fair-combinatorial-auction.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Fair Combinatorial Batch Auction"
-description: "CoW Protocol collects and aggregates intents off-chain and auctions them off to solvers. The auction is a Fair Combinatorial Batch Auction (FCBA) because each solver can submit multiple bids. A solver can submit multiple bids on individual orders, in which case each \"bid\" represents the best price this solver can provide to an individual order. However, a solver can also submit \"batched\" bids, that is, bids on groups of orders."
+sidebarTitle: "Batch auctions"
+description: "How CoW Protocol's Fair Combinatorial Batch Auction (FCBA) aggregates intents and selects winning solver bids to maximize user surplus."
 ---
 
 The protocol filters out \`\`unfair'' batched bids, which are those delivering less to an order than some available "non-batched" bids. It then selects the combination of winning bids that maximizes the surplus received by the orders that are part of the auction (subject to some computational constraints due to the combinatorial nature of the problem).

cow-protocol/explanation/introduction/intents.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Intents"
-description: "Rather than placing orders by  that executes directly on-chain (i.e. as happens on Uniswap or SushiSwap), CoW Protocol users place orders by  that specifies parameters like the assets and amounts they would like to trade. The intent is a signed message which allows the solvers to execute a trade on behalf of the user using their specified assets and amounts."
+description: "CoW Protocol uses signed intent messages instead of on-chain transactions, letting solvers find optimal execution paths on behalf of users."
 ---
 
 There are a number of [financial](#financial-benefits-of-intents) and [technical](#technical-benefits-of-intents) advantages to intent-based trading.
@@ -12,7 +12,7 @@
 Thanks to its intent-based architecture, CoW Protocol delegates the job of finding the optimal execution path to professional third parties known as [solvers](/cow-protocol/explanation/introduction/solvers). Solvers not only scan all available on-chain liquidity (similar to a DEX aggregator) they also provide extra price improvements in several ways:
 
 * [**Coincidence of Wants**](/cow-protocol/explanation/how-it-works/coincidence-of-wants): Direct P2P (peer-to-peer) matching for two or more users who have expressed opposite buy and sell intents for the same token pair. This optimization, enabled by batch auctions, allows users to bypass liquidity provider (LP) fees and it reduces the gas fees for trading as orders don't need to interact with other non-CoW Protocol smart contracts.
 * **Private Market Maker Inventory**: Many solvers have access to off-chain liquidity through CEX inventory, integration with private market makers, or private liquidity of their own. This allows them to fill certain trades at better prices than what may be available through on-chain AMMs at any given time.
 * [**MEV Protection**](/cow-protocol/explanation/benefits/mev-protection): On CoW Protocol, users are never exposed to MEV bots. Instead, solvers settle trades on behalf of the user, taking on all MEV risk. In addition, solvers submit all orders in a batch at a uniform clearing price, meaning there is no advantage to re-ordering trades (the basis of all MEV exploitation).
 
 ## Technical Benefits of Intents
@@ -20,7 +20,7 @@
 The intent-based architecture of CoW Protocol also provides a number of technical benefits:
 
 * Enabling [solvers](/cow-protocol/explanation/introduction/solvers) to execute all sorts of transactions (not just trades) based on specific instructions and on-chain conditions. This powers products like [CoW Hooks](/cow-protocol/explanation/order-types/cow-hooks) and [Programmatic Orders](/cow-protocol/explanation/order-types/programmatic-orders)
 * Establishing additional rules for the way orders settle on-chain, such as guaranteeing that the trade is settled at [EBBO](/cow-protocol/reference/core/definitions#ebbo) (Ethereum best bid and offer, guaranteeing that the baseline price for the trade is what on-chain AMMs offer) and uniform clearing prices (where trades with the same token pair in the same batch are cleared at the same price)
 * Allowing users to pay gas fees in their *sell token* without needing to hold the chain-native token (like ETH) in their wallet
 * Eliminating fees for failed transactions
 * Allowing users to place multiple orders at once

cow-protocol/explanation/order-types/cow-hooks.mdx

@@ -1,15 +1,15 @@
 ---
 title: "CoW Hooks"
-description: "CoW Hooks allow users to pair any Ethereum action (or set of actions) with an order on CoW Protocol, leveraging the  to execute the actions together in the sequence."
+description: "CoW Hooks let you pair arbitrary Ethereum actions with CoW Protocol orders, executing pre-swap and post-swap logic atomically."
 ---
 
 Hooks execute the entire sequence as a single transaction. True to the CoW Protocol model, users pay gas fees in their sell token if, and only if, the sequence of transactions succeeds. Under the hood, CoW Hooks are arbitrary Ethereum "calls" that attach to an order and execute before and/or after the order. Developers and advanced traders can use code to express an intent that performs some action before a swap (pre-hooks) and after a swap (post-hooks).
 
 ## Pre-Hooks
 
 These are actions that execute before the swap, allowing pre-hooks to be used to "set up" an order. Some examples including:
 
 * Unstaking tokens just-in-time for trading
 * Claiming an airdrop right before dumping
 * Signing token approvals so that the approval and the trade itself are batched together as a single action
 
@@ -32,7 +32,7 @@
     Browse and use pre-built hooks, or publish your own
   </Card>
   <Card title="Build a Hook dApp" icon="code" href="/cow-swap/hooks/hook-dapp">
     Develop a custom hook dApp for the CoW Swap interface
   </Card>
   <Card title="Post-Hook Examples" icon="arrow-right" href="/cow-swap/hooks/post-hook-examples">
     Swap → stake, swap → bridge, and swap → vault patterns

cow-protocol/explanation/order-types/liquidations.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Liquidations"
-description: "How lending protocols can use CoW Protocol to execute liquidations with MEV protection and competitive pricing, using ERC-1271 smart orders and the settlement contract's on-chain guarantees."
+description: "How lending protocols use CoW Protocol for MEV-protected liquidations with ERC-1271 smart orders and competitive pricing."
 ---
 
 ## The problem with traditional liquidations

cow-protocol/explanation/order-types/pay-debt-flash-loans.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Repay debt with collateral using flash loans"
-description: "A key use case of flash loans is the ability to repay debt with collateral, since flash loans allow users to close or reduce their debt positions without needing upfront liquidity."
+sidebarTitle: "Repay debt (flash loans)"
+description: "Repay debt with collateral using CoW Protocol flash loans — close or reduce debt positions without upfront liquidity."
 ---
 
 Instead of requiring users to have assets readily available to repay their loans, flash loans enable them to temporarily borrow the needed funds, use those funds to repay their debt, and immediately reclaim their locked collateral. Once the collateral is received, it can be swapped or liquidated to cover the borrowed amount, ensuring the loan is repaid within the same transaction.
@@ -22,7 +23,7 @@
 
 #### Lender allows a third-party to initiate the transfer of collateral tokens
 
 In this case, the user can sign a pre-hook that deploys a [COWShed](https://github.com/cowdao-grants/cow-shed) to repay the debt using flash-loaned tokens. `COWShed` is a user owned ERC-1967 proxy deployed at a deterministic address. This deterministic deployment allows users to set the proxy address as the receiver for cowswap orders with pre/post-hooks. The user signs a EIP-712 message for the pre/post-hooks which gets validated. Only user signed hooks are executed on the user's proxy. This allows users to confidently perform permissioned actions in the hooks such as:
 
 * transferring assets from the proxy to someone else.
 * use the proxy to add collateral or repay debt on a maker CDP or an AAVE debt position, etc.
@@ -35,5 +36,5 @@
 
 If the lender does not allow third-party to initiate the transfer of collateral tokens from the lending pool to the trader's address, the process becomes more involved. In this case, the repayment must come directly from the owner's account, meaning the owner cannot simply be an EOA (Externally Owned Account). Instead, it must be a smart contract (e.g. a SAFE wallet). That enables you to authorize function calls coming from the safe by signing them with the safe. That way you can create a hook initiating the withdrawal of the collateral tokens that a third-party can initiate. This is not possible when the collateral owner is an EOA.
 
 Additionally, repayment might not always involve selling the collateral token directly. In some cases, the protocol allows selling an interest-bearing version of the token instead. For example, if the collateral is aUSDC (which represents USDC deposited in Aave and earning interest), selling aUSDC instead of withdrawing and selling USDC directly ensures a more seamless repayment process. Understanding these trade-offs helps determine the correct approach based on the specific requirements of the lending protocol.
 

cow-protocol/explanation/order-types/programmatic-orders.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Programmatic orders"
-description: "In addition to normal wallets, CoW Protocol also supports smart contract wallets that implement . This allows users to place orders through smart contracts with programmable parameters that execute based on certain conditions."
+description: "CoW Protocol programmatic orders execute from smart contracts based on on-chain conditions like prices, balances, or time elapsed."
 ---
 
 We call these types of orders "programmatic orders" and we've developed a framework for creating programmatic orders, aptly named the "Programmatic Order Framework."
@@ -16,7 +16,7 @@
 **Example Use-Cases of Programmatic Orders:**
 
 * **Advanced order types:** The conditional nature of programmatic orders allows for complex order types such as stop-loss, good-after-time, take-profit, and more. In fact, CoW Protocol's [TWAP orders](/cow-protocol/explanation/order-types/twap-orders) are built on top of the Programmatic Order Framework.
 * **Automated wallet operations:** Wallets of all sizes can automate recurring actions using the Programmatic Order Framework. DAOs can automate payroll, treasury diversification, fee collections and more, while individuals can automate portfolio rebalancing, yield farming, hedge market positions and more.
 * **Protocol integrations:** Through the Programmatic Order Framework, protocols can add custom functionality to any transaction type. DAO tooling companies, for example, can build plug-n-play products while DeFi protocols can leverage the power of the Framework to assist with recurring protocol-level transactions like loan liquidations.
 
 ## Getting started

cow-protocol/explanation/order-types/twap-orders.mdx

@@ -1,6 +1,6 @@
 ---
 title: "TWAP orders"
-description: "Time-Weighted Average Price (TWAP) orders are an advanced order type available on CoW Protocol that breaks up a large order into several smaller pieces. TWAP orders are ideal for executing big trades with minimal price impact."
+description: "TWAP orders on CoW Protocol split large trades into smaller parts over time, minimizing price impact and improving average execution."
 ---
 
 ## How TWAP Orders Work
@@ -22,13 +22,13 @@
 * **Lower price impact**: As with slippage, breaking up a large order into small pieces allows users to spread their liquidity needs over time, reducing price impact
 * **100% of order surplus**: On CoW Swap, all order surplus is forwarded to the user. If an order executes for a price better than the quoted price - thanks to [Coincidences of Wants](/cow-protocol/explanation/how-it-works/coincidence-of-wants) or any other price improvement that solvers are able to find - the extra price improvement will be forwarded to the user
 * **Eliminating market fluctuations**: By giving traders the time-weighted average price, TWAP orders smooth out market volatility
 * **Custom order parameters**: Users can choose how many parts to split their TWAP order into, adjust the execution timeframe, and even enable a "price protection" feature which prevents execution at unfavorable prices due to market volatility
 
 ## TWAP Requirements
 
 There are also several requirements for placing TWAP orders through CoW Protocol
 
 * Trades on Ethereum Mainnet must be a minimum of $1,000 (the minimum is only $5 for trades on Gnosis chain, Arbitrum One and Base)
 * Users must have a [Safe wallet](https://safe.global/wallet) with an [upgraded fallback handler](https://blog.cow.fi/all-you-need-to-know-about-cow-swaps-new-safe-fallback-handler-8ef0439925d1)
 
 ## Getting started

cow-protocol/howto/cow-explorer.mdx

@@ -1,10 +1,10 @@
 ---
 title: "Viewing orders"
-description: "As CoW Protocol utilizes an off-chain orderbook, and settles on-chain, getting a holistic view of the current state of CoW Protocol requires a combination of on-chain and off-chain data. Individually, this information is available from the following:"
+description: "Use CoW Explorer to view orders, batch auctions, and trading activity on CoW Protocol by combining on-chain and off-chain data."
 ---
 
 * [Order book API](/cow-protocol/reference/apis/orderbook) (off-chain)
 * CoW Protocol Subgraph (on-chain)
 
 Switching between these tools, and reading raw JSON data is better suited for computers, not humans. To make it easier to view the current state of CoW Protocol, we've built a tool that combines the two, providing a convenient and holistic view of the current state of CoW Protocol.
 

cow-protocol/howto/integrate/api.mdx

@@ -1,13 +1,13 @@
 ---
 title: "API Integration Guide"
-description: "Step-by-step guide to integrating with the CoW Protocol orderbook API — from requesting a quote, to computing signing amounts, to creating and monitoring orders."
+description: "Integrate with the CoW Protocol orderbook API — request quotes, compute signing amounts, create and monitor orders."
 ---
 
 import { InlineResource } from '/snippets/resource-actions.jsx'
 
 ## Overview
 
 This guide walks through integrating with the CoW Protocol orderbook API — from requesting a quote, to computing the amounts you need to sign, to creating and monitoring orders.
 
 An intent in CoW Protocol is a signed message that represents a user's wish to trade. It doesn't execute a trade directly — instead, it delegates execution to solvers who find the optimal path.
 
@@ -21,17 +21,17 @@
 
 | Chain | Production | Staging |
 |---|---|---|
 | **Ethereum** | <InlineResource value="https://api.cow.fi/mainnet" href="https://api.cow.fi/mainnet" /> | <InlineResource value="https://barn.api.cow.fi/mainnet" href="https://barn.api.cow.fi/mainnet" /> |
 | **Gnosis Chain** | <InlineResource value="https://api.cow.fi/xdai" href="https://api.cow.fi/xdai" /> | <InlineResource value="https://barn.api.cow.fi/xdai" href="https://barn.api.cow.fi/xdai" /> |
 | **Arbitrum One** | <InlineResource value="https://api.cow.fi/arbitrum_one" href="https://api.cow.fi/arbitrum_one" /> | <InlineResource value="https://barn.api.cow.fi/arbitrum_one" href="https://barn.api.cow.fi/arbitrum_one" /> |
 | **Base** | <InlineResource value="https://api.cow.fi/base" href="https://api.cow.fi/base" /> | <InlineResource value="https://barn.api.cow.fi/base" href="https://barn.api.cow.fi/base" /> |
 | **Avalanche** | <InlineResource value="https://api.cow.fi/avalanche" href="https://api.cow.fi/avalanche" /> | <InlineResource value="https://barn.api.cow.fi/avalanche" href="https://barn.api.cow.fi/avalanche" /> |
 | **Polygon** | <InlineResource value="https://api.cow.fi/polygon" href="https://api.cow.fi/polygon" /> | <InlineResource value="https://barn.api.cow.fi/polygon" href="https://barn.api.cow.fi/polygon" /> |
 | **Linea** | <InlineResource value="https://api.cow.fi/linea" href="https://api.cow.fi/linea" /> | <InlineResource value="https://barn.api.cow.fi/linea" href="https://barn.api.cow.fi/linea" /> |
 | **BNB** | <InlineResource value="https://api.cow.fi/bnb" href="https://api.cow.fi/bnb" /> | <InlineResource value="https://barn.api.cow.fi/bnb" href="https://barn.api.cow.fi/bnb" /> |
 | **Plasma** | <InlineResource value="https://api.cow.fi/plasma" href="https://api.cow.fi/plasma" /> | <InlineResource value="https://barn.api.cow.fi/plasma" href="https://barn.api.cow.fi/plasma" /> |
 | **Ink** | <InlineResource value="https://api.cow.fi/ink" href="https://api.cow.fi/ink" /> | <InlineResource value="https://barn.api.cow.fi/ink" href="https://barn.api.cow.fi/ink" /> |
 | **Sepolia** | <InlineResource value="https://api.cow.fi/sepolia" href="https://api.cow.fi/sepolia" /> | <InlineResource value="https://barn.api.cow.fi/sepolia" href="https://barn.api.cow.fi/sepolia" /> |
 
 <Tip>
 Use **staging** (barn) for testing. Use **production** for real trades.
@@ -409,7 +409,7 @@
 
 | Scheme | Method |
 |---|---|
 | `eip712` | Standard EIP-712 typed data signing (most common for EOAs) |
 | `ethsign` | `eth_sign` with an EIP-191 prefix |
 | `presign` | On-chain pre-signature via the settlement contract |
 | `eip1271` | Smart contract signature via `isValidSignature` (for smart contract wallets) |
@@ -615,7 +615,7 @@
 | Error type | Meaning |
 |---|---|
 | `InsufficientBalance` | Trader doesn't have enough sell token |
 | `InsufficientAllowance` | Sell token not approved to the vault relayer |
 | `InvalidSignature` | Signature doesn't match the order data |
 | `DuplicatedOrder` | An identical order already exists |
 | `MissingFrom` | `from` field required but not provided |
@@ -629,9 +629,9 @@
 
 Before placing an order, walk through these checks. Most failed orders come down to one of these issues.
 
 ### 1. Token allowance to the Vault Relayer
 
 The trader's wallet must have approved the CoW Protocol Vault Relayer contract (`0xC92E8bdf79f0507f65a392b0ab4667716BFE0110`) to spend the sell token **before placing the order** (not before getting the quote — quotes don't require allowance). If the allowance is insufficient, the order will be accepted by the API but solvers will not be able to execute it, and you'll see an `InsufficientAllowance` error if the backend checks balances at submission time.
 
 Make sure the approval amount covers at least the signed `sellAmount` of the order.
 
@@ -669,7 +669,7 @@
 
 | Symptom | Likely cause |
 |---|---|
 | `InsufficientAllowance` error on order creation | Sell token not approved to Vault Relayer |
 | `InsufficientBalance` error on order creation | Wallet doesn't hold enough sell token for the signed sell amount |
 | `InvalidSignature` error on order creation | `signingScheme` mismatch, wrong amounts signed, or encoding error |
 | Order accepted but never executed | Allowance or balance dropped after placement, or price moved past limit |

cow-protocol/howto/integrate/sdk.mdx

@@ -1,18 +1,18 @@
 ---
 title: "SDK Integration"
-description: "The CoW SDK provides programmatic access to CoW Protocol's functionality, enabling you to build custom trading applications with full control over the user interface and trading logic."
+description: "Build custom CoW Protocol trading applications with the CoW SDK — full control over UI, trading logic, and order management."
 hidden: true
 ---
 
 ## Overview
 
 The CoW SDK is a TypeScript library that offers multiple levels of abstraction, from high-level trading functions to low-level API access. It supports multiple blockchain adapters (Ethers v5/v6, Viem) and works across all CoW Protocol-enabled networks.
 
 ## Key Features
 
 * **Trading SDK**: High-level API for swaps and limit orders
 * **Multi-network support**: Ethereum, Gnosis Chain, Arbitrum, Base, Polygon, and more
 * **Flexible adapters**: Works with Ethers v5/v6 and Viem
 * **Order management**: Create, sign, and manage orders programmatically
 * **Quote fetching**: Get real-time pricing before executing trades
 
@@ -33,7 +33,7 @@
 * **Custom UI requirements**: Building unique trading interfaces
 * **Advanced features**: Implementing complex trading logic or order types
 * **Backend integration**: Server-side order management
 * **DApp development**: Integrating trading into existing applications
 
 ## Next Steps
 

cow-protocol/howto/solvers/fee-computation.mdx

@@ -1,5 +1,6 @@
 ---
 title: "Fee computation for limit orders"
+sidebarTitle: "Fee computation"
 description: "Guidelines for how solvers should compute fees when executing limit orders, where users sign orders with zero fees and solvers propose fees at execution time."
 ---
 
@@ -32,7 +33,7 @@
 When computing fees for a limit order, solvers should estimate:
 
 - **Gas cost**: The gas required to execute the order's swap interactions on-chain, priced at the current gas rate
 - **Liquidity cost**: Any adverse price impact from routing through AMMs
 - **Revert risk**: A small buffer to account for the probability that the settlement fails
 
 ### What counts as "execution cost"
@@ -50,7 +51,7 @@
 - Systematically overcharging to accumulate positive slippage
 
 <Warning>
 Violations of fair fee practices are considered potentially slashable offenses under CIP-11's malicious behavior provisions. The protocol monitors fee behavior and systematic overcharging can lead to penalties. See the [competition rules](/cow-protocol/reference/core/auctions/competition-rules#governance) for details.
 </Warning>
 
 ## How fees interact with rewards

cow-protocol/howto/solvers/flashloans_support.mdx

@@ -1,17 +1,18 @@
 ---
 title: "How to execute flashloans orders"
+sidebarTitle: "Flash loan execution"
 description: "This short tutorial explains how orders with flashloans hints can be executed by solvers."
 ---
 
 ## Where to get information about an order’s flashloan?
 
 Information about an order's flashloan is added by the user inside the order’s [appdata](/cow-protocol/reference/core/intents/app-data). As a reminder, the autopilot only shares the appdata hash as part of the auction instance it shares with the [drivers](/cow-protocol/explanation/architecture/driver), and so it is the driver's responsibility to recover the full appdata.
 
 <Note>
   [Solvers](/cow-protocol/explanation/architecture/solver-engine) connected to the reference driver already receive the full appdata from the driver.
 </Note>
 
 For example, this [staging order](https://explorer.cow.fi/gc/orders/0x413a7246f58441ad92ea19c09cef90d1b23a1e211e0963f3d39b7db48140533d669685c660c260d80b614f8d1a5ffd24c4e3b82668cd8760) has the appdata hash `0xa8476d34ec1e22b818cf3d6289e30271a04a4e38a8a3a71f947b5881de06a852` which can be looked up [here](https://barn.api.cow.fi/xdai/api/v1/app_data/0xa8476d34ec1e22b818cf3d6289e30271a04a4e38a8a3a71f947b5881de06a852). Specifically, in the `metadata` field, the `flashloan` entry looks as follows:
 
 ```
       "flashloan": {        "amount": "20000000000000000000",        "liquidityProvider": "0xb50201558B00496A145fE76f7424749556E326D8",        "protocolAdapter": "0x19167A179bcDDBecc2d655d059f20501E5323560",        "receiver": "0x19167A179bcDDBecc2d655d059f20501E5323560",        "token": "0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d"      }
@@ -19,56 +20,56 @@
 
 We now briefly explain what each entry means:
 
 * `amount`: units (in wei) that should be flashloaned;
 * `token`: which token should be flashloaned;
 * `receiver`: address that is supposed to receive the tokens;
 * `liquidityProvider`: the lending protocol’s contract (i.e. AavePool);
 * `protocolAdapter`: which address needs to be used to adapt the `liquidityProvider` to CoW Protocol’s flashloan machinery.
 
 ## Adjustments needed in the solver/driver
 
 ### Encoding the Call to the Flashloan Router
 
 As the flashloan needs to be available over the entire duration of the settlement, all flashloan settlements will have to go through the [flashloan router](/cow-protocol/reference/contracts/periphery/flashloans#iflashloanrouter-contract) (deterministically deployed at `0x9da8b48441583a2b93e2ef8213aad0ec0b392c69`; see the [flash-loan-router repository](https://github.com/cowprotocol/flash-loan-router) and the mainnet deployment [here](https://etherscan.io/address/0x9da8b48441583a2b93e2ef8213aad0ec0b392c69#code)). So, instead of calling `settle()` on the settlement contract, the driver has to call `flashloanAndSettle()` on the flashloan router contract. This `flashloanAndSettle()` call takes 2 arguments:
 
 1. `Loan.Data[]`, which can be trivially initialized with the data from the order’s `flashloan` field;
 2. the settlement, which is the calldata for the regular `settle()` call the router will eventually initiate after taking out all the flashloans.
 
 <Note>
   Specifically for the Aave integration, the driver is not required to inject any additional permissioned interactions. If the call to the flashloan router is constructed correctly and the pre- and post-hooks of the order are included, the call should succeed.
 
   We stress again that this is fully handled by the reference driver.
 </Note>
 
 ### Estimating the Gas Costs
 
 Solvers are responsible for capturing enough network fees to cover the total gas cost of a settlement. The flashloan flow, as described in the previous section, requires a call to a wrapper contract, which first takes the loans and then calls the settlement contract. This wrapper adds an overhead compared to just calling the settlement contract, and for this reason solvers should pay extra attention when estimating the total gas needed.
 
 <Warning>
   Proper gas estimation will be needed for all solvers - even the ones connected to the reference driver, as the reference driver does not do any post-processing and adjustments of the network fees computed by solvers. If this overhead is not taken into account, every time a solver settles a flashloan order would result in losses due to the underestimated gas costs.
 </Warning>
 
 <Note>
   If the solver does a simulation of the `eth_call` as part of its gas estimation logic, one will need to adjust it to call the flashloan router instead of the settlement contract. Alternatively, one can consider heuristically adding an overhead to estimate the additional gas needed. Some information on the gas can be found [here](https://github.com/cowprotocol/flash-loan-router/pull/19).
 </Note>
 
 ### Adjusting the Order Filtering Logic
 
 Many solvers implement some order filtering logic that, for example, discards orders with missing balances early so the matching engine does not have to process them. Orders may be placed if taking out a flashloan and executing the pre-hooks will lead to sufficient balance and allowance for the order. In Aave’s case, for example, the order will only pass the signature verification check if the pre-hook executed successfully. And that can only be executed if the `receiver` in the flashloan hint got enough tokens before hand.
 
 There are multiple ways for a solver to handle this:
 
 * assume an order is good if it uses flashloan;
 * adjust the solver's verification logic to simulate the whole flashloan (as discussed in the section about calling the router);
 * adjust the solver's verification logic to "fake" the flashloan by using state overrides to make it appear as if the flashloan `receiver` got the tokens it needed.
 
 ### Handling Bigger Auction Instances
 
 Together with the support for flashloans, we want to minimize the order filtering the autopilot does before even building the auction. This filtering was initially implemented as a performance optimization since most of the orders do not have sufficient balance, and the plan is to remove it. The order filtering is already implemented in the reference driver as well so nothing should change for solvers connected to that. For other solver/ drivers the auction in the `/solve` endpoint will contain \~3K orders or more from now on.
 
 ## Details on Aave’s Integration
 
 Aave will cover 3 new use cases:
 
 1. **Collateral swap**: User has a debt position and wants to change the collateral they use ([example](https://explorer.cow.fi/gc/orders/0x413a7246f58441ad92ea19c09cef90d1b23a1e211e0963f3d39b7db48140533d669685c660c260d80b614f8d1a5ffd24c4e3b82668cd8760)).
 
@@ -77,8 +78,8 @@
 3. **Debt swap**: User has a debt in a token and wants to swap for something else. Think about leverage, changing the debt to reduce interest for example ([example](https://explorer.cow.fi/gc/orders/0x6c100f2f6bb46ebf1c9f52660fdbe31079d4f982f56b524605358bd419af3a6237c390b08d5a3104b3efc1401e8d11e52624c75868d305a0)).
 
 <Note>
   These orders do not involve Aave’s `aToken` (i.e. `aUSDC` instead of `USDC`) but supporting them is recommended to participate in the non-flashloan version of each of the three usecases.
 </Note>
 
 Assuming the flashloan router call is encoded correctly, Aave’s orders will move the flashloaned funds to the correct spot using the pre-hook and will repay the flashloan in the post-hook. No additional calls have to be encoded in a solution. However, for this to work the flashloan has to be taken out with the given flashloan information. Getting the tokens, for example, by private liquidity is not supported in this use case.
 

cow-protocol/howto/solvers/onboard.mdx

@@ -1,5 +1,7 @@
 ---
 title: "Joining The CoW Protocol Solver Competition"
+sidebarTitle: "Solver onboarding"
+description: "Step-by-step guide to onboarding as a solver in the CoW Protocol competition, from shadow testing to bonding pool setup."
 ---
 
 > ***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.
@@ -18,7 +20,7 @@
 6. Moving to production
 7. Weekly rewards and accounting
 8. Moving to other networks
 9. Joining the mainnet competition
 10. Joining the quoting competition
 11. F.A.Q.
 
@@ -28,7 +30,7 @@
 
 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
 
@@ -48,10 +50,10 @@
 
 ### Exposed Endpoint
 
 The exposed endpoint provided must be of the following format: \{base\_url}/$\{envName}/$\{network} - for example: [https://api.mysolver.io/staging/mainnet](https://api.mysolver.io/staging/mainnet) envName values: shadow, staging, prod supported networks: arbitrum-one, avalanche, base, bnb, linea, mainnet, polygon, xdai (gnosis) and more are coming out!
 
 <Note>
   The request body received by your `/solve` endpoint is quite large. If you are using Nginx, the default request size limit will be too small and prevent you from receiving any auctions. Add the following directive to your Nginx `http`, `server`, or `location` block:
 
   ```nginx
   client_max_body_size 10M;
@@ -113,22 +115,22 @@
 
 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                    |
 
 > ***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.
 
@@ -140,7 +142,7 @@
 
 ## 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.
 
@@ -148,14 +150,14 @@
 
 ## 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.
 
 ## 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.
 
 ## 10. Joining the quoting competition
 
@@ -163,11 +165,11 @@
 
 ## 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)
 
@@ -177,7 +179,7 @@
 
 ### 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.
 
 In the staging (barn) competition settling happens on-chain but the volume is much lower. That way the solver is tested by actually settling orders on chain.
 

cow-protocol/howto/solvers/routes_integration.mdx

@@ -1,5 +1,7 @@
 ---
 title: "Getting new routes integrated Into CoW Protocol"
+sidebarTitle: "Routes integration"
+description: "How DeFi teams can integrate new liquidity sources and trading routes into CoW Protocol's solver network for better price discovery."
 ---
 
 ## Overview

cow-protocol/overview.mdx

@@ -1,6 +1,6 @@
 ---
 title: "What is CoW Protocol?"
-description: "CoW Protocol is the most user-protective trading protocol in DeFi, using batch auctions and solver competition to deliver MEV protection, better prices, and gasless trading."
+description: "CoW Protocol uses batch auctions and solver competition to deliver MEV protection, better prices, and gasless trading on Ethereum."
 ---
 
 <img src="/images/what-is-cow-protocol.png" alt="What is CoW Protocol" style={{ width: '100%', borderRadius: '12px', marginBottom: '2rem' }} />
@@ -18,10 +18,10 @@
 
 <CardGroup cols={2}>
   <Card title="MEV Protection" icon="shield-check">
     Batch auctions with uniform clearing prices eliminate frontrunning and sandwich attacks. Your trades are safe from MEV bots.
   </Card>
   <Card title="Better Prices" icon="chart-line">
     Solvers access on-chain DEXs, private market makers, and peer-to-peer matching (Coincidence of Wants) to find the best execution.
   </Card>
   <Card title="Gasless Trading" icon="gas-pump">
     No ETH needed for gas. Fees are taken from the sell token. If the order can't execute, you pay nothing.
@@ -38,7 +38,7 @@
     Users express **what** they want to trade, not **how**. You sign a message specifying tokens and amounts — solvers handle the rest. [Learn more](/cow-protocol/explanation/introduction/intents)
   </Step>
   <Step title="Solvers">
     Professional third parties compete in an auction to fill your order at the best price. They scan all liquidity sources: AMMs, aggregators, private market makers, and other users' orders. [Learn more](/cow-protocol/explanation/introduction/solvers)
   </Step>
   <Step title="Batch Auctions">
     Orders are grouped into batches and settled together, enabling peer-to-peer matching (Coincidence of Wants) and uniform clearing prices that eliminate MEV. [Learn more](/cow-protocol/explanation/introduction/fair-combinatorial-auction)
@@ -55,7 +55,7 @@
     Instant execution at the best price
   </Card>
   <Card title="Limit Orders" icon="arrow-right-arrow-left" href="/cow-protocol/explanation/order-types/limit-orders">
     Set your price, gasless and free
   </Card>
   <Card title="TWAP" icon="clock" href="/cow-protocol/explanation/order-types/twap-orders">
     Split large trades over time
@@ -93,9 +93,9 @@
 | Section | What you'll find |
 |---|---|
 | **[How It Works](/cow-protocol/explanation/how-it-works/flow-of-an-order)** | Order flow, Coincidence of Wants, protocol vs swap |
 | **[Benefits](/cow-protocol/explanation/benefits/mev-protection)** | MEV protection, price improvement, gasless trading |
 | **[Order Types](/cow-protocol/explanation/order-types/market-orders)** | Market, limit, TWAP, programmatic, hooks, flash loans |
 | **[Tutorials](/cow-swap/tutorials/swap)** | Step-by-step guides for CoW Swap and Explorer |
 | **[Architecture](/cow-protocol/explanation/architecture/overview)** | Orderbook, Autopilot, Driver, Solver Engine |
 | **[API Reference](/cow-protocol/reference/apis/orderbook)** | Orderbook, Solver, and Driver APIs |
 | **[Contracts](/cow-protocol/reference/contracts/core)** | Settlement, VaultRelayer, AllowList addresses |

cow-protocol/reference/contracts/core/allowlist.mdx

@@ -1,6 +1,6 @@
 ---
 title: "GPv2AllowlistAuthentication"
-description: "import HistoricalFact from './_gpv2.md'"
+description: "GPv2AllowlistAuthentication contract reference for managing solver permissions in CoW Protocol's settlement system."
 ---
 
 ## Architecture

cow-protocol/reference/contracts/core/settlement.mdx

@@ -1,6 +1,6 @@
 ---
 title: "GPv2Settlement"
-description: "import HistoricalFact from './_gpv2.md'"
+description: "GPv2Settlement contract reference — the core CoW Protocol contract that executes batch auction settlements on-chain."
 ---
 
 ## Architecture
@@ -11,7 +11,7 @@
 * A list of trades to execute
 * A list of interactions
 
 A solver monitors on-chain liquidity and on receiving batch-auction instances from the Protocol, it determines which orders can be matched, the clearing prices of the settlement, and what extra liquidity is necessary from the blockchain.
 
 Normally, all orders in a settlement are settled with *uniform clearing prices*, which means that every user receives the same price for the same token.
 
@@ -28,13 +28,13 @@
 
 ### Trades
 
 Trades contain a description of the users' orders, a signature for verifying its validity, and the executed amount (for partially fillable orders).
 
 The contract decodes the order parameters from the trade.
 
 ### Interactions
 
 Interactions allow solvers to execute arbitrary calls to any on-chain contract. Normally, they are used to interact with other on-chain liquidity providers, for example, to make a swap call to Uniswap.
 
 <Accordion title="Protocol fee collection">
   Interactions are also used for accounting / bookkeeping purposes as well. As trades are executed, the Protocol collects a fee from each trade and stores this in the settlement contract (known as *[internal buffers](/cow-protocol/reference/core/definitions#internal-buffers)*). At regular intervals, the Protocol withdraws the fees from the settlement contract to the Protocol's treasury Safe.
@@ -68,13 +68,13 @@
 | `sellToken`         | `ERC-20` token sell                                                                                                                                                                             |
 | `buyToken`          | `ERC-20` token to buy                                                                                                                                                                           |
 | `receiver`          | The address that will receive the proceedings of the trade. If this field is `address(0)` (i.e. the zero address `0x00...0`), then the user who signed the trade is going to receive the funds. |
 | `sellAmount`        | Amount of `sellToken` that is sold in wei.                                                                                                                                                      |
 | `buyAmount`         | Amount of `buyToken` that is bought in wei                                                                                                                                                      |
 | `validTo`           | UNIX timestamp (in seconds) until which the order is valid                                                                                                                                      |
 | `appData`           | Extra information about the order. Not enforced by the smart contract outside of signature verification (may be used for referrals etc).                                                        |
 | `feeAmount`         | Amount of fees paid in `sellToken` wei                                                                                                                                                          |
 | `kind`              | `buy` or `sell`                                                                                                                                                                                 |
 | `partiallyFillable` | partially fillable (`true`) or fill-or-kill (`false`)                                                                                                                                           |
 | `sellTokenBalance`  | From where the `sellToken` balance is withdrawn                                                                                                                                                 |
 | `buyTokenBalance`   | Where the `buyToken` is deposited                                                                                                                                                               |
 
@@ -143,7 +143,7 @@
 
 #### `settle`
 
 This function is permissioned and can only be called by solvers passing the allow-list authentication. It executes a settlement:
 
 ```
 function settle(    IERC20[] calldata tokens,    uint256[] calldata clearingPrices,    GPv2Trade.Data[] calldata trades,    GPv2Interaction.Data[][3] calldata interactions) external nonReentrant onlySolver;

cow-protocol/reference/contracts/core/vault-relayer.mdx

@@ -1,11 +1,11 @@
 ---
 title: "GPv2VaultRelayer"
-description: "import HistoricalFact from './_gpv2.md'"
+description: "GPv2VaultRelayer contract reference — protects user funds from malicious solvers by managing token allowances separately."
 ---
 
 ## Architecture
 
 The `GPv2VaultRelayer` contract is an important component used to protect user funds from malicious solvers. As previously mentioned, the `GPv2Settlement` contract allows using arbitrary on-chain liquidity through interactions (such as performing a swap on [Balancer V2](https://balancer.fi), or performing a Paraswap trade). If `Vault` and `ERC-20` allowances were made directly to a `GPv2Settlement` contract, a malicious solver could drain user funds through the interaction mechanism. However, since these allowances are made to the `GPv2VaultRelayer` contract and interactions to the contract are strictly forbidden, malicious solvers have no direct access to user funds. The `GPv2Settlement` contract uses the `GPv2VaultRelayer` to withdraw user tokens only as part of the trade, which contains strong guarantees that the user's signed order parameters are respected.
 
 The `GPv2VaultRelayer` has access to user balances through 3 mechanisms:
 
@@ -25,18 +25,18 @@
 
 ### Balancer External Balances
 
 The second mechanism that the `GPv2VaultRelayer` contract can use to withdraw user `ERC-20` tokens is through `Vault` external balances. This works by having an `ERC-20` allowance for the Balancer Vault, and a relayer approval for the `GPv2VaultRelayer` contract.
 
 This allowance and approval combination allows the `GPv2VaultRelayer` contract to transfer `ERC-20` tokens through the `Vault`. Roughly speaking, the process works in the following way:
 
 1. `GPv2VaultRelayer` request to the Balancer Vault an `ERC-20` transfer from the user account to the `GPv2Settlement` contract
 2. The Balancer Vault verifies that the `GPv2VaultRelayer` contract is: a. Authorized by Balancer governance to act as a relayer b. The user has set an approval for that specific relayer
 3. The Balancer Vault issues an `ERC-20` transfer from the user account to the `GPv2Settlement` contract using the Vault's existing `ERC-20` allowance
 
 This system for withdrawing user funds has several advantages such as:
 
 * It can reuse existing `Vault` `ERC-20` allowances and doesn't require new ones specific to the CoW Protocol.
 * Upgrades to the CoW Protocol contract would only require a single relayer approval for all tokens instead of individual `ERC-20` approvals for each token being traded.
 * The `GPv2VaultRelayer` approval can be revoked by a single transaction to the `Vault` instead of multiple transactions to each `ERC-20` token for which the user wants to remove the approval.
 
 Orders with the `sellTokenBalance` flag set to `external` will withdraw using this process.

cow-protocol/reference/contracts/periphery/composable-cow.mdx

@@ -1,6 +1,6 @@
 ---
 title: "ComposableCoW"
-description: "ComposableCoW is the contract that implements programmatic orders on CoW Protocol. Programmatic orders are a subset of smart contract orders. It allows one to create programmatic orders that:"
+description: "ComposableCoW contract reference for creating self-expressing, self-validating programmatic orders on CoW Protocol."
 ---
 
 1. Can be used to generate multiple discrete order (self-expressing)
@@ -16,23 +16,23 @@
 The following principles have been employed in the architectural design:
 
 1. `O(1)` gas-efficiency for `n` programmatic order creation / replacement / deletion
 2. Programmatic orders **SHOULD** behave the same as a discrete order for EOAs (self-custody of assets, i.e. "wrapper" contracts not required)
 3. Programmatic orders **SHOULD** be optimized towards *statelessness* - pass required data via `calldata`
 4. **MAY** enhance the [Safe](https://safe.global) user experience when paired with [`ExtensibleFallbackHandler`](https://hackmd.io/-nLuF3JIRyuS5w864_mbrg) 🐮🔒
 
 By using Merkle Trees, the gas efficiency of `O(1)` is achieved for `n` programmatic orders. This is achieved by storing the Merkle Tree root on-chain, and passing the Merkle Tree proof to the `ComposableCoW` contract. This allows for `O(1)` gas efficiency for adding / removing programmatic orders.
 
 For simplicity, single orders are also supported, however, this is **NOT** recommended for large `n` as the gas efficiency is `O(n)`.
 
 ### Execution context
 
 As there are many nested contracts, it's important for a callee to know some context from the caller. To achieve this, ComposableCoW passes a `bytes32` variable `ctx` to the callee, such that:
 
 ```
 ctx = merkle root of orders: bytes32(0)      single order:          H(ConditionalOrderParams)
 ```
 
 Having this context also allows for programmatic orders / merkle roots to use this as a key in a mapping, to store programmatic order-specific data.
 
 #### Programmatic order verification flow
 
@@ -139,7 +139,7 @@
 ### Guarantees and Invariants
 
 * CoW Protocol's settlement contract enforces single-use orders, i.e. **NO** `GPv2Order` can be filled more than once
 * For merkle trees, `H(ConditionalOrderParams)` **MUST** be a member of the merkle tree `roots[owner]`
 * For single orders, `singleOrders[owner][H(ConditionalOrderParams)] == true`
 
 <Warning>
@@ -167,7 +167,7 @@
 </Note>
 
 <Check>
   When used with Merkle Trees and a cryptographically-secure random `salt`, the programmatic order is effectively private (until a discrete order cut from this programmatic order is broadcast to the CoW Protocol API).
 </Check>
 
 <Warning>
@@ -186,11 +186,11 @@
 
 | **Field**       | **Description**                                          |
 | --------------- | -------------------------------------------------------- |
 | `proof`         | Merkle Tree proof (if applicable, zero length otherwise) |
 | `params`        | [`ConditionalOrderParams`](#conditionalorderparams)      |
 | `offchainInput` | Off-chain input (if applicable, zero length otherwise)   |
 
 By setting `proof` to zero-length, this indicates to `ComposableCoW` that the order is a single order, and not part of a Merkle Tree.
 
 ### `Proof`
 
@@ -224,7 +224,7 @@
 | `IPFS`    | `5`            | `abi.encode(bytes32 ipfsCid)`                                                                          |
 
 <Warning>
   Locations above are for the point of defining a standard. The provided watch-tower currently does *not* support Merkle Tree proofs for orders.
 </Warning>
 
 <Accordion title="JSON schema for proofs">
@@ -237,7 +237,7 @@
 
 ### `roots`
 
 Using an `owner` as a key, the `roots` mapping stores the Merkle Tree root for the programmatic orders of that `owner`.
 
 ```
 mapping(address => bytes32) public roots;
@@ -273,7 +273,7 @@
 
 #### `setRoot` / `setRootWithContext`
 
 A `safe` or `owner` calls the respective setter method to set the Merkle Tree root for their programmatic orders:
 
 ```
 function setRoot(bytes32 root, Proof calldata proof) public;function setRootWithContext(    bytes32 root,    Proof calldata proof,    IValueFactory factory,    bytes calldata data) external;
@@ -281,12 +281,12 @@
 
 | **Parameter** | **Description**                                                                         |
 | ------------- | --------------------------------------------------------------------------------------- |
 | `root`        | Merkle Tree root of programmatic orders                                                  |
 | `proof`       | [`Proof`](#proof)                                                                       |
 | `factory`     | An `IValueFactory` that will be used to populate the `ctx` storage slot (if applicable) |
 | `data`        | Data to be passed to the `factory` to populate the `ctx` storage slot (if applicable)   |
 
 When a new merkle root is set, emits `MerkleRootSet(address indexed owner, bytes32 root, Proof proof)`.
 
 <Note>
   `ComposableCoW` will **NOT** verify the proof data passed in via the `proof` parameter for `setRoot`. It is the responsibility of the client and watch-tower to verify / validate this.
@@ -335,7 +335,7 @@
 
 #### `getTradeableOrderWithSignature`
 
 A watch-tower calls the `getTradeableOrderWithSignature` method to get a discrete order that is tradeable on CoW Protocol:
 
 ```
 function getTradeableOrderWithSignature(    address owner,    IConditionalOrder.ConditionalOrderParams calldata params,    bytes calldata offchainInput,    bytes32[] calldata proof) external view returns (GPv2Order.Data memory order, bytes memory signature);
@@ -360,7 +360,7 @@
 
 ### Custom error codes
 
 * `ProofNotAuthed()` - the proof is not authorized (merkle root incorrect)
 * `SingleOrderNotAuthed()` - the single order is not authorized
 * `SwapGuardRestricted()` - the swap guard did not pass verification
 * `InvalidHandler()` - the handler is not a valid programmatic order

cow-protocol/reference/contracts/programmatic/twap.mdx

@@ -1,6 +1,6 @@
 ---
 title: "TWAP"
-description: "A simple  (TWAP) trade may be thought of as  smaller trades happening every  time interval, commencing at time . Additionally, it is possible to limit a part's validity of the order to a certain  of time interval ."
+description: "TWAP smart contract reference for CoW Protocol — data structures, verification logic, and order creation for time-weighted trades."
 ---
 
 ## Data Structure
@@ -25,7 +25,7 @@
 * `t` = 86400 (duration of each part, in seconds)
 * `span` = 0 (duration of `span`, in seconds, or `0` for entire interval)
 
 If Alice also wanted to restrict the duration in which each part traded in each day, she may set `span` to a non-zero duration. For example, if Alice wanted to execute the TWAP, each day for 30 days, however only wanted to trade for the first 12 hours of each day, she would set `span` to `43200` (ie. `60 * 60 * 12`).
 
 Using `span` allows for use cases such as weekend or week-day only trading.
 
@@ -39,7 +39,7 @@
    * `salt`: set to a unique value.
    * `staticInput`: the ABI-encoded `TWAP.Data` struct.
 
 2. Use the `struct` from (1) as either a Merkle leaf, or with `ComposableCoW.create` to create a single programmatic order.
 
 3. Approve `GPv2VaultRelayer` to trade `n x partSellAmount` of the safe's `sellToken` tokens (in the example above, `GPv2VaultRelayer` would receive approval for spending 12,000,000 DAI tokens).
 

cow-protocol/reference/core/auctions.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Auction mechanism"
-description: "CoW Protocol uses an implementation of the  for executing trades. Within a given auction, the goal is to compute prices and traded amounts to maximize a well-defined function, subject to a fairness constraint."
+description: "CoW Protocol's batch auction mechanism — how solvers compete to maximize surplus subject to fairness constraints."
 ---
 
 This can be formulated as a concrete optimization problem that needs to be solved, and this is where solvers come into play. Informally, a solver is an algorithm that takes as its input an auction instance and outputs a set of solutions (or bids), each corresponding to how it can best execute different combinations of orders in the batch. The solutions proposed by all solvers are then processed by the protocol, which selects (potentially multiple) winners according to a well-defined objective function.

cow-protocol/reference/core/auctions/accounting.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Solver competition accounting process"
-description: "There is an accounting process in place for the solver competition. It is performed separately on each chain. Currently, the execution of the accounting process takes place once a week for all chains the protocol operates on, and each accounting week starts on Tuesday at midnight UTC and concludes a week later at midnight UTC. This accounting process consists of the following:"
+sidebarTitle: "Accounting"
+description: "Weekly accounting process for the CoW Protocol solver competition, covering rewards, protocol fees, and settlement contract balances."
 ---
 
 * calculation of total rewards/penalties, as specified by the [mechanism](/cow-protocol/reference/core/auctions/rewards);
@@ -15,7 +16,7 @@
 
 In each accounting week, we first identify all auctions that took place within that week. Specifically:
 
 * we identify all blocks with a timestamp that is at least as large as the starting Tuesday, 00:00 UTC timestamp and strictly smaller than the ending Teusday, 00:00 UTC timestamp ([this Dune query](https://dune.com/queries/3333356) does exactly this computation). Let \[X,Y] denote this interval;
 * we then look at all auctions whose block deadline (i.e., the latest block for which the on-chain submission is considered valid/on-time) is larger or equal than X and smaller or equal than Y, and these are the auctions for which we compute rewards for that particular accounting week.
 
 At the end of each accounting week, for each solver, the rewards and penalties are aggregated, and we have a performance reward per solver; note this can be negative in the case where penalties exceed rewards. The reward, naturally expressed in the native token, for each auction can be found in this Dune table: [https://dune.com/queries/4351957](https://dune.com/queries/4351957) (see `capped_payment` column).
@@ -24,7 +25,7 @@
 
 We stress that performance rewards and quote rewards are kept separate in the accounting.
 
 We also highlight that performance and quote rewards are both paid in COW. To convert rewards from the native currency to COW, we use the average COW price, in USD, as provided in the `prices.usd` Dune table, where the blockchain is set to Ethereum, so as to ensure that this price is always available. The average is taken over the last 24h of the accounting period, in order to reduce the possibility of manipulating that price (see [here](https://github.com/cowprotocol/dune-queries/blob/6ee39f14eb74fee770fe9b79ceef7b18fc5e5dba/cowprotocol/accounting/rewards/main_rewards_dashboard_query_2510345.sql#L57) for the Dune sql code that does this specific calculation). The native token's average price in USD is also computed similarly (see [here](https://github.com/cowprotocol/dune-queries/blob/6ee39f14eb74fee770fe9b79ceef7b18fc5e5dba/cowprotocol/accounting/rewards/main_rewards_dashboard_query_2510345.sql#L64)). Once these two prices are available, the conversion from native token to COW and vice versa is straightforward.
 
 ## Protocol and partner fees
 
@@ -56,7 +57,7 @@
 
 In this section, we share a few details about how protocol/partner/network fees are computed by observing an on-chain execution. When it comes to protocol and partner fees, one needs to be aware of the fee policies associated with an order. These fee policies are shared with solvers as part of the auction instance sent to them, and are also revealed for each trade in the [Order Book API Reference](/cow-protocol/reference/apis/orderbook). This allows us to fully determine the protocol and partner fees associated with the order.
 
 To use an example, suppose that we have a sell order that sells 1 WETH and the user receives 3000 USDC. When checking the api, we might see the following:
 
 ```
     "executedProtocolFees": [      {        "policy": {          "surplus": {            "factor": 0.5,            "maxVolumeFactor": 0.01          }        },        "amount": "5000000",        "token": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"      }    ]
@@ -66,11 +67,11 @@
 
 Once we know how much is the protocol fee, we can add it to the amount received by the user, in case of a sell order, or subtract it from the sell amount of the trade, in case of a buy order, in order to compute what we call the "raw buy amount" (or "raw sell amount" respectively). Using this amount and the uniform clearing price vector the solver proposed in its execution, we can now identify the network fee the solver charged the user.
 
 To elaborate a bit on the above, we clarify that for each transaction, a solver is required to report a uniform clearing price vector as part of the calldata, meaning a vector that has one price per token traded, as well as custom prices on a per trade basis. These custom prices allow a solver to capture fees, whenever needed. The uniform clearing price vector is meant to describe the exchange rates in the absence of fees. So once we have the raw sell/buy amount, we can apply the uniform clearing price vector and see how much the user "would" have sold if there was no network fee charged. The difference between what the user actually sold and what they would have sold in case of zero network fees exactly identifies how much was the network fee charged to the trade.
 
 Going back to our example, suppose the solver charged 0.001 WETH for the above trade. This means that the solver received 1 WETH, kept 0.001 WETH aside, and then swapped 0.999 WETH for 3005 USDC. The solver then realized that the protocol fee is 5 USDC, and thus kept 5 USDC aside, while returning 3000 USDC to the user. The uniform clearing prices, since they capture the exchange rate in the absence of fees, would then be set as follows: ucp(WETH) = 3005 and ucp(USDC) = 0.999. While the custom trade prices would be set to p(WETH) = 3000 and p(USDC) = 1.
 
 From the actual on-chain execution, as we mentioned, one can reverse-engineer the solver's execution and determine using the fee policies that the protocol fee is 5 USDC. Which means that the raw buy amount is equal to 3005 USDC. By observing the calldata, we recover the UCP vector, and apply the exchange rate implied by that vector, which gives that the user "should" have sold 3005 \* 0.999 / 3005 = 0.999 WETH. Since the user actually sold 1 WETH, we then conclude that the difference, i.e., 1 - 0.999 = 0.001 WETH, was the network fee the solver charged for the trade.
 
 ### Slippage
 
@@ -112,7 +113,7 @@
 function payOverdraft(address solver) external payable;
 ```
 
 To check an overdraft, call `solverOverdraftBalance` with the solver address. To pay it off, call `payOverdraft` with the solver address and attach the desired payment as `msg.value` in wei.
 
 <Note>
   Solvers should monitor their overdraft status regularly. Accumulated overdrafts reduce future payouts and, if left unaddressed, can significantly delay reward distributions. The [solver rewards Dune dashboard](https://dune.com/cowprotocol/cow-solver-rewards) can be used to track current balances and outstanding overdraft amounts.

cow-protocol/reference/core/auctions/competition-rules.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Solver competition rules"
-description: "All solvers participating in the solver competition must abide by certain rules. In this section, we outline all these rules. They naturally split into three classes:"
+description: "Rules for CoW Protocol solver competition — smart contract, off-chain protocol, and governance-enforced requirements."
 ---
 
 1. Those enforced explicitly by the [smart contract](#smart-contract)
@@ -37,38 +37,38 @@
 
     2. Post-hooks need to be executed after pushing out user order proceeds
 
     3. Partially fillable orders:
 
        1. Should execute the pre-hooks on the first fill only
        2. Should execute the post-hooks on every fill
 
     4. Execution of a hook means:
 
        1. There exists an internal CALL in the settlement transaction with a matching triplet: target, gasLimit, calldata
        2. The hook needs to be attempted, meaning the hook reverting is not violating any rules
        3. Intermediate calls between the call to settle and hook execution must not revert
        4. The available gas forwarded to the hook CALL is greater or equal than specified gasLimit
 
   * The settlement is executed before or at the deadline of that auction. Not following these rules can result in immediate denylisting of a solver until a manual inspection is executed. These rules are currently implemented in the [circuit-breaker-validator](https://github.com/cowprotocol/circuit-breaker-validator).
 
 * Buffer usage: solvers are allowed to use funds in the settlement contract for certain types of use cases.
 
   * Solvers are supposed to store *protocol and partner fees* in the settlement contract.
   * Solvers are allowed to store funds to cover *network fees* in the contract.
   * Solvers are allowed to use funds in the settlement contract to offset price variations on liquidity sources, also referred to as *slippage*.
   * Solvers are allowed to use funds in the settlement contract for executing trades, also referred to as *internalizations*, if the token which accumulates in the contract is among marked as `"trusted": true` in the auction json, see the [API specification](/cow-protocol/reference/apis/driver). Solvers bear responsibility for all changes to balances of the settlement contract. The concrete implementation of buffer accounting is described in the [accounting section](/cow-protocol/reference/core/auctions/accounting).
 
 <Note>
   The deadline for solutions depends on the network and is set as a specific number of blocks after the current block at the time of sending the settle request to the solver:
 
   * Mainnet: 3 blocks
   * Arbitrum: 40 blocks
   * Gnosis chain: 5 blocks
   * Base: 20 blocks
   * Avalanche: 20 blocks
   * Polygon: 20 blocks
   * BNB: 40 blocks
   * Linea: 20 blocks
   * Plasma: 20 blocks
 </Note>
 
@@ -77,10 +77,10 @@
 Social consensus rules are not enforced by the smart contract or the autopilot. However, by voting on them in a CoW Improvement Proposal (CIP), CoW DAO has decided that these rules should be followed to ensure a healthy competition. For that, the core team has developed monitoring tools that check every on-chain settlement and flag suspicious ones.
 
 <Warning>
   At CoW DAO's discretion, systematic violation of these rules may lead to penalizing or slashing of the offending solver.
 </Warning>
 
 * Provision of unfair solutions ([CIP-11](https://snapshot.org/#/cow.eth/proposal/0x16d8c681d52b24f1ccd854084e07a99fce6a7af1e25fd21ddae6534b411df870)). Uniform directional clearing prices computed by solvers should be in line (or even better) than what the users would get elsewhere. This becomes particularly relevant for solutions where CoWs happen, i.e., when some volume is settled as part of a CoW and not by routing through an AMM. This rule is often referenced as "EBBO" (Ethereum Best Bid and Offer), and the AMMs that "should" be considered by solvers when computing an execution route for an order are referenced as "Baseline liquidity". Baseline liquidity is defined with a set of protocols and a set of so-called base tokens, such that for every protocol and every order, the following pairs are considered:
 
   * sell token / base token
   * buy token / base token
@@ -88,50 +88,50 @@
 
   ### Base protocols and tokens
 
   The following detail sections list the protocols and base tokens that are considered for Ethereum Mainnet and Gnosis Chain:
 
   <Accordion title="Ethereum mainnet baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Sushiswap, Swapr, Balancer v2, Pancakeswap
     * **Base tokens**: [`WETH`](https://etherscan.io/token/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2), [`DAI`](https://etherscan.io/token/0x6B175474E89094C44Da98b954EedeAC495271d0F), [`USDC`](https://etherscan.io/token/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48), [`USDT`](https://etherscan.io/token/0xdAC17F958D2ee523a2206206994597C13D831ec7), [`COMP`](https://etherscan.io/token/0xc00e94Cb662C3520282E6f5717214004A7f26888), [`MKR`](https://etherscan.io/token/0x9f8F72aA9304c8B593d555F12eF6589cC3A579A2), [`WBTC`](https://etherscan.io/token/0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599), [`GNO`](https://etherscan.io/token/0x6810e776880C02933D47DB1b9fc05908e5386b96)
   </Accordion>
 
   <Accordion title="Gnosis Chain baseline protocols and tokens">
     * **Protocols**: Honeyswap, Sushiswap, Baoswap, Swapr, Balancer v2
     * **Base tokens**: [`WXDAI`](https://gnosisscan.io/token/0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d), [`HNY`](https://gnosisscan.io/token/0x71850b7e9ee3f13ab46d67167341e4bdc905eef9), [`USDT`](https://gnosisscan.io/token/0x4ECaBa5870353805a9F068101A40E0f32ed605C6), [`USDC`](https://gnosisscan.io/token/0xDDAfbb505ad214D7b80b1f830fcCc89B60fb7A83), [`sUSD`](https://gnosisscan.io/token/0xB1950Fb2C9C0CbC8553578c67dB52Aa110A93393), [`WBTC`](https://gnosisscan.io/token/0x8e5bbbb09ed1ebde8674cda39a0c169401db4252), [`GNO`](https://gnosisscan.io/token/0x9C58BAcC331c9aa871AFD802DB6379a98e80CEdb), [`STAKE`](https://gnosisscan.io/token/0xb7D311E2Eb55F2f68a9440da38e7989210b9A05e), [`xOWL`](https://gnosisscan.io/token/0x0905Ab807F8FD040255F0cF8fa14756c1D824931), [`WETH`](https://gnosisscan.io/token/0x6A023CCd1ff6F2045C3309768eAd9E68F978f6e1), [`wstETH`](https://gnosisscan.io/address/0x6c76971f98945ae98dd7d4dfca8711ebea946ea6), [`sDAI`](https://gnosisscan.io/address/0xaf204776c7245bf4147c2612bf6e5972ee483701), [`USDC.e`](https://gnosisscan.io/address/0x2a22f9c3b484c3629090FeED35F17Ff8F88f76F0)
   </Accordion>
 
   <Accordion title="Arbitrum baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Sushiswap, Swapr, Balancer v2, Pancakeswap
     * **Base tokens**: [`WETH`](https://arbiscan.io/token/0x82af49447d8a07e3bd95bd0d56f35241523fbab1), [`USDC`](https://arbiscan.io/token/0xaf88d065e77c8cc2239327c5edb3a432268e5831), [`USDT`](https://arbiscan.io/token/0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9), [`DAI`](https://arbiscan.io/token/0xda10009cbd5d07dd0cecc66161fc93d7c9000da1), [`GNO`](https://arbiscan.io/token/0xa0b862f60edef4452f25b4160f177db44deb6cf1)
   </Accordion>
 
   <Accordion title="Base chain baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Balancer v2
     * **Base tokens**: [`WETH`](https://basescan.org/address/0x420000000000000000000000000000000000000), [`USDC`](https://basescan.org/address/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913), [`DAI`](https://basescan.org/address/0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb)
   </Accordion>
 
   <Accordion title="Avalanche chain baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Balancer v2
     * **Base tokens**: [`WAVAX`](https://snowscan.xyz/address/0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7), [`USDC`](https://snowscan.xyz/address/0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e), [`USDT`](https://snowscan.xyz/address/0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7)
   </Accordion>
 
   <Accordion title="Polygon chain baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Balancer v2
     * **Base tokens**: [`WPOL`](https://polygonscan.com/address/0x0d500b1d8e8ef31e21c99d1db9a6444d3adf1270), [`USDC`](https://polygonscan.com/address/0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359), [`USDT`](https://polygonscan.com/address/0xc2132d05d31c914a87c6611c10748aeb04b58e8f)
   </Accordion>
 
   <Accordion title="BNB chain baseline protocols and tokens">
     * **Protocols**: Uniswap v2/v3, Pancake Swap
     * **Base tokens**: [`WBNB`](https://bnbscan.com/address/0xbb4cdb9cbd36b01bd1cbaebf2de08d9173bc095c), [`BUSD`](https://bnbscan.com/address/0xe9e7cea3dedca5984780bafc599bd69add087d56), [`USDT`](https://bnbscan.com/address/0x55d398326f99059ff775485246999027b3197955), [`WETH`](https://bnbscan.com/address/0x2170ed0880ac9a755fd29b2688956bd959f933f8)
   </Accordion>
 
   <Accordion title="Linea chain baseline protocols and tokens">
     * **Protocols**: Uniswap v3
     * **Base tokens**: [`WETH`](https://lineascan.build/token/0xe5d7c2a44ffddf6b295a15c148167daaaf5cf34f), [`USDC`](https://lineascan.build/token/0x176211869ca2b568f2a7d4ee941e073a821ee1ff), [`USDT`](https://lineascan.build/token/0xa219439258ca9da29e9cc4ce5596924745e12b93)
   </Accordion>
 
   <Accordion title="Plasma chain baseline protocols and tokens">
     * **Protocols**: Uniswap v3
     * **Base tokens**: [`WETH`](https://plasmascan.to/token/0x9895D81bB462A195b4922ED7De0e3ACD007c32CB), [`USDT0`](https://plasmascan.to/token/0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb), [`WXPL`](https://plasmascan.to/token/0x6100E367285b01F48D07953803A2d8dCA5D19873)
   </Accordion>
 
@@ -143,7 +143,7 @@
 
 * Local Token Conservation, aka illegal surplus shifts ([CIP-11](https://snapshot.org/#/cow.eth/proposal/0x16d8c681d52b24f1ccd854084e07a99fce6a7af1e25fd21ddae6534b411df870)). Due to the nature of batching, a solver can intentionally transfer surplus among orders that share a common token. This is not allowed, and non-trivial surplus shifts can be penalized and can lead to solver slashing.
 
 * Pennying/overbidding ([CIP-13](https://snapshot.org/#/cow.eth/proposal/0x812273c78abe1cea303d8381e1fb901a4cb701715fd24f4b769d0a0b3779b3e2)). Pennying or overbidding is the intentional inflation of the reported score, by a solver, with the hope that their solution will win and that solver rewards, and/or the possibility of positive slippage, will cover the loss that they seem to be committing to. Systematically doing so can lead to solver slashing.
 
 * Other malicious behavior ([CIP-11](https://snapshot.org/#/cow.eth/proposal/0x16d8c681d52b24f1ccd854084e07a99fce6a7af1e25fd21ddae6534b411df870)). Malicious solver behavior is not limited to the above examples. Slashing can still happen for other reasons where there is intentional harm caused to the user and/or the protocol at the discretion of the CoW DAO. A concrete example of such is a solver intentionally not including the [pre/post hooks](/cow-protocol/reference/core/intents/hooks) associated with an order.
 

cow-protocol/reference/core/auctions/ebbo-rules.mdx

@@ -1,11 +1,11 @@
 ---
 title: "EBBO violations: details"
-description: "In this section, we will elaborate on the details about what consistutes an EBBO violation, and what actions are taken by the DAO in case such a violation occurs. The content of this section is based on ."
+description: "What constitutes an EBBO violation in CoW Protocol and how the DAO enforces reimbursement when solvers fail to meet best execution."
 ---
 
 ## Certificate of EBBO violation
 
 A certificate for an EBBO violation consists of a reference routing on a block (and log index) between the start of the auction and when the settlement happened onchain. A reference routing for a trade at a given block (and index) is an execution of that trade which only uses liquidity from base protocols and routes through base tokens (see the "Base protocols and tokens" section [here](/cow-protocol/reference/core/auctions/competition-rules) for the definition of base protocols and base tokens). The surplus received by users in this routing is used as reference surplus. The difference between the reference surplus and the surplus actually received by the user is the size of the EBBO violation. This amount needs to be reimbursed to a user.
 
 A certificate for an EBBO violation can be challenged by the solver who is accused of the EBBO violation by providing a different block (and index), within 72 hours of the notification of the violation. In this case, a reference routing on this block (and index) might be proposed by the core team and used as certificate instead. The new certificate, if any, cannot be challenged again.