feat: technical reference (#28)

# Description
This PR contains the canonical Technical Reference for CoW Protocol.

# Changes

- [x] Implemented core / periphery methodology 
- [x] Migrated previous documentation, and had proof-read
- [x] All contracts extensively documented
- [x] Typedoc generation for SDKs
- [x] Interactive swagger use for APIs

## Related Issues

Fixes #6, #8

---------

Co-authored-by: Federico Giacon <[email protected]>
Co-authored-by: Felix Henneke <[email protected]>

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "external/cow-sdk"]
 	path = external/cow-sdk
 	url = https://github.com/cowprotocol/cow-sdk
+[submodule "external/app-data"]
+	path = external/app-data
+	url = https://github.com/cowprotocol/app-data

docs/README.mdx

@@ -0,0 +1 @@
+# CoW DAO

docs/cow-protocol/README.mdx

@@ -1 +1,11 @@
-# CoW Protocol (Batch Auctions)
+# CoW Protocol (Batch Auctions)
+
+CoW Protocol matches users' intents via batch auctions from a variety of on-chain liquidity sources.
+
+When matching intents, CoW Protocol first seeks a _Coincidence of Wants_ (CoW) within the existing batch to offer an even better price than any pool/market maker can. If no CoW is found, CoW Protocol then seeks the best price for a trade from available on-chain liquidity.
+
+On-chain liquidity sources include: 
+- AMMs (e.g. Uniswap, Sushiswap, Balancer, Curve, etc.)
+- DEX Aggregators (e.g. 1inch, Paraswap, Matcha, etc.)
+
+Therefore, CoW Protocol is essentially an aggregator of aggregators.

docs/cow-protocol/analyze/README.mdx

@@ -1 +1,5 @@
+---
+draft: true
+---
+
 # Analyzing auctions

docs/cow-protocol/analyze/dune.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 1
+draft: true
 ---
 
 # Dune Analytics

docs/cow-protocol/arbitrate/README.mdx

@@ -1 +1,5 @@
+---
+draft: true
+---
+
 # Arbitrating auctions

docs/cow-protocol/arbitrate/autopilot.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 2
+draft: true
 ---
 
 # Autopilot

docs/cow-protocol/arbitrate/driver.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 1
+draft: true
 ---
 
 # Driver

docs/cow-protocol/create/README.mdx

@@ -1,5 +1,7 @@
----
-pagination_label: "Creating orders"
----
+# Creating orders
 
-# Overview
+CoW Protocol is designed to be user interface agnostic. A user may create an intent from:
+
+- Official web applications (e.g. [CoW Swap](./create/cowswap-ui))
+- 3rd party integrations (e.g. [Balancer](https://app.balancer.fi))
+- Custom integrations (e.g. scripts, bots, etc)

docs/cow-protocol/create/cowswap-ui/README.mdx

@@ -1,3 +1,24 @@
 # CoW Swap
 
-## Liquidity Integrated
+[CoW Swap](https://swap.cow.fi) 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.
+
+![CoW Swap website](/img/cowswap/overview.png)
+
+## Supported Wallets
+
+CoW Swap supports many popular wallets including:
+
+- [Rabby](https://rabby.io) / [MetaMask](https://metamask.io) 
+- [Safe](https://safe.global) (as a Safe app)
+- [WalletConnect v2](https://walletconnect.com)
+- [Coinbase Wallet](https://wallet.coinbase.com)
+- [Trezor](https://trezor.io)
+- [Ledger](https://www.ledger.com)
+- [Ambire](https://ambire.com)
+- [Alpha](https://alphawallet.com)
+- [Trust Wallet](https://trustwallet.com)
+- [Keystone](https://keyst.one)
+
+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 Protocol directly into your wallet interface.

docs/cow-protocol/create/cowswap-ui/cancel.mdx

@@ -0,0 +1,36 @@
+---
+sidebar_position: 3
+---
+
+import CancellationOffChainOnChain from '../../../partials/_cancellation_offchain_versus_onchain.mdx'
+
+# Cancel
+
+:::note
+
+Before we begin, please note that our solvers can be quite quick, so it is entirely possible that your order will have already been filled before it can be invalidated.
+
+:::
+
+As CoW Protocol runs an off-chain order book, it is possible to cancel an intent before it is matched. This is done by signing an off-chain cancellation message and submitting it to the [OrderBook API](../../reference/apis/orderbook).
+
+## Finding pending intents
+
+![Finding pending intents](/img/cowswap/cancel_pending.png)
+
+![Cancelling an intent](/img/cowswap/cancel_intent.png)
+
+## Off-chain vs on-chain cancellation
+
+Off-chain cancellations are *optimistic* in that it signals to the order book that you no longer wish to trade. This is useful as it doesn't involve any on-chain transactions and is therefore free. Provided that the intent has not been settled on chain, it will be removed from the order book and will not be matched.
+
+<CancellationOffChainOnChain
+    alt="Cancel off-chain"
+    src="/img/cowswap/cancel_offchain.png"
+/>
+
+![Cancel on-chain](/img/cowswap/cancel_onchain.png)
+
+After you have selected "on-chain", click "Request cancellation" to submit the transaction. You will be prompted to sign the transaction with your wallet.
+
+![Sign on-chain cancellation](/img/cowswap/cancel_onchain_signing.png)

docs/cow-protocol/create/cowswap-ui/limit.mdx

@@ -0,0 +1,60 @@
+---
+sidebar_position: 5
+---
+
+import CancellationOffChainOnChain from '../../../partials/_cancellation_offchain_versus_onchain.mdx'
+
+# Limit orders
+
+CoW Protocol supports limit orders, where users are able to buy or sell tokens at a specified price or better.
+
+A buy limit order allows a trader to specify the maximum price they are willing to pay for a token, while a sell limit order allows a trader to specify the minimum price they are willing to sell a token for.
+
+CoW Swap provides an intuitive interface in which one may place their limit orders.
+
+## Place a limit order
+
+Let's assume the example that we want to sell our `COW` that we purchased previously. We can set the limit price at which we want to sell, and the duration over which the limit order is valid:
+
+![Limit orders](/img/cowswap/limit_place_order.png)
+
+:::caution
+
+Fees for limit orders are taken from the surplus CoW Protocol generates for your order - that is, by executing your order at a better price than your limit price. CoW Protocol is capable of finding much better prices than are otherwise available due to its unique batch auction mechanism; in situations where it can't find a better price, it will wait until the market price is sufficient to cover both your limit price and the network fees. This means that your order may not execute exactly when the market price hits your limit price.
+
+:::
+
+At this point, CoW Swap will prompt you to review your limit order:
+
+![Review limit order](/img/cowswap/limit_review_order.png)
+
+:::tip
+
+By default, CoW Swap sets your limit order to _partially fillable_. This allows your order to fill gradually as liquidity comes available. Partially fillable orders usually complete faster than _fill or kill_ orders and also provide better prices, so they are the default mechanism used to execute limit orders. You can turn off partially fillable limit orders and revert back to _fill or kill_ through the swap panel settings.
+
+:::
+
+Once the limit order has been reviewed, click 'Place limit order' to proceed with intent signing:
+
+![Sign intent](/img/cowswap/limit_sign.png)
+
+Upon signing the intent with your wallet, the limit order will now appear in open orders:
+
+![View orders](/img/cowswap/limit_view_orders.png)
+
+## Cancel a limit order
+
+Now we've been doing some thinking and realised we shouldn't be selling `COW`, so we want to cancel our limit order. We can do this by clicking the context menu on the order and selecting 'Cancel order':
+
+![Cancel context menu](/img/cowswap/limit_cancel_context.png)
+
+After selecting 'Cancel order`, you will be prompted to confirm this action. Cancelling orders requires signing an off-chain message that is submitted to the order-book (or alternatively this may be done using an on-chain transaction).
+
+<CancellationOffChainOnChain
+    alt="Cancel confirm"
+    src="/img/cowswap/limit_cancel_confirm.png"
+/>
+
+Once the order has been cancelled, it will be removed from the open orders list:
+
+![Cancel confirmed](/img/cowswap/limit_cancel_confirmed.png)

docs/cow-protocol/create/cowswap-ui/native.mdx

@@ -0,0 +1,48 @@
+---
+sidebar_position: 4
+---
+
+import EthFlowTip from '../../../partials/_eth_flow.mdx'
+
+# Native tokens
+
+CoW Protocol is only capable of handling ERC20 tokens. There are two ways in which to execute a swap from native tokens CoW Protocol:
+
+1. Wrap the native token into an ERC20 token (eg. `ETH` to `WETH`) and then swap it on CoW Protocol; or
+2. Use the [Eth-flow](/docs/cow-protocol/reference/contracts/periphery/eth-flow) contract to place an order on your behalf.
+
+## Wrap native tokens
+
+If a user elects to wrap their native tokens to trade, they must follow three steps:
+
+1. Wrap the native token into it's wrapped ERC20 counterpart (on-chain transaction)
+2. Approve the wrapped token to be spent by the CoW Protocol (on-chain transaction)
+3. Swap the wrapped token on CoW Protocol to the desired token (off-chain signed intent)
+
+The CoW Swap UI has built-in support for wrapping native tokens. Simply select the native token you want to wrap and it's wrapped ERC20 counterpart (e.g. `ETH` and `WETH`).
+
+![Wrapping Native tokens](/img/cowswap/native_wrap.png)
+
+## Eth-flow
+
+In an attempt to smooth the user experience, CoW Protocol has introduced the [Eth-flow](/docs/cow-protocol/reference/contracts/periphery/eth-flow) contract. This allows users to automate the [above process](#wrap-native-tokens), all in one **on-chain** transaction.
+
+Using Eth-flow is transparent to the user in CoW Swap, simply select the native token you want to swap and the desired token. CoW Swap will automatically detect if the native token needs to be wrapped and will execute the Eth-flow contract on your behalf.
+
+![Swap Native tokens](/img/cowswap/native_swap.png)
+
+:::tip
+
+CoW Swap will prompt you with the option to wrap your ETH and use the classic WETH experience ([as detailed above](#wrap-native-tokens)).
+
+:::
+
+After selecting your tokens, CoW Swap will prompt you to confirm the swap. This will be a single on-chain transaction that will wrap your native tokens (if required) and place the swap intent on CoW Protocol.
+
+![Confirm Native tokens](/img/cowswap/native_confirm.png)
+
+<EthFlowTip />
+
+Once you have confirmed the swap, your wallet will prompt you to the on-chain transaction interacting with Eth-flow. On completion of this transaction, your swap intent will be placed on CoW Protocol:
+
+![Eth-flow Transaction](/img/cowswap/native_tx.png)

docs/cow-protocol/create/cowswap-ui/swap.mdx

@@ -0,0 +1,57 @@
+---
+sidebar_position: 2
+---
+
+import TokenApprovalWarning from '../../../partials/_token_approvals.mdx'
+import ReceiverAndIntentWarning from '../../../partials/_receiver.mdx'
+
+# Swap
+
+Swapping is the bread and butter of CoW Protocol! Let's swap some tokens!
+
+## Select tokens
+
+Consider an example swapping 0.05 `WETH` for `COW`.
+
+![GPv2VaultRelayer approval required](/img/cowswap/swap_need_approval.png)
+
+Oh, it looks like we need to approve the [`GPv2VaultRelayer`](/docs/cow-protocol/reference/contracts/core#gpv2vaultrelayer) to spend our `WETH`! This is because the [`GPv2VaultRelayer`](/docs/cow-protocol/reference/contracts/core#gpv2vaultrelayer) is the one that will pull the `WETH` from our wallet and send it to the [settlement](/docs/cow-protocol/reference/contracts/core#gpv2settlement) contract that will co-ordinate the swap on our behalf.
+
+## Approve sell token
+
+:::tip
+
+Some tokens, such as `USDC`, `DAI`, and `COW` support permit-style approvals. This means that you can approve the [`GPv2VaultRelayer`](/docs/cow-protocol/reference/contracts/core#gpv2vaultrelayer) to spend your tokens without having any initial gas for an on-chain transaction. This is a great way to save on gas costs!
+
+You don't have to worry about this, as CoW Swap will automatically detect if the token supports permit-style approvals and will guide you through the process.
+
+:::
+
+![GPv2VaultRelayer default approval](/img/cowswap/swap_approval_default.png)
+
+By default, CoW Swap prompt you to approve [`GPv2VaultRelayer`](/docs/cow-protocol/reference/contracts/core#gpv2vaultrelayer) an "unlimited" allowance for the sell token. This has the benefits of:
+
+- Not having to approve multiple times
+- Save on gas costs
+
+<TokenApprovalWarning token="WETH" spender="GPv2VaultRelayer" />
+
+Once the `approve` transaction is confirmed, you can proceed to swap!
+
+![GPv2VaultRelayer approved](/img/cowswap/swap_approved.png)
+
+## Confirm swap
+
+When you're ready to swap, click the "Swap" button. You will be prompted with a confirmation dialog to confirm the swap. This is where you can review the details of the swap (ie. the quote, the slippage tolerance, etc.). If you're happy with the details, click "Confirm Swap". You will be prompted to sign the intent to swap.
+
+<ReceiverAndIntentWarning />
+
+![Confirm Swap](/img/cowswap/swap_confirm.png)
+
+At this stage, your wallet will prompt you to sign the intent to swap. The user interface for this will vary depending on your wallet. You 
+
+![Signing Swap](/img/cowswap/swap_signing.png)
+
+Once the intent has been signed, it will be submitted to CoW Protocol. You are able to [view your order](/docs/cow-protocol/view) on [CoW Explorer](https://explorer.cow.fi).
+
+![Swap confirmed](/img/cowswap/swap_confirmed.png)

docs/cow-protocol/create/cowswap-ui/twap.md

@@ -1,5 +1,6 @@
 ---
 sidebar_position: 6
+draft: true
 ---
 
 # TWAP orders

docs/cow-protocol/create/custom-integration/README.mdx

@@ -1,3 +1,7 @@
+---
+draft: true
+---
+
 # Custom integrations
 
 ## Protocol

docs/cow-protocol/create/custom-integration/composable-cow.md

@@ -1,5 +1,24 @@
 ---
 sidebar_position: 2
+draft: true
 ---
 
 # ComposableCoW
+
+## Use cases
+
+Currently a _smart contract_ interacting with CoW is required to either:
+
+1. Call `GPv2Settlement.setPreSignature(orderUid)` (API signing type "pre-sign"); or
+2. Implement `isValidSignature(bytes32,bytes)` (API signing type "eip1271"), where the `bytes32` parameter passed is the EIP-712 digest of the `GPv2Order.Data`.
+
+Presently orders have been spawning new contracts on chain, necessitating the handling of basic `retrieve` / `cancel` functionality to recover assets. `Safe` already provides a best-in-class for this purpose, so let's not reinvent the wheel! 🛞
+
+Use cases that this revised architecture seeks to enable include:
+
+* Automatically swap token ABC for XYZ above a defined threshold balance of ABC.
+* Good after time (`GAT`) orders (discrete orders, conditional on a starting time).
+* TWAP by breaking orders into `n x GAT` orders.
+* Private conditional orders (trailing stop loss)
+* Wait4CoW orders (only matching an order with other CoW traders)
+* Doing all the above simultaneously (`n x conditional orders`)