Update the_problem.md

[acanidio-econ]

Added an intro to explain what is the purpose of this section.

Added "cow amm orders" as order type

General rewrite

Summary by CodeRabbit

• Documentation
  • Reframed the optimization problem as a two-step routing + bidding flow and expanded the solver description.
  • Replaced "batches" with "auctions" and clarified validity, execution cadence, and horizon language.
  • Renamed order taxonomy to Sell/Buy with explicit fill‑or‑kill and partial‑fill semantics.
  • Added CoW AMM order definitions, perpetual-auction behavior, and unified their scoring with sell orders.
  • Clarified solver vs. protocol fee wording and updated feasibility, scoring, and enforcement notes.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[vercel]

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

Project	Deployment	Preview	Updated (UTC)
docs	Ready	Preview	Dec 1, 2025 9:59am

[coderabbitai]

Walkthrough

Reframes the auction problem doc: replaces “batches” with “auctions”, expands the opening to a solver-centered "What is solving?" description, broadens order taxonomy (adds CoW AMM orders, sell/buy formalism, FOK/partial semantics), and updates feasibility, scoring, and fee wording. Documentation-only edits.

Changes

Cohort / File(s)

Summary

Auction problem documentation reframe docs/cow-protocol/reference/core/auctions/the_problem.md

Rewrites introduction to "What is solving?", replaces "batches" with "auctions" throughout, renames/expands order taxonomy (Limit Sell/Buy → Sell/Buy Orders with fill-or-kill and partial semantics), introduces CoW AMM orders (acceptance sets S, surplus U, price π) and marks them as always-present, clarifies solver vs protocol (gas) fees, extends solution/feasibility language to include CoW AMM and external liquidity, renames "Social consensus rules" to "All other competition rules", and updates scoring formulas and penalties/slashing wording.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Verify consistent replacement of "batch" → "auction" and that no occurrences remain.
• Confirm CoW AMM symbols/definitions (S, U, π) are consistent and unambiguous.
• Check scoring, feasibility, and UDCP wording aligns with related docs (see possibly related PRs).

Possibly related PRs

• updating problem definition for combinatorial auctions #507 — Overlapping edits to the same auctions/problem doc (UDCP, scoring, competition rules).
• Update competition_rules.md #498 — Related updates to uniform directional clearing prices and winner-selection/scoring language.
• Update README.mdx #496 — Other documentation changes to auction mechanism and solver role descriptions.

Suggested reviewers

• harisang
• pretf00d

Poem

🐇 I nudge the doc with careful hops,
Auctions bloom where batches stopped,
AMMs whisper prices clear,
Terms aligned and rules appear,
Hooray — the meadow's tidy now! 🌿

Pre-merge checks and finishing touches

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete—it lacks a proper 'Changes' section with detailed, itemized information about what was modified and why.	Expand the description to include a detailed 'Changes' section with specific bullet points explaining each modification made to the documentation.
Title check	❓ Inconclusive	The title 'Update the_problem.md' is vague and generic—it only describes the file being edited without conveying what substantive changes were made.	Use a more descriptive title that highlights the main change, such as 'Integrate CoW AMM orders into the_problem.md' or 'Rewrite and expand optimization problem documentation'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch acanidio-econ-patch-11

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

1-109: Terminology replacement verified; fix additional typos discovered during verification.

The batch-to-auction terminology replacement is complete (no "batch" references remain). However, verification revealed several typos and grammatical errors in the document:

• Line 6: "matehmatical" → "mathematical"
• Line 6: "What is solving?" → rephrase to "What is it solving?" or "What does it solve?"
• Line 8: "specifies feasible an in and out" → "specifies feasible in and out"
• Line 28: "speficied" → "specified"
• Line 28: "tollerance" → "tolerance"

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 25e2c88 and f116ea4.

📒 Files selected for processing (1)

• docs/cow-protocol/reference/core/auctions/the_problem.md (5 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/cow-protocol/reference/core/auctions/the_problem.md

[grammar] ~6-~6: Ensure spelling is correct
Context: ...r_position: 1 --- # What is solving? A matehmatical, high-level description At a high leve...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~28-~28: Ensure spelling is correct
Context: ...g to settle for. The limit price can be speficied explicitly (as in the case of limit ord...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[grammar] ~28-~28: Ensure spelling is correct
Context: ...from an underlying quote and a slippage tollerance parameter (as in the case of market ord...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

---

[style] ~83-~83: You’ve already used the word ‘also’ once in your sentence, so using it again may be redundant.
Context: ... :::note Solvers are also expected to also charge a fee to cover the costs of executing a...

(REDUNDANT_FILLER)

🪛 markdownlint-cli2 (0.18.1)

docs/cow-protocol/reference/core/auctions/the_problem.md

10-10: Link text should be descriptive

(MD059, descriptive-link-text)

🔇 Additional comments (3)

docs/cow-protocol/reference/core/auctions/the_problem.md (3)

46-60: Buy Orders section looks good.

The content is clearly written, mathematically precise, and consistent with the sell orders section. The updated terminology and structural clarity improve readability.

---

62-74: New CoW AMM orders section is well-integrated.

The section provides clear technical definitions, uses consistent notation with sell orders, and effectively explains the key distinction (perpetual validity). The constant-product AMM formula is correctly presented.

---

89-106: Solution section updates are well-structured and clear.

The section effectively expands the definition to include CoW AMM orders and external liquidity sources, clarifies the feasibility criteria, updates the competition rules reference, and correctly adjusts the scoring formula. The distinction that π is applied only to buy orders (while CoW AMM orders are scored like sell orders) is well-explained.

[fhenneke]

Just left a few nitpicks.

Generally reads a lot better than before. Adding CoW AMMs explicitly is also a good idea.

[fhenneke]

This renders a bit strange as surplus_function. Maybe "... we define the surplus function ..."?

[acanidio-econ]

I don't know if you can have a general definition of surplus function that could apply to any order (basket order or whatever). I guess beside saying that it should be increasing in the buy amounts and decreasing in the sell amounts, I don't know if you can say more in general. Of course, once you have a specific order type, you can specify the surplus function for that order type

[fhenneke]

I was trying to refer to the formatting of ... we define _surplus_function_ $$U_S:S\rightarrow \mathbb R$$, .... I see how in general surplus is not easy to define. One could leave out _surplus_function_ or change it to ... the utility function ....

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

6-6: Fix spelling error in heading (unresolved from prior review).

"Matehmatical" should be "mathematical."

-# What is solving? A matehmatical, high-level description
+# What is solving? A mathematical, high-level description

🧹 Nitpick comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

22-22: Clarify surplus function phrasing.

The phrasing "surplus_function" renders awkwardly. Consider: "Also, to each order $$S$$ we define the surplus function $$U_S:S\rightarrow \mathbb R$$" for better clarity and consistency.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f116ea4 and d4a3946.

📒 Files selected for processing (1)

• docs/cow-protocol/reference/core/auctions/the_problem.md (5 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/cow-protocol/reference/core/auctions/the_problem.md

[grammar] ~6-~6: Ensure spelling is correct
Context: ...r_position: 1 --- # What is solving? A matehmatical, high-level description At a high leve...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (4)

docs/cow-protocol/reference/core/auctions/the_problem.md (4)

26-44: Sell and Buy Orders sections well refactored.

The updated language for fill-or-kill and partially fillable orders is clearer, and the shift from "batches" to "auctions" is consistent. The sections now better explain order validity across multiple auctions.

Also applies to: 46-60

---

62-74: CoW AMM orders section is well-structured.

The new section clearly defines acceptance sets, surplus functions, and the price interpretation. The note about perpetual validity (line 74) aligns with the protocol design and addresses prior feedback. Mathematical notation is consistent with the Sell/Buy order definitions.

---

89-106: Solution, feasibility, and scoring definitions well-integrated.

The updates seamlessly incorporate CoW AMM orders into the solution framework. The shift from "Social consensus rules" to "All other competition rules" is clearer, and the caution note now explicitly mentions penalizing/slashing. The scoring definition correctly treats CoW AMM orders like sell orders (consistent with their matching acceptance set and surplus function).

Please verify that treating CoW AMM orders identically to sell orders for scoring purposes (line 104) is intentional and aligns with the protocol's intended incentive structure, especially given fhenneke's earlier note that CoW AMM orders can act as both buy and sell orders depending on solver strategy.

---

8-10: Opening description and link improvements effective.

The expanded description at line 8 now clearly explains the solver's role and the two-step optimization process. The descriptive link at line 10 improves accessibility and readability compared to bare "[here]" text.

[coderabbitai]

Actionable comments posted: 0

♻️ Duplicate comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

6-6: Fix spelling error in heading.

"Matehmatical" should be "mathematical."

-# What is solving? A matehmatical, high-level description
+# What is solving? A mathematical, high-level description

🧹 Nitpick comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

22-22: Improve readability of "surplus function" phrasing.

Using italics for the compound term _surplus_function_ renders awkwardly. Consider rephrasing to improve clarity:

-Also, to each order $$S$$ we define _surplus_function_ $$U_S:S\rightarrow \mathbb R$$
+Also, to each order $$S$$ we define the surplus function $$U_S:S\rightarrow \mathbb R$$

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d4a3946 and b3e3ea7.

📒 Files selected for processing (1)

• docs/cow-protocol/reference/core/auctions/the_problem.md (5 hunks)

🧰 Additional context used

🪛 LanguageTool

docs/cow-protocol/reference/core/auctions/the_problem.md

[grammar] ~6-~6: Ensure spelling is correct
Context: ...r_position: 1 --- # What is solving? A matehmatical, high-level description At a high leve...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🔇 Additional comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

62-74: CoW AMM orders section introduces order type correctly and consistently.

The new CoW AMM orders definition maintains consistency with sell order treatment (acceptance sets, surplus function formalization) while clearly delineating the key distinction—perpetual validity across auctions. The mathematical formalization and real-world example (constant product pool pricing) are clear.

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

docs/cow-protocol/reference/core/auctions/the_problem.md (1)

89-89: Clarify the syntax and grammar of the solution definition.

The sentence structure is ambiguous: "suppose there are $$I$$ users and CoW AMM orders and J external liquidity sources" does not specify a count for CoW AMM orders and lacks parallel structure with the other quantities.

To improve clarity, consider:

-Formally, suppose there are $$I$$ users and CoW AMM orders and _J_ external liquidity sources.
+Formally, suppose there are $$I$$ users, $$C$$ CoW AMM pools, and _J_ external liquidity sources.

This makes the structure parallel (each entity type has an associated count variable) and matches the subsequent list of trades {o_1, o_2, ...o_I, l_1, l_2, ..., l_J}.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b3e3ea7 and 508830b.

📒 Files selected for processing (1)

• docs/cow-protocol/reference/core/auctions/the_problem.md (5 hunks)

🔇 Additional comments (6)

docs/cow-protocol/reference/core/auctions/the_problem.md (6)

6-8: Excellent reframing of the solving problem.

The new opener clearly defines a solver's role and inputs (orders, liquidity state, protocol rules) and outputs (solutions with feasible amounts). The two-step optimization framing (routing then bidding) provides good high-level structure.

---

26-44: Strong improvements to sell order presentation.

The rewrite clarifies fill-or-kill vs. partial-fillable semantics with explicit formal definitions and adds helpful detail about multi-auction validity. The surplus function definition is mathematically sound.

---

46-60: Buy orders section is now parallel and complete.

The renaming from "Limit Buy Orders" to "Buy Orders" is consistent with sell orders, and the formal definitions for both fill-or-kill and partial-fillable variants mirror the sell order treatment. The note about multi-auction execution adds consistency.

---

62-75: New CoW AMM orders section is well-structured and informative.

The section properly introduces CoW AMM orders with:

• Clear acceptance set and surplus function (paralleling sell orders)
• Concrete price formula for constant-product pools
• Important clarification that CoW AMM orders persist across auctions

The technical definitions align with the broader framework established for user orders.

Please confirm with the protocol team that the acceptance set and surplus function definitions for CoW AMM orders (lines 66–68) and the price interpretation (lines 70–72) reflect the intended semantics and are consistent with the current implementation.

---

87-100: Solution and competition rules sections modernized.

The solution definition now correctly includes CoW AMM orders. The renaming of "Social consensus rules" to "All other competition rules" (line 93) is more neutral and better descriptive. The feasibility constraint wording is simplified.

One minor note: line 89's grammatical structure could be tightened (see earlier comment on line 89).

---

102-107: Scoring formula correctly extended to CoW AMM orders.

The inclusion of CoW AMM orders in the sell-side scoring formula (line 104) is consistent with their earlier definition as having the same surplus and fee structure. The note clarifying fee denomination (line 107) is helpful context.