CIP: Penalty Cap Redesign

[fhenneke]

Documentation change reflecting the penalty cap redesign CIP draft: the chain-specific absolute penalty cap is replaced by a per-order penalty cap.

This PR would be merged, after filling in the CIP-XX placeholders, if the CIP were to pass.

Summary by CodeRabbit

• Documentation
  • Updated solver rewards documentation to include CIP-XX guidance.
  • Clarified performance reward caps, including chain-specific upper limits and lower limits based on unsettled orders.
  • Documented per-order penalty caps using quote value, a global 20 USD limit, fill fraction, and chain/token-pair basis points.
  • Expanded solver strategy guidance to explain how penalties are bounded.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 18, 2026 10:07am

[coderabbitai]

Important

Review available on request

• 🔍 Trigger review

Reviews should be triggered manually for repositories with fewer than 10 stars. Select Trigger review above or comment @coderabbitai review to review the latest changes. For a full review, comment @coderabbitai full review.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 044f5f82-fb06-429f-b335-314caad79dcd

📝 Walkthrough

Walkthrough

The solver rewards documentation references CIP-XX, updates chain-specific performance caps, defines lower caps from unsettled orders, and clarifies penalty guidance for late or absent settlement.

Changes

Solver rewards

Layer / File(s)	Summary
Reward caps and solver guidance docs/cow-protocol/reference/core/auctions/rewards.md	The introduction references CIP-XX. Upper caps use chain-specific β values. Lower caps use unsettled winning orders with quote-based, USD-equivalent, chain-specific, and token-pair-specific limits. Solver guidance refers to the relevant orders’ penalty caps.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• cowprotocol/docs#603: Updates the same solver-rewards documentation and related CIP-XX terminology.

Suggested reviewers: architsharma7, harisang

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main documentation change: redesigning the penalty cap.
Description check	✅ Passed	The description explains the purpose, key change, and CIP placeholder condition, although it omits the template headings and checklist.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/penalty-cap-redesign

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 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/rewards.md`:
- Line 155: Update the solver guidance paragraph to replace “revert risk” with
“settlement-failure risk,” ensuring the reported-score adjustment explicitly
covers both late and absent settlement cases represented by the penalty caps.
- Line 44: Update the user-facing definition near the upper cap c_u to replace
“onchain” with “on-chain,” leaving the rest of the sentence unchanged.
- Around line 51-55: Update the definition of c_l in the rewards documentation
to explicitly define unsettled_i as the winning auction-order pairs from solver
i’s solutions that were not fully settled. Specify that each pair contributes
its penalty cap for the unexecuted portion, including the appropriate
partial-fill accounting, rather than treating only entirely unsettled orders as
contributors.
- Around line 59-65: Update the penalty-cap definition near
\textrm{penaltyCap}_o to remove the claim that \bar{c} equals the native-token
equivalent of 20 USD. Describe \bar{c} using the chain-specific lower-cap values
and terminology established by the actual CIP or implementation contract,
without introducing a price source or rounding rule.

🪄 Autofix

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: d27cfbc0-0ab7-476c-a86a-9bed96b891f0

📥 Commits

Reviewing files that changed from the base of the PR and between b5c361d and 244e6cb.

📒 Files selected for processing (1)

• docs/cow-protocol/reference/core/auctions/rewards.md

[Architsharma7]

"$$\textrm{missingScore}_i$$ is the sum of the scores of solver $$i$$'s winning solutions that reverted.

nit: since you changed the "revert"s in the other sections to "did not settle" / "were not settled", it make sense to change it here too to maintain consistency.
Otherwise, GTG.