doc: fix formatting of 'unfair' in auction documentation 💅

[glokos]

Summary by CodeRabbit

• Documentation
  • Clarified auction logic: explains removal of unfair batched bids before selecting the bid mix that maximizes total value within computational limits.
  • Standardized introductory wording about how intents are collected and auctions are executed for improved readability.

[vercel]

@glokos is attempting to deploy a commit to the cow Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Walkthrough

Updated a single documentation page to reword the auction flow: it now states that unfair batched bids are removed first (those worse than a regular single bid), then a bid mix is selected to maximize total value within computational limits; also made minor wording adjustments to the introductory paragraph.

Changes

Cohort / File(s)	Change Summary
Documentation — fair combinatorial auction docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md	Rewrote auction logic description to state that unfair batched bids are first removed, then a bid mix is selected to maximize total value within computational limits; minor introductory wording edits.

Sequence Diagram(s)

sequenceDiagram
    participant Client as Intent Collector
    participant Doc as Auction Docs (flow)
    participant Filter as Unfair-Bid Filter
    participant Solver as Solver / Search
    participant Output as Winning Mix

    Note over Client,Doc: intents collected and auction described
    Client->>Doc: submit intents
    Doc->>Filter: evaluate batched bids
    alt Batched bid worse than single
        Filter->>Filter: mark as unfair (remove)
    else Batched bid acceptable
        Filter->>Solver: pass to solver
    end
    Filter->>Solver: pass remaining bids
    Solver->>Solver: search/select bid mix (maximize total value within limits)
    Solver->>Output: produce winning mix
    Note over Output: results returned/presented

Loading

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Single documentation file changed; no code, API, or behavioral changes.
• Review focus: confirm wording accurately reflects intended auction flow.

Possibly related PRs

• Update README.mdx #496 — Related documentation update clarifying fairness filtering and solver/output selection in the fair combinatorial auction.
• Update competition_rules.md #498 — Another related doc change describing removal of unfair batched bids and selection of winning bid mixes.

Suggested reviewers

• pretf00d
• harisang

Poem

I nibbled words and hopped about,
Removed the clutter, cleared the rout,
First toss the unfair bids away,
Then pick the mix to win the day —
A rabbit’s note on auction play! 🐰✨

Pre-merge checks and finishing touches

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title claims to fix formatting of 'unfair' but the summary shows substantive content changes to auction logic description, not just formatting fixes.	Update the title to accurately reflect the main changes: rewording of auction logic description and introductory paragraph structure, not just formatting fixes.
Description check	⚠️ Warning	The pull request description is completely empty, missing all required template sections including Description, Changes, and related issues.	Add a complete pull request description following the template, explaining why the changes are needed and listing the detailed changes made.

✅ 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

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 170d286 and affe53c.

📒 Files selected for processing (1)

• docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/cow-protocol/concepts/introduction/fair-combinatorial-auction.md

---

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.}

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[glokos]

I have read the CLA Document and I hereby sign the CLA

[pretf00d]

suggested an improvement

[fhenneke]

Could you have a look, @acanidio-econ? With this PR, we move away from using technical terms.

• "filters" -> "removes"
• "non-batched bid" -> "regular, single bid"
• "combination of bids" -> "mix of bids"

But maybe it is not so bad in this first paragraph on fair combinatorial auctions.

[acanidio-econ]

"non-batched bid" -> "regular, single bid"
this change is problematic because each solver can submit multiple bids, where a bid specifies an execution for one or multiple orders. So a "single bid" is not necessary a bid on a single order

[fhenneke]

Would this work?

Suggested change

	The protocol removes any "unfair" batched bids - ones that would give an order a worse outcome than a regular, single bid. Then, from the remaining options, it picks the mix of bids that gives traders the most total value possible, while staying within the system's computational limits.
	The protocol removes any "unfair" batched bids - ones that would give an order a worse outcome than some reference bid. Then, from the remaining options, it picks the mix of bids that gives traders the most total value possible, while staying within the system's computational limits.

@acanidio-econ

[acanidio-econ]

the previous paragraph talks about "bid on individual orders" (which is not 100% correct but I guess it is fine here). So how about: "The protocol removes any "unfair" batched bids - ones that would give an order a worse outcome than an available bid on only that order"

[acanidio-econ]

"The protocol removes any "unfair" batched bids - ones that would give an order a worse outcome than a reference bid. In most cases, the reference bid for an order is simply the best available bid containing only that order (for the general case, see [with the correct reference to the more technical explanation]"