Update streaming quote docs: only progressively better quotes are emitted#647
Update streaming quote docs: only progressively better quotes are emitted#647fleupold wants to merge 1 commit into
Conversation
cowprotocol/services#4648 changed POST /api/v1/quote/stream to only emit quotes that rank better than the best one already sent, defer individual solver errors, and rank verified quotes above unverified ones regardless of amount. Update the section added in #638 to match. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughThe API integration docs now describe progressive best-so-far quote streaming, solver verification and ranking, no-usable-quote errors, and first-quote timing based on the fastest solver. ChangesQuote stream documentation
Estimated code review effort: 2 (Simple) | ~10 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 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.
🧹 Nitpick comments (2)
docs/cow-protocol/integrate/api.mdx (2)
86-86: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win"Last event is always the best quote" doesn't hold when the stream ends in an error.
Line 86 says the terminal event can be an
errorevent with aPriceEstimationErrorbody when no usable quote exists. Line 88 then unconditionally states "the last event received when the stream closes is the best available quote." These two statements conflict for the no-usable-quote case — the last event there is an error, not a quote — and a client relying on line 88 literally could mishandle that case.✏️ Suggested wording tweak
-Because every event improves on the previous one, the last event received when the stream closes is the best available quote — clients do not need to rank events themselves. +Because every event improves on the previous one, the last *quote* event received before the stream closes is the best available quote — clients do not need to rank events themselves. If the stream closes with a terminal `error` event instead, no usable quote was found.Also applies to: 88-88
🤖 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/integrate/api.mdx` at line 86, Update the streaming behavior documentation around the terminal error description and the “last event” guidance to clarify that the final event is the best quote only when at least one usable quote was streamed; when no usable quote exists, the stream ends with the final PriceEstimationError event instead.
79-79: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winClarify "improves" means rank, not necessarily price.
Line 79 says "every update improves on the last," but line 84 then says a later (verified) event "may... report a slightly worse price than an earlier one." Without qualifying "improves" as rank (verified > unverified, not raw amount), readers may assume price is monotonically improving, which line 84 contradicts.
✏️ Suggested wording tweak
-The first event arrives as soon as the fastest solver responds, and after that a quote is only emitted when it ranks better than the best one already sent, so the client can show a price immediately and every update improves on the last. +The first event arrives as soon as the fastest solver responds, and after that a quote is only emitted when it ranks better than the best one already sent, so the client can show a price immediately and every update improves on the last by rank (verification status, then amount) — not necessarily by price.Also applies to: 84-84
🤖 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/integrate/api.mdx` at line 79, Clarify the event-update description around “every update improves on the last” to specify that improvement refers to solver ranking, not necessarily the quoted price amount. Align the wording with the later verified-event explanation in the same section, preserving the immediate first event and subsequent better-ranked update behavior.
🤖 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.
Nitpick comments:
In `@docs/cow-protocol/integrate/api.mdx`:
- Line 86: Update the streaming behavior documentation around the terminal error
description and the “last event” guidance to clarify that the final event is the
best quote only when at least one usable quote was streamed; when no usable
quote exists, the stream ends with the final PriceEstimationError event instead.
- Line 79: Clarify the event-update description around “every update improves on
the last” to specify that improvement refers to solver ranking, not necessarily
the quoted price amount. Align the wording with the later verified-event
explanation in the same section, preserving the immediate first event and
subsequent better-ranked update behavior.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 9fd2b361-c040-4e6e-8ac5-e0419688ee06
📒 Files selected for processing (1)
docs/cow-protocol/integrate/api.mdx
1 participant
Description
cowprotocol/services#4648 (merged 2026-07-27) changed the behavior of
POST /api/v1/quote/stream: instead of emitting every per-solver quote (including errors and lower-quality updates), the stream now only emits a quote when it ranks better than the best one already sent. Individual solver errors are no longer streamed — a terminalerrorevent is only sent if no solver returned a usable quote. Verified quotes rank above unverified ones regardless of the quoted amount.This updates the Streaming Quotes section introduced in #638 to match the new behavior.
Changes
priceQualityis ignored and every event carries its ownverifiedflagerrorevent carries aPriceEstimationErrorbody (e.g.NoLiquidity) and is only sent when no usable quote exists🤖 Generated with Claude Code
Summary by CodeRabbit
verifiedflag and verification priority.