feat: technical reference #28
Conversation
mfw78
added
documentation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
|
||
| :::caution | ||
|
|
||
| Be very careful when signing an intent to trade. All of the associated parameters are final and cannot be changed once the intent is signed and submitted to the API. If you make a mistake, you will need to cancel the intent and create a new one. |
There was a problem hiding this comment.
Link on cancel would be nice.
|
|
||
| ## 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': |
There was a problem hiding this comment.
Bit strange that we have a separate section for cancelling a market order but canceling a limit order is part of the limit order page.
Maybe it makes sense to document market and limit order cancelling on the same page to avoid repeating ourselves (e.g. off-chain cancellation not guaranteed and so on).
|
|
||
| ## 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. |
There was a problem hiding this comment.
nit: New docs use ie. or ie whereas existing docs use i.e..
|
|
||
| :::caution | ||
|
|
||
| Allowing interactions by solvers, creates the possibility of malicious solvers that can steal funds from the settlement contract. This is why the Protocol only allows interactions to be executed by whitelisted solvers, and requires that the solver post a bond to the Protocol before it can be whitelisted. |
There was a problem hiding this comment.
Do we have a section explaining the process, reasoning and details for solver bonds in detail that we could link here?
| | `sellToken` | `ETH` | `WETH` | | | ||
| | `buyToken` | any | same as user | | | ||
| | `receiver` | `!= address(0)` | same as user | Must **NOT** be the zero address as this has the meaning of `self` in CoW Protocol | | ||
| | `sellAmount` | any | same as user | | | ||
| | `buyAmount` | any | same as user | | | ||
| | `validTo` | any | `type(uint32).max` | Required to be fixed at the maximum point in the future as `filledAmount` in `GPv2Settlement` contract is relied upon which can be cleared by `freeFilledAmountStorage` | | ||
| | `appData` | any | same as user | | | ||
| | `feeAmount` | any | same as user | | | ||
| | `kind` | `sell` | `sell` | Limited to `sell` intents only as dust from `buy` intents left in the Eth-flow contract would not be economical for a user to withdraw | | ||
| | `partiallyFillable` | any | same as user | | | ||
| | `sellTokenBalance` | `external` | `external` | Only `external` implemented | | ||
| | `buyTokenBalance` | `external` | `external` | Only `external` implemented | |
There was a problem hiding this comment.
Note that a user intent doesn't really "exist" as described onchain, the data used onchain is (sligtly) different. We could mention somewhere how this corresponds to the actual ETH-flow data.
|
|
||
| :::note | ||
|
|
||
| Orders are not matched by the CoW Protocol infrastructure unless the `quoteId` refers to a valid and fresh quote in the API. |
| As there are many nested contracts, it's important for a callee to know some context from the caller. To achieve this, ComposableCoW passes a `bytes32` variable `ctx` to the callee, such that: | ||
|
|
||
| ``` | ||
| ctx = merkle root of orders: bytes32(0) | ||
| single order: H(ConditionalOrderParams) | ||
| ``` | ||
|
|
||
| Having this context also allows for conditional orders / merkle roots to use this as a key in a mapping, to store conditional order-specific data. |
There was a problem hiding this comment.
The execution context is zero if the order isn't a single order, right? Considering that single orders aren't recommended, I would clearly say that this is only used in this case.
| As there are many nested contracts, it's important for a callee to know some context from the caller. To achieve this, ComposableCoW passes a `bytes32` variable `ctx` to the callee, such that: | |
| ``` | |
| ctx = merkle root of orders: bytes32(0) | |
| single order: H(ConditionalOrderParams) | |
| ``` | |
| Having this context also allows for conditional orders / merkle roots to use this as a key in a mapping, to store conditional order-specific data. | |
| Single orders allow the caller to specify additional context data. | |
| As there are many nested contracts, it's important for a callee to know some context from the caller. To achieve this, ComposableCoW passes a `bytes32` variable `ctx` to the callee, such that: | |
| ``` | |
| ctx = H(ConditionalOrderParams) | |
| ``` | |
| Having this context also allows for conditional orders / merkle roots to use this as a key in a mapping, to store conditional order-specific data. | |
| When using orders based on Merkle trees instead of single orders, then there is no execution context and `ctx` is set to `bytes32(0)`. |
| ```mermaid | ||
| flowchart TD | ||
| A[Extensible Fallback Handler: SignatureVerifierMuxer] -->|isValidSafeSignature| B[Check Authorization: MerkleRoot \n Proof & ConditionalOrderParams] | ||
| B -->|valid| S[SwapGuard:verify] | ||
| S -->|invalid| I[Revert] | ||
| S -->|valid| V[IConditionalOrder:verify] | ||
| B -->|invalid| C(Check Authorization: Single Order \n ConditionalOrderParams) | ||
| C -->|valid| V | ||
| C -->|invalid| I | ||
| V -->|valid| T[Return ERC1271 Magic] | ||
| V -->|invalid| I | ||
| ``` |
There was a problem hiding this comment.
This graph seems inconsistent with the contract to me. Two things are weird:
- Single order authorization is checked only if Merkle proof verification fails. Arguably not wrong, since
size(proof) == 0can be considered part of the verification, but I think it's better if we don't see it as a failure but as an option between two choices. (Otherwise, as a developer, I worry that if my signature is an invalid Merkle proof then it might somehow be interpreted as a valid single order signature). - In the diagram,
SwapGuard:verifyis only checked if it's a valid Merkle proof, but to my understanding it's also checked for single orders.
This is what I'd have expected.
flowchart TD
A[Extensible Fallback Handler: SignatureVerifierMuxer] -->|isValidSafeSignature| B[Check Authorization]
B -->|valid single order| S[SwapGuard:verify]
B -->|valid Merkle proof| S
B -->|invalid| I[Revert]
S -->|valid| V[IConditionalOrder:verify]
S -->|invalid| I
V -->|valid| T[Return ERC1271 Magic]
V -->|invalid| I
|
|
||
| :::note | ||
|
|
||
| All values **EXCLUDING** `offchainInput` are **verified** by ComposableCoW prior to calling an order type's `verify`. |
There was a problem hiding this comment.
This is key to the composable CoW framework and I'm not sure it's stressed enough.
My understanding of this framework is that the contract stores order information onchain (be it single orders or through a Merkle root) and all these parameters are exactly what is stored onchain for verification. A developer doesn't need to bother validating this data again, and this is why you'd use this framework rather than doing everything yourself.
| All values **EXCLUDING** `offchainInput` are **verified** by ComposableCoW prior to calling an order type's `verify`. | |
| ComposableCoW is responsible for checking that all values **EXCLUDING** `offchainInput` belong to an order that was previously registered on-chain. |
However, this begs the question of how order creation/registration works, so maybe that should be handled earlier?
|
|
||
| ### Discrete order generators | ||
|
|
||
| A conditional order that generates discrete orders shall implement the `IConditionalOrderGenerator` interface. |
There was a problem hiding this comment.
Here the discrete order is the CoW Swap order that would be tradable, but when I was reading this I thought this was a way to create a valid order in composable CoW. I see, going back, that there is a distinction between that and a conditional order, but it's easier to forget, and also one expects first to create a conditional order and then to use it.
In general, it would be great in the architecture part to spell out that "discrete orders" is what will actually be executed on CoW Swap.
docs/cow-protocol/reference/contracts/periphery/composable_cow.md
Outdated
Show resolved
Hide resolved
| | `SWARM` | `3` | `abi.encode(bytes32 swarmCac)` | | ||
| | `IPFS` | `5` | `abi.encode(bytes32 ipfsCid)` | |
| ## Off-chain | ||
|
|
||
| ### Watch-tower | ||
|
|
||
| As these orders are not automatically indexed by the CoW Protocol, there needs to be some method of relaying them to the Order Book API for inclusion in a batch. | ||
|
|
||
| This is the responsibility of a [watch-tower](https://github.com/cowprotocol/watch-tower). CoW Protocol runs a watch-tower that will monitor the `ConditionalOrderCreated` event, and relay the discrete orders to the Order Book API. | ||
|
|
||
| There is also a [DAppNode package for running a watch-tower](https://github.com/cowprotocol/dappnodepackage-cow-watch-tower). |
There was a problem hiding this comment.
We already discussed the watchtower quite a bit before introducing it. Maybe we should move this to the architecture section? It's part of why we have conditional orders, so it makes sense to me, even if it isn't strictly contract-related.
Co-authored-by: Federico Giacon <[email protected]> Co-authored-by: Felix Henneke <[email protected]>
mfw78
force-pushed
the
technical-reference
branch
from
d101c48 to
927d1d7
Compare
|
New dependencies detected. Learn more about Socket for GitHub ↗︎
|
|
OK, I've addressed most of the above comments / integrated suggestions. I'm merging this, leaving the above unresolved, to come back to towards the top of the waterfall / CoW DAO-wide review of docs. |
Description
This PR contains the canonical Technical Reference for CoW Protocol.
Changes
Related Issues
Fixes #6, #8