From 11cf6ff21a66bc09ea7edeaf9fcb53face1ffc0a Mon Sep 17 00:00:00 2001 From: tamir Date: Mon, 3 Aug 2026 09:57:32 +0300 Subject: [PATCH 1/5] Clarify that sellAmount/buyAmount reflect an order's remaining (unfilled) amount, while fullSellAmount/fullBuyAmount are the original signed amounts that stay constant across auctions. --- docs/cow-protocol/reference/core/auctions/schema.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/cow-protocol/reference/core/auctions/schema.md b/docs/cow-protocol/reference/core/auctions/schema.md index 104ca6729..fd5323b72 100644 --- a/docs/cow-protocol/reference/core/auctions/schema.md +++ b/docs/cow-protocol/reference/core/auctions/schema.md @@ -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. +- `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. @@ -107,6 +109,8 @@ 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, @@ -114,7 +118,7 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether } ``` -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. ### `deadline` From 46f7e31a69c5cefd19e469ceee91ef1e693d9572 Mon Sep 17 00:00:00 2001 From: tamir Date: Tue, 4 Aug 2026 09:07:51 +0300 Subject: [PATCH 2/5] Clarify why sellAmount/buyAmount can differ from fullSellAmount/fullBuyAmount: partial fills reduce them to the remaining unfilled amount, and volume-based protocol/partner fees additionally scale them so solvers can route on sellAmount/buyAmount while ignoring fees, and the driver can charge those fees afterwards without violating the user's original signed limit. --- docs/cow-protocol/reference/core/auctions/schema.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/cow-protocol/reference/core/auctions/schema.md b/docs/cow-protocol/reference/core/auctions/schema.md index fd5323b72..05024a097 100644 --- a/docs/cow-protocol/reference/core/auctions/schema.md +++ b/docs/cow-protocol/reference/core/auctions/schema.md @@ -76,10 +76,12 @@ 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. 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. -- `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. +- `sellAmount`: a stringified integer denoting the sell amount that solvers should use when computing a solution, measured in terms of the smallest denomination of the sell token. This can differ from `fullSellAmount` (the order's original, signed sell amount) for two reasons: + 1. For a partially fillable order that has already been (partly) filled in a previous auction, `sellAmount` is reduced to the *remaining*, unfilled amount, i.e., it already accounts for the `executed` amount. + 2. For essentially every order, `sellAmount` is additionally scaled down to account for any volume-based protocol/partner fee (see `protocolFees`) that will be charged on top of the solution. It is chosen such that, once the driver charges that fee, the amount ultimately taken from the user still respects the order's original limit, `fullSellAmount`. This lets solvers compute solutions using `sellAmount` directly and ignore fees entirely, while the driver applies protocol/partner fees afterwards without violating the user's signed limit price. +- `buyAmount`: analogous to `sellAmount`, but for the buy side: a stringified integer, measured in terms of the smallest denomination of the buy token, that reflects both the remaining unfilled amount (for partially filled orders) and any volume-fee adjustment relative to `fullBuyAmount`. +- `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 never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged. +- `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 never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged. - `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. @@ -118,7 +120,7 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether } ``` -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. +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. In this particular example `sellAmount`/`buyAmount` coincide with `fullSellAmount`/`fullBuyAmount` because the order has not been partially filled and has no `protocolFees` applied. In general, the two pairs will differ: `sellAmount`/`buyAmount` shrink further whenever an order is partially filled across auctions, and are also scaled relative to `fullSellAmount`/`fullBuyAmount` whenever a volume-based protocol/partner fee applies (which is the case for nearly all orders), so that the driver can charge that fee on top of a solver's solution without ever exceeding the user's originally signed limit. ### `deadline` From c7c9b2722400e256a23624f324805f0813208ffe Mon Sep 17 00:00:00 2001 From: tamir Date: Tue, 4 Aug 2026 09:10:59 +0300 Subject: [PATCH 3/5] Clarify why sellAmount/buyAmount can differ from fullSellAmount/fullBuyAmount: partial fills reduce them to the remaining unfilled amount, and volume-based protocol/partner fees additionally scale them so solvers can route on sellAmount/buyAmount while ignoring fees, and the driver can charge those fees afterwards without violating the user's original signed limit. --- docs/cow-protocol/reference/core/auctions/schema.md | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/docs/cow-protocol/reference/core/auctions/schema.md b/docs/cow-protocol/reference/core/auctions/schema.md index 05024a097..094d4ae6c 100644 --- a/docs/cow-protocol/reference/core/auctions/schema.md +++ b/docs/cow-protocol/reference/core/auctions/schema.md @@ -76,12 +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 sell amount that solvers should use when computing a solution, measured in terms of the smallest denomination of the sell token. This can differ from `fullSellAmount` (the order's original, signed sell amount) for two reasons: - 1. For a partially fillable order that has already been (partly) filled in a previous auction, `sellAmount` is reduced to the *remaining*, unfilled amount, i.e., it already accounts for the `executed` amount. - 2. For essentially every order, `sellAmount` is additionally scaled down to account for any volume-based protocol/partner fee (see `protocolFees`) that will be charged on top of the solution. It is chosen such that, once the driver charges that fee, the amount ultimately taken from the user still respects the order's original limit, `fullSellAmount`. This lets solvers compute solutions using `sellAmount` directly and ignore fees entirely, while the driver applies protocol/partner fees afterwards without violating the user's signed limit price. -- `buyAmount`: analogous to `sellAmount`, but for the buy side: a stringified integer, measured in terms of the smallest denomination of the buy token, that reflects both the remaining unfilled amount (for partially filled orders) and any volume-fee adjustment relative to `fullBuyAmount`. -- `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 never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged. -- `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 never reduced for a previously executed amount nor adjusted for volume fees, so it stays constant across auctions for the same order and represents the limit that the driver must not violate once fees are charged. +- `sellAmount`: a stringified integer denoting the sell amount solvers should use when computing a solution, measured in terms of the smallest denomination of the sell token. It can be smaller than `fullSellAmount` for two reasons: it's reduced by any amount already executed on a partially fillable order, and it's scaled down to net out any volume-based protocol/partner fee, so solvers can use it directly without worrying about fees. +- `buyAmount`: the buy-side counterpart to `sellAmount`, measured in terms of the smallest denomination of the buy token. It can be smaller than `fullBuyAmount` for the same two reasons. +- `fullSellAmount`: a stringified integer denoting the order's original sell amount as signed by the user, measured in terms of the smallest denomination of the sell token. It stays constant across auctions and is the limit the driver must not violate once fees are charged. +- `fullBuyAmount`: a stringified integer denoting the order's original buy amount as signed by the user, measured in terms of the smallest denomination of the buy token. It stays constant across auctions and is the limit the driver must not violate once fees are charged. - `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. @@ -120,7 +118,7 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether } ``` -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. In this particular example `sellAmount`/`buyAmount` coincide with `fullSellAmount`/`fullBuyAmount` because the order has not been partially filled and has no `protocolFees` applied. In general, the two pairs will differ: `sellAmount`/`buyAmount` shrink further whenever an order is partially filled across auctions, and are also scaled relative to `fullSellAmount`/`fullBuyAmount` whenever a volume-based protocol/partner fee applies (which is the case for nearly all orders), so that the driver can charge that fee on top of a solver's solution without ever exceeding the user's originally signed 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. Here, `sellAmount`/`buyAmount` equal `fullSellAmount`/`fullBuyAmount` because the order has not been partially filled and has no `protocolFees` applied. In general they can differ: partial fills reduce `sellAmount`/`buyAmount` to the remaining unfilled amount, and volume-based fees scale them down further, so the driver can charge those fees afterwards without violating the user's original limit. ### `deadline` From 3cb6f4d76d4d688dfb6296f633b40f9dee753983 Mon Sep 17 00:00:00 2001 From: tamir Date: Mon, 10 Aug 2026 09:50:51 +0300 Subject: [PATCH 4/5] Updated example and its explanation --- docs/cow-protocol/reference/core/auctions/schema.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/cow-protocol/reference/core/auctions/schema.md b/docs/cow-protocol/reference/core/auctions/schema.md index 094d4ae6c..944a76c92 100644 --- a/docs/cow-protocol/reference/core/auctions/schema.md +++ b/docs/cow-protocol/reference/core/auctions/schema.md @@ -108,17 +108,23 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether "sellToken": "0xdef1ca1fb7fbcdc777520aa7f396b4e015f497ab", "buyToken": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", "sellAmount": "1000000000000000000000", - "buyAmount": "284138335", + "buyAmount": "284195174", "fullSellAmount": "1000000000000000000000", "fullBuyAmount": "284138335", "feeAmount": "0", "kind": "sell", "partiallyFillable": false, - "class": "limit" + "class": "limit", + "protocolFees": [ + { + "kind": "volume", + "factor": 0.0002 + } + ] } ``` -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. Here, `sellAmount`/`buyAmount` equal `fullSellAmount`/`fullBuyAmount` because the order has not been partially filled and has no `protocolFees` applied. In general they can differ: partial fills reduce `sellAmount`/`buyAmount` to the remaining unfilled amount, and volume-based fees scale them down further, so the driver can charge those fees afterwards without violating the user's original 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 the user has signed for a minimum of 284138335 USDC atoms (`fullBuyAmount`). The order also carries a `protocolFees` entry for a 2 bps volume fee, which the driver will deduct from the buy side once the trade settles. Since the order has not been partially filled, `sellAmount` still equals `fullSellAmount`, but `buyAmount` is scaled up from `fullBuyAmount` to net out that fee: `buyAmount` = `fullBuyAmount` / (1 - 0.0002) = 284138335 / 0.9998 ≈ 284195174.03, rounded down to 284195174. Solvers can then route on `sellAmount`/`buyAmount` while ignoring fees entirely, and once the driver charges its 2 bps cut of the 284195174 USDC bought (≈56839 USDC atoms), the user is left with exactly the signed minimum of 284138335 USDC atoms — so the original limit is never violated. This is the usual case in practice: on most chains essentially every order carries some volume-based protocol or partner fee, so `buyAmount`/`sellAmount` differ from `fullBuyAmount`/`fullSellAmount` even without any partial fill; the two only coincide when there is no such fee, which is rare. ### `deadline` From c1a13f518a32a97f3b0f6d5f2d1acd0ec159c91b Mon Sep 17 00:00:00 2001 From: tamir Date: Mon, 10 Aug 2026 18:54:15 +0300 Subject: [PATCH 5/5] Applied cr notes --- docs/cow-protocol/reference/core/auctions/schema.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/cow-protocol/reference/core/auctions/schema.md b/docs/cow-protocol/reference/core/auctions/schema.md index 944a76c92..17db1e356 100644 --- a/docs/cow-protocol/reference/core/auctions/schema.md +++ b/docs/cow-protocol/reference/core/auctions/schema.md @@ -114,17 +114,11 @@ An example Fill-or-Kill user limit buy order that sells 1000 [COW](https://ether "feeAmount": "0", "kind": "sell", "partiallyFillable": false, - "class": "limit", - "protocolFees": [ - { - "kind": "volume", - "factor": 0.0002 - } - ] + "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 the user has signed for a minimum of 284138335 USDC atoms (`fullBuyAmount`). The order also carries a `protocolFees` entry for a 2 bps volume fee, which the driver will deduct from the buy side once the trade settles. Since the order has not been partially filled, `sellAmount` still equals `fullSellAmount`, but `buyAmount` is scaled up from `fullBuyAmount` to net out that fee: `buyAmount` = `fullBuyAmount` / (1 - 0.0002) = 284138335 / 0.9998 ≈ 284195174.03, rounded down to 284195174. Solvers can then route on `sellAmount`/`buyAmount` while ignoring fees entirely, and once the driver charges its 2 bps cut of the 284195174 USDC bought (≈56839 USDC atoms), the user is left with exactly the signed minimum of 284138335 USDC atoms — so the original limit is never violated. This is the usual case in practice: on most chains essentially every order carries some volume-based protocol or partner fee, so `buyAmount`/`sellAmount` differ from `fullBuyAmount`/`fullSellAmount` even without any partial fill; the two only coincide when there is no such fee, which is rare. +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 the user has signed for a minimum of 284138335 USDC atoms (`fullBuyAmount`). The order also carries a 2 bps volume fee, which the driver will deduct from the buy side once the trade settles. Since the order has not been partially filled, `sellAmount` still equals `fullSellAmount`, but `buyAmount` is scaled up from `fullBuyAmount` to net out that fee: `buyAmount` = `fullBuyAmount` / (1 - 0.0002) = 284138335 / 0.9998 ≈ 284195174.03, rounded down to 284195174. Solvers can then route on `sellAmount`/`buyAmount` while ignoring fees entirely, and once the driver charges its 2 bps cut of the 284195174 USDC bought (≈56839 USDC atoms), the user is left with exactly the signed minimum of 284138335 USDC atoms — so the original limit is never violated. This is the usual case in practice: on most chains essentially every order carries some volume-based protocol or partner fee, so `buyAmount`/`sellAmount` differ from `fullBuyAmount`/`fullSellAmount` even without any partial fill; the two only coincide when there is no such fee, which is rare. ### `deadline`