Update rewards.md #560
Update rewards.md #560
Conversation
rewrite of the "buffer accounting" and "Solver's strategy"
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughUpdated the auctions rewards doc: added CIP‑36, tightened wording that on‑chain execution must match submitted solution, replaced "Additional solver costs (slippage)" with "Buffer accounting" (buffers, net slippage, weekly netting), clarified negative payments/caps, and made terminology/formatting edits. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Possibly related PRs
Suggested reviewers
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning, 1 inconclusive)
✅ Passed checks (1 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: 2
🧹 Nitpick comments (3)
docs/cow-protocol/reference/core/auctions/rewards.md (3)
21-21: Minor hyphenation correction needed.The rewritten phrasing is clearer and more precise. However, the compound adjective should be hyphenated: "a solution as executed-on-chain must equal the solution as submitted at the bidding stage."
-From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. +From the protocol's perspective, a solution as executed-on-chain must equal the solution as submitted at the bidding stage.
67-67: Optional: Tighten wordy phrase.The phrase "With respect to optimal bidding" could be shortened to "For optimal bidding strategy" or simply "Regarding optimal bidding" for more concise phrasing, though the current wording is acceptable for formal documentation.
70-70: Improve link text and intensifier wording.Two optional improvements:
Descriptive link text: Replace "here" with a descriptive phrase like "discussion on combinatorial auctions and reward dynamics" for better accessibility and clarity.
Replace weak intensifier: "very large" is overused; consider alternatives like "substantial," "significant," or "considerable" for stronger language.
Apply this optional diff:
-then the winning solver wins more when it underreports its score. The filtering step of the fair combinatorial auction also makes this problem more complex, because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion). +then the winning solver wins more when it underreports its score. The filtering step of the fair combinatorial auction also makes this problem more complex, because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [discussion on combinatorial auctions and reward dynamics](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877)).For the "very large" phrase, consider:
-if the difference between the best and second-best solution is very large, then the winning solver wins more when it underreports its score. +if the difference between the best and second-best solution is substantial, then the winning solver wins more when it underreports its score.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
-
docs/cow-protocol/reference/core/auctions/rewards.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~52-~52: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[grammar] ~58-~58: Ensure spelling is correct
Context: ...possible that the state of the external liquidiy sources used as part of a solution chan...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~58-~58: Ensure spelling is correct
Context: ...ase of negative slippage the solver can utliize the buffers available in the settlement...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~60-~60: Ensure spelling is correct
Context: ...icit element of the mechanism, they are nonethless relevant in determining the solver's op...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~66-~66: Ensure spelling is correct
Context: ...ettling a solution on the chain and the revery risk. With respect to optimal bidding,...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[style] ~67-~67: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revery risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~70-~70: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
70-70: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (7)
docs/cow-protocol/reference/core/auctions/rewards.md (7)
7-7: Improved clarity and comprehensive CIP coverage.The rewritten introduction explicitly states the subsidy mechanism and provides clear, organized references to all relevant CIPs for both solver competition and price estimation rewards. The inclusion of CIP-36 in both contexts is appropriate given its relevance to both reward types.
35-35: Cleaner phrasing.The simplified phrasing "required to pay the protocol" is more direct and readable than the original. No technical content change.
43-43: Correct formatting inconsistency.The addition of the equals sign in the Avalanche specification brings it into alignment with other chain specifications (Ethereum, Arbitrum, Base, Polygon, Lens, BNB). This formatting correction ensures consistent mathematical notation throughout the document.
48-48: Valuable edge case clarification.The addition explicitly explains the single-solver case by introducing the empty solution concept, which improves technical clarity without changing the mechanism. This helps readers understand why
$$\textrm{referenceScore}_i = 0$$ in this scenario.
52-52: Clear cost specification.The rewritten phrase explicitly clarifies that solver costs extend beyond gas to include transaction execution costs more broadly. This improves technical precision. The static analysis tool flags "at a disadvantage" as potentially wordy, but the phrasing is acceptable in this context for clarity.
74-74: Accurate CIP coverage in section header.Adding CIP-36 to the price estimation section header correctly reflects that this CIP covers both solver competition and price estimation rewards, maintaining consistency with the introduction.
76-84: Improved price estimation competition explanation.The rewritten section provides clearer context on what the price estimation competition entails, explicitly detailing:
- Single-order batch auction structure with trivial limit price
- Clear optimization objectives for sell/buy requests
- Well-organized four conditions for quote rewards with proper CIP attribution
The restructured explanation is more pedagogically effective than the original.
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
docs/cow-protocol/reference/core/auctions/rewards.md (3)
21-21: Add hyphen to compound adjective "on-chain".Line 21 reads "executed on chain" but should use "executed on-chain" when functioning as a compound adjective modifying the noun phrase. This improves readability and consistency with standard technical documentation style.
Apply this diff:
-From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. +From the protocol's perspective, a solution as executed on-chain must equal the solution as submitted at the bidding stage.
67-67: Consider wordiness improvements in optimal bidding discussion.Static analysis flags two opportunities to tighten phrasing in this section:
- Line 67: "With respect to optimal bidding" is slightly wordy. Consider: "For optimal bidding" or "Regarding optimal bidding" for a more direct opening.
- Line 70: "very large" uses an overused intensifier. Consider: "substantially larger" or simply "large" depending on intended emphasis.
These are minor stylistic refinements that could improve readability without changing technical content.
Also applies to: 70-70
70-70: Make link text more descriptive for accessibility.Line 70 contains a link with text "[here]" which is non-descriptive. Per markdown best practices and accessibility guidelines, link text should convey its purpose.
Apply this diff to improve link clarity:
-see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion +see [this discussion on combinatorial auction edge cases](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for more context
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/rewards.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~52-~52: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[style] ~67-~67: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revert risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~70-~70: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
70-70: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (3)
docs/cow-protocol/reference/core/auctions/rewards.md (3)
56-60: Confirm past spelling corrections in buffer accounting section.Past review comments flagged three spelling errors in this newly rewritten section (lines 58-60). Verification confirms all corrections are in place:
- "liquidiy" → "liquidity" ✓
- "utliize" → "utilize" ✓
- "nonethless" → "nonetheless" ✓
The rewritten Buffer accounting section is now substantively sound and free of the flagged orthographic errors.
66-66: Confirm revert risk spelling correction in Solver's strategy section.Past review flagged a spelling error "revery risk" on this line. Verification confirms the correction is in place: "revert risk" ✓.
The section is now free of this critical spelling error.
74-95: Price estimation section rewrite is clear and accurate.The updated section properly reflects the expanded CIP references (CIPs 27, 36, 57, 72) and the four reward conditions are clearly presented. Reward amounts by chain are correctly formatted and aligned with the updated header. No issues identified in this section.
fhenneke
left a comment
fhenneke
left a comment
There was a problem hiding this comment.
I just added minor comments. Otherwise looks good to me.
| The presence of the cap on rewards $$c_u$$, however, makes the problem more complex as it introduces a "first-price auction" logic: if the difference between the best and second-best solution is very large, then the winning solver wins more when it underreports its score. However, determining the optimal amount of underreporting is very complex and requires each solver to make strong assumptions regarding the performance of competing solvers. There are also some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion). | ||
| The presence of the cap on rewards $$c_u$$, however, makes the problem more complex as it introduces a "first-price auction" logic: if the difference between the best and second-best solution is very large, then the winning solver wins more when it underreports its score. The filtering step of the fair combinatorial auction also makes this problem more complex, because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion). However, determining the optimal amount of underreporting is very complex and requires each solver to make strong assumptions regarding the performance of competing solvers. | ||
|
|
||
| To summarize, truthfully revealing the (cost-adjusted) score that a solver can generate for each submitted solution is optimal if the cap is not binding, and misreporting does not affect $$\textrm{referenceScore}_i$$. It is not necessarily optimal in uncompetitive auctions when the difference between the best and second-best solution may be large, and in some edge cases in which a solver may benefit from making the filtering step less stringent. However, in these cases, deriving the optimal strategy is a very complex problem. We conclude by noting that most CoW Protocol batches are very competitive - the cap on rewards is binding only in about 9% of auctions - and that a solver benefits by making the filtering steps less stringent for its opponents only in sporadic cases. |
There was a problem hiding this comment.
Leaving the fraction of capped auctions in the docs is a bit risky as it can change at any time. I would either add a date ("(as of November 2025)") or remove the concrete number.
There was a problem hiding this comment.
Good point, I changed the text
Co-authored-by: Felix Henneke <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
docs/cow-protocol/reference/core/auctions/rewards.md (1)
70-70: Use descriptive link text instead of generic "[here]".Line 70 contains a link with generic text
[here](https://forum.cow.fi/...). Provide more descriptive link text that indicates what the reader will find, such as[discussion of combinatorial auctions and edge cases](...).Apply this diff:
-see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion +see the [discussion of combinatorial auctions and edge cases](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/rewards.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~52-~52: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[style] ~67-~67: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revert risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~70-~70: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
70-70: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (3)
docs/cow-protocol/reference/core/auctions/rewards.md (3)
72-72: Add temporal context to the concrete percentage or reconsider inclusion.Line 72 references "about 9% of auctions" where the cap is binding, but lacks a date to indicate when this measurement was taken. Since market conditions and auction patterns change, this statistic could become stale. Per previous feedback, you should either add a date qualifier (e.g., "as of November 2025") or remove the concrete number entirely to avoid the documentation becoming misleading.
Was the decision to keep the 9% figure without a date intentional, or should this be updated per the prior reviewer's suggestion?
64-64: Verify terminology: is "routing" appropriately used for batched solutions?Line 64 uses "routing" broadly when discussing both single-group and multi-group (batched) solutions. Earlier reviewer feedback questioned whether "routing" is the right term for batches. Confirm whether this terminology is intentional or if "ordering strategy" or another term would be more precise.
Is the use of "routing" for batched solutions the intended terminology, or should this be reconsidered?
56-60: Buffer accounting section is well-clarified; verify intent on CIP-17 reference.The rewritten "Buffer accounting" section successfully clarifies the mechanisms and terminology around buffers and slippage. Spelling corrections (liquidity, utilize, nonetheless) are in place.
However, earlier feedback suggested reconsidering the CIP-17 reference, noting that multiple CIPs address buffer accounting. Was the decision to retain the CIP-17 reference intentional, or should the reference list be expanded or generalized?
Co-authored-by: Felix Henneke <[email protected]>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (5)
docs/cow-protocol/reference/core/auctions/rewards.md (5)
21-21: Hyphenate "on-chain" as a compound adjective.Line 21 uses "on chain" but this should be "on-chain" when functioning as a compound adjective.
-From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. +From the protocol's perspective, a solution as executed on-chain must equal the solution as submitted at the bidding stage.
72-72: Add date context to concrete metric "9%".Line 72 includes a concrete percentage ("9% of auctions") without temporal context, which risks becoming stale documentation. Per previous feedback, either anchor this to a date ("as of November 2025") or replace with a more general statement.
-...and that a solver benefits by making the filtering steps less stringent for its opponents only in sporadic cases. +...and that a solver benefits by making the filtering steps less stringent for its opponents only in sporadic cases (as of November 2025, the cap is binding in approximately 9% of auctions).
67-67: Simplify opening phrase for clarity.Line 67 opens with "With respect to optimal bidding," which is wordy. Consider "Regarding optimal bidding" or simply "For optimal bidding" for better conciseness.
-With respect to optimal bidding, note that the protocol rewards allow a solver to participate in an auction without misreporting... +For optimal bidding, note that the protocol rewards allow a solver to participate in an auction without misreporting...
52-52: Consider tightening "at a disadvantage" for conciseness.Line 52 uses "at a disadvantage," which is somewhat wordy. Alternatives like "disadvantaged," "outcompeted," or "loses competitiveness" could be more direct.
-Of course, a solver who adjusts their score downward too aggressively is then at a disadvantage in the auction. +Of course, a solver who adjusts their score downward too aggressively is then disadvantaged in the auction.
70-70: Replace weak intensifier "very" with stronger adjective.Line 70 uses "very large" to describe the difference between solutions. Consider a more specific or emphatic descriptor like "substantial," "dramatic," or "disproportionate" for stronger impact.
-...if the difference between the best and second-best solution is very large, then the winning solver wins more when it underreports its score. +...if the difference between the best and second-best solution is substantial, then the winning solver wins more when it underreports its score.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/rewards.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~52-~52: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[style] ~67-~67: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revert risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~70-~70: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
70-70: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (1)
docs/cow-protocol/reference/core/auctions/rewards.md (1)
56-72: Appreciate the buffer accounting rewrite and solver strategy clarification.The expanded buffer accounting section (lines 56–60) effectively communicates the mechanics of slippage and weekly net settlements, providing crucial context for solver strategy. The reworded solver strategy section clearly delineates the routing approach, batching logic, and incentives around truthful bidding. The addition of revert risk to scoring considerations (line 66) properly reflects solver obligations. The past spelling and terminology errors have been corrected.
added "at the time of writing (Nov 2025)" when mentioning that only 9% of auctions are capped
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/cow-protocol/reference/core/auctions/rewards.md (1)
70-70: Replace non-descriptive link text "[here]" with meaningful anchor text and avoid "very large" intensifier.The link text "[here]" fails accessibility guidelines (MD059). Additionally, "very large" is an overused intensifier. Revise both issues:
-The presence of the cap on rewards $$c_u$$, however, makes the problem more complex as it introduces a "first-price auction" logic: if the difference between the best and second-best solution is very large, then the winning solver wins more when it underreports its score. The filtering step of the fair combinatorial auction also makes this problem more complex, because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion). +The presence of the cap on rewards $$c_u$$, however, makes the problem more complex as it introduces a "first-price auction" logic: if the difference between the best and second-best solution is substantial, then the winning solver wins more when it underreports its score. The filtering step of the fair combinatorial auction also makes this problem more complex, because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see the [forum discussion on combinatorial auctions and rewards](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for details).
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
-
docs/cow-protocol/reference/core/auctions/rewards.md(3 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~52-~52: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[style] ~67-~67: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revert risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~70-~70: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
70-70: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (6)
docs/cow-protocol/reference/core/auctions/rewards.md (6)
56-61: Buffer accounting section successfully clarifies slippage and weekly netting mechanisms.The new section provides valuable clarity on how negative and positive slippage are handled, the role of buffers, and the weekly net settlement process. Spelling and grammar are correct throughout. The reference to the accounting section for more details works well, and the removal of the CIP-17 reference streamlines the text as suggested in prior feedback.
43-43: Avalanche cap definition now includes upper limit.The Avalanche chain cap definition now correctly specifies both
$$c_l = 0.3 ;\textrm{AVAX}$$ and$$c_u = 0.4 ;\textrm{AVAX}$$ , matching the format of other chain specifications. This aligns the documentation with the implementation.
48-48: Single solver edge case rewording addresses prior feedback.The new phrasing "If only one solver submits solutions,
$$\textrm{referenceScore}_i$$ is, by definition, zero" directly states the outcome rather than referencing an exceptional case, which improves clarity. This resolves the prior reviewer concern about explaining edge cases circularly.
72-72: Date-qualified cap binding percentage mitigates documentation staleness risk.The new summary statement "the cap on rewards is binding only in about 9% of auctions" is now qualified with "(as of November 2025)" timing context, which addresses prior concern about hardcoding a potentially volatile metric. This is a pragmatic improvement that allows the metric to be revisited later if needed.
64-66: Solver strategy section successfully broadens discussion to include batched solutions and fair sharing.The revised solver strategy explanation now clearly articulates the multi-step routing approach (single pair groups → best routing → batched solutions), and explicitly references fair sharing principles. The text on gas costs and revert risk is correctly phrased, and the overall narrative flow is improved. The "revert risk" terminology is correct.
7-7: CIP-36 additions to reward specification sections strengthen cross-referencing.The addition of CIP-36 to both the general solver competition rewards paragraph (line 7) and the price estimation competition header (line 74) provides more comprehensive CIP coverage. These additions are substantively correct and improve navigability.
Also applies to: 78-78
| :::note | ||
|
|
||
| From the protocol's perspective, a solution executed on chain must equal the solver's initial commitment. | ||
| From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. |
There was a problem hiding this comment.
Fix hyphenation: "on chain" should be "on-chain".
When used as an adjective phrase modifying a noun, "on-chain" should be hyphenated. LanguageTool flagged this style requirement.
Apply this diff:
-From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage.
+From the protocol's perspective, a solution as executed on-chain must equal the solution as submitted at the bidding stage.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. | |
| From the protocol's perspective, a solution as executed on-chain must equal the solution as submitted at the bidding stage. |
🧰 Tools
🪛 LanguageTool
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In docs/cow-protocol/reference/core/auctions/rewards.md around line 21, the
phrase "on chain" should be hyphenated when used as an adjective; change "as
executed on chain" to "as executed on-chain" so the sentence reads: "From the
protocol's perspective, a solution as executed on-chain must equal the solution
as submitted at the bidding stage." Ensure only that hyphenation is updated and
no other text is altered.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (2)
docs/cow-protocol/reference/core/auctions/rewards.md (2)
21-21: ** Fix hyphenation: "on-chain" when used as adjective modifier.**This issue was previously flagged but remains unfixed. When "on-chain" is used as an adjective (modifying "as executed"), it requires a hyphen per English grammar conventions.
Apply this diff:
-From the protocol's perspective, a solution as executed on chain must equal the solution as submitted at the bidding stage. +From the protocol's perspective, a solution as executed on-chain must equal the solution as submitted at the bidding stage.
71-71: ** Replace non-descriptive link text "[here]" with meaningful anchor.**This issue was previously flagged (marked as addressed in commits 7408f18 to e1d31c9) but the non-descriptive link text remains. MD059 requires descriptive link text for accessibility and SEO.
Apply this diff:
-...because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see [here](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for a discussion). However... +...because there are some edge cases in which by reducing the score of a solution, solver $i$ can benefit by making the filtering steps less stringent for its opponents (see the [forum discussion on combinatorial auctions and rewards](https://forum.cow.fi/t/combinatorial-auctions-from-theory-to-practice-via-some-more-theory-about-rewards/2877) for details). However...
🧹 Nitpick comments (1)
docs/cow-protocol/reference/core/auctions/rewards.md (1)
53-53: Consider tightening wordiness in three locations (optional style improvement).LanguageTool flagged three optional wordiness improvements that could enhance clarity:
- Line 53: "at a disadvantage" could be tightened to "disadvantaged" or similar
- Line 68: "With respect to optimal bidding" could be shortened to "Regarding optimal bidding" or "For optimal bidding"
- Line 71: "very large" uses the overused intensifier "very"; consider "substantial" or "large" alone
These are optional style refinements; the current phrasing is clear and acceptable.
Also applies to: 68-68, 71-71
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/cow-protocol/reference/core/auctions/rewards.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/cow-protocol/reference/core/auctions/rewards.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...s perspective, a solution as executed on chain must equal the solution as submitt...
(QB_NEW_EN_HYPHEN)
[style] ~53-~53: ‘at a disadvantage’ might be wordy. Consider a shorter alternative.
Context: ...score downward too aggressively is then at a disadvantage in the auction. The mechanism, therefor...
(EN_WORDINESS_PREMIUM_AT_A_DISADVANTAGE)
[style] ~68-~68: ‘With respect to’ might be wordy. Consider a shorter alternative.
Context: ...tion on the chain and the revert risk. With respect to optimal bidding, note that the protocol...
(EN_WORDINESS_PREMIUM_WITH_RESPECT_TO)
[style] ~71-~71: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...en the best and second-best solution is very large, then the winning solver wins more when...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.18.1)
docs/cow-protocol/reference/core/auctions/rewards.md
71-71: Link text should be descriptive
(MD059, descriptive-link-text)
🔇 Additional comments (3)
docs/cow-protocol/reference/core/auctions/rewards.md (3)
57-62: ✅ Buffer accounting section is well-structured and addresses prior feedback.The rewritten section effectively explains slippage mechanics and buffer usage without the overly specific CIP-17 reference. Spelling and terminology are accurate.
75-96: ✅ Price estimation competition section is well-updated with expanded conditions and CIP-36 integration.The updated header correctly includes CIP-36 alongside other CIPs, and the conditions for quote rewards (lines 79-85) are clearer. Reward values and chain listings appear accurate.
49-49: ✅ New edge case explanations improve document completeness.Line 49 clarifies the single-solver case for referenceScore, and the note at line 53 effectively explains the cost-adjustment mechanism. Both additions enhance reader understanding of solver incentives.
Also applies to: 53-53
rewrite of the "buffer accounting" and "Solver's strategy" (plus a bunch of small things)
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.