+
+---
+
+```json
+{
+ "protocolFeeBps": "2",
+ "quote": {
+ "buyAmount": "191179999",
+ "feeAmount": "62483346430736",
+ "sellAmount": "99937516653569264",
+ "kind": "sell"
+ },
+ ...
+}
+```
+
+| Field | Description |
+|---|---|
+| `protocolFeeBps` | Protocol fee in basis points |
+| `quote.sellAmount` | Sell amount **after** network costs have been deducted |
+| `quote.feeAmount` | Network costs, in **sell token** units |
+| `quote.buyAmount` | Buy amount **after** network costs and protocol fee have been deducted |
+
+### Buy order response
+
+
+
+---
+
+```json
+{
+ "protocolFeeBps": "2",
+ "quote": {
+ "buyAmount": "200000000",
+ "feeAmount": "42560776189182",
+ "sellAmount": "104486220751250279",
+ "kind": "buy"
+ },
+ ...
+}
+```
+
+For buy orders, `sellAmount` is **after** the protocol fee, and the `feeAmount` (network costs) is **not yet included** in the sell amount — it must be added separately.
+
+## 3. Amount Stages
+
+The quote response and order construction use a shared vocabulary of amount stages — each representing the token amount at a specific point in the fee pipeline. Understanding these terms is essential for interpreting quote values and building orders correctly.
+
+| Term | Description |
+|---|---|
+| **`beforeAllFees`** (= `spotPrice`) | The raw exchange rate with no fees applied. This is the theoretical "perfect world" price. It serves as the reference point for calculating partner fees and slippage. |
+| **`afterProtocolFees`** | Amount after CoW Protocol's own fee (`protocolFeeBps`) has been applied. |
+| **`afterNetworkCosts`** | Amount after gas costs (network costs) have been applied. Network costs are always denominated in the **sell token**, but may be converted to buy token units when applied to the buy side. |
+| **`afterPartnerFees`** | Amount after the integrator/partner fee has been deducted. |
+| **`afterSlippage`** | The final amount after the user's slippage tolerance has been applied. **This is the value signed into the order** — it is the minimum the user will receive (sell orders) or the maximum they will pay (buy orders). |
+
+### Flow for sell orders
+
+
+
+>The code below is simplified, see the full working code in [CoW SDK `getQuoteAmountsAndCosts`](https://github.com/cowprotocol/cow-sdk/blob/main/packages/order-book/src/quoteAmountsAndCosts/getQuoteAmountsAndCosts.ts).
+
+The `/quote` response maps directly to `afterNetworkCosts`. `beforeAllFees` is reconstructed from it for partner fee calculations:
+
+```ts
+// /quote response maps to afterNetworkCosts
+const afterNetworkCosts = {
+ sellAmount: quote.sellAmount,
+ buyAmount: quote.buyAmount,
+}
+
+// reconstruct beforeAllFees (spot price) — used as the base for partner fee calculation
+const networkCostAmountInBuyCurrency = (quote.buyAmount * quote.feeAmount) / quote.sellAmount
+const beforeAllFees = {
+ sellAmount: quote.sellAmount + quote.feeAmount,
+ buyAmount: quote.buyAmount + networkCostAmountInBuyCurrency + protocolFeeAmount,
+}
+
+// partner fee is deducted from buy amount, relative to spot price
+const afterPartnerFees = {
+ sellAmount: afterNetworkCosts.sellAmount,
+ buyAmount: afterNetworkCosts.buyAmount - partnerFeeAmount,
+}
+// partnerFeeAmount = beforeAllFees.buyAmount * partnerFeeBps / 10000
+
+// slippage reduces buy amount (user accepts receiving less)
+const afterSlippage = {
+ sellAmount: afterPartnerFees.sellAmount,
+ buyAmount: afterPartnerFees.buyAmount - slippageAmount,
+}
+// slippageAmount = afterPartnerFees.buyAmount * slippageBps / 10000
+
+// sell is set to spot price — settlement contract deducts network costs itself
+const amountsToSign = {
+ sellAmount: beforeAllFees.sellAmount, // = quote.sellAmount + quote.feeAmount
+ buyAmount: afterSlippage.buyAmount, // minimum to receive
+}
+```
+
+### Flow for buy orders
+
+>The code below is simplified, see the full working code in [CoW SDK `getQuoteAmountsAndCosts`](https://github.com/cowprotocol/cow-sdk/blob/main/packages/order-book/src/quoteAmountsAndCosts/getQuoteAmountsAndCosts.ts).
+
+
+
+The `/quote` sell amount maps to `afterProtocolFees`. The buy amount is fixed and maps to `beforeAllFees`:
+
+```ts
+// /quote response: sell maps to afterProtocolFees, buy is fixed (= beforeAllFees)
+const afterProtocolFees = {
+ sellAmount: quote.sellAmount,
+ buyAmount: quote.buyAmount,
+}
+
+// reconstruct beforeAllFees (spot price) — used as the base for partner fee calculation
+const beforeAllFees = {
+ sellAmount: quote.sellAmount - protocolFeeAmount,
+ buyAmount: quote.buyAmount,
+}
+
+// add network costs to sell amount
+const afterNetworkCosts = {
+ sellAmount: quote.sellAmount + quote.feeAmount,
+ buyAmount: quote.buyAmount,
+}
+
+// partner fee is added to sell amount, relative to spot price
+const afterPartnerFees = {
+ sellAmount: afterNetworkCosts.sellAmount + partnerFeeAmount,
+ buyAmount: afterNetworkCosts.buyAmount,
+ // partnerFeeAmount = beforeAllFees.sellAmount * partnerFeeBps / 10000
+}
+
+// slippage increases sell amount (user accepts paying more)
+const afterSlippage = {
+ sellAmount: afterPartnerFees.sellAmount + slippageAmount,
+ buyAmount: afterPartnerFees.buyAmount,
+ // slippageAmount = afterPartnerFees.sellAmount * slippageBps / 10000
+}
+
+// buy is fixed (exact amount to receive), sell includes all fees and slippage
+const amountsToSign = {
+ sellAmount: afterSlippage.sellAmount, // maximum to pay
+ buyAmount: beforeAllFees.buyAmount, // = quote.buyAmount
+}
+```
+
+## 4. Fees & Slippage
+
+Several layers of fees transform the raw spot price into the final amounts signed in the order.
+
+### Fee types
+
+| Fee | Description | Token |
+|---|---|---|
+| **Network costs** | Gas fees for on-chain execution, estimated by the protocol | Sell token |
+| **Protocol fee** | CoW Protocol's fee, expressed in basis points (`protocolFeeBps`) | Buy token (sell orders) / Sell token (buy orders) |
+| **Partner fee** | Optional fee added by integrators (e.g. widget providers) | Buy token (sell orders) / Sell token (buy orders) |
+| **Slippage** | Tolerance buffer to account for price movements | Buy token (sell orders) / Sell token (buy orders) |
+
+## Spot Price (beforeAllFees)
+
+The spot price is the exchange rate before any fees are applied. It serves as the reference for partner fee and slippage calculations.
+
+### Sell order
+
+```
+beforeAllFees.sellAmount = quote.sellAmount + quote.feeAmount
+
+Network Costs (buy token) = (quote.buyAmount × quote.feeAmount) / quote.sellAmount
+
+beforeAllFees.buyAmount = quote.buyAmount + protocolFeeAmount + Network Costs (buy token)
+
+```
+
+
+### Buy order
+
+```
+beforeAllFees.sellAmount = quote.sellAmount - protocolFeeAmount
+
+beforeAllFees.buyAmount = quote.buyAmount
+```
+
+## Protocol Fee
+
+The protocol fee is expressed as basis points (`protocolFeeBps`) in the quote response.
+
+### Sell orders (buy token units)
+
+For sell orders, `quote.buyAmount` is already **after** the protocol fee has been deducted:
+
+```
+protocolFeeAmount = quote.buyAmount × (protocolFeeBps / 10000) / (1 − protocolFeeBps / 10000)
+```
+
+### Buy orders (sell token units)
+
+For buy orders, the protocol fee is applied to the sum of sell amount and network costs:
+
+```
+protocolFeeAmount = (quote.sellAmount + quote.feeAmount) × (protocolFeeBps / 10000) / (1 + protocolFeeBps / 10000)
+```
+
+## Partner Fee
+
+The partner (integrator) fee is calculated as a percentage of the **spot price** (`beforeAllFees`), not the post-fee amounts.
+
+### Sell orders (buy token units)
+
+```
+partnerFeeAmount = beforeAllFees × partnerFeePercent / 100
+```
+
+### Buy orders (sell token units)
+
+The same formula applies, but the result is in sell token units.
+
+## Slippage
+
+Slippage tolerance uses the same calculation as the partner fee, but it is applied to the **`afterPartnerFees`** amount rather than the spot price:
+
+```
+slippageAmount = afterPartnerFees × slippagePercent / 100
+```
+
+## Forming the Final Order
+
+The signed order combines the quote API response with UI/integrator settings:
+
+| Source | Fields |
+|---|---|
+| `/quote` API response | `sellAmount`, `buyAmount`, `feeAmount`, `protocolFeeBps` |
+| UI / integrator settings | `partnerFee`, `slippage` |
+
+The resulting order contains the **`afterSlippage`** buy amount (for sell orders) or sell amount (for buy orders), which the protocol guarantees as the minimum the user will receive (or maximum they'll pay). Fixed amount (`sellAmount` for `SELL` order, `buyAmount` for `BUY` order), meanwhile, corresponds to the spot price amount.
+
+### Sell order
+
+```typescript
+const orderToSign = {
+ sellAmount: beforeAllFees.sellAmount,
+ buyAmount: afterSlippage.buyAmount
+}
+```
+
+### Buy order
+
+```typescript
+const orderToSign = {
+ sellAmount: afterSlippage.sellAmount,
+ buyAmount: beforeAllFees.buyAmount
+}
+```
diff --git a/docs/cow-protocol/concepts/how-it-works/protocol-vs-swap.md b/docs/cow-protocol/concepts/how-it-works/protocol-vs-swap.md
new file mode 100644
index 000000000..ec00abee2
--- /dev/null
+++ b/docs/cow-protocol/concepts/how-it-works/protocol-vs-swap.md
@@ -0,0 +1,38 @@
+---
+sidebar_position: 3
+---
+
+# CoW Protocol vs. CoW Swap
+
+While the two are intertwined, there are important differences between CoW Protocol and CoW Swap.
+
+
+
+## CoW Protocol
+
+CoW Protocol is a trading protocol that leverages [intents](../introduction/intents) and [fair combinatorial batch auctions](../introduction/fair-combinatorial-auction) to find optimal prices and protect orders from Maximal Extractable Value (MEV).
+
+The protocol groups orders together into batches and relies on a competition between third parties, known as [solvers](../introduction/solvers), to find the best execution price for all orders in a given batch.
+
+Solvers search all available on-chain liquidity and even tap off-chain private inventory to fill orders.
+If two orders in a batch are swapping opposite assets, solvers match them together in a peer-to-peer [*Coincidence of Wants (CoW)*](./coincidence-of-wants) trade.
+
+Once they have found their solutions, solvers compete to win the right to settle a batch of orders.
+The protocol runs a solver competition and picks the "winning" solver to settle each batch of orders, defined as the solver that can maximize surplus for traders.
+Solvers typically win the competition by finding the best combination of on- and off-chain liquidity sources, the most optimal CoW, the most efficient technical execution, or a combination of these in a single settlement.
+
+## CoW Swap
+
+CoW Swap was the first trading interface built on top of CoW Protocol and is currently the most popular way for users to trade with CoW Protocol.
+
+Other trading apps and dApps, like Balancer, have also integrated CoW Protocol natively within their trading interfaces and advanced traders often place trades directly through the protocol.
+
+The UI of CoW Swap includes some unique features, such as:
+
+- Wallet history
+- User token balances
+- Games
+- The legendary "Moo" sound
+- Fortune cookies
+
+CoW Swap works with many popular wallets, including [Rabby](https://rabby.io/), [MetaMask](https://metamask.io/), [Trust Wallet](https://trustwallet.com/), [Safe](https://safe.global/), [Trezor](https://trezor.io/), [Ledger](https://www.ledger.com/), and any wallet supporting [WalletConnect v2](https://walletconnect.com/).
diff --git a/docs/cow-protocol/concepts/introduction/_category_.json b/docs/cow-protocol/concepts/introduction/_category_.json
new file mode 100644
index 000000000..50c26e743
--- /dev/null
+++ b/docs/cow-protocol/concepts/introduction/_category_.json
@@ -0,0 +1,9 @@
+{
+ "position": 1,
+ "label": "Introduction",
+ "collapsible": true,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md b/docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md
new file mode 100644
index 000000000..252818a22
--- /dev/null
+++ b/docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 3
+---
+
+# Fair Combinatorial Batch Auction
+
+CoW Protocol collects and aggregates [intents](./intents) off-chain and auctions them off to [solvers](./solvers). The auction is combinatorial 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.
+
+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).
+
+
+
+The fair combinatorial auction provides several benefits:
+
+- [**MEV Protection**](../benefits/mev-protection): Fair combinatorial auctions allow for Uniform Directed Clearing Prices (UDP), where a directed asset pair that appears multiple times across orders in the same auction settles for a consistent price. This makes transaction order irrelevant within the block, undermining the ability for MEV bots to extract value.
+- **[Coincidence of Wants](../how-it-works/coincidence-of-wants)**: When multiple orders trade the same assets within an auction, there may be an opportunity for a peer-to-peer swap that doesn't tap on-chain liquidity, which a solver could exploit by submitting a batched bid.
+- **Fairness**: Ensuring that each order receives as much as it would have received had that order been auctioned off alone.
diff --git a/docs/cow-protocol/concepts/introduction/intents.md b/docs/cow-protocol/concepts/introduction/intents.md
new file mode 100644
index 000000000..cebc31194
--- /dev/null
+++ b/docs/cow-protocol/concepts/introduction/intents.md
@@ -0,0 +1,35 @@
+---
+sidebar_position: 1
+---
+
+# Intents
+
+Rather than placing orders by _**signing a raw transaction**_ that executes directly on-chain (i.e. as happens on Uniswap or SushiSwap), CoW Protocol users place orders by _**signing an "intent to trade" message**_ 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.
+
+There are a number of [financial](#financial-benefits-of-intents) and [technical](#technical-benefits-of-intents) advantages to intent-based trading.
+
+## Financial Benefits of Intents
+
+When a user places a trade directly on-chain, the execution path is set in stone and the trader receives whatever price (+/- slippage) the AMM or aggregator they're trading on gives them.
+
+Thanks to its intent-based architecture, CoW Protocol delegates the job of finding the optimal execution path to professional third parties known as [solvers](./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**](../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**](../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
+
+The intent-based architecture of CoW Protocol also provides a number of technical benefits:
+
+- Enabling [solvers](./solvers) to execute all sorts of transactions (not just trades) based on specific instructions and on-chain conditions. This powers products like [CoW Hooks](../order-types/cow-hooks) and [Programmatic Orders](../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
+- Allowing the protocol to settle orders in batches, generating efficiencies from [Coincidence of Wants](../how-it-works/coincidence-of-wants) or gas savings.
diff --git a/docs/cow-protocol/concepts/introduction/solvers.md b/docs/cow-protocol/concepts/introduction/solvers.md
new file mode 100644
index 000000000..d363b3e7b
--- /dev/null
+++ b/docs/cow-protocol/concepts/introduction/solvers.md
@@ -0,0 +1,25 @@
+---
+sidebar_position: 2
+---
+
+# Solvers
+
+CoW Protocol delivers optimal price outcomes by leveraging an open solver competition for order matching.
+
+
+
+Solvers are bonded third parties that execute trades on behalf of users through an [intent-based delegated execution model](intents).
+
+Once a user submits an [intent](intents), the protocol groups it alongside other intents in a batch auction.
+As soon as a batch is "closed for orders", meaning that it stops considering new orders, the protocol runs a [competition](/cow-protocol/reference/core/auctions) where solvers submit solutions for the intents in the batch.
+
+Whichever solver offers the best [solution](/cow-protocol/reference/core/auctions/the-problem#solution) for the batch auction (defined as the solver that provides the most surplus to user orders) gets to execute the orders.
+
+Solvers are compensated in COW tokens for settling batches, incentivizing them to compete to find better prices and win the right to execute user intents.
+
+## How Solvers Work
+
+Solvers can move tokens on behalf of the user using the `ERC-20` approvals that the user granted to the [vault relayer](/cow-protocol/reference/contracts/core/vault-relayer) contract.
+The [settlement](/cow-protocol/reference/contracts/core/settlement) contract, meanwhile, verifies the signature of the user's intent and ensures that execution happens according to the limit price and quantity specified by the user.
+
+Anyone with some DeFi knowledge and ability to code an optimizations algorithm can create a solver.
diff --git a/docs/cow-protocol/concepts/order-types/_category_.json b/docs/cow-protocol/concepts/order-types/_category_.json
new file mode 100644
index 000000000..a485b4964
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/_category_.json
@@ -0,0 +1,9 @@
+{
+ "position": 3,
+ "label": "Order types",
+ "collapsible": true,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/docs/cow-protocol/concepts/order-types/cow-hooks.mdx b/docs/cow-protocol/concepts/order-types/cow-hooks.mdx
new file mode 100644
index 000000000..3c7c1dd00
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/cow-hooks.mdx
@@ -0,0 +1,28 @@
+---
+sidebar_position: 6
+---
+
+# CoW Hooks
+
+CoW Hooks allow users to pair any Ethereum action (or set of actions) with an order on CoW Protocol, leveraging the [solvers](../introduction/solvers) to execute the actions together in the sequence.
+
+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
+
+## Post-Hooks
+
+These are actions that execute after the swap, taking advantage of trade proceeds. Examples include:
+
+- Bridging funds to L2s
+- Staking funds
+
+## Getting started
+
+To get started with writing a CoW Hook, check out [our technical documentation](/cow-protocol/reference/core/intents/hooks). You can also [read more about CoW Hooks on our blog](https://blog.cow.finance/cow-hooks-you-are-in-control-480ccb40044a) or through our tutorials — [here](https://www.youtube.com/watch?v=FT36lWtC1Oc) and [here](https://www.youtube.com/watch?v=29OaasbqY_g).
diff --git a/docs/cow-protocol/concepts/order-types/limit-orders.md b/docs/cow-protocol/concepts/order-types/limit-orders.md
new file mode 100644
index 000000000..e9b580c1c
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/limit-orders.md
@@ -0,0 +1,23 @@
+---
+sidebar_position: 2
+---
+
+# Limit orders
+
+Limit orders are orders to buy or sell tokens at a specified price before a certain expiration date.
+
+If the market price of the asset matches the target price at any point before the expiration date, the order executes. Otherwise, it expires. Limit orders are ideal for trades that are price-sensitive but not time-sensitive.
+
+### How CoW Protocol Does Limit Orders
+
+Thanks to CoW Protocol's [intent-based trading model](../introduction/intents), limit orders come with a few big advantages over their counterparts on other DEX's:
+
+- **Gasless Order Management**: Traders can create, modify, and cancel limit orders without paying any gas fees.
+- **Simultaneous Orders**: Traders can use the same crypto balance to place multiple outstanding orders at once and CoW Protocol automatically fills them as long as the user wallet has funds in it.
+- **Order Surplus**: Across all CoW Protocol orders, traders receive the price determined at execution time. When it comes to limit orders, if the market price falls below the limit price, the user receives all the upside (unlike other exchanges, which would execute the limit order at the limit price, regardless of the asset's true market price). Additionally, any price improvements the solvers generate through finding better execution paths (i.e. finding a [Coincidence of Wants](../how-it-works/coincidence-of-wants)) belong to the trader.
+
+CoW Protocol's limit orders provide more flexibility and better prices than other DEX's thanks to the protocol's [intents-based execution](../introduction/intents) and [fair combinatorial batch auctions architecture](../introduction/fair-combinatorial-auction).
+
+## Getting started
+
+Wanting to place a limit order? Check out our [limit order tutorial](/cow-protocol/tutorials/cow-swap/limit). You can also [read about limit orders on our blog.](https://blog.cow.finance/the-cow-has-no-limits-342e7eae8794)
diff --git a/docs/cow-protocol/concepts/order-types/market-orders.md b/docs/cow-protocol/concepts/order-types/market-orders.md
new file mode 100644
index 000000000..4398d438a
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/market-orders.md
@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+---
+
+# Market orders
+
+Market orders are orders to buy or sell tokens as soon as possible at the current market rate.
+
+They are essentially limit orders where the limit price is close to or below the current market rate.
+
+When users place a market order on CoW Protocol, they agree to receive the best price that the solvers can find at that moment in time. Market orders are **fill or kill** (as opposed to partially fillable), meaning solvers have to find liquidity for the order in its entirety or wait to execute the order until enough liquidity is available.
+
+As with other exchanges, users also need to specify a "slippage tolerance" which allows the price to deviate by some percentage in order to ensure execution even in volatile market conditions.
+
+:::note
+
+Unlike other DEXs, your slippage tolerance cannot be extracted by MEV Bots (cf. [MEV Protection](../benefits/mev-protection)).
+If the solvers are able to find optimizations within the batch auction your order is settled with, you may also get a better price.
+
+:::
+
+## Getting started
+
+Wanting to make a market order? Check out our [market order tutorial](/cow-protocol/tutorials/cow-swap/swap).
diff --git a/docs/cow-protocol/concepts/order-types/milkman-orders.md b/docs/cow-protocol/concepts/order-types/milkman-orders.md
new file mode 100644
index 000000000..6e5eb634e
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/milkman-orders.md
@@ -0,0 +1,38 @@
+---
+sidebar_position: 5
+---
+
+# Milkman orders
+
+Milkman is an order placement mechanism developed by [Yearn Finance](https://yearn.fi/) in collaboration with CoW Protocol through the [CoW DAO Grants program](https://grants.cow.finance/).
+
+The contract allows users to utilize a price feed for their orders rather than specifying a fixed price.
+This means orders can execute at a fair market price even far into the future, making Milkman a popular choice for DAOs and governance-dependent trades.
+
+
+
+Let's say a DAO wants to sell 10,000 ETH from its treasury for USDC.
+The DAO's governance process dictates that the trade must first be put to a vote, but this means that the price of ETH will fluctuate significantly from the time the proposal is created to the time the trade actually executes.
+
+Rather than specifying a minimum fixed number of tokens they are willing to receive for their trade, users can utilize Milkman to specify a price feed (from an oracle source such as Chainlink, Tellor, or any custom on-chain data source) that will give the order a fair market price at the time of execution.
+
+Finally, once a user places a trade via Milkman, the order gets sent to the CoW Protocol order book where solvers pick it up and compete to find the best execution price for it.
+
+## Getting started
+
+Milkman follows a UniswapV2-style interface. To interact with Milkman, smart contracts need only to call the following function:
+
+```solidity
+function requestSwapExactTokensForTokens(
+ uint256 amountIn,
+ IERC20 fromToken,
+ IERC20 toToken,
+ address to,
+ address priceChecker,
+ bytes calldata priceCheckerData
+)
+```
+
+The priceChecker is the data feed provider, and priceCheckerData is an array of arbitrary bytes that the function passes to the price checker (e.g. the desired slippage tolerance).
+
+Price checkers have been deployed for Chainlink, Curve, SushiSwap, Uniswap V2, Uniswap V3, and combinations of these. Deployment addresses can be found [here](https://github.com/cowdao-grants/milkman/blob/main/DEPLOYMENTS.md), and the core Milkman code can be found [here](https://github.com/cowdao-grants/milkman/blob/main/contracts/Milkman.sol). Anyone can run a [Milkman bot](https://github.com/cowprotocol/milkman-bot), which simply functions as a hook that watches for new swap requests and surfaces them to CoW Protocol. Running a bot is fairly easy if you have a Kubernetes cluster; the instructions are in the repo.
diff --git a/docs/cow-protocol/concepts/order-types/pay-debt-flash-loans.md b/docs/cow-protocol/concepts/order-types/pay-debt-flash-loans.md
new file mode 100644
index 000000000..40da67eaf
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/pay-debt-flash-loans.md
@@ -0,0 +1,41 @@
+---
+sidebar_position: 6
+---
+
+# Repay debt with collateral using flash loans
+
+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.
+
+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.
+
+This approach eliminates the need for users to preemptively sell assets or find external liquidity, making it a highly flexible and efficient way to manage debt positions.
+
+### How to pay back a debt with collateral
+
+This can be achieved using a buy order where:
+
+- The **buy token** is the flash loaned asset that needs to be repaid.
+- The **buy amount** is the exact amount needed to repay the flash loan (it must be sufficient to complete the transaction; otherwise, the transaction will revert!).
+- The **sell token** is the asset used as collateral.
+- The **sell amount** is the full collateral amount.
+
+The receiver of the order must always be the settlement contract, to let the protocol handle repaying the appropriate amount for you.
+
+When it comes to repaying debt, the approach depends on the lender's contract terms. Some lenders allow a third party to initiate the transfer of collateral tokens from the lending pool to the trader's address, while others may not.
+
+#### 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.
+
+In order to create the `COWShed`, the user can use the [COWShed SDK](https://github.com/cowprotocol/cow-sdk/tree/main/src/cow-shed).
+
+The underlying user order is only used to repay the required flash loan. Since the repayment is handled via `COWShed`, the user can be either an EOA (Externally Owned Account) or a contract (e.g., a SAFE wallet).
+
+#### Lender does not allow a third-party to initiate the transfer of collateral tokens
+
+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.
\ No newline at end of file
diff --git a/docs/cow-protocol/concepts/order-types/programmatic-orders.md b/docs/cow-protocol/concepts/order-types/programmatic-orders.md
new file mode 100644
index 000000000..e7cc85e66
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/programmatic-orders.md
@@ -0,0 +1,29 @@
+---
+sidebar_position: 4
+---
+
+# Programmatic orders
+
+In addition to normal wallets, CoW Protocol also supports smart contract wallets that implement `ERC-1271`.
+This allows users to place orders through smart contracts with programmable parameters that execute based on certain conditions.
+
+We call these types of orders "programmatic orders" and we've developed a framework for creating programmatic orders, aptly named the "Programmatic Order Framework."
+
+## Creating & Using Programmatic Orders
+
+CoW Protocol's Programmatic Order Framework makes it easy to create conditional orders that execute when certain on-chain conditions are met (such as asset prices, wallet balances, time elapsed, and much more).
+
+The Framework takes care of all the boilerplate code necessary to create orders through CoW Protocol, so users only have to focus on coding the order logic itself.
+Programmatic order intents can also be created, updated, or deleted as a group with just a single transaction.
+
+Thanks to the Programmatic Order Framework, users can automate everything from complex trading strategies to advanced order types, portfolio management, DAO operations, and more with just a few lines of code.
+
+**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](./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
+
+To start developing with the Programmatic Order Framework, check out our [technical documentation](/cow-protocol/reference/contracts/periphery/composable-cow). You can also read more about programmatic orders [on our blog](https://blog.cow.finance/introducing-the-programmatic-order-framework-from-cow-protocol-088a14cb0375).
diff --git a/docs/cow-protocol/concepts/order-types/twap-orders.md b/docs/cow-protocol/concepts/order-types/twap-orders.md
new file mode 100644
index 000000000..b75ced36b
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/twap-orders.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 3
+---
+
+# TWAP orders
+
+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.
+
+## How TWAP Orders Work
+
+TWAP orders split up a large order into a series of normal limit orders that trade at fixed intervals. When setting up a TWAP order, users specify how many parts they'd like to split their trade into, as well as the total duration of the order (can be hours, days, weeks, or even months).
+
+TWAP orders on CoW Protocol require several inputs:
+
+- **Assets**: Just like you would with a regular swap, begin by specifying the assets you want to swap
+- **Price Protection**: One of the unique parts of TWAP orders on CoW Protocol is the "price protection" option which allows you to specify the minimum market price you'd be willing to take for your order. If the price of the asset you're buying falls below what you specify for any, that part of the TWAP order will not execute until the price recovers above your threshold
+- **Number of Parts**: Here you specify how many parts you'd like to split your large order into
+- **Total Duration**: Specify the total length of time that you want all parts of your order to execute over
+
+## Benefits
+
+TWAP orders provide a number of benefits, especially when it comes to large orders:
+
+- **Lower slippage**: Breaking up a large order into smaller pieces allows users to set a smaller slippage tolerance for each piece than if they had executed the large order as one
+- **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](../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.finance/all-you-need-to-know-about-cow-swaps-new-safe-fallback-handler-8ef0439925d1)
+
+## Getting started
+
+Wanting to place a TWAP order? Check out our [TWAP order tutorial](/cow-protocol/tutorials/cow-swap/twap). You can also [read about TWAP on our blog.](https://blog.cow.finance/cow-swap-launches-twap-orders-d5583135b472)
diff --git a/docs/cow-protocol/concepts/order-types/wrappers.md b/docs/cow-protocol/concepts/order-types/wrappers.md
new file mode 100644
index 000000000..78a921808
--- /dev/null
+++ b/docs/cow-protocol/concepts/order-types/wrappers.md
@@ -0,0 +1,60 @@
+---
+sidebar_position: 7
+---
+
+# Generalized Wrappers
+
+Generalized wrappers are a new framework to allow custom logic to execute before and/or after order settlement on CoW Protocol. They enable complex DeFi workflows—like flash loans, leveraged positions, and programmatic orders—all while preserving the security and assurances granted by CoW Protocol.
+
+## What are Wrappers?
+
+Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding the settlement contract. When a solver executes a settlement that includes a wrapper, they call the wrapper contract instead of the settlement contract directly. The wrapper calls the settlement contract on behalf of the solver.
+
+This mechanism extends CoW Protocol's functionality in a modular way, allowing new features and integrations to be added without modifying the core settlement contract or requiring any changes to solver implementations.
+
+## Use Cases
+
+As we begin to roll out wrappers more widely across our infrastructure, below is an overview of some of the ways Wrappers can be used.
+
+* **Leveraged Positions:** By wrapping the execution context of a CoW settlement, protocols implementing leveraged position opening capabilities can be supported.
+ - This case is utilized by [Euler](https://github.com/cowprotocol/euler-integration-contracts) to open, close, and collateral swap leverage positions with the [Ethereum Vault Connector](https://evc.wtf/) in the flagship implementation of the wrapper contracts.
+* **Flash Loan Integration:** Currently, CoW Protocol uses a dedicated `FlashLoanRouter` contract for flash loan functionality. However, this implementation comes with additional implementation effort from both the solvers and the CoW Protocol backend infrastructure. With generalized wrappers, flash loan integration becomes simpler and more flexible.
+* **Programmatic Orders:** Wrappers can place, gate, or cancel the execution of user orders when authorized, allowing for advanced order types like TWAP, OCO, Stop-Loss/Take-Profit, or DCA with support for every type of wallet.
+* **Protocol-Approved Hooks:** Unlike [CoW Hooks](./cow-hooks.mdx), which can revert even if the order is executed successfully, wrappers provide a way to enforce required pre- and post-settlement operations that the user may want. Since wrappers are protocol-approved through the allowlist authenticator, they can implement critical functionality that must execute:
+ - Cross chain transfers (pre- or post-transfer)
+ - Deposit in a vault or other wrapper contract (swap and stake)
+* **Something else:** Anyone can build and submit a new wrapper contract, and there are few restrictions on what a wrapper can do during execution.
+
+## Considerations
+
+While wrappers are powerful, there are important considerations to keep in mind:
+
+### Gas Overhead
+
+Wrappers add gas overhead to settlement transactions. This is an important factor in deciding whether to use a wrapper — see the [Integration Guide](../../integrate/wrappers.mdx#gas-estimation) for benchmarks and estimation guidance.
+
+### Requires Protocol Approval
+
+Wrappers cannot be deployed and used immediately—they must be approved by CoW DAO through the allowlist authenticator. This approval process ensures high-quality wrapper implementations and safety for solvers, but means there's a roadblock for developers looking to extend CoW Protocol. Developers should plan for this approval process when building wrapper-based integrations.
+
+### Wrapper and Settlement Call Pairing not Guaranteed On-chain
+
+Despite off-chain rules incentivizing solvers to execute wrappers as specified by an order, this is not enforced onchain and a solver may (due to technical error or malicious intent) execute an order without the corresponding wrapper. Conversely, the solver may execute the wrapper without the corresponding order in the settlement call. This means wrappers must be designed defensively:
+
+- If a wrapper is strictly required as part of an order, the order should fail to settle without it
+- If the wrapper call must be executed with the order settlement, it should revert if the settlement output is not delivered.
+- Wrappers should validate all input data and fail in cases where a user's funds could be at risk
+
+## Getting Started
+
+Wrappers are a powerful tool for advanced integrations on CoW Protocol. To start building with wrappers:
+
+- **For developers**: See the [Integration Guide](../../integrate/wrappers.mdx) for implementation details, code examples, and security guidelines
+- **For technical specs**: Consult the [Technical Reference](../../reference/contracts/periphery/wrapper.mdx) for detailed contract documentation and API specifications
+
+To learn more about wrappers and see example implementations:
+
+- **For Wrapper Contract Builders:** [Euler Integration Contracts Repository](https://github.com/cowprotocol/euler-integration-contracts) - Contains the `CowWrapper` abstract contract and example implementations
+- **For Solvers:** [Services Repository PR #3700](https://github.com/cowprotocol/services/pull/3700) - Example backend integration implementation. Good reference for solvers looking to support wrappers.
+
+Wrappers represent a significant evolution in CoW Protocol's capabilities, enabling complex DeFi workflows while maintaining security and simplicity for solvers. As more wrappers are developed and approved, they will continue to expand what's possible with intent-based trading.
diff --git a/docs/cow-protocol/integrate/README.mdx b/docs/cow-protocol/integrate/README.mdx
new file mode 100644
index 000000000..58342a334
--- /dev/null
+++ b/docs/cow-protocol/integrate/README.mdx
@@ -0,0 +1,38 @@
+# Integrate CoW Protocol
+
+CoW Protocol offers multiple integration approaches to suit different development needs and use cases. Whether you're building a DeFi application, creating a custom trading interface, or integrating CoW's functionality into your existing platform, there's an integration method that fits your requirements.
+
+## Integration Approaches
+
+| Approach | Best For | Development Effort | Customization Level |
+|----------|----------|-------------------|---------------------|
+| **Widget** | Quick integration, minimal setup | Low | Basic styling and configuration |
+| **SDK** | Full control, custom UI | Medium | Complete control over UI/UX |
+| **API** | Backend integration, custom logic | High | Maximum flexibility |
+
+## Choose Your Integration Method
+
+### 🎨 Widget Integration
+Perfect for getting started quickly with minimal development effort. The CoW Widget provides a pre-built trading interface that can be embedded into any web application.
+
+- **Setup time**: Minutes
+- **Customization**: Theme, token lists, styling
+- **Use case**: Quick integration, MVP development
+
+### 🛠️ SDK Integration
+Ideal for developers who want to build custom trading interfaces while leveraging CoW Protocol's powerful features.
+
+- **Setup time**: Hours to days
+- **Customization**: Complete UI control
+- **Use case**: Custom applications, advanced features
+
+### 🔧 API Integration
+Best for backend services, advanced integrations, and when you need maximum control over the trading logic.
+
+- **Setup time**: Days to weeks
+- **Customization**: Full control over all aspects
+- **Use case**: Backend services, complex integrations
+
+---
+
+Choose the integration method that best fits your project's requirements and development timeline. Each approach is designed to provide progressively more control and customization options.
\ No newline at end of file
diff --git a/docs/cow-protocol/integrate/_category_.json b/docs/cow-protocol/integrate/_category_.json
new file mode 100644
index 000000000..f4439d2a9
--- /dev/null
+++ b/docs/cow-protocol/integrate/_category_.json
@@ -0,0 +1,9 @@
+{
+ "position": 4,
+ "label": "Integrate",
+ "collapsible": true,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index"
+ }
+}
\ No newline at end of file
diff --git a/docs/cow-protocol/integrate/api.mdx b/docs/cow-protocol/integrate/api.mdx
new file mode 100644
index 000000000..16d11ecb7
--- /dev/null
+++ b/docs/cow-protocol/integrate/api.mdx
@@ -0,0 +1,166 @@
+# API Integration
+
+The CoW Protocol API provides direct access to the protocol's functionality through RESTful endpoints. This approach offers maximum flexibility and control for backend integrations and custom implementations.
+
+## Overview
+
+The API integration allows you to interact with CoW Protocol at the lowest level, giving you complete control over order management, quote fetching, and trade execution. This is ideal for advanced integrations, backend services, and custom trading logic.
+
+## Key APIs
+
+### Order Book API
+The primary API for creating and managing orders on CoW Protocol.
+
+- **Base URL**: `https://api.cow.finance/`
+- **Purpose**: Quote generation, order submission, order management
+- **Authentication**: No API key required for basic operations
+
+### Key Endpoints
+
+- `POST /api/v1/quote` - Get trading quotes
+- `POST /api/v1/orders` - Submit signed orders
+- `GET /api/v1/orders/{uid}` - Get order details
+- `DELETE /api/v1/orders/{uid}` - Cancel orders
+- `GET /api/v1/trades` - Get trade history
+
+## Quick Start Example
+
+### 1. Get a Quote
+
+```bash
+curl -X POST "https://api.cow.finance/mainnet/api/v1/quote" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "sellToken": "0xA0b86a33E6411Ec5d0b9dd2E7dC15A9CAA6C1F8e",
+ "buyToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+ "sellAmountBeforeFee": "1000000",
+ "kind": "sell",
+ "from": "0xYourWalletAddress"
+ }'
+```
+
+### 2. Sign and Submit Order
+
+```javascript
+// After getting a quote, sign the order
+const order = {
+ ...quoteResponse,
+ signature: await signOrder(quoteResponse, signer),
+ signingScheme: "eip712"
+}
+
+// Submit the signed order
+const response = await fetch('https://api.cow.finance/mainnet/api/v1/orders', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify(order)
+})
+
+const orderId = await response.text()
+```
+
+### 3. Monitor Order Status
+
+```javascript
+// Check order status
+const orderResponse = await fetch(
+ `https://api.cow.finance/mainnet/api/v1/orders/${orderId}`
+)
+const orderDetails = await orderResponse.json()
+
+console.log('Order status:', orderDetails.status)
+```
+
+## Network Endpoints
+
+CoW Protocol APIs are available on multiple networks:
+
+- **Mainnet**: `https://api.cow.finance/mainnet/api/v1/`
+- **Gnosis Chain**: `https://api.cow.finance/xdai/api/v1/`
+- **Arbitrum**: `https://api.cow.finance/arbitrum_one/api/v1/`
+- **Base**: `https://api.cow.finance/base/api/v1/`
+- **Sepolia (Testnet)**: `https://api.cow.finance/sepolia/api/v1/`
+
+## Order Signing
+
+Orders must be cryptographically signed before submission. The signing process involves:
+
+1. **EIP-712 Domain**: Chain-specific domain separator
+2. **Order Struct**: Structured order data
+3. **Signature**: ECDSA signature or pre-signed order
+
+```javascript
+import { ethers } from 'ethers'
+
+// Example order signing with ethers.js
+const domain = {
+ name: 'Gnosis Protocol',
+ version: 'v2',
+ chainId: 1,
+ verifyingContract: '0x9008D19f58AAbD9eD0D60971565AA8510560ab41'
+}
+
+const types = {
+ Order: [
+ { name: 'sellToken', type: 'address' },
+ { name: 'buyToken', type: 'address' },
+ { name: 'receiver', type: 'address' },
+ // ... other order fields
+ ]
+}
+
+const signature = await signer._signTypedData(domain, types, orderData)
+```
+
+## Error Handling
+
+The API returns standard HTTP status codes:
+
+- **200**: Success
+- **400**: Bad Request (invalid parameters)
+- **404**: Order not found
+- **429**: Rate limited
+- **500**: Internal server error
+
+```javascript
+try {
+ const response = await fetch(apiUrl, requestOptions)
+
+ if (!response.ok) {
+ const error = await response.json()
+ throw new Error(`API Error: ${error.description}`)
+ }
+
+ return await response.json()
+} catch (error) {
+ console.error('Order submission failed:', error)
+}
+```
+
+## When to Use the API
+
+- **Backend integration**: Server-side order management
+- **Custom trading logic**: Advanced order types and strategies
+- **High-frequency trading**: Programmatic order placement
+- **Multi-chain applications**: Cross-chain arbitrage and liquidity
+- **Analytics platforms**: Order and trade data analysis
+
+## Rate Limits
+
+- **Quote requests**: 10 requests/second
+- **Order submission**: 5 requests/second
+- **General endpoints**: 100 requests/minute
+
+## Next Steps
+
+For complete API documentation including all endpoints, parameters, and response schemas, see:
+
+- **[Order Book API Reference](/cow-protocol/reference/apis/orderbook)** - Complete endpoint documentation
+- **[API Documentation](https://api.cow.finance/docs/)** - Interactive API explorer
+
+## Resources
+
+- **[Order Book API Reference](/cow-protocol/reference/apis/orderbook)** - Detailed API documentation
+- **[API Explorer](https://api.cow.finance/docs/)** - Interactive documentation
+- **[GitHub Examples](https://github.com/cowprotocol/cow-sdk/tree/main/examples)** - Code examples
+- **[Order Signing Guide](../reference/core/signing_schemes.mdx)** - Cryptographic signing details
\ No newline at end of file
diff --git a/docs/cow-protocol/integrate/sdk.mdx b/docs/cow-protocol/integrate/sdk.mdx
new file mode 100644
index 000000000..f4c4d5c8b
--- /dev/null
+++ b/docs/cow-protocol/integrate/sdk.mdx
@@ -0,0 +1,85 @@
+# SDK Integration
+
+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.
+
+## 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
+
+## Quick Start Example
+
+```typescript
+import { SupportedChainId, OrderKind, TradeParameters, TradingSdk } from '@cowprotocol/cow-sdk'
+import { ViemAdapter } from '@cowprotocol/sdk-viem-adapter'
+import { createPublicClient, http, privateKeyToAccount } from 'viem'
+import { mainnet } from 'viem/chains'
+
+// Setup adapter
+const adapter = new ViemAdapter({
+ provider: createPublicClient({
+ chain: mainnet,
+ transport: http('YOUR_RPC_URL')
+ }),
+ signer: privateKeyToAccount('YOUR_PRIVATE_KEY' as `0x${string}`)
+})
+
+// Initialize SDK
+const sdk = new TradingSdk({
+ chainId: SupportedChainId.MAINNET,
+ appCode: 'YOUR_APP_CODE',
+}, {}, adapter)
+
+// Define trade parameters
+const parameters: TradeParameters = {
+ kind: OrderKind.SELL,
+ sellToken: '0xA0b86a33E6411Ec5d0b9dd2E7dC15A9CAA6C1F8e', // USDC
+ sellTokenDecimals: 6,
+ buyToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
+ buyTokenDecimals: 18,
+ amount: '1000000', // 1 USDC
+}
+
+// Get quote and execute trade
+const { quoteResults, postSwapOrderFromQuote } = await sdk.getQuote(parameters)
+const orderId = await postSwapOrderFromQuote()
+
+console.log('Order created:', orderId)
+```
+
+## Installation
+
+```bash
+# Install the SDK
+npm install @cowprotocol/cow-sdk
+
+# Install an adapter (choose one)
+npm install @cowprotocol/sdk-viem-adapter viem
+npm install @cowprotocol/sdk-ethers-v6-adapter ethers
+npm install @cowprotocol/sdk-ethers-v5-adapter ethers@^5.7.0
+```
+
+## When to Use the SDK
+
+- **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
+
+For comprehensive documentation, examples, and advanced usage patterns, visit the [CoW SDK Documentation](/cow-protocol/reference/sdks/cow-sdk).
+
+## Resources
+
+- **[Complete SDK Documentation](/cow-protocol/reference/sdks/cow-sdk)** - Detailed guides and API reference
+- **[GitHub Repository](https://github.com/cowprotocol/cow-sdk)** - Source code and examples
+- **[API Reference](https://api.cow.finance/docs/)** - REST API documentation
+- **[Examples](https://github.com/cowprotocol/cow-sdk/tree/main/examples)** - React and Node.js examples
\ No newline at end of file
diff --git a/docs/cow-protocol/integrate/widget.mdx b/docs/cow-protocol/integrate/widget.mdx
new file mode 100644
index 000000000..44105a97b
--- /dev/null
+++ b/docs/cow-protocol/integrate/widget.mdx
@@ -0,0 +1,106 @@
+# Widget Integration
+
+The CoW Widget is the fastest way to integrate CoW Protocol's trading functionality into your application. It provides a complete, pre-built trading interface that can be embedded with just a few lines of code.
+
+## Overview
+
+The CoW Widget is a ready-to-use React component that provides the full CoW Swap trading experience. It's perfect for projects that want to add trading functionality quickly without building a custom interface from scratch.
+
+## Key Features
+
+- **Zero configuration**: Works out-of-the-box with minimal setup
+- **Fully responsive**: Adapts to different screen sizes
+- **Customizable themes**: Light, dark, and custom color schemes
+- **Partner fees**: Earn revenue on trades through your integration
+- **Multi-network support**: All CoW Protocol-enabled networks
+- **Wallet integration**: Connect to existing wallet providers or standalone mode
+
+## Quick Start Example
+
+```typescript
+import { createCowSwapWidget, CowSwapWidgetParams } from '@cowprotocol/widget-lib'
+
+// HTML element where the widget will be rendered
+const widgetContainer = document.getElementById('cowswap-widget')
+
+const params: CowSwapWidgetParams = {
+ appCode: 'YOUR-APP-NAME', // Required: identifies your app
+ width: 600,
+ height: 640,
+ sell: { asset: 'USDC' },
+ buy: { asset: 'WETH', amount: '0.1' },
+ theme: 'light', // 'light' | 'dark' | custom theme object
+ partnerFee: {
+ bps: 50, // 0.5% fee
+ recipient: '0xYourFeeRecipientAddress',
+ },
+}
+
+createCowSwapWidget(widgetContainer, { params })
+```
+
+## Installation
+
+```bash
+# Install the widget library
+npm install @cowprotocol/widget-lib
+```
+
+## Configuration Options
+
+The widget supports extensive customization:
+
+- **Trading pairs**: Pre-select sell/buy tokens and amounts
+- **Partner fees**: Earn revenue on trades (up to 1%)
+- **Custom themes**: Match your app's branding
+- **Token lists**: Use custom token lists
+- **Wallet integration**: Connect to your app's wallet or standalone mode
+- **Event handling**: Listen to trading events and notifications
+
+## Example with Custom Theme
+
+```typescript
+import { createCowSwapWidget, CowSwapWidgetPalette } from '@cowprotocol/widget-lib'
+
+const customTheme: CowSwapWidgetPalette = {
+ baseTheme: 'light',
+ primary: '#00ff85',
+ background: '#f7f7f7',
+ paper: '#1a4435',
+ text: '#ffffff',
+}
+
+const params = {
+ appCode: 'YOUR-APP-NAME',
+ theme: customTheme,
+ // ... other params
+}
+
+createCowSwapWidget(widgetContainer, { params })
+```
+
+## When to Use the Widget
+
+- **Rapid integration**: Get trading functionality live in minutes
+- **Standard UI/UX**: When CoW Swap's interface meets your needs
+- **Minimal development**: Perfect for MVPs and quick prototypes
+- **Partner fees**: Easy way to monetize trading volume
+
+## Widget Configurator
+
+Use the interactive configurator at [widget.cow.finance](https://widget.cow.finance) to:
+- Preview different configurations
+- Generate code snippets
+- Test custom themes
+- Configure partner fees
+
+## Next Steps
+
+For detailed configuration options, event handling, and advanced customization, see the [Widget Tutorial](../tutorials/widget/widget.md).
+
+## Resources
+
+- **[Widget Configurator](https://widget.cow.finance)** - Interactive configuration tool
+- **[Complete Widget Guide](../tutorials/widget/widget.md)** - Detailed documentation
+- **[GitHub Repository](https://github.com/cowprotocol/cowswap)** - Source code
+- **[Partner Fee Program](/governance/fees/partner-fee)** - Revenue sharing details
\ No newline at end of file
diff --git a/docs/cow-protocol/integrate/wrappers.mdx b/docs/cow-protocol/integrate/wrappers.mdx
new file mode 100644
index 000000000..c9ef66d12
--- /dev/null
+++ b/docs/cow-protocol/integrate/wrappers.mdx
@@ -0,0 +1,326 @@
+# Wrapper Integration
+
+Generalized wrappers enable custom logic to execute surrounding CoW Protocol settlements. This guide covers both using existing wrappers in your orders and building new wrapper contracts.
+
+**Choose your path:**
+- **[Building New Wrappers](#for-wrapper-developers)** - Develop custom wrapper contracts for advanced DeFi workflows
+- **[Using Existing Wrappers](#for-order-creators-and-frontend-developers)** - Add wrappers to your orders and integrate into your application
+- **[Executing Wrappers as a Solver](#for-solvers)** - Everything solvers need to know to execute wrapper orders
+
+---
+
+## For Wrapper Developers
+
+This section covers building new wrapper contracts from scratch.
+
+### Overview
+
+To build a wrapper, you will:
+
+1. Inherit from the `CowWrapper` abstract contract
+2. Implement `_wrap()` with your pre/post-settlement logic
+3. Implement `validateWrapperData()` for input validation
+4. Test thoroughly on testnets
+5. Review the [Implementation Requirements](../reference/contracts/periphery/wrapper.mdx#implementation-requirements-for-integrators) to ensure your wrapper meets the acceptance requirements
+6. Submit for allowlist approval by the CoW Protocol team
+
+Building a wrapper is a significant undertaking.
+An insecure wrapper would put user and protocol funds at risk.
+Make sure you understand CoW Protocol well before starting.
+A contract audit by a reputable firm is mandatory before a wrapper is considered for approval.
+Read more on the details of creating a wrapper from [the wrapper contract information page](../reference/contracts/periphery/wrapper.mdx).
+
+---
+
+## For Order Creators and Frontend Developers
+
+This section shows you how to use existing wrappers in your orders and integrate wrapper support into your application.
+
+### Adding Wrappers to Orders
+
+To use a wrapper in your order, add it to the `appData` when creating the order:
+
+### AppData Structure
+
+```typescript
+interface WrapperCall {
+ target: string; // Wrapper contract address (must be allowlisted)
+ data?: string; // Optional hex-encoded wrapper-specific data
+ isOmittable?: boolean; // Whether solver can skip this wrapper (default: false)
+}
+```
+
+**Fields:**
+- **`target`** (required): Address of the allowlisted wrapper contract
+- **`data`** (optional): Hex-encoded data specific to the wrapper. Can be empty or omitted if the wrapper doesn't need custom data.
+- **`isOmittable`** (optional): Defaults to `false`
+ - `false` = Solver MUST execute the wrapper with exact data or be slashed
+ - `true` = Solver MAY skip the wrapper if they find a better solution
+
+### Example: Using the CoW SDK
+
+```typescript
+import { OrderBookApi, OrderQuoteRequest, OrderCreation } from '@cowprotocol/cow-sdk'
+
+// Create order with wrapper
+const orderCreation: OrderCreation = {
+ // ... standard order fields (sellToken, buyToken, amounts, etc.)
+
+ appData: {
+ // ... other appData fields
+ wrappers: [
+ {
+ target: "0x1234...", // Flash loan wrapper address
+ data: "0xabcd...", // Encoded flash loan params
+ isOmittable: false // Must execute
+ }
+ ]
+ }
+}
+
+// Submit order
+const orderId = await orderBookApi.sendOrder(orderCreation)
+```
+
+### Example: Multiple Wrappers (Nested)
+
+You can chain multiple wrappers in a single order:
+
+```typescript
+appData: {
+ wrappers: [
+ {
+ target: "0x1111...", // Flash loan wrapper
+ data: "0xaaaa...",
+ isOmittable: false
+ },
+ {
+ target: "0x2222...", // Leverage wrapper
+ data: "0xbbbb...",
+ isOmittable: false
+ }
+ ]
+}
+```
+
+The wrappers execute in sequence: Wrapper1 → Wrapper2 → Settlement → Wrapper2 (post) → Wrapper1 (post). Note that wrappers from other users' orders may be interspersed, though this should generally not affect the execution of the order.
+
+### Validating Wrapper Configuration
+
+Before submitting an order, you can confirm the wrapper encoding is valid using [`CowWrapperHelpers`](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers).
+
+```typescript
+// On-chain validation (via Ethers/Viem)
+const helper = new ethers.Contract(HELPER_ADDRESS, HELPER_ABI, provider)
+
+const isValid = await helper.verifyAndBuildWrapperData([
+ {
+ target: '0xSomeAddress',
+ data: '0xSomeData'
+ },
+ {
+ target: '0xSomeAddress2',
+ data: '0x'
+ }
+])
+// Returns encoded chainedWrapperData if valid, reverts if invalid
+```
+
+This checks:
+- All wrappers are allowlisted
+- Each wrapper can parse its data successfully
+
+See the [periphery contract reference](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers) for deployment addresses.
+
+---
+
+## For Solvers
+
+This section explains how to execute settlements that include wrapper contracts as part of your solver implementation.
+
+### Detecting Wrapper Orders
+
+Wrappers are specified in the order's [`appData`](../reference/core/auctions/schema.md) under the `wrappers` field:
+
+```json
+{
+ "wrappers": [
+ {
+ "target": "0x1234...",
+ "data": "0xabcdef...",
+ "isOmittable": false
+ }
+ ]
+}
+```
+
+**Fields:**
+- **`target`**: Address of the wrapper contract
+- **`data`**: Wrapper-specific data
+- **`isOmittable`**: Whether the `target` and `data` must be executed unmodified as part of the order execution
+
+`target` may be any address and `data` is arbitrary bytes that will be passed to the target. There is generally no need for decoding the wrapper data since the execution process uses the same opaque format on each wrapper.
+
+### Solver Requirements
+
+#### 1. Execute Non-Omittable Wrappers
+
+Orders with `"isOmittable": false` **MUST** be executed with the specified wrapper. You may be slashed for not doing so.
+
+If `"isOmittable": true`, you MAY skip the wrapper if you find a better solution without it.
+
+#### 2. Verify Wrapper Authentication and Simulate
+
+All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is advised to verify this is the case before attempting to process a wrapper order.
+
+Additionally, wrappers define additional operations that may revert, so it is strongly recommended to *simulate the settlement transaction* while including the wrapper call to verify its viability. The call trace can also be inspected for any unusual behavior.
+
+:::warning
+The wrapper will be _directly_ called from the solver address and will mediate the settlement.
+Since the data is user-supplied, it may be malicious.
+:::
+
+#### 3. Include Wrappers in the Solution
+
+Whether using the CoW Protocol-provided driver or your own, ensure wrapper information flows from the auction to your final settlement transaction. This data should be passed unmodified from the orders in the auction to the final `Solution` submitted to the API.
+
+### Encoding Wrapper Settlements
+
+:::info
+If you're using the driver provided by CoW Protocol, you can skip this section - the driver handles encoding automatically.
+:::
+
+#### Manual Encoding
+
+To execute a settlement with wrappers:
+
+##### 1. Change Transaction Target
+
+Your transaction should call `wrappedSettle()` on the **first** wrapper (not the settlement contract):
+
+```typescript
+// Without wrapper
+tx = {
+ to: SETTLEMENT_CONTRACT,
+ data: encodeSettle(...)
+}
+
+// With wrapper
+tx = {
+ to: wrappers[0].target, // First wrapper address
+ data: encodeWrappedSettle(...) // See below
+}
+```
+
+##### 2. Construct settleData Parameter
+
+The `settleData` parameter is the **exact** calldata you would send to `GPv2Settlement.settle()`, including the 4-byte function selector:
+
+```typescript
+const settleData = settlementContract.interface.encodeFunctionData("settle", [
+ tokens,
+ clearingPrices,
+ trades,
+ interactions
+]);
+// This is your settleData - unchanged from normal settlement
+```
+
+##### 3. Encode the `chainedWrapperData` Parameter
+
+Build `chainedWrapperData` according to the [Calldata Encoding Specification](../reference/contracts/periphery/wrapper.mdx#calldata-encoding-specification).
+
+##### 4. Call wrappedSettle
+
+```typescript
+const tx = {
+ // The `chainedWrapperData` does not include the first wrapper to call,
+ // so it is supplied here as the _target_ of the settlement call.
+ to: wrappers[0].target,
+ data: wrapperContract.interface.encodeFunctionData("wrappedSettle", [
+ settleData, // From step 2
+ chainedWrapperData // From step 3
+ ])
+}
+```
+
+#### Using CowWrapperHelpers
+
+`CowWrapperHelpers` is a read-only periphery contract that can be called to validate many important points prior to execution. See the [periphery contract documentation](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers).
+
+### Accumulating Wrappers in Solutions
+
+#### Using CoW-Provided Driver
+
+If you're using the CoW Protocol-provided driver, wrappers are handled automatically. Just ensure your solver process includes wrapper information in the solution output.
+
+#### Custom Implementation
+
+If implementing your own solver:
+
+1. **Collect wrappers from orders**: As you process orders in an auction, collect all `wrappers` arrays from order appData
+2. **Aggregate for batch**: Combine wrappers needed for all orders in the settlement batch
+3. **Include in solution**: Add aggregated wrappers to your solution structure
+4. **Encode transaction**: Use the encoding algorithm above to construct the final transaction
+
+**Example (conceptual):**
+
+```typescript
+// Process auction
+const solution = {
+ orders: [...],
+ wrappers: [] // Collect here
+};
+
+for (const order of auction.orders) {
+ if (order.appData.wrappers) {
+ // Add wrappers needed for this order
+ solution.wrappers.push(...order.appData.wrappers);
+ }
+}
+
+// Encode final transaction using the manual encoding steps described above:
+// 1. Set tx target to solution.wrappers[0].target
+// 2. Build settleData from your normal GPv2Settlement.settle() calldata
+// 3. Build chainedWrapperData per the Calldata Encoding Specification in the reference docs
+// 4. Call wrappedSettle(settleData, chainedWrapperData) on the first wrapper
+const tx = {
+ to: solution.wrappers[0].target,
+ data: wrapperContract.interface.encodeFunctionData("wrappedSettle", [
+ settleData,
+ chainedWrapperData
+ ])
+};
+```
+
+### Testing and Validation
+
+#### Gas Estimation
+
+Account for wrapper gas overhead in your bids — see [Gas Overhead](../reference/contracts/periphery/wrapper.mdx#gas-overhead) for benchmarks and scaling factors. The easiest way to estimate overhead for a specific wrapper is to simulate the wrapper transaction against an empty settlement.
+
+### Common Issues
+
+#### Issue: "Not authorized" error
+
+**Cause**: Wrapper is not allowlisted in `GPv2AllowlistAuthenticator`
+
+**Solution**: Verify wrapper is DAO-approved before including in settlement
+
+#### Issue: Settlement reverts in wrapper
+
+**Cause**: Incorrect encoding or wrapper-specific validation failure
+
+**Solution**:
+- Verify `settleData` is identical to what you'd send to `GPv2Settlement.settle()`
+- Check `chainedWrapperData` encoding follows specification exactly
+- Use `CowWrapperHelpers` for validation
+
+### Solver Resources
+
+#### Documentation
+- **[Wrapper Concepts](../concepts/order-types/wrappers.md)** - High-level overview
+- **[Contracts Reference](../reference/contracts/periphery/wrapper.mdx)** - Contract specifications
+- **[Services PR #3700](https://github.com/cowprotocol/services/pull/3700)** - Reference encoding implementation in production
+
+---
diff --git a/docs/cow-protocol/reference/_category_.json b/docs/cow-protocol/reference/_category_.json
new file mode 100644
index 000000000..490fdbe74
--- /dev/null
+++ b/docs/cow-protocol/reference/_category_.json
@@ -0,0 +1,9 @@
+{
+ "position": 3,
+ "label": "Technical reference",
+ "collapsible": true,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/docs/cow-protocol/reference/apis/_category_.json b/docs/cow-protocol/reference/apis/_category_.json
new file mode 100644
index 000000000..368784de4
--- /dev/null
+++ b/docs/cow-protocol/reference/apis/_category_.json
@@ -0,0 +1,9 @@
+{
+ "label": "APIs",
+ "position": 6,
+ "collapsible": true,
+ "collapsed": true,
+ "link": {
+ "type": "generated-index"
+ }
+}
diff --git a/docs/cow-protocol/reference/apis/driver.mdx b/docs/cow-protocol/reference/apis/driver.mdx
new file mode 100644
index 000000000..c8e2acdac
--- /dev/null
+++ b/docs/cow-protocol/reference/apis/driver.mdx
@@ -0,0 +1,9 @@
+---
+sidebar_position: 2
+---
+
+import {SwaggerDoc} from '../../../../src/components/swagger-doc/SwaggerDoc';
+
+# Driver API
+
+Maintenance
-- The cow.fi domain is currently under maintenance. We'll be back shortly. -
-{ id, tokens, orders, liquidity?, effectiveGasPrice, deadline } + activate Solver Engine + Solver Engine ->>Solver Engine: compute matching + Solver Engine-->>Driver: { solutions: [ { id, prices, trades, interactions, score } ] } + deactivate Solver Engine +``` + +The information received by the driver should be sufficient to produce valid responses, meaning that the solver engine could be implemented as a pure function. +However, in practice, solver engines often benefit from additional state management, such as indexing liquidity sources and simulating execution routes for more accurate cost estimates, to remain competitive. + +## Methodology + +The inner workings are engine specific and highly depend on the underlying matching algorithm. +While third-party aggregator algorithms are proprietary (the engine simply calls their API for as many orders as possible), the baseline solver engine can give an idea of how to generate basic solutions for simple problem instances. + +### 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 + +The solver can receive an optional object with each order that provides hints for using flash loans. These hints act as guidance, but the solver is free to return a different list of flash loan objects in their solution. The solver has three options: + +- Provide no hint: In this case, the driver will assume the flash loan hint attached to the order gets settled in the solution. +- Use the provided hint: The solver can directly copy the flash loan hint included with the order. +- Define a custom hint: The solver can specify a different flash loan hint, allowing for better optimization of flash loan usage. + +A key requirement for flash loans is that all steps must take place within the same caller context. By maintaining this context, flash loans remain risk-free, as the transaction can be reverted if the tokens cannot be returned at the end. However, CoW Protocol cannot hold on to this context directly. To ensure that all steps execute within the same caller context, the GPv2 Settlement contract's [settle](../../../reference/contracts/core/settlement.md#settle) function is called from within the [IFlashLoanRouter](../../../reference/contracts/periphery/flash-loans.md#iflashloanrouter-contract) contract callback. Rather than directly calling the GPv2 Settlement contract, the solver first interacts with the `IFlashLoanRouter` contract. + +The solver must consider the gas cost implications of using a flash loan, as the associated overhead is non-negligible. + +The settlement contract will receive the swap order funds, but it is the solver’s responsibility to ensure the flash loan is fully repaid within the same transaction. Additionally, the solver needs to account for when the funds will become available, factoring in any user-defined pre-hooks. + +The reference driver facilitates this process by pulling funds from the `IFlashLoanRouter` contract and transferring them to the user, so they can be used for the order swap. Since the settlement contract is the recipient of the swap, the driver must then move the funds back to the `IFlashLoanRouter` contract, ensuring that the flash loan lender can retrieve the required repayment from it. If a solver chooses to implement a custom driver, they are responsible for managing this behavior as they deem appropriate. + +We support the following flash-loan lenders: + +- Any lender that is compatible with [ERC-3156](https://eips.ethereum.org/EIPS/eip-3156) interface (for example [Maker](https://docs.makerdao.com/smart-contract-modules/flash-mint-module)). +- [Aave](https://aave.com/docs/developers/flash-loans#overview). + +```mermaid +sequenceDiagram + activate Solver + Solver->>+IFlashLoanRouter: flashloanAndSettle + IFlashLoanRouter->>+FlashloanProvider: flash loan + FlashloanProvider-->>IFlashLoanRouter: loan token + FlashloanProvider->>+IFlashLoanRouter: flash loan + participant Settlement + actor User + IFlashLoanRouter-->>User: loan token + IFlashLoanRouter->>+Settlement: settle + Settlement->>+User: preInteraction + User->>Personal: repay debt + Personal-->>User: collateral token + User-->>-Settlement: collateral token + Settlement->>+User: order execution + User-->>-Settlement: return loaned token + Settlement-->>-IFlashLoanRouter: return loaned token + deactivate IFlashLoanRouter + IFlashLoanRouter-->>FlashloanProvider: return loaned token + deactivate FlashloanProvider + deactivate IFlashLoanRouter + deactivate Solver +``` + +## Dependencies + +Solver engines need to be "registered" inside the driver configuration file to receive requests. +Check `driver::infra::config::file::SolverConfig` for the available configuration parameters. diff --git a/docs/cow-protocol/tutorials/building.mdx b/docs/cow-protocol/tutorials/building.mdx new file mode 100644 index 000000000..9cd68c6a1 --- /dev/null +++ b/docs/cow-protocol/tutorials/building.mdx @@ -0,0 +1,35 @@ +--- +sidebar_position: 6 +--- + +# Building on CoW Protocol + +So, you want to build on top of CoW Protocol? Great! We are excited to see what you will build. + +The protocol is designed to be flexible and therefore built on top of by the community. Here you will find resources to get started. + +## Code examples + +You won't find any code examples here in the documentation. Wait, what? Yes, that's right. +We believe that code examples are a bad way to _learn_. +They are often outdated, incomplete and don't teach you how to think about the problem at hand. + +To better serve builders, we have created a [**comprehensive live-coding environment**](https://learn.cow.finance), with tutorials that teach you how to build on top of CoW Protocol. +You can find the live-coding environment at [learn.cow.finance](https://learn.cow.finance). +Powered by web containers, you can run your code from the comfort of your browser, without having to install anything. +It comes pre-configured with the CoW Protocol SDK and get's straight to the point, showing you how to: + +- All basic order steps (quoting, signing, submitting, cancelling, application data) +- Advanced order features (Eth-Flow, Pre-signed orders, `ERC-1271` signing) + +## Detailed documentation + +You've found our new documentation already! Did you know that the documentation also includes an extensive [technical reference](/category/technical-reference) covering: + +- JavaScript SDKs (`cow-sdk` / `app-data`) +- Rest APIs (`orderbook`, `solver`, `driver`) +- Smart contracts (all core and periphery contracts) + +## Getting support + +Confused? Have a question? We are here to help! Join our [Discord](https://discord.com/invite/cowprotocol) and ask your development questions in the `#tech-talk` channel! \ No newline at end of file diff --git a/docs/cow-protocol/tutorials/cow-amm-deployer.mdx b/docs/cow-protocol/tutorials/cow-amm-deployer.mdx new file mode 100644 index 000000000..2683c40b8 --- /dev/null +++ b/docs/cow-protocol/tutorials/cow-amm-deployer.mdx @@ -0,0 +1,83 @@ +--- +sidebar_position: 6 +--- + +# CoW AMM Deployer +The [CoW AMM Deployer](https://app.safe.global/share/safe-app?appUrl=https%3A%2F%2Fdeploy-cow-amm.bleu.fi&chain=et) is a user-friendly Safe App that simplifies the process of deploying and managing [CoW AMMs](https://cow.finance/cow-amm) (Automated Market Makers) from Safe wallets. It enables users without programming skills to take advantage of the benefits of CoW AMM. + +The app was developed by [bleu](https://github.com/bleu-fi) with sponsorship from the [CoW Grants DAO](https://grants.cow.finance/). + +This app is only accessible from a Safe wallet. + +:::caution + +The Safe wallet you use to create a CoW AMM should **ONLY** be used for the purpose of deploying a CoW AMM. + +::: + +:::tip + +Provide the tokens for the CoW AMM to your Safe wallet **before** creating the CoW AMM. Beware **any** imbalance between tokens will _automatically_ be traded. + +::: + +## Prerequisites +Before using the CoW AMM Deployer, ensure that you have the following: +1. A Safe wallet: If you don't have one, follow these steps to create a new Safe wallet: + - Go to the [Safe website](https://app.safe.global/welcome) and click on "Create new Safe". + - Choose the network (e.g., Ethereum) and the number of required confirmations. + - Add the owners of the Safe wallet and set the threshold for confirmations. + - Review and create the Safe wallet. +2. Necessary tokens: Transfer both tokens that you want to provide liquidity for to your Safe wallet. Make sure you have sufficient amounts of each token. + +Once that's done, you're ready to create your first CoW AMM! + +## Creating an AMM +To create a new CoW AMM using the deployer, follow these steps: +1. Access the CoW AMM Deployer app from your Safe wallet. +2. On the homepage, click on the "Create AMM" button. +3. Fill in the required information in the AMM creation form: + - **Token Pair**: Select the token pair you want to provide liquidity for. Both tokens should already be in your Safe wallet. + - **Price Oracle**: Choose the price oracle (e.g., Balancer, Uniswap V2) to provide price hints to the watch-tower about your CoW AMM. Enter the pool identifier used by the selected protocol. You can also load this information from the protocol subgraph using the provided button. If the button fails, it means there isn't a pool with at least $1000 USD of TVL for that token pair. + - **Minimum Trade Amount**: Specify the minimum amount of the first token required for each trade. For most tokens, this value is automatically filled. If not, a strategy may be to calculate the equivalent of $10 USD in the first token. + - **Fallback Handler**: If your wallet is unsupported, upgrade to a Safe with the special fallback handler. [Learn all about the new Safe Extensible Fallback Handler](https://blog.cow.finance/all-you-need-to-know-about-cow-swaps-new-safe-fallback-handler-8ef0439925d1) and its relevance to Safe in this [overview](https://help.safe.global/en/articles/40838-what-is-a-fallback-handler-and-how-does-it-relate-to-safe). Naturally, the upgrade process has undergone [extensive auditing](https://github.com/cowprotocol/composable-cow/tree/ab3addad9bc05acdbf5fb040eb5c336209b58e31/audits) for increased peace of mind. +4. Review the entered information and click on the "Create AMM" button. +5. Sign the transaction on your Safe wallet to confirm the AMM creation. +6. Wait for the transaction to be confirmed. You will be redirected to the "Manager" page once the AMM is successfully created. + + + +## Managing and Editing an AMM +The "Manager" page provides an overview of your CoW AMM LP position and allows you to manage and edit its parameters. + +The page displays the following information: +- **Total Value**: The total value of the liquidity provided to the AMM, calculated based on the current token prices. +- **Token Amounts**: The individual amounts of each token in the AMM liquidity pool. +- **Price Oracle**: The selected price oracle used by the AMM. +- **Swaps Link**: A link to view the swaps executed by the CoW AMM on the CoW Explorer. + +From the "Manager" page, you can perform two actions: +1. **Stop AMM LP Position**: Clicking this button will redirect you to a confirmation page. After confirming, the CoW AMM will be stopped, and the tokens in your Safe wallet will no longer be used to provide liquidity. +2. **Edit AMM LP Parameters**: This action will redirect you to the AMM creation form, pre-filled with the current parameters of the AMM. You can modify the parameters as needed and push the changes your existing AMM. + + + +## Additional Resources +- [CoW AMM Documentation](https://cow.finance/cow-amm) +- [CoW Grants DAO](https://grants.cow.finance/) +- [Safe Wallet Documentation](https://help.safe.global/) +- [CoW Swap (Safe App)](https://app.safe.global/share/safe-app?appUrl=https%3A%2F%2Fswap.cow.finance&chain=eth) + +## Troubleshooting and FAQs + +### Frequently Asked Questions +1. **Can I create multiple CoW AMMs with the same Safe wallet?** + - No. + +2. **What happens to my tokens when I stop an AMM LP position?** + - When you stop an AMM LP position, your tokens in your Safe will no longer be used to provide liqudity. As the CoW AMM **IS** the Safe when there is an active CoW AMM, the liquidity never leaves your Safe wallet! You can then withdraw or use them for other purposes. + +3. **Can I change the token pair of an existing AMM?** + - No, once an AMM is created with a specific token pair, you cannot change the token pair. If you want to provide liquidity for a different token pair, you need to create a new AMM. + +For further assistance or questions, join the [CoW Protocol Discord](https://discord.com/invite/cowprotocol) and ask in the `#tech-talk` channel. diff --git a/docs/cow-protocol/tutorials/cow-explorer/README.mdx b/docs/cow-protocol/tutorials/cow-explorer/README.mdx new file mode 100644 index 000000000..fb47d4651 --- /dev/null +++ b/docs/cow-protocol/tutorials/cow-explorer/README.mdx @@ -0,0 +1,24 @@ +# Viewing orders + +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: + +- [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. + +Enter the [CoW Explorer](#cow-explorer) 🐮🔎. + +## CoW Explorer + +[CoW Explorer](https://explorer.cow.finance) is an "[Etherscan](https://etherscan.io)"-like interface for the CoW Protocol. It allows users to visualize the orders they have placed on the protocol, as well as the orders that have been executed, across all networks that the protocol is deployed on. + +Users may search for: + +- Order details by [`orderID`](./cow-explorer/order) +- Orders placed by a specific [user's address](./cow-explorer/address) +- Orders settled by a specific [batch auction's `transactionHash`](./cow-explorer/batch-auction) + + diff --git a/docs/cow-protocol/tutorials/cow-explorer/_category_.json b/docs/cow-protocol/tutorials/cow-explorer/_category_.json new file mode 100644 index 000000000..a91802c0b --- /dev/null +++ b/docs/cow-protocol/tutorials/cow-explorer/_category_.json @@ -0,0 +1,6 @@ +{ + "position": 2, + "label": "CoW Explorer", + "collapsible": true, + "collapsed": true +} diff --git a/docs/cow-protocol/tutorials/cow-explorer/address.md b/docs/cow-protocol/tutorials/cow-explorer/address.md new file mode 100644 index 000000000..f5be63a0f --- /dev/null +++ b/docs/cow-protocol/tutorials/cow-explorer/address.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 2 +id: address +--- + +# By user address + +A user may want to see the details of all orders that they have placed. +When searching for their address, they will be presented with an overview of all orders that they have placed. + +For example, below the user has searched for their address [`0x2557...3af7`]( +https://explorer.cow.finance/gc/address/0x2557ed03e34f0141722a643589f007836a683af7) that contains multiple orders that were placed on CoW Protocol on Gnosis Chain: + + + +By default, the explorer will show all orders that have been placed by the user, regardless of their status, in reverse chronological order. + +
+
\ No newline at end of file
diff --git a/docs/cow-protocol/tutorials/cow-explorer/batch_auction.md b/docs/cow-protocol/tutorials/cow-explorer/batch_auction.md
new file mode 100644
index 000000000..d1253ec9c
--- /dev/null
+++ b/docs/cow-protocol/tutorials/cow-explorer/batch_auction.md
@@ -0,0 +1,46 @@
+---
+sidebar_position: 3
+id: batch-auction
+---
+
+# By batch auction
+
+A batch auction is settled on-chain as a single transaction, and it is this transaction hash that is used to query the details of the batch auction. By simply searching for the transaction hash, the user will be presented with an overview of the batch auction.
+
+The batch auction details page provides:
+
+- A list of all orders that were settled in the batch auction
+- A graph showing the routing within the batch auction
+
+Let's take a look at the example batch auction [`0x35f6...0fac`](https://explorer.cow.finance/tx/0x35f65ec4a9d84e27bdb6844f13e7cb72d9de62e6ef95855181bf577d69300fac) below...
+
+## Orders
+
+In the "Orders" tab, the user can see all the orders that were settled in the batch auction. If the user clicks on the respective order ID, they will be taken to the order details page for that order.
+
+
+
+## Settlement graph
+
+This is perhaps one of the most interesting areas, where one can take what was previously an abstract concept of a batch auction, and visualize it in a way that is easy to understand.
+
+This is a visual representation of the routing that was used to settle the batch auction.
+
+There are two types of visualizations, which can be toggled in the controls at the top right of the graph tab:
+
+
+
+### Transfer based
+
+The default visualization method.
+This graph shows the orders that were settled in the batch auction, and the routing that was used to settle the batch auction.
+The graph is interactive, and the user can hover over any of the edges to see the amount that was settled between the respective nodes of the graph.
+
+
+
+### Trade based
+
+This graph shows the tokens traded as nodes, and the edges are the flow between them.
+Green arrows denote protocol trades; red arrows represent token flows through the various pools/AMMs/liquidity sources which make the trades possible.
+
+
diff --git a/docs/cow-protocol/tutorials/cow-explorer/order.md b/docs/cow-protocol/tutorials/cow-explorer/order.md
new file mode 100644
index 000000000..0b23b7bbb
--- /dev/null
+++ b/docs/cow-protocol/tutorials/cow-explorer/order.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 1
+---
+
+# By order
+
+A user may want to see the details of a specific order that they have placed.
+They can search for this order by its unique identifier, the `orderUid`.
+This identifier is returned when an order is placed and can be used to query the details of the order.
+
+:::note
+
+For brevity, the `orderUid` is referred to as "Order ID" in the explorer, and is shortened to the first 8 characters of the `orderUid`.
+
+:::
+
+## Fill-or-kill
+
+Below is a simple example of Order ID [`56ac15a9`](https://explorer.cow.finance/orders/0x56ac15a9dd943743936e29d45e836e87de20b69ee32481338588922b5cc9ee4a04d84e1d86cfad5ffea5e9ab833276481bf965e46322d6ea) that has been filled:
+
+
+
+Understanding orders listing details
+ +| **Field** | **Description** | +|---|---| +| **Order ID** | The first 8 characters of the `orderUid` for the submitted order. | +| **Type** | Sell or buy order. | +| **Sell amount** | The amount and token that the user is selling. | +| **Buy amount** | The amount and token that the user is buying. | +| **Limit price** | The limit price is the price at which this order shall be filled. | +| **Surplus** | The (averaged) surplus for this order. This is the positive difference between the initial limit price and the actual (average) execution price. | +| **Created** | The date and time at which the order was submitted. The timezone is based on the browser locale settings. | +| **Status** | The order status is either `Open`, `Filled`, `Expired`, `Cancelled`, `Partially Filled`, or `Pre-signing` | + +
+
+
+## Partially fillable
+
+A more complex example may be a user who has placed a _partially fillable_ order. This means that the user has expressed a swap intent for a certain amount of tokens, but the order may be filled in multiple batches. This can only be used with [Limit orders](../cow-swap/limit).
+
+
+
+By clicking the "View fills" button, the user can see the fills that have been executed for this order. Fills for the above example are shown below:
+
+
+
+Here we can see that the order has been 100% filled, but in dozens of batches. For ease of analysis, an overview is shown providing:
+
+- The total amount filled (in this case 100%)
+- The average execution price (in this case 0.22134041 ANT for DAI)
+- Total surplus (in this case 0.39% / 860.894 DAI)
+- The limit price applied across all fills (in this case 0.22222222 ANT for DAI)
+
+## States
+
+As CoW Explorer is meant to help users visualize their signed orders, a critical parameter to show is the _state_ of the signed order. This parameter has the following status:
+
+- **Open** (pending)**:** State for a standing order. Orders in this state are being considered by the solvers. It is the entry state for all orders[^presign], the default from the moment the order is placed. From here the order can transition to all other states.
+- **Filled:** State for an executed/settled order. Orders in this state have been executed and the corresponding funds transferred to the target account. Orders in this state will have available a link to the corresponding Etherscan settlement transaction. This settlement transaction would contain your order's execution and any other orders that are part of the same batch.
+- **Expired:** State for orders that have not been executed. Orders in this state have not been executed during the defined expiration time.
+- **Cancelled:** State for orders that have been cancelled. Orders in this state have been cancelled as per user request.
+- **Partially-filled:** State for orders that have been partially executed. Parts of the order have been executed and the corresponding funds transferred to the target account.
+- **Pre-signing:** State for orders that are to be pre-signed. Commonly used for orders submitted from a Smart Contract wallet, such as the [Safe](https://safe.global/) wallet.
+
+[^presign]: Except for pre-signed orders, where the first state is **Pre-signing**.
diff --git a/docs/cow-protocol/tutorials/cow-swap/README.mdx b/docs/cow-protocol/tutorials/cow-swap/README.mdx
new file mode 100644
index 000000000..0e16dc546
--- /dev/null
+++ b/docs/cow-protocol/tutorials/cow-swap/README.mdx
@@ -0,0 +1,20 @@
+# CoW Swap
+
+[CoW Swap](https://swap.cow.finance/#/swap?utm_source=docs.cow.finance&utm_content=cow-swap-tutorial) is the first interface built on top of CoW Protocol and serves as a reference implementation for developers wishing to build user interfaces for CoW Protocol.
+
+The interface may look very familiar to the average DeFi user, as it is originally based on the [Uniswap](https://uniswap.org) interface. This provides users with a familiar user experience, while benefiting from the unique features of CoW Protocol.
+
+
+
+## Supported Wallets
+
+CoW Swap supports many popular wallets including:
+
+- Injected wallets, such as [Rabby](https://rabby.io), [MetaMask](https://metamask.io), [Trust Wallet](https://trustwallet.com). In general any wallet implementing [EIP-1193](https://eips.ethereum.org/EIPS/eip-1193)
+- Multisigs wallets such as [Safe](https://safe.global), both as a [Safe app](https://app.safe.global/share/safe-app?appUrl=https%3A%2F%2Fswap.cow.finance&chain=eth), or using Wallet Connect (IOS, Android and Web).
+- Any wallet supporting [WalletConnect v2](https://walletconnect.com) such as most mobile wallets.
+- Hardware wallets such as [Trezor](https://trezor.io), either directly, or through integration with injected wallets such us Rabby or Metamask.
+
+If you've developed a wallet that supports [`EIP-712`](https://eips.ethereum.org/EIPS/eip-712) or [`ERC-1271`](https://eips.ethereum.org/EIPS/eip-1271) signing, and would like to have your wallet supported by CoW Swap, please [file an issue](https://github.com/cowprotocol/cowswap/issues/new) or reach out to us on [Discord](https://discord.com/invite/cowprotocol).
+
+Alternatively, you may wish to integrate CoW Swap directly into your wallet interface. If you would like to integrate CoW Swap to your wallet, and would like support in the integration process, please reach out to us on bd@cow.finance.
diff --git a/docs/cow-protocol/tutorials/cow-swap/_category_.json b/docs/cow-protocol/tutorials/cow-swap/_category_.json
new file mode 100644
index 000000000..b28a2926a
--- /dev/null
+++ b/docs/cow-protocol/tutorials/cow-swap/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 1,
+ "label": "CoW Swap",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/docs/cow-protocol/tutorials/cow-swap/custom-links.md b/docs/cow-protocol/tutorials/cow-swap/custom-links.md
new file mode 100644
index 000000000..0d18c9f77
--- /dev/null
+++ b/docs/cow-protocol/tutorials/cow-swap/custom-links.md
@@ -0,0 +1,83 @@
+---
+title: Make custom links
+---
+
+# Custom Links
+
+[CoW Swap](https://swap.cow.finance) supports URL query parameters to allow anyone to create a custom link for sharing a specific trade with a friend or on social media, or for creating a custom link to a specific trade for your own use.
+
+### Examples
+
+- [`https://swap.cow.finance`](https://swap.cow.finance) - CoW Swap main page (`swap` is default page)
+- [`https://swap.cow.finance/#/swap`](https://swap.cow.finance/#/swap) - `swap` page
+- [`https://swap.cow.finance/#/limit`](https://swap.cow.finance/#/limit) - `limit` orders page
+- [`https://swap.cow.finance/#/100/swap`](https://swap.cow.finance/#/100/swap) - `swap` page on Gnosis chain network
+- [`https://swap.cow.finance/#/100/limit/WXDAI/COW`](https://swap.cow.finance/#/100/limit/WXDAI/COW) - Create a `limit` order to sell `WXDAI` for `COW`
+- [`https://swap.cow.finance/#/1/swap/WETH/COW?sellAmount=100`](https://swap.cow.finance/#/1/swap/WETH/COW?sellAmount=100) - Swap `100 WETH` for `COW`
+- [`https://swap.cow.finance/#/1/swap/WETH/COW?buyAmount=10000&recipient=vitalik.eth`](https://swap.cow.finance/#/1/swap/WETH/COW?buyAmount=10000&recipient=vitalik.eth) - Buy on `swap` sending the outcome to a custom recipient (can be either address or ens)
+- [`https://swap.cow.finance/#/100/limit/WETH/WXDAI?sellAmount=2&buyAmount=6000`](https://swap.cow.finance/#/100/limit/WETH/WXDAI?sellAmount=2&buyAmount=6000) - Create a limit order to sell `2 WETH` for `6000 WXDAI`
+
+## Query Parameters
+
+Even though the main page is `swap`, each page has it's own specific URL parameters that can be set, in addition to global parameters that are used on all pages. Parameters not applicable to a page will have no effect on UI settings.
+
+Fortunately, the `swap` and `limit` pages have the same URL query parameters!
+
+### URL links format
+
+#### Swap
+
+`https://swap.cow.finance/#/Understanding order details
+ +| **Field** | **Description** | +|---|---| +| **Order ID** | The first 8 characters of the `orderUid` for the submitted order. | +| **From** | The account address which signed the order. | +| **To** | The account address which will/did receive the bought amount. | +| **Transaction hash** | The on-chain settlement transaction for this order (only applicable when Status is `Filled` and not partially fillable). Can be viewed on Etherscan. | +| **Status** | The order status is either `Open`, `Filled`, `Expired`, `Cancelled`, `Partially Filled`, or `Pre-signing` | +| **Submission time** | The date and time at which the order was submitted. The timezone is based on the browser locale settings. | +| **Expiration time** | The date and time at which an order will expire and effectively be cancelled. Depending on the type of order, it may have partial fills upon expiration. | +| **Type** | CoW Protocol supports three types of orders - `Market`, `Limit` and `Liquidity`. May be further classed `Fill or Kill` or `Partial execution`. | +| **Amount** | The total sell and buy amount for this order. Sell amount includes the fee. | +| **Limit price** | The limit price is the price at which this order shall be (partially) filled, in combination with the specified slippage. The fee is already deducted from the sell amount. | +| **Execution price** | The actual price at which this order has been matched and executed, after deducting fees from the amount sold. | +| **Order surplus** | The (averaged) surplus for this order. This is the positive difference between the initial limit price and the actual (average) execution price. | +| **Filled** | Indicates what percentage amount this order has been filled and the amount sold/bought. Amount sold includes the fee. | +| **Fees** | The amount of fees paid for this order. This will show a progressive number for orders with partial fills. | +| **App Data** | The AppData hash for this order. It can denote encoded metadata with info on the app, environment and more, although not all interfaces follow the same pattern. Show more will try to decode that information. | + ++ +
+ +After all signatures are collected and the transaction is submitted on-chain, your order becomes 'active'. The "Orders overview" allows you to monitor its current status and see the full list of active orders. +
+ +
| 
|
+| ------------------------------------------------------------------ | ----------------------------------------------------------------------- |
+
+**Hook dApp** - is an application that allows you to conveniently program an order to perform any action before or after a swap.
+
+In the CoW Swap interface you can find several hooks for different tasks. For example, you can claim GNO from Gnosis validators before your swap. You can also specify an arbitrary call to a smart contract before or after your swap using the "Build your own hooks" dApp.
+
+But that's not all. You can also develop your own application that will install a hook in CoW Swap!
+For this purpose, there is a custom application based on [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe).
+
+In order to add a custom hook, you need to:
+
+- Click "add Pre/Post-Hook Action"
+- Go to "My Custom Hooks" tab
+- Paste a URL of the hook dApp
+
+
+
+:::note
+
+CoW Hooks are still under development!
+But you can test it by switching "Enable hooks" toggle ON in the Swap settings.
+
+:::
+
+## How to develop CoW Hook dApps
+
+CoW Hook dApp is a web application that communicates with CoW Swap using [post-messages](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
+For your convenience there is a npm library [`@cowprotocol/hook-dapp-lib`](https://www.npmjs.com/package/@cowprotocol/hook-dapp-lib) which provides everything necessary to get started with your hook dApp development.
+
+### Install
+
+```bash
+yarn add @cowprotocol/hook-dapp-lib
+```
+
+```bash
+npm install @cowprotocol/hook-dapp-lib
+```
+
+It provides:
+
+- [`EIP-1193`](https://eips.ethereum.org/EIPS/eip-1193) provider to interact with a user wallet
+- `HookDappContext` which contains environment parameters (chainId, account, etc.) and current order parameters (sell token, validTo, etc.)
+
+And it expects calling following callbacks:
+
+- `addHook` when a hook data is ready and can be added to an order
+- `editHook` when hook parameters were changed (edit mode)
+- `setSellToken / setBuyToken` if you want to change the trade assets
+
+### Quick start
+
+Let's create a simple hook dApp that checks the COW token balance of the order creator.
+
+```html
+
+
+
+
+
+
+
+```
+
+### Types specification
+
+```typescript
+import { initCoWHookDapp, CoWHookDappActions, HookDappContext } from '@cowprotocol/hook-dapp-lib'
+
+// context: HookDappContext
+// actions: CoWHookDappActions
+// provider: EIP-1193
+const { actions, provider } = initCoWHookDapp({ onContext(context: HookDappContext) {} })
+```
+
+---
+
+#### `HookDappContext`
+
+| Parameter | Type | Optional | Description |
+| ----------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `chainId` | `number` | false | Current chainId in CoW Swap. |
+| `account` | `string` | true | The user's account address. If not set, the wallet is not connected yet. |
+| `orderParams` | `HookDappOrderParams \| null` | false | The parameters for the order. If value is `null`, the order is not ready yet. See [HookDappOrderParams](https://github.com/cowprotocol/cowswap/blob/develop/libs/hook-dapp-lib/src/types.ts#L29) for more details. |
+| `hookToEdit` | `CowHookDetails` | true | CoW Swap supports editing hooks that have been created already. If the parameter is set, then it's in edit mode. See [CowHookDetails](https://github.com/cowprotocol/cowswap/blob/develop/libs/hook-dapp-lib/src/types.ts#L18) for more details. |
+| `isSmartContract` | `boolean \| undefined` | true | Whether the account is a smart contract. `undefined` if unknown. |
+| `isPreHook` | `boolean` | false | Indicates the position of the hook. |
+
+---
+
+#### `CoWHookDappActions`
+
+| Parameter | Type | Description |
+| ---------------------------- | -------------------------------------- | ------------------------------------------------------------------- |
+| `addHook` | `(payload: CowHookCreation) => void` | The callback should be executed once the hook is ready to be added. |
+| `editHook` | `(payload: CowHookDetails) => void` | The callback should be executed when the hook data is changed. |
+| `setSellToken / setBuyToken` | `(token: { address: string }) => void` | Optionally you can change the asset for sell/buy. |
+
+### Manifest
+
+As stated at the beginning of this document, in the CoW Swap interface you can add your application as a custom application.
+To do this, the application must contain `manifest.json` file with following structure:
+
+```json
+{
+ "cow_hook_dapp": {
+ "id": "06a2747d08f0026f47aebb91ac13172a318eb3f6116f742751e2d83cc61b8753",
+ "name": "Your Hook Dapp",
+ "descriptionShort": "Your Hook Dapp short description",
+ "description": "Your Hook Dapp full description",
+ "version": "0.0.1",
+ "website": "https://your-cow-hook.dapp",
+ "image": "http://your-cow-hook.dapp/logo.png",
+ "conditions": {
+ "position": "pre",
+ "smartContractWalletSupported": false,
+ "supportedNetworks": [1, 100, 42161]
+ }
+ }
+}
+```
+
+| Parameter | Type | Description |
+| -------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | `string` | 64-bit hex application identifier `(keccak256(YOUR_APP_NAME))`. This value is used to match hooks in an order with the dApp that generated the hook. |
+| `name` | `string` | The name of the Hook Dapp. |
+| `descriptionShort` | `string` | A short description. |
+| `description` | `string` | A full, detailed description of the Hook Dapp. |
+| `version` | `string` | The version number of the Hook Dapp, typically following semantic versioning. |
+| `website` | `string` (URL) | The URL link to the Hook Dapp's official website. |
+| `image` | `string` (URL) | The URL link to the Hook Dapp's logo or representative image. |
+| `conditions.position` | `pre \| post` | Specifies the execution position of the hook, `pre` or `post`. If not set, then the Hook Dapp supports both positions. |
+| `conditions.walletCompatibility` | `HookDappWalletCompatibility[]` | Indicates whether the Hook Dapp supports smart contract wallets or EOAs. |
+| `conditions.supportedNetworks` | `array` of `integers` | List of supported network IDs (e.g., `1` for Ethereum mainnet, `100` for Gnosis chain, `42161` for Arbitrum, `8453` for Base). If not set, then the Hook Dapp will be available for any network supported by CoW Swap. |
+
+## Advanced Hook Dapps
+
+For more complex scenarios, such as transferring the buy amount to another smart-contract or other smart-contract related actions, you will probably need CoW Shed:
+
+- [CoW Shed](https://github.com/cowdao-grants/cow-shed)
+- [Permit, Swap & Bridge CoW Hook example](https://v1.docs.cow.finance/overview/cow-hooks/cow-hooks-example/permit-swap-and-bridge-cow-hook)
diff --git a/docs/cow-protocol/tutorials/solvers/_category_.json b/docs/cow-protocol/tutorials/solvers/_category_.json
new file mode 100644
index 000000000..faeaf2ead
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/_category_.json
@@ -0,0 +1,6 @@
+{
+ "position": 3,
+ "label": "Solvers",
+ "collapsible": true,
+ "collapsed": true
+}
diff --git a/docs/cow-protocol/tutorials/solvers/create.md b/docs/cow-protocol/tutorials/solvers/create.md
new file mode 100644
index 000000000..38a7a6840
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/create.md
@@ -0,0 +1,81 @@
+---
+sidebar_position: 1
+draft: true
+---
+
+# Create a solver
+
+## Requirements
+
+Creating a solver requires knowledge of:
+
+- Programming
+- Optimization algorithms; or
+- An easy route / path that is not yet used by the existing solvers
+
+For the example below, we will use:
+
+- Rust as the programming language
+- Knowledge of a route that is not yet used by the existing solvers
+
+## Idea
+
+Let us consider the case of [Yearn](https://yearn.fi) tokens. A user has `USDC` and wants to buy `yvUSDC`. If no solver understands how to deposit into a Yearn vault, all solutions from solvers will require an LP `USDC/yvUSDC` to settle the order. But we know how to deposit into a Yearn vault, so we can create a solver that understands how to do that.
+
+:::tip Get the big picture
+
+CoW Protocol infrastructure is a lot of services running together in herd harmony, which is a bit intimidating at the beginning. Before proceeding, it would be advisable to read the architectural overview to get a better understanding of how CoW Protocol works and its entities.
+
+:::
+
+### Setup
+
+:::caution
+
+it is assumed you have rust setup correctly with `rustup`.
+
+:::
+
+
+Let's start simple. Let's first run a solver which solves a json we send by hand with curl.
+
+Start by cloning [https://github.com/gnosis/cow-dex-solver](https://github.com/gnosis/cow-dex-solver)
+
+cow-dex-solver will give you a good idea of how a solver service is architectured.
+You have a method called `solve()` which receives the batch `orders` and returns a `SettledBatchAuctionModel` aka a solution.
+
+To run, exec:
+
+```
+cargo run -v
+```
+
+Once the service is running you can start throwing jsons at it.
+I started reading the code and playing with different json setups calling:
+
+```bash
+curl -vX POST "http://127.0.0.1:8000/solve" \
+ -H "accept: application/json" \
+ -H "Content-Type: application/json" \
+ --data "@/Users/user/dev/cow-dex-solver/sample.json"
+```
+
+You can get some inspiration from prod examples here: (insert example)
+[http://gnosis-europe-gpv2-solver.s3-website.eu-central-1.amazonaws.com/index.html#data/prod/2022/01/](http://gnosis-europe-gpv2-solver.s3-website.eu-central-1.amazonaws.com/index.html#data/prod/2022/01/)
+
+Make sure to test what happens when there is a **COW**!
+
+### My solver code
+
+I forked cow-dex-solver and wrote my first lines of rust.
+You can check out my solver's code at:
+[https://github.com/poolpitako/cow-dex-solver/pull/1](https://github.com/poolpitako/cow-dex-solver/pull/1)
+
+
+## References
+
+- Set of problem instances and solutions, for testing the algorithm
+- [CoW Protocol driver](https://github.com/cowprotocol/services), for simulating solutions on-chain.
+- Problem specification
+- [Batch auction MIP formulation](https://github.com/gnosis/dex-research/blob/master/BatchAuctionOptimization/batchauctions.pdf)
+
diff --git a/docs/cow-protocol/tutorials/solvers/deploy.md b/docs/cow-protocol/tutorials/solvers/deploy.md
new file mode 100644
index 000000000..bc7ab832b
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/deploy.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 3
+draft: true
+---
+
+# Deploy a solver
+
+Once the Driver is running, we can now locally deploy our solver server so that it can receive the instances from the Driver, solve them, and then report back the solution to the Driver. The solver receives the instance in JSON format via an HTTP Get request, solves the instance and then, via an HTTP POST request, sends the solution (again in JSON format) to the Driver.
+
+An example of a publicly available solver, namely the Dex CoW Solver, can be found here:
+
+[https://github.com/gnosis/cow-dex-solver](https://github.com/gnosis/cow-dex-solver)
+
+You can follow the simple instructions of the Dex CoW Solver to locally deploy that particular solver.
+
+For potential questions/issues regarding the testing of solvers, we also encourage everyone to contact our team in the CoW Swap Discord: [https://discord.com/invite/cowprotocol](https://discord.com/invite/cowprotocol)
+
diff --git a/docs/cow-protocol/tutorials/solvers/evaluate.md b/docs/cow-protocol/tutorials/solvers/evaluate.md
new file mode 100644
index 000000000..1ac758120
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/evaluate.md
@@ -0,0 +1,17 @@
+---
+sidebar_position: 4
+draft: true
+---
+
+# Evaluate a solver
+
+## Getting notified about the ranking
+
+A very useful functionality provided by the driver is the "notify" endpoint, which notifies all solvers participating in an auction about the ranking, once the bidding has closed, i.e., once all solutions have been submitted and have been ranked. (To find out about how solutions are ranked, see [this](https://docs.cow.finance/off-chain-services/in-depth-solver-specification/solver-auction-and-rewards) section).
+
+The implementation details of the notify endpoint can be found in this PR:
+[https://github.com/cowprotocol/services/pull/684](https://github.com/cowprotocol/services/pull/684)
+
+which describes the callback that the driver does to the solvers once the ranking is complete.
+
+This is very useful both for debugging purposes (as the endpoint also reveals whether the solution failed to simulate) and for interacting with private liquidity quotes that can be immediately "released", once the solver is notified that they did not win the auction.
diff --git a/docs/cow-protocol/tutorials/solvers/flashloans_support.md b/docs/cow-protocol/tutorials/solvers/flashloans_support.md
new file mode 100644
index 000000000..442add2e5
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/flashloans_support.md
@@ -0,0 +1,100 @@
+---
+sidebar_position: 4
+---
+
+# How to execute flashloans orders
+
+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](/docs/cow-protocol/reference/core/intents/app_data.mdx). As a reminder, the autopilot only shares the appdata hash as part of the auction instance it shares with the [drivers](/docs/cow-protocol/tutorials/arbitrate/solver/driver.md), and so it is the driver's responsibility to recover the full appdata.
+
+:::note
+[Solvers](/docs/cow-protocol/tutorials/arbitrate/solver/solver-engine.md) connected to the reference driver already receive the full appdata from the driver.
+:::
+
+For example, this [staging order](https://explorer.cow.finance/gc/orders/0x413a7246f58441ad92ea19c09cef90d1b23a1e211e0963f3d39b7db48140533d669685c660c260d80b614f8d1a5ffd24c4e3b82668cd8760) has the appdata hash `0xa8476d34ec1e22b818cf3d6289e30271a04a4e38a8a3a71f947b5881de06a852` which can be looked up [here](https://barn.api.cow.finance/xdai/api/v1/app_data/0xa8476d34ec1e22b818cf3d6289e30271a04a4e38a8a3a71f947b5881de06a852). Specifically, in the `metadata` field, the `flashloan` entry looks as follows:
+
+```json
+ "flashloan": {
+ "amount": "20000000000000000000",
+ "liquidityProvider": "0xb50201558B00496A145fE76f7424749556E326D8",
+ "protocolAdapter": "0x19167A179bcDDBecc2d655d059f20501E5323560",
+ "receiver": "0x19167A179bcDDBecc2d655d059f20501E5323560",
+ "token": "0xe91D153E0b41518A2Ce8Dd3D7944Fa863463a97d"
+ }
+```
+
+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.
+
+:::
+
+### 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.
+
+
+:::caution
+
+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.
+
+:::
+
+:::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).
+
+:::
+
+### 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.finance/gc/orders/0x413a7246f58441ad92ea19c09cef90d1b23a1e211e0963f3d39b7db48140533d669685c660c260d80b614f8d1a5ffd24c4e3b82668cd8760)).
+
+2. **Repay debt with collateral**: Use some of the collateral to repay the debt. This is essentially auto-liquidating without a fee ([example](https://explorer.cow.finance/gc/orders/0xab8596fb7eae317bf15b1b4d57169f5e6714479e38661e0f06df7e7f12409915d20982aedc2074bd3b798cd6c02f6e03e51743cc68cdd580
+)).
+
+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.finance/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.
+
+:::
+
+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.
diff --git a/docs/cow-protocol/tutorials/solvers/from_shadow_to_prod.md b/docs/cow-protocol/tutorials/solvers/from_shadow_to_prod.md
new file mode 100644
index 000000000..1ac9a0117
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/from_shadow_to_prod.md
@@ -0,0 +1,29 @@
+---
+sidebar_position: 3
+draft: true
+---
+
+# Integrating your solver
+
+
+## Shadow competition (testing)
+
+- When a solver team has a solver prototype ready for testing, we encourage them to get in touch with the core team so that they can test their solver in the so-called shadow competition. The shadow competition is a risk-free environment that receives production orderflow but only does simulations, and is a good first step for solvers to test their solver engines against the competition.
+
+:::note
+
+In order to get connected to the shadow competition, feel free to reach out to an admin of the ["CoW Swap Solvers"](https://t.me/+2Z_-DW57meA1MDlh) group on Telegram.
+
+:::
+
+## Live competition (production)
+
+- To connect to the live competition, each solver is required to be part of a "bonding pool", as specified by [CIP-7](https://snapshot.org/#/cow.eth/proposal/0x267edf7a0bd3c771cfca763322f011ee106d8d5158612c11da29183260d1dba7); see [this section](/cow-protocol/reference/core/auctions/bonding-pools) for more details.
+
+:::note
+
+As the requirements for a bonding pool are substantial, the DAO has also set up the CoW bonding pool, currently managed by the core team, and any solver team can apply to be part of that pool. In such a case, the core team will schedule some meetings with the corresponding solver team, will do some KYC and will make an informed decision about whether the solver can join that pool or not. As a requirement, any solver team that is part of the CoW bonding pool is required to lock 25% of the COW rewards they receive (via the solver rewards program) until they exit the CoW bonding pool. For more information about the CoW bonding pool and for applying to become part of it, feel free to reach out to an admin of the ["CoW Swap Solvers"](https://t.me/+2Z_-DW57meA1MDlh) group on Telegram.
+
+:::
+
+Once a solver becomes part of a bonding pool, then the core team will proceed to allow-list the solver and connect it to the live competition.
diff --git a/docs/cow-protocol/tutorials/solvers/local_test.md b/docs/cow-protocol/tutorials/solvers/local_test.md
new file mode 100644
index 000000000..ee9bd2ba0
--- /dev/null
+++ b/docs/cow-protocol/tutorials/solvers/local_test.md
@@ -0,0 +1,70 @@
+---
+sidebar_position: 2
+---
+
+# Locally testing a solver with the CoW Protocol orderflow
+
+CoW Protocol infrastructure is a lot of services running together in herd harmony, which is a bit intimidating at the beginning. Before proceeding, it would be advisable to read the architectural overview to get a better understanding of how CoW Protocol works and its entities.
+
+In order to test a solver against CoW Protocol's orderflow, one needs to locally run the following components
+
+- autopilot, which will be configured to point, for example, to the production orderbook and to send the auctions to a local driver.
+- driver, which will receive auctions from the autopilot and forward them to the solver engine
+- the solver engine that is meant to be tested, run as a local http server able to receive `/solve` requests from the driver and respond to them.
+
+:::caution
+
+It is assumed you have rust setup correctly with `rustup`.
+
+:::
+
+The repository where all the backend services can be found is this one: [https://github.com/cowprotocol/services](https://github.com/cowprotocol/services). Here are the main instructions to run the autopilot and the driver.
+
+For the autopilot, we run
+
+```
+ cargo run --bin autopilot -- --native-price-estimators "baseline|http://driver/baseline" --skip-event-sync true --node-url $NODE_URL --shadow https://api.cow.finance/mainnet --drivers "mysolver1|http://localhost:11088/mysolver1"
+```
+
+where one needs to set the NODE_URL appropriately (e.g., a free Infura endpoint).
+
+:::caution
+
+CoW Protocol services infrastructure can be very heavy on RPC resource consumption. Be careful if using with post-paid plans, it's recommended to keep a close eye on RPC resource consumption.
+
+:::
+
+For the driver, we run
+
+```
+ cargo run -p driver -- --config driver.config.toml --ethrpc $NODE_URL
+```
+
+where one needs to configure driver.config.toml to point to their solver engine. A sample such file can be found [here](https://github.com/cowprotocol/services/blob/main/crates/driver/example.toml).
+
+Once the above are set up and running, one can then start testing their solver engine against one of the following orderbooks:
+
+| Orderbook URL | Network | Environment |
+| ------------------------------------------ | ------------ | ----------- |
+| Main DAO safe bound to COW token holder votes on `cow.eth` snapshot space | Mainnet | +| [CoW DAO (USDC)](https://app.safe.global/home?safe=eth:0xA1cb7762F40318ee0260F53e15De835fF001cb7E) | `0xA1cb7762F40318ee0260F53e15De835fF001cb7E`
Safe controlled by CoW DAO dedicated for storing `USDC` | Mainnet | +| [Solver payouts](https://app.safe.global/home?safe=eth:0xA03be496e67Ec29bC62F01a428683D7F9c204930) | `0xA03be496e67Ec29bC62F01a428683D7F9c204930`
Responsible for executing solver payouts according to the DAO-defined [solver accounting rules](https://forum.cow.finance/t/cip-20-auction-model-for-solver-rewards/1405); it receives collected fees from the settlement contract | Mainnet | +| [Solver controller](https://app.safe.global/home?safe=eth:0x423cEc87f19F0778f549846e0801ee267a917935) | `0x423cEc87f19F0778f549846e0801ee267a917935`
Responsible for adding / removing solvers from the settlement contract allow-list, according to DAO-defined solver bonding rules; it also converts the collected protocol fees to ETH | Mainnet | +| [CoW Treasury](https://app.safe.global/home?safe=eth:0x616dE58c011F8736fa20c7Ae5352F7f6FB9F0669) | `0x616dE58c011F8736fa20c7Ae5352F7f6FB9F0669`
Managed with support of Karpatkey DAO to generate yield on idle treasury funds | Mainnet | +| [CoW DAO (GC)](https://app.safe.global/home?safe=gno:0xcA771eda0c70aA7d053aB1B25004559B918FE662) | `0xcA771eda0c70aA7d053aB1B25004559B918FE662`
CoW DAO main safe on Gnosis Chain | GC | +| [Grants Committee](https://app.safe.global/home?safe=gno:0xCA1F000D520c21C47E6c634DD31b92b91A6338bD) | `0xCA1F000D520c21C47E6c634DD31b92b91A6338bD`
Controlled by 7 committee members, responsible for funding CoW Grants | GC | +| [Grants Funds](https://app.safe.global/home?safe=gno:0xDA00000B30dCf0C3f5d968e4451Ebdee6950d63e) | `0xDA00000B30dCf0C3f5d968e4451Ebdee6950d63e`
Controlled by CoW DAO and Grants Committee to allow CoW DAO clawback of grants funds | GC | +| [Grant Funds (Volume-based Partner Reward Program - COW)](https://app.safe.global/home?safe=gno:0xbD96C4Fe53f1d89a8Bdb3522BCEDfB20b5601b69) | `0xbD96C4Fe53f1d89a8Bdb3522BCEDfB20b5601b69`
Controlled by CoW DAO and Grants Committee to allow CoW DAO clawback of grants funds | GC | \ No newline at end of file diff --git a/docs/governance/process/README.mdx b/docs/governance/process/README.mdx new file mode 100644 index 000000000..93da18c2f --- /dev/null +++ b/docs/governance/process/README.mdx @@ -0,0 +1,80 @@ +--- +sidebar_position: 3 +--- + +import Living from '../_living.md' + +# Governance Process + +
Proposer] + Community[
CoW Community] + Phase1[Phase 1: Draft Proposal
Forum discussion, incorporating feedback
min Duration: six days] + Phase2[Phase 2: Consensus
Community vote on Snapshot
Duration: seven days] + ProposalRejected(Proposal rejected) + ProposalAccepted[Transaction execution* and proposal implementation] + + direction LR + Proposer -->|Submit initial proposal| Phase1 + Phase1 --> Phase2 + Community -->|Discussion| Phase1 + Community -->|Voting| Phase2 + Phase2 -->|Consensus is not reached| ProposalRejected + Phase2 -->|Consensus is reached| ProposalAccepted +``` + +(*) note: if the execution is via oSnap module for automatic execution on-chain, it adds a three day delay to the actual transaction execution. + +### Phase 1: Community Discussion + +**Minimum time: 6 days** + +In the first phase, a *draft* proposal is created and posted to the forum. The purpose of the Draft Proposal phase is to establish formal discussion around a potential proposal. + +To create a Draft Proposal please follow these steps: + +- Create a new topic in the [Governance category](https://forum.cow.finance/c/cow-improvement-proposals-cip/6/none), using the [proposal template pinned](https://forum.cow.finance/t/cip-0-template/28) to the top of the _Governance Resources_ category. +- Engage in discussion to build support for the proposal. +- If your proposal includes any on chain interactions by CoW DAO, you will need to write the code for your proposal while it is in draft stage. It is **required** to provide Tenderly transaction simulations. You may wish to wait until the proposal gathers some support before doing this. + +Once you are confident the proposal is in a stable state, and at least the minimum time has passed since the proposal was first published, you can move the proposal yourself to the [next phase](#phase-2-voting). + +**Note: there is an exception to the 6-days rule with fast-tracked proposals that only require 72hours (3 days) on the forum: at the moment of writing, these include slashing proposals due to EBBO-violation (refer to CIP-52)** + +### Phase 2: Voting + +**Vote duration: 7 days** + +- Anyone that holds >10,000 COW can advance a CIP and post it to [snapshot](https://snapshot.org/#/cow.eth) assuming all criteria defined in [Phase 1](#phase-1-community-discussion) above are met. +- Assign the CIP a number in the form `CIP-###`. +- Change the topic from _Draft Proposal_ to **Active Proposal**. +- Create a snapshot vote with a duration of 7 days, and cross link the snapshot and forum post. +- If your proposal should include an executable transactions, you will now need to create the transaction on the oSnap Snapshot module as part of the process for posting the proposal on Snapshot. +- After creating the proposal on Snapshot and before proceeding, please double and triple check that the included transaction is correct. Asking another community member for a review is advised. + +**Note that the oSnap implementation on CoW DAO adds a three day delay in execution after the voting is successfully closed.** + +## Process Improvement + +The aforementioned process is open to improvement. If you have any suggestions, please post them in the [Governance category](https://forum.cow.finance/c/cow-improvement-proposals-cip/6/none) of the forum. Proposals that increase governance efficiency and/or decentralization are encouraged, as CoW Protocol continues to move to a more community-owned and decentralized governance model. diff --git a/docs/governance/process/_category_.json b/docs/governance/process/_category_.json new file mode 100644 index 000000000..04ef35319 --- /dev/null +++ b/docs/governance/process/_category_.json @@ -0,0 +1,3 @@ +{ + "position": 3 +} diff --git a/docs/governance/process/template.md b/docs/governance/process/template.md new file mode 100644 index 000000000..0698148ba --- /dev/null +++ b/docs/governance/process/template.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 2 +--- + +# CIP Template + +> 📜 This template is to be used to create any new CoW DAO Improvement Proposal. + +:::note + +CIP number will be assigned by a forum moderator when the proposal is moved to the second phase. When creating a topic to submit your CIP, please name accordingly, `CIP-draft: title`. + +::: + +````md +# CIP-Draft: Template + +CIP:
+
+
+ {open && (
+
+ )
+}
diff --git a/src/components/AiActionsDropdown/styles.module.css b/src/components/AiActionsDropdown/styles.module.css
new file mode 100644
index 000000000..3d4d6d489
--- /dev/null
+++ b/src/components/AiActionsDropdown/styles.module.css
@@ -0,0 +1,108 @@
+.wrapper {
+ position: relative;
+ display: inline-block;
+}
+
+.trigger {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ padding: 6px 14px;
+ border: none;
+ border-radius: 8px;
+ background: #052B65;
+ color: #fff;
+ font-size: 0.85rem;
+ cursor: pointer;
+ transition: opacity 0.15s, box-shadow 0.15s;
+}
+
+:global(html[data-theme='dark']) .trigger {
+ background: #CAE9FF;
+ color: #052B65;
+}
+
+.trigger:hover {
+ opacity: 0.9;
+ box-shadow: var(--ifm-global-shadow-lw);
+}
+
+.triggerIcon {
+ width: 18px;
+ height: 18px;
+ opacity: 1;
+}
+
+.chevron {
+ width: 14px;
+ height: 14px;
+ opacity: 0.8;
+ transition: transform 0.15s;
+}
+
+.chevronOpen {
+ transform: rotate(180deg);
+}
+
+.dropdown {
+ position: absolute;
+ top: calc(100% + 4px);
+ right: 0;
+ z-index: 100;
+ min-width: 260px;
+ padding: 6px;
+ border: 1px solid var(--ifm-color-emphasis-200);
+ border-radius: 10px;
+ background: var(--ifm-background-color);
+ box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
+}
+
+.item {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ width: 100%;
+ padding: 10px 12px;
+ border: none;
+ border-radius: 8px;
+ background: none;
+ color: var(--ifm-color-emphasis-800);
+ font-size: 0.85rem;
+ text-decoration: none;
+ cursor: pointer;
+ transition: background 0.12s;
+}
+
+.item:hover {
+ background: var(--ifm-background-surface-color);
+ color: var(--ifm-color-emphasis-900);
+ text-decoration: none;
+}
+
+.itemIcon {
+ width: 20px;
+ height: 20px;
+ flex-shrink: 0;
+ opacity: 0.75;
+}
+
+.itemText {
+ display: flex;
+ flex-direction: column;
+ align-items: flex-start;
+}
+
+.itemLabel {
+ font-weight: 500;
+ line-height: 1.3;
+}
+
+.itemDesc {
+ font-size: 0.75rem;
+ color: var(--ifm-color-emphasis-700);
+ line-height: 1.3;
+}
+
+.copied .itemLabel {
+ color: #16a34a;
+}
diff --git a/src/components/HomepageFeatures/index.tsx b/src/components/HomepageFeatures/index.tsx
new file mode 100644
index 000000000..91ef4601d
--- /dev/null
+++ b/src/components/HomepageFeatures/index.tsx
@@ -0,0 +1,70 @@
+import React from 'react';
+import clsx from 'clsx';
+import styles from './styles.module.css';
+
+type FeatureItem = {
+ title: string;
+ Svg: React.ComponentType
+
+
+
+
+
+
+ {editUrl && (
+
+ )}
+
+ )}
+ docs directory.
+
+ ),
+ },
+ {
+ title: 'Powered by React',
+ Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+ description: (
+ <>
+ Extend or customize your website layout by reusing React. Docusaurus can
+ be extended while reusing the same header and footer.
+
+ ),
+ },
+];
+
+function Feature({title, Svg, description}: FeatureItem) {
+ return (
+
+
+ );
+}
+
+export default function HomepageFeatures(): JSX.Element {
+ return (
+
+
+
+
+
+ {title}
+{description}
+
+
+
+ {FeatureList.map((props, idx) => (
+
+ MEV Blocker has been acquired.
++ Read the announcement on{' '} + + smg.org + + . +
+We are redirecting you to the new home.
++ Redirecting you in {remaining} {secondLabel}. +
+ + Go to docs.mevblocker.io now + ++ If you are not redirected{' '} + + click here + + . +
+
+ {syntheticTitle && (
+
+ {syntheticTitle}
+
+ )}
+ {!syntheticTitle && (
+ {children}
+
+ )
+}
diff --git a/src/theme/NotFound/index.tsx b/src/theme/NotFound/index.tsx
new file mode 100644
index 000000000..3b94a5600
--- /dev/null
+++ b/src/theme/NotFound/index.tsx
@@ -0,0 +1,32 @@
+import React, { useEffect } from 'react'
+import { useLocation } from '@docusaurus/router'
+import OriginalNotFound from '@theme-original/NotFound'
+
+const MEV_PREFIX = '/mevblocker/'
+const MEV_REDIRECT = '/mevblocker'
+
+const NotFound = (props: React.ComponentProps
+
+ )}
+ Redirecting...
++ This content has moved. Taking you to /mevblocker. +
+