Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughA new documentation file explaining how intents are formed in CoW Protocol, covering the three-stage flow (Intention → Quote → Intent), intention payload fields, quote response interpretation, amount-stage vocabulary, fee breakdown, and the mapping between quote values and signed order amounts. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
🧹 Nitpick comments (1)
docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md (1)
125-125: Two unresolved TODO comments for SDK links.Both
[//]: # (TODO: add a link to SDK)comments at lines 125 and 166 are placeholder reminders. The caution at the top of the document already references the CoW SDK — consider linking to../../reference/sdks/cow-sdk(or the relevant SDK documentation section) in both flow diagrams before this document is published.Would you like me to draft the link text for both TODO locations?
Also applies to: 166-166
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` at line 125, Replace the two placeholder comment lines `[//]: # (TODO: add a link to SDK)` with a Markdown link pointing to the CoW SDK docs (use the relative path ../../reference/sdks/cow-sdk) in both locations referenced in the diff so the flow diagrams link to the SDK; update the link text to something clear like "CoW SDK" and ensure both TODO occurrences are replaced consistently (the two comment locations in this file).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md`:
- Around line 275-289: The formulas use percent variables (partnerFeePercent,
slippagePercent) while the TS examples use basis points (partnerFeeBps,
slippageBps), causing inconsistent units; update the markdown so units are
consistent by either (A) changing the formulas to use bps (e.g., partnerFeeBps /
10000, slippageBps / 10000) or (B) adding a single inline clarifying sentence
near partnerFeeAmount and slippageAmount stating the equivalence
(partnerFeePercent / 100 = partnerFeeBps / 10000 and slippagePercent / 100 =
slippageBps / 10000) and reference afterPartnerFees to show slippage applies to
that amount—pick one approach and apply it to both Partner Fee and Slippage
sections for consistency.
- Around line 16-20: The intro claims "three stages" and shows "Intention →
Quote → Intent" but the document contains four numbered sections ("Intention",
"Quote", "Amount Stages", "Fees & Slippage"); fix by either changing the intro
to say "four stages" and updating the diagram to include "Amount Stages" and
"Fees & Slippage", or keep the diagram as-is and move "Amount Stages" and "Fees
& Slippage" to be subsections under the "Intent" section (remove their top-level
numbering) so the count and headers match; update the heading texts "Amount
Stages" and "Fees & Slippage" accordingly to reflect the chosen approach.
- Around line 18-20: Several fenced code blocks in the document are missing
language identifiers; update each unlabelled triple-backtick block to include an
appropriate language hint (e.g., add text for diagrams like the block containing
"Intention → Quote → Intent", add http for the POST example "POST
https://api.cow.fi/mainnet/api/v1/quote", and add text or math for formula-like
snippets such as "beforeAllFees.sellAmount = quote.sellAmount +
quote.feeAmount"); apply the same change to all other unlabelled fenced blocks
in the file so every ```...``` has a language tag.
- Around line 55-59: Replace the ungrammatical note text "More details see in
[Order Book API](../../reference/apis/orderbook.mdx)" with a corrected phrase
such as "See the Order Book API for more details" (keeping the existing link
target); update the sentence in the note block so it reads clearly and includes
proper punctuation.
- Around line 243-247: Remove the stray trailing backslash on the
beforeAllFees.buyAmount assignment so the line correctly assigns quote.buyAmount
(matching the pattern used for beforeAllFees.sellAmount); update the assignment
expression for beforeAllFees.buyAmount to be a normal equals assignment
referencing quote.buyAmount to fix the syntax error.
- Around line 257-267: The formulas for protocolFeeAmount use protocolFeeBps
raw; convert it to a decimal rate first (e.g., protocolFeeRate = protocolFeeBps
/ 10000) and then apply that rate in the formulas: for sell orders compute
protocolFeeAmount = quote.buyAmount × protocolFeeRate / (1 − protocolFeeRate)
and for buy orders compute protocolFeeAmount = (quote.sellAmount +
quote.feeAmount) × protocolFeeRate / (1 + protocolFeeRate); update any
occurrences of protocolFeeBps in the doc to reference protocolFeeRate (or
explicitly show division by 10000) so the examples and formulas use the
normalized basis-point value.
---
Nitpick comments:
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md`:
- Line 125: Replace the two placeholder comment lines `[//]: # (TODO: add a link
to SDK)` with a Markdown link pointing to the CoW SDK docs (use the relative
path ../../reference/sdks/cow-sdk) in both locations referenced in the diff so
the flow diagrams link to the SDK; update the link text to something clear like
"CoW SDK" and ensure both TODO occurrences are replaced consistently (the two
comment locations in this file).
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (4)
static/img/concepts/intents/buy-order-quote.pngis excluded by!**/*.pngstatic/img/concepts/intents/quote-amounts-buy.pngis excluded by!**/*.pngstatic/img/concepts/intents/quote-amounts-sell.pngis excluded by!**/*.pngstatic/img/concepts/intents/sell-order-quote.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md
Comment on lines
+16
to
+20
| Forming an intent follows three stages: | ||
|
|
||
| ``` | ||
| Intention → Quote → Intent | ||
| ``` |
Contributor
There was a problem hiding this comment.
Stage count inconsistency between intro and section headers.
Line 16 states "three stages" and the diagram shows Intention → Quote → Intent, but the document has four numbered sections (1. Intention, 2. Quote, 3. Amount Stages, 4. Fees & Slippage). Either update the intro to reflect four stages, or re-label/un-number sections 3 and 4 as subsections of intent formation so they don't look like top-level stages.
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` around
lines 16 - 20, The intro claims "three stages" and shows "Intention → Quote →
Intent" but the document contains four numbered sections ("Intention", "Quote",
"Amount Stages", "Fees & Slippage"); fix by either changing the intro to say
"four stages" and updating the diagram to include "Amount Stages" and "Fees &
Slippage", or keep the diagram as-is and move "Amount Stages" and "Fees &
Slippage" to be subsections under the "Intent" section (remove their top-level
numbering) so the count and headers match; update the heading texts "Amount
Stages" and "Fees & Slippage" accordingly to reflect the chosen approach.
Comment on lines
+18
to
+20
| ``` | ||
| Intention → Quote → Intent | ||
| ``` |
Contributor
There was a problem hiding this comment.
MD040: All plain fenced code blocks are missing a language identifier.
markdownlint-cli2 flags all of these. Add an appropriate language hint (e.g. text for diagrams/formulas, http for the URL block, math where LaTeX-style notation is used).
✏️ Proposed fixes (representative examples)
-```
+```text
Intention → Quote → Intent
```diff
-```
+```http
POST https://api.cow.fi/mainnet/api/v1/quote
```diff
-```
+```text
beforeAllFees.sellAmount = quote.sellAmount + quote.feeAmount
...
Apply the same pattern to all remaining unlabelled fenced blocks at lines 243, 257, 265, 275, and 287.
</details>
Also applies to: 26-28, 231-238, 243-247, 257-259, 265-267, 275-277, 287-289
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.21.0)</summary>
[warning] 18-18: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md around
lines 18 - 20, Several fenced code blocks in the document are missing language
identifiers; update each unlabelled triple-backtick block to include an
appropriate language hint (e.g., add text for diagrams like the block containing
"Intention → Quote → Intent", add http for the POST example "POST
https://api.cow.fi/mainnet/api/v1/quote", and add text or math for formula-like
snippets such as "beforeAllFees.sellAmount = quote.sellAmount +
quote.feeAmount"); apply the same change to all other unlabelled fenced blocks
in the file so every ... has a language tag.
</details>
<!-- fingerprinting:phantom:triton:churro -->
<!-- This is an auto-generated comment by CodeRabbit -->
Comment on lines
+55
to
+59
| :::note | ||
|
|
||
| More details see in [Order Book API](../../reference/apis/orderbook.mdx) | ||
|
|
||
| ::: |
Contributor
There was a problem hiding this comment.
Grammar: "More details see in"
✏️ Proposed fix
-More details see in [Order Book API](../../reference/apis/orderbook.mdx)
+For more details, see the [Order Book API](../../reference/apis/orderbook.mdx).
📝 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.
Suggested change
| :::note | |
| More details see in [Order Book API](../../reference/apis/orderbook.mdx) | |
| ::: | |
| :::note | |
| For more details, see the [Order Book API](../../reference/apis/orderbook.mdx). | |
| ::: |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` around
lines 55 - 59, Replace the ungrammatical note text "More details see in [Order
Book API](../../reference/apis/orderbook.mdx)" with a corrected phrase such as
"See the Order Book API for more details" (keeping the existing link target);
update the sentence in the note block so it reads clearly and includes proper
punctuation.
Comment on lines
+243
to
+247
| ``` | ||
| beforeAllFees.sellAmount = quote.sellAmount - protocolFeeAmount | ||
|
|
||
| beforeAllFees.buyAmount = quote.buyAmount\ | ||
| ``` |
Contributor
There was a problem hiding this comment.
Stray trailing backslash on beforeAllFees.buyAmount line.
✏️ Proposed fix
-beforeAllFees.buyAmount = quote.buyAmount\
+beforeAllFees.buyAmount = quote.buyAmount
📝 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.
Suggested change
| ``` | |
| beforeAllFees.sellAmount = quote.sellAmount - protocolFeeAmount | |
| beforeAllFees.buyAmount = quote.buyAmount\ | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 243-243: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` around
lines 243 - 247, Remove the stray trailing backslash on the
beforeAllFees.buyAmount assignment so the line correctly assigns quote.buyAmount
(matching the pattern used for beforeAllFees.sellAmount); update the assignment
expression for beforeAllFees.buyAmount to be a normal equals assignment
referencing quote.buyAmount to fix the syntax error.
Comment on lines
+257
to
+267
| ``` | ||
| protocolFeeAmount = quote.buyAmount × protocolFeeBps / (1 − protocolFeeBps) | ||
| ``` | ||
|
|
||
| ### Buy orders (sell token units) | ||
|
|
||
| For buy orders, the protocol fee is applied to the sum of sell amount and network costs: | ||
|
|
||
| ``` | ||
| protocolFeeAmount = (quote.sellAmount + quote.feeAmount) × protocolFeeBps / (1 + protocolFeeBps) | ||
| ``` |
Contributor
There was a problem hiding this comment.
Protocol fee formulas are mathematically wrong — protocolFeeBps is used raw instead of normalized.
protocolFeeBps is in basis points (e.g. 2 means 0.02%), so it must be divided by 10000 before being used in the fee formula. As written, with protocolFeeBps = 2:
- Sell order (line 258):
quote.buyAmount × 2 / (1 − 2)→ negative number. - Buy order (line 266):
(sellAmount + feeAmount) × 2 / (1 + 2)→ ~67% of volume, not ~0.02%.
🐛 Proposed fix
-protocolFeeAmount = quote.buyAmount × protocolFeeBps / (1 − protocolFeeBps)
+protocolFeeAmount = quote.buyAmount × (protocolFeeBps / 10000) / (1 − protocolFeeBps / 10000)-protocolFeeAmount = (quote.sellAmount + quote.feeAmount) × protocolFeeBps / (1 + protocolFeeBps)
+protocolFeeAmount = (quote.sellAmount + quote.feeAmount) × (protocolFeeBps / 10000) / (1 + protocolFeeBps / 10000)🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 257-257: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 265-265: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` around
lines 257 - 267, The formulas for protocolFeeAmount use protocolFeeBps raw;
convert it to a decimal rate first (e.g., protocolFeeRate = protocolFeeBps /
10000) and then apply that rate in the formulas: for sell orders compute
protocolFeeAmount = quote.buyAmount × protocolFeeRate / (1 − protocolFeeRate)
and for buy orders compute protocolFeeAmount = (quote.sellAmount +
quote.feeAmount) × protocolFeeRate / (1 + protocolFeeRate); update any
occurrences of protocolFeeBps in the doc to reference protocolFeeRate (or
explicitly show division by 10000) so the examples and formulas use the
normalized basis-point value.
Comment on lines
+275
to
+289
| ``` | ||
| partnerFeeAmount = beforeAllFees × partnerFeePercent / 100 | ||
| ``` | ||
|
|
||
| ### Buy orders (sell token units) | ||
|
|
||
| The same formula applies, but the result is in sell token units. | ||
|
|
||
| ## Slippage | ||
|
|
||
| Slippage tolerance uses the same calculation as the partner fee, but it is applied to the **`afterPartnerFees`** amount rather than the spot price: | ||
|
|
||
| ``` | ||
| slippageAmount = afterPartnerFees × slippagePercent / 100 | ||
| ``` |
Contributor
There was a problem hiding this comment.
Inconsistent units between formula sections and inline code — bps vs percent.
The ## Partner Fee and ## Slippage sections express amounts as partnerFeePercent / 100 and slippagePercent / 100, while the TypeScript code blocks in Section 3 consistently use partnerFeeBps / 10000 and slippageBps / 10000. These are numerically equivalent but use different variable names and units without any cross-reference.
Either align the formula notation to use bps consistently, or add a brief inline note making the equivalence explicit (e.g., partnerFeePercent / 100 = partnerFeeBps / 10000).
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 275-275: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 287-287: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.md` around
lines 275 - 289, The formulas use percent variables (partnerFeePercent,
slippagePercent) while the TS examples use basis points (partnerFeeBps,
slippageBps), causing inconsistent units; update the markdown so units are
consistent by either (A) changing the formulas to use bps (e.g., partnerFeeBps /
10000, slippageBps / 10000) or (B) adding a single inline clarifying sentence
near partnerFeeAmount and slippageAmount stating the equivalence
(partnerFeePercent / 100 = partnerFeeBps / 10000 and slippagePercent / 100 =
slippageBps / 10000) and reference afterPartnerFees to show slippage applies to
that amount—pick one approach and apply it to both Partner Fee and Slippage
sections for consistency.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
♻️ Duplicate comments (6)
docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx (6)
247-251: Stray trailing backslash onbeforeAllFees.buyAmount— already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 247 - 251, Remove the stray trailing backslash from the assignment to beforeAllFees.buyAmount so the line reads a normal assignment (beforeAllFees.buyAmount = quote.buyAmount) and does not include an extraneous backslash; check the nearby assignment to beforeAllFees.sellAmount and ensure both properties are plain numeric assignments in the how-intents-are-formed.mdx content block.
26-28: Missing language specifier on fenced code blocks — already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 26 - 28, The fenced code block containing the HTTP request line "POST https://api.cow.fi/mainnet/api/v1/quote" is missing a language specifier; update the fence to include an appropriate language identifier (e.g., http or bash) so syntax highlighting and linting work correctly by changing the opening backticks to something like ```http above that POST line.
261-271: Protocol fee formulas use rawprotocolFeeBpsinstead of dividing by 10,000 — already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 261 - 271, The formulas use raw protocolFeeBps instead of converting basis points to a fraction; update both equations so protocolFeeBps is divided by 10000 (e.g., replace protocolFeeBps with protocolFeeBps / 10000) when computing protocolFeeAmount for the buy-side expression involving protocolFeeAmount, quote.buyAmount, protocolFeeBps and the sell-side expression involving protocolFeeAmount, quote.sellAmount, quote.feeAmount and protocolFeeBps.
279-293: Inconsistent units between formula sections (percent) and TypeScript examples (bps) — already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 279 - 293, The documentation shows formulas using percent (partnerFeeAmount and slippageAmount) but the TypeScript examples elsewhere use basis points (bps), causing inconsistency; update the formulas or text to match the code by either (A) changing the math to use bps (divide by 10000) and noting the parameter names, or (B) keeping percent in the formula and explicitly state the conversion from bps to percent where the TypeScript examples (e.g., the places that pass partnerFeeBps or slippageBps) are referenced; ensure you update the partnerFeeAmount and slippageAmount descriptions to reference the same unit (bps or percent) used in the TypeScript examples and include the conversion rule so readers can unambiguously map the docs to the functions/variables in code.
55-59: Grammar: "More details see in" — already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 55 - 59, The note text "More details see in [Order Book API](../../reference/apis/orderbook.mdx)" has incorrect word order; update that sentence in the note block to a natural phrasing such as "See the Order Book API for more details." or "For more details, see the Order Book API." Replace the existing string exactly while preserving the link target and surrounding note markers.
16-20: Stage count inconsistency and missing code block language specifier — already reported.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 16 - 20, Update the mismatch between the declared "three stages" and the stages line and add a code-block language specifier: either change the text "Forming an intent follows three stages:" to match the shown stages "Intention → Quote → Intent" (or adjust the arrow sequence to reflect the true number of stages), and change the fenced block to include a language token (e.g., replace ``` with ```text) so the code block is properly tagged; adjust the surrounding sentence or the stage items (the string "Intention → Quote → Intent") accordingly to keep them consistent.
🧹 Nitpick comments (1)
docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx (1)
162-165:amountsToSign(flow sections) andorderToSign(final-order section) refer to the same structure — align the naming.Using different identifiers for the same concept across code examples forces readers to reconcile them mentally. Pick one name and use it consistently throughout the document.
Also applies to: 308-313
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around lines 162 - 165, The examples use two different names for the same structure — amountsToSign and orderToSign — causing confusion; pick one identifier and rename all occurrences so they match (e.g., change amountsToSign -> orderToSign or vice versa) in the "flow" sections (including the snippet with amountsToSign) and the "final-order" section (where orderToSign appears), updating any accompanying comments/field references (sellAmount, buyAmount) to remain consistent with the chosen name.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx`:
- Line 129: Replace the literal Markdown comment placeholder "[//]: # (TODO: add
a link to SDK)" with a proper MDX link to the SDK in both occurrences; edit the
MDX content so the placeholder string is removed and replaced by an inline link
using standard Markdown/MDX link syntax, e.g. [SDK](<SDK_URL>), ensuring the
actual SDK_URL is provided and the link renders correctly (no raw comment left
behind).
- Line 304: Replace the ambiguous sentence "Fixed amount is the spot price
amount." with a clear summary that identifies which amount is fixed and why:
state that for fixed-amount intents (rather than flexible ones) the protocol
uses the spot-price amount as the fixed value, clarifying whether that refers to
the buy or sell side and that it does not change with slippage; reference the
term afterSlippage and the phrase "fixed amount" so readers understand that
afterSlippage is the guaranteed minimum/maximum while the "fixed amount" equals
the spot price used in fixed-amount orders.
- Around line 287-293: Clarify that afterPartnerFees is an object and use the
correct property based on order side: for sell orders use
afterPartnerFees.buyAmount and for buy orders use afterPartnerFees.sellAmount;
update the slippage formula description to read "slippageAmount =
afterPartnerFees.buyAmount × slippagePercent / 100 (for sell orders)" and
"slippageAmount = afterPartnerFees.sellAmount × slippagePercent / 100 (for buy
orders)" and ensure the surrounding text references afterPartnerFees,
slippageAmount, slippagePercent, and the order side (sell/buy) so readers know
which property to use.
- Around line 279-286: The formulas currently treat beforeAllFees as a scalar;
update the sell-order formula to reference beforeAllFees.buyAmount when
computing partnerFeeAmount (partnerFeeAmount = beforeAllFees.buyAmount ×
partnerFeePercent / 100) and add an explicit buy-order formula that uses
beforeAllFees.sellAmount (partnerFeeAmount = beforeAllFees.sellAmount ×
partnerFeePercent / 100) so both sections reference the correct object
properties (symbols: beforeAllFees, partnerFeeAmount, partnerFeePercent).
---
Duplicate comments:
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx`:
- Around line 247-251: Remove the stray trailing backslash from the assignment
to beforeAllFees.buyAmount so the line reads a normal assignment
(beforeAllFees.buyAmount = quote.buyAmount) and does not include an extraneous
backslash; check the nearby assignment to beforeAllFees.sellAmount and ensure
both properties are plain numeric assignments in the how-intents-are-formed.mdx
content block.
- Around line 26-28: The fenced code block containing the HTTP request line
"POST https://api.cow.fi/mainnet/api/v1/quote" is missing a language specifier;
update the fence to include an appropriate language identifier (e.g., http or
bash) so syntax highlighting and linting work correctly by changing the opening
backticks to something like ```http above that POST line.
- Around line 261-271: The formulas use raw protocolFeeBps instead of converting
basis points to a fraction; update both equations so protocolFeeBps is divided
by 10000 (e.g., replace protocolFeeBps with protocolFeeBps / 10000) when
computing protocolFeeAmount for the buy-side expression involving
protocolFeeAmount, quote.buyAmount, protocolFeeBps and the sell-side expression
involving protocolFeeAmount, quote.sellAmount, quote.feeAmount and
protocolFeeBps.
- Around line 279-293: The documentation shows formulas using percent
(partnerFeeAmount and slippageAmount) but the TypeScript examples elsewhere use
basis points (bps), causing inconsistency; update the formulas or text to match
the code by either (A) changing the math to use bps (divide by 10000) and noting
the parameter names, or (B) keeping percent in the formula and explicitly state
the conversion from bps to percent where the TypeScript examples (e.g., the
places that pass partnerFeeBps or slippageBps) are referenced; ensure you update
the partnerFeeAmount and slippageAmount descriptions to reference the same unit
(bps or percent) used in the TypeScript examples and include the conversion rule
so readers can unambiguously map the docs to the functions/variables in code.
- Around line 55-59: The note text "More details see in [Order Book
API](../../reference/apis/orderbook.mdx)" has incorrect word order; update that
sentence in the note block to a natural phrasing such as "See the Order Book API
for more details." or "For more details, see the Order Book API." Replace the
existing string exactly while preserving the link target and surrounding note
markers.
- Around line 16-20: Update the mismatch between the declared "three stages" and
the stages line and add a code-block language specifier: either change the text
"Forming an intent follows three stages:" to match the shown stages "Intention →
Quote → Intent" (or adjust the arrow sequence to reflect the true number of
stages), and change the fenced block to include a language token (e.g., replace
``` with ```text) so the code block is properly tagged; adjust the surrounding
sentence or the stage items (the string "Intention → Quote → Intent")
accordingly to keep them consistent.
---
Nitpick comments:
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx`:
- Around line 162-165: The examples use two different names for the same
structure — amountsToSign and orderToSign — causing confusion; pick one
identifier and rename all occurrences so they match (e.g., change amountsToSign
-> orderToSign or vice versa) in the "flow" sections (including the snippet with
amountsToSign) and the "final-order" section (where orderToSign appears),
updating any accompanying comments/field references (sellAmount, buyAmount) to
remain consistent with the chosen name.
ℹ️ Review info
Configuration used: defaults
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (4)
static/img/concepts/intents/buy-order-quote.pngis excluded by!**/*.pngstatic/img/concepts/intents/quote-amounts-buy.pngis excluded by!**/*.pngstatic/img/concepts/intents/quote-amounts-sell.pngis excluded by!**/*.pngstatic/img/concepts/intents/sell-order-quote.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx
|
|
||
|  | ||
|
|
||
| [//]: # (TODO: add a link to SDK) |
Contributor
There was a problem hiding this comment.
Unresolved TODO comments in published documentation.
Both lines contain [//]: # (TODO: add a link to SDK) placeholders. In MDX, this Markdown comment syntax may not be suppressed by the JSX renderer and could either render literally or emit warnings. These TODOs should be resolved — replace each with the actual SDK link — before merging.
Also applies to: 170-170
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` at line
129, Replace the literal Markdown comment placeholder "[//]: # (TODO: add a link
to SDK)" with a proper MDX link to the SDK in both occurrences; edit the MDX
content so the placeholder string is removed and replaced by an inline link
using standard Markdown/MDX link syntax, e.g. [SDK](<SDK_URL>), ensuring the
actual SDK_URL is provided and the link renders correctly (no raw comment left
behind).
Comment on lines
+279
to
+286
| ``` | ||
| partnerFeeAmount = beforeAllFees × partnerFeePercent / 100 | ||
| ``` | ||
|
|
||
| ### Buy orders (sell token units) | ||
|
|
||
| The same formula applies, but the result is in sell token units. | ||
|
|
Contributor
There was a problem hiding this comment.
Partner fee formulas reference beforeAllFees as a scalar — missing property specifier and buy-order formula.
beforeAllFees is an object ({ sellAmount, buyAmount }). Using it bare in a formula is ambiguous. The sell-order formula needs .buyAmount, and the buy-order section omits the formula entirely instead of showing it explicitly.
✏️ Proposed fix
### Sell orders (buy token units)
-partnerFeeAmount = beforeAllFees × partnerFeePercent / 100
+partnerFeeAmount = beforeAllFees.buyAmount × partnerFeePercent / 100
### Buy orders (sell token units)
-The same formula applies, but the result is in sell token units.
+```
+partnerFeeAmount = beforeAllFees.sellAmount × partnerFeePercent / 100
+```
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around
lines 279 - 286, The formulas currently treat beforeAllFees as a scalar; update
the sell-order formula to reference beforeAllFees.buyAmount when computing
partnerFeeAmount (partnerFeeAmount = beforeAllFees.buyAmount × partnerFeePercent
/ 100) and add an explicit buy-order formula that uses beforeAllFees.sellAmount
(partnerFeeAmount = beforeAllFees.sellAmount × partnerFeePercent / 100) so both
sections reference the correct object properties (symbols: beforeAllFees,
partnerFeeAmount, partnerFeePercent).
Comment on lines
+287
to
+293
| ## Slippage | ||
|
|
||
| Slippage tolerance uses the same calculation as the partner fee, but it is applied to the **`afterPartnerFees`** amount rather than the spot price: | ||
|
|
||
| ``` | ||
| slippageAmount = afterPartnerFees × slippagePercent / 100 | ||
| ``` |
Contributor
There was a problem hiding this comment.
Slippage formula uses afterPartnerFees as a scalar — needs property specifier.
Same ambiguity as the partner fee formula: afterPartnerFees is an object. For sell orders the basis is .buyAmount; for buy orders it's .sellAmount.
✏️ Proposed fix
### Sell orders
-slippageAmount = afterPartnerFees × slippagePercent / 100
+slippageAmount = afterPartnerFees.buyAmount × slippagePercent / 100
### Buy orders
+slippageAmount = afterPartnerFees.sellAmount × slippagePercent / 100🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` around
lines 287 - 293, Clarify that afterPartnerFees is an object and use the correct
property based on order side: for sell orders use afterPartnerFees.buyAmount and
for buy orders use afterPartnerFees.sellAmount; update the slippage formula
description to read "slippageAmount = afterPartnerFees.buyAmount ×
slippagePercent / 100 (for sell orders)" and "slippageAmount =
afterPartnerFees.sellAmount × slippagePercent / 100 (for buy orders)" and ensure
the surrounding text references afterPartnerFees, slippageAmount,
slippagePercent, and the order side (sell/buy) so readers know which property to
use.
| | `/quote` API response | `sellAmount`, `buyAmount`, `feeAmount`, `protocolFeeBps` | | ||
| | UI / integrator settings | `partnerFee`, `slippage` | | ||
|
|
||
| The resulting order contains the **`afterSlippage`** buy amount (for sell orders) or sell amount (for buy orders), which the protocol guarantees as the minimum the user will receive (or maximum they'll pay). Fixed amount is the spot price amount. |
Contributor
There was a problem hiding this comment.
Unclear closing sentence in "Forming the Final Order" intro.
"Fixed amount is the spot price amount." is incomplete — it doesn't identify which amount is fixed, for which order type, or why. Suggest replacing with a clearer summary:
✏️ Proposed fix
-The resulting order contains the **`afterSlippage`** buy amount (for sell orders) or sell amount (for buy orders), which the protocol guarantees as the minimum the user will receive (or maximum they'll pay). Fixed amount is the spot price amount.
+The resulting order contains the **`afterSlippage`** buy amount (for sell orders) or sell amount (for buy orders), which the protocol guarantees as the minimum the user will receive (or maximum they'll pay). The complementary amount (sell for sell-orders, buy for buy-orders) is set to the **spot price** (`beforeAllFees`), allowing solvers to capture any surplus above the guaranteed amount.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/cow-protocol/concepts/how-it-works/how-intents-are-formed.mdx` at line
304, Replace the ambiguous sentence "Fixed amount is the spot price amount."
with a clear summary that identifies which amount is fixed and why: state that
for fixed-amount intents (rather than flexible ones) the protocol uses the
spot-price amount as the fixed value, clarifying whether that refers to the buy
or sell side and that it does not change with slippage; reference the term
afterSlippage and the phrase "fixed amount" so readers understand that
afterSlippage is the guaranteed minimum/maximum while the "fixed amount" equals
the spot price used in fixed-amount orders.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Related to cowprotocol/cow-sdk#800
This document explains how intent amounts are formed including all costs and fees for sell/buy orders.
Summary by CodeRabbit
Documentation