Skip to content

Improve docs for solver API: limit amounts vs full amounts #650

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Open
tamir-cow wants to merge 5 commits into
base: main
Choose a base branch
from
+8 −4
Open

Improve docs for solver API: limit amounts vs full amounts #650

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
11cf6ff
Clarify that sellAmount/buyAmount reflect an order's remaining (unfil…
tamir-cow Aug 3, 2026
46f7e31
Clarify why sellAmount/buyAmount can differ from fullSellAmount/fullB…
tamir-cow Aug 4, 2026
c7c9b27
Clarify why sellAmount/buyAmount can differ from fullSellAmount/fullB…
tamir-cow Aug 4, 2026
3cb6f4d
Updated example and its explanation
tamir-cow Aug 10, 2026
c1a13f5
Applied cr notes
tamir-cow Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/cow-protocol/reference/core/auctions/schema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,8 +76,10 @@ This key maps to a list containing the set of orders in the batch. Each entry in
- `uid`: this is the unique identifier of the order.
- `sellToken`: a string denoting the address of the sell token.
- `buyToken`: a string denoting the address of the buy token.
- `sellAmount`: a stringified integer denoting the limit amount that is being sold, measured in terms of the smallest denomination of the sell token.
- `buyAmount`: a stringified integer denoting the limit amount that is being bought. Similar to the `sellAmount`, it is measured in terms of the smallest denomination of the buy token.
- `sellAmount`: a stringified integer denoting the limit amount that is being sold, measured in terms of the smallest denomination of the sell token. For a partially fillable order that has already been filled in a previous auction, this is the *remaining* amount that is still available to be matched (i.e., it already accounts for the `executed` amount), and is the value solvers should use when computing a solution.
Comment thread
fhenneke marked this conversation as resolved.
Outdated
- `buyAmount`: a stringified integer denoting the limit amount that is being bought. Similar to the `sellAmount`, it is measured in terms of the smallest denomination of the buy token, and for a partially filled order it likewise reflects only the remaining, unexecuted portion.
- `fullSellAmount`: a stringified integer denoting the *original*, full limit sell amount of the order as signed by the user, measured in terms of the smallest denomination of the sell token. Unlike `sellAmount`, this value is not reduced to account for any amount that has already been executed in a previous auction, so it stays constant across auctions for the same order.
- `fullBuyAmount`: a stringified integer denoting the *original*, full limit buy amount of the order as signed by the user, measured in terms of the smallest denomination of the buy token. Unlike `buyAmount`, this value is not reduced to account for any amount that has already been executed in a previous auction, so it stays constant across auctions for the same order.
- `created`: creation time of the order, denominated in epoch seconds.
- `validTo`: integer indicating the time until which the order is valid.
- `kind`: a string of the set {"sell", "buy"}, describing whether the order is a `sell` or `buy` order.
Expand Down Expand Up @@ -107,14 +109,16 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether
"buyToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"sellAmount": "1000000000000000000000",
"buyAmount": "284138335",
"fullSellAmount": "1000000000000000000000",
"fullBuyAmount": "284138335",
"feeAmount": "0",
"kind": "sell",
"partiallyFillable": false,
"class": "limit"
}
```

The above entry should be interpreted as follows. It is a Fill-or-Kill order since the flag `partiallyFillable` is set to `false`. Moreover, it is a sell order since its `kind` is set to `sell`. Finally, this is a `limit` order, meaning that it has a zero-signed fee, which implies that the solver is free to choose an appropriate fee to cover its execution cost. This means that, if executed, the user will send a total of 1000000000000000000000 COW atoms to the settlement contract and, no matter how much fee the solver will charge, the user is guaranteed to receive at least 284138335 USDC atoms.
The above entry should be interpreted as follows. It is a Fill-or-Kill order since the flag `partiallyFillable` is set to `false`. Moreover, it is a sell order since its `kind` is set to `sell`. Finally, this is a `limit` order, meaning that it has a zero-signed fee, which implies that the solver is free to choose an appropriate fee to cover its execution cost. This means that, if executed, the user will send a total of 1000000000000000000000 COW atoms to the settlement contract and, no matter how much fee the solver will charge, the user is guaranteed to receive at least 284138335 USDC atoms. Since this order has not been partially filled yet, `sellAmount`/`buyAmount` and `fullSellAmount`/`fullBuyAmount` coincide here; for a partially fillable order that already has a non-zero `executed` amount from a previous auction, `sellAmount` and `buyAmount` would instead reflect only the remaining, unfilled portion, while `fullSellAmount` and `fullBuyAmount` would still refer to the order's original amounts.

@coderabbitai coderabbitai Bot Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Correct the fee explanation for limit sell orders.

For a kind: "sell" limit order, the user transfers executedAmount + fee in the sell token. The current text says the user transfers exactly 1000000000000000000000 COW atoms, even though it also says the solver can charge a fee. State that the example executes 1000 COW atoms and that any solver-computed fee is added to the transfer.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/cow-protocol/reference/core/auctions/schema.md` at line 121, Update the
limit sell order explanation in the entry beginning “The above entry should be
interpreted as follows” to state that the example executes 1000 COW atoms and
the user transfers that executed amount plus any solver-computed fee in COW.
Remove the claim that the total transfer is exactly 1000000000000000000000 COW
atoms, while preserving the guaranteed USDC amount and surrounding order
semantics.



### `deadline`
Expand Down
Loading