Improve docs for solver API: limit amounts vs full amounts - #650
Improve docs for solver API: limit amounts vs full amounts#650tamir-cow wants to merge 3 commits into
Conversation
…led) amount, while fullSellAmount/fullBuyAmount are the original signed amounts that stay constant across auctions.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Review limit reached
Next review available in: 56 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughThe order schema now distinguishes remaining fee-adjusted executable amounts from original signed amounts. The example includes the full amount fields and explains partial fills and volume-based fees. ChangesOrder amount schema
Estimated code review effort: 1 (Trivial) | ~2 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/cow-protocol/reference/core/auctions/schema.md`:
- 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f1a2083d-6d59-41da-bf42-223cc1b7004e
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/schema.md
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
🗄️ 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.
…uyAmount: 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.
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/cow-protocol/reference/core/auctions/schema.md`:
- Line 123: The example explanation should not state that the user sends exactly
1000000000000000000000 COW atoms when a solver fee may apply. Update the
sell-fulfillment wording to describe the transfer as 1000 COW atoms plus any
solver-computed fee, while preserving the existing minimum USDC guarantee and
other order details.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 3c816f04-5735-4455-9471-98dedcac92a0
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/schema.md
| ``` | ||
|
|
||
| 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. 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. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Correct the example’s sell-token transfer explanation.
Line 123 states that the user sends exactly 1000000000000000000000 COW atoms, although the solver may charge a fee. For a sell fulfillment, the transfer is executedAmount + fee. State that this example transfers 1000 COW atoms plus any solver-computed fee.
Proposed wording
- 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.
+ This means that, if executed, the user will send the executed amount of 1000000000000000000000 COW atoms plus any solver-computed fee to the settlement contract. The user is guaranteed to receive at least 284138335 USDC atoms.🤖 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 123, The example
explanation should not state that the user sends exactly 1000000000000000000000
COW atoms when a solver fee may apply. Update the sell-fulfillment wording to
describe the transfer as 1000 COW atoms plus any solver-computed fee, while
preserving the existing minimum USDC guarantee and other order details.
…uyAmount: 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.
| ``` | ||
|
|
||
| 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. 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. |
There was a problem hiding this comment.
This case of buyAmount = fullBuyAmount does not happen in practice on most chains. This example should cover the usual case, I think, of a 2bps volume fee. The given signed amount of 284138335 would be consistent with a buyAmount of 284138335 / (1 - 0.0002) = 284195174.03... rounded to 284195174.
2 participants
Clarify that sellAmount/buyAmount reflect an order's remaining (unfilled) amount, while fullSellAmount/fullBuyAmount are the original signed amounts that stay constant across auctions.
Summary by CodeRabbit
fullSellAmountandfullBuyAmountfields in the order schema.