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.

Author: tamir-cow

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`