docs: add comprehensive generalized wrappers documentation#595
Open
docs: add comprehensive generalized wrappers documentation#595
Conversation
Add complete documentation for CoW Protocol's generalized wrappers feature
across three audience-specific files:
- concepts/order-types/wrappers.md: High-level overview explaining what
wrappers are, use cases (Euler leverage, flash loans, TWAP, protocol hooks),
benefits, and considerations
- integrate/wrappers.mdx: Practical integration guide with three sections:
* For Order Creators: How to add wrappers to orders via appData
* For Wrapper Developers: Building custom wrapper contracts with security
requirements and implementation examples
* For Solvers: Encoding wrapper settlements and handling wrapper execution
- reference/contracts/periphery/wrapper.mdx: Smart contract reference focused
on ICowWrapper interface, CowWrapper abstract contract, implementation
patterns, and on-chain behavior
Each file serves a distinct purpose and audience while cross-linking to
provide comprehensive coverage of the wrapper system.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds three new documentation pages introducing Generalized Wrappers for the CoW Protocol: a conceptual overview, an integration guide, and a technical reference covering wrapper architecture, data encoding, execution flow, and security considerations. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
rect rgba(200,220,255,0.5)
participant User
participant Solver
participant Authenticator
participant WrapperA as Wrapper (A)
participant WrapperB as Wrapper (B)
participant Settlement as SettlementContract
participant External as ExternalProtocol
end
User->>Solver: submit order + appData.wrappers
Solver->>Authenticator: validate wrapper allowlist
Authenticator-->>Solver: allow / deny
alt allowed
Solver->>WrapperA: call wrappedSettle(dataA, next=WrapperB)
WrapperA->>WrapperA: _wrap pre-settlement logic
WrapperA->>WrapperB: _next(pass remaining data)
WrapperB->>WrapperB: _wrap pre/post logic
WrapperB->>Settlement: _next -> call settlement target
Settlement->>External: execute settlement (swaps, transfers)
External-->>Settlement: settlement result
Settlement-->>WrapperB: return
WrapperB->>WrapperA: return (post-settle)
WrapperA-->>Solver: final return
else denied
Authenticator-->>Solver: revert / reject
end
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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: 14
🤖 Fix all issues with AI agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md`:
- Line 44: Fix the spelling in the header "### Progmatic Orders" by changing it
to "### Programmatic Orders" in the docs file; locate the header string
"Progmatic Orders" and replace it with "Programmatic Orders" so the section
title is correct.
- Line 7: Fix the typos and punctuation in the "Generalized wrappers" sentence:
change "progmatic" to "programmatic" and replace the double dash "--" with an em
dash "—" (or a comma) so the sentence reads cleanly (e.g., "...like flash loans,
leveraged positions, and programmatic orders— all while preserving..."). Update
the sentence in the wrappers.md content where "Generalized wrappers is a new
framework..." appears.
- Line 17: Fix typos and minor wording in the paragraph: change "guarenteed" to
"guaranteed", remove the extra space before "wrappers" so it reads "audited and
wrappers" properly as "audited wrappers" (or "audited and wrappers" -> remove
stray "and" if intended), change "solver" to plural "solvers", and lowercase
"Wrapper functionality" to "wrapper functionality" for consistency; update the
sentence in the docs content (the paragraph referencing
GPv2AllowlistAuthenticator and settlement contract) accordingly.
- Line 74: Update the phrase "high quality wrapper implementations" to use a
hyphenated compound adjective: change it to "high-quality wrapper
implementations" in the sentence describing the approval process by the
allowlist authenticator and CoW DAO (the sentence beginning "Wrappers cannot be
deployed..."). Ensure the hyphen is added only when "high-quality" directly
modifies "wrapper implementations."
- Line 92: Update the broken link pointing to
../../reference/contracts/periphery/wrapper.md by changing its extension to .mdx
(../../reference/contracts/periphery/wrapper.mdx) in the text "**For technical
specs**" inside the wrapper documentation; locate the markdown link string
"../../reference/contracts/periphery/wrapper.md" and replace ".md" with ".mdx"
so it points to the correct Technical Reference file (wrapper.mdx).
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Line 131: Replace the placeholder link in the sentence "Wrappers are specified
in the order's [`appData`](TODO) under the `wrappers` field" with the actual
documentation path for appData: locate the appData docs by searching the repo
for the "appData" heading or file (the page that documents order.appData), then
update the TODO to that MDX/URL (use a relative docs path or absolute docs URL
consistent with other links in docs/cow-protocol/integrate/wrappers.mdx) so the
link points directly to the appData section.
- Line 320: Replace the misspelled word "simpulate" with "simulate" in the
sentence that reads "Account for wrapper gas overhead in your bids. The easiest
way to do this is to simpulate the wrapper transaction against an empty
settlement." so it reads "...simulate the wrapper transaction against an empty
settlement."; locate that exact sentence to make the single-word correction.
- Line 164: Update the incorrect documentation link: change the path string in
the sentence referencing GPv2AllowlistAuthenticator from
../references/contracts/core/allowlist.md to
../reference/contracts/core/allowlist.md so the link points to the existing
reference directory and continues to mention GPv2AllowlistAuthenticator for
context.
- Line 343: Update the broken link in docs/cow-protocol/integrate/wrappers.mdx
by changing the reference from "../reference/contracts/periphery/wrapper.md" to
"../reference/contracts/periphery/wrapper.mdx" so it points to the actual
wrapper.mdx file; locate the link text "**[Contracts
Reference](../reference/contracts/periphery/wrapper.md)**" and replace the .md
extension with .mdx.
- Line 8: The navigation link in docs/cow-protocol/integrate/wrappers.mdx has
mismatched bold markers around the link text ("Executing Wrappers as a Solver"
with anchor "#for-solvers") causing formatting issues; fix it by making the bold
markers balanced — either wrap the entire link and trailing description in
**...** or remove the leading ** so the link uses normal markdown; update the
line containing the "[Executing Wrappers as a Solver](`#for-solvers`) - Everything
solvers need to know to execute wrapper orders" text to have correct opening and
closing bold markers.
- Around line 254-257: The docs use two different names for the same
value—chainedWrapperData vs wrapperData—causing confusion in the call to
wrapperContract.interface.encodeFunctionData("wrappedSettle"); make the names
consistent by either (A) changing the second parameter in the encodeFunctionData
call from chainedWrapperData to wrapperData, or (B) updating the earlier
function that returns wrapperData to return/mention chainedWrapperData instead;
ensure the comment "From step 3" and the variable name used in wrappedSettle's
argument list (wrapperData/chainedWrapperData) match exactly.
In `@docs/cow-protocol/reference/contracts/periphery/wrapper.mdx`:
- Line 477: Replace the misspelled word "reccomended" with "recommended" in the
sentence that reads "It is reccomended to use
[Cannon](https://usecannon.com/learn) to make it easy to redeploy your
wrappers." (search for the exact string "reccomended" in the wrapper.mdx content
to locate the spot).
- Line 283: Fix the spelling mistake in the documentation: change "reccomended"
to "recommended" in the sentence mentioning ICowWrapper and CowWrapper so it
reads "It is strongly recommended to **NOT** implement `ICowWrapper` directly.
The `CowWrapper` abstract contract provides:". Update the phrase near the
references to ICowWrapper and CowWrapper accordingly.
- Around line 129-134: Fix the malformed Markdown code block under the
"Example:" section by converting the loose fenced text into a proper fenced code
block: ensure the "Example:" label is followed by a fenced block using ```text,
include the two lines "[0x0005][0xAABBCCDDEE][0x1234...ABCD][0x0003][0x112233]"
and "↑len ↑data ↑next wrapper ↑len ↑data" exactly as shown, and
close the block with ``` so the snippet displays correctly in the docs reference
for wrapper.mdx.
🧹 Nitpick comments (1)
docs/cow-protocol/reference/contracts/periphery/wrapper.mdx (1)
43-43: Clarify incomplete phrase."allowing CoW orders" appears incomplete. Perhaps it should be "allowing multiple CoW orders to use different wrappers in the same batch" or similar?
📝 Suggested clarification
-3. **Nested Support**: Multiple wrappers chain by encoding addresses sequentially, allowing CoW orders +3. **Nested Support**: Multiple wrappers chain by encoding addresses sequentially, allowing multiple orders with different wrappers in the same settlement batch
|
|
||
| ### Wrapper Authentication | ||
|
|
||
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed. |
Contributor
There was a problem hiding this comment.
Fix spelling error.
"guarenteed" should be "guaranteed".
✍️ Proposed fix
-For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed.
+For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited wrappers can interact with the settlement contract, protecting users, solvers, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guaranteed to be completed.Note: Also fixed "solver" → "solvers", removed extra space before "wrappers", and capitalization of "Wrapper functionality" → "wrapper functionality" for consistency.
📝 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
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited and wrappers can interact with the settlement contract, protecting users, solver, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed. | |
| For security, all wrappers must be approved through CoW Protocol's `GPv2AllowlistAuthenticator` before they can be used. This ensures that only audited wrappers can interact with the settlement contract, protecting users, solvers, and the protocol from malicious contracts. Unlike [hooks](./cow-hooks.mdx), wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guaranteed to be completed. |
🧰 Tools
🪛 LanguageTool
[grammar] ~17-~17: Ensure spelling is correct
Context: ...s such as cross-chain operations can be guarenteed to be completed. ### Wrapper Nesting ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md` at line 17, Fix typos and
minor wording in the paragraph: change "guarenteed" to "guaranteed", remove the
extra space before "wrappers" so it reads "audited and wrappers" properly as
"audited wrappers" (or "audited and wrappers" -> remove stray "and" if
intended), change "solver" to plural "solvers", and lowercase "Wrapper
functionality" to "wrapper functionality" for consistency; update the sentence
in the docs content (the paragraph referencing GPv2AllowlistAuthenticator and
settlement contract) accordingly.
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@docs/cow-protocol/concepts/order-types/wrappers.md`:
- Line 11: In the sentence starting "Wrappers are smart contracts that 'wrap'
the settlement process..." replace "surrounding settlement contract" with
"surrounding the settlement contract" so the phrase reads "executing custom
logic surrounding the settlement contract" to correct the missing article;
locate the phrase in wrappers.md and update that sentence accordingly.
- Around line 52-54: Replace the inconsistent "Cross chain transfers (pre- or
post- transfer)" phrase with a hyphenated form: "Cross-chain transfers (pre- or
post-transfer)" so it matches the existing "cross-chain" usage and also
hyphenates "post-transfer"; update the exact line containing the phrase "Cross
chain transfers" in the document.
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Around line 12-16: Multiple subsection headings (e.g., "Overview", "Adding
Wrappers to Orders", "Detecting Wrapper Orders" and other similar entries) are
incorrectly using "##" and therefore sit at the same level as the three main
audience headings ("For Wrapper Developers", "For Order Creators…", "For
Solvers"); change these subsection headings from "##" to "###" so they become
children of their respective audience sections (update every occurrence
referenced in the comment such as the "Overview", "Adding Wrappers to Orders",
"Detecting Wrapper Orders" headings and the other instances mentioned) to
restore proper heading hierarchy and TOC nesting.
- Around line 217-237: The encodeWrapperData function assumes wrapper.data
always exists and uses wrapper.data.length and slice, which breaks when
WrapperCall.data is optional; update encodeWrapperData to normalize data per
wrapper (e.g., const data = wrapper.data ?? '0x'; if (data === '') data = '0x'),
compute dataLength safely as Math.max(0, (data.length - 2) / 2), generate
lengthHex from that number, and only append data.slice(2) when dataLength > 0;
apply these changes in the encodeWrapperData function so it handles undefined or
empty wrapper.data without throwing.
🧹 Nitpick comments (1)
docs/cow-protocol/integrate/wrappers.mdx (1)
298-314: Wrapper accumulation example blindly collects duplicates.The conceptual example pushes all wrappers from all orders without deduplication. If two orders reference the same wrapper, it would appear twice. Consider adding a comment or dedup logic to clarify expected behavior for readers.
Comment on lines
+217
to
+237
| function encodeWrapperData(wrappers: WrapperCall[]): string { | ||
| let wrapperData = '0x'; | ||
|
|
||
| for (const [index, wrapper] of wrappers.entries()) { | ||
| // Skip first wrapper's address (it's the transaction target) | ||
| if (index !== 0) { | ||
| // Add wrapper address (20 bytes, without 0x prefix) | ||
| wrapperData += wrapper.target.slice(2); | ||
| } | ||
|
|
||
| // Encode data length as u16 big-endian (2 bytes) | ||
| const dataLength = (wrapper.data.length - 2) / 2; // Remove '0x' and convert to byte length | ||
| const lengthHex = dataLength.toString(16).padStart(4, '0'); | ||
| wrapperData += lengthHex; | ||
|
|
||
| // Add wrapper data (without 0x prefix) | ||
| wrapperData += wrapper.data.slice(2); | ||
| } | ||
|
|
||
| return wrapperData; | ||
| } |
Contributor
There was a problem hiding this comment.
Encoding function doesn't handle optional/empty data field.
The WrapperCall interface (line 43) declares data as optional (data?: string), but this encoding function unconditionally accesses wrapper.data.length and wrapper.data.slice(2). If data is undefined or an empty string, this will throw at runtime.
Proposed fix
function encodeWrapperData(wrappers: WrapperCall[]): string {
let wrapperData = '0x';
for (const [index, wrapper] of wrappers.entries()) {
// Skip first wrapper's address (it's the transaction target)
if (index !== 0) {
// Add wrapper address (20 bytes, without 0x prefix)
wrapperData += wrapper.target.slice(2);
}
+ const rawData = wrapper.data ?? '0x';
// Encode data length as u16 big-endian (2 bytes)
- const dataLength = (wrapper.data.length - 2) / 2; // Remove '0x' and convert to byte length
+ const dataLength = (rawData.length - 2) / 2; // Remove '0x' and convert to byte length
const lengthHex = dataLength.toString(16).padStart(4, '0');
wrapperData += lengthHex;
// Add wrapper data (without 0x prefix)
- wrapperData += wrapper.data.slice(2);
+ wrapperData += rawData.slice(2);
}
return wrapperData;
}📝 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
| function encodeWrapperData(wrappers: WrapperCall[]): string { | |
| let wrapperData = '0x'; | |
| for (const [index, wrapper] of wrappers.entries()) { | |
| // Skip first wrapper's address (it's the transaction target) | |
| if (index !== 0) { | |
| // Add wrapper address (20 bytes, without 0x prefix) | |
| wrapperData += wrapper.target.slice(2); | |
| } | |
| // Encode data length as u16 big-endian (2 bytes) | |
| const dataLength = (wrapper.data.length - 2) / 2; // Remove '0x' and convert to byte length | |
| const lengthHex = dataLength.toString(16).padStart(4, '0'); | |
| wrapperData += lengthHex; | |
| // Add wrapper data (without 0x prefix) | |
| wrapperData += wrapper.data.slice(2); | |
| } | |
| return wrapperData; | |
| } | |
| function encodeWrapperData(wrappers: WrapperCall[]): string { | |
| let wrapperData = '0x'; | |
| for (const [index, wrapper] of wrappers.entries()) { | |
| // Skip first wrapper's address (it's the transaction target) | |
| if (index !== 0) { | |
| // Add wrapper address (20 bytes, without 0x prefix) | |
| wrapperData += wrapper.target.slice(2); | |
| } | |
| const rawData = wrapper.data ?? '0x'; | |
| // Encode data length as u16 big-endian (2 bytes) | |
| const dataLength = (rawData.length - 2) / 2; // Remove '0x' and convert to byte length | |
| const lengthHex = dataLength.toString(16).padStart(4, '0'); | |
| wrapperData += lengthHex; | |
| // Add wrapper data (without 0x prefix) | |
| wrapperData += rawData.slice(2); | |
| } | |
| return wrapperData; | |
| } |
🤖 Prompt for AI Agents
In `@docs/cow-protocol/integrate/wrappers.mdx` around lines 217 - 237, The
encodeWrapperData function assumes wrapper.data always exists and uses
wrapper.data.length and slice, which breaks when WrapperCall.data is optional;
update encodeWrapperData to normalize data per wrapper (e.g., const data =
wrapper.data ?? '0x'; if (data === '') data = '0x'), compute dataLength safely
as Math.max(0, (data.length - 2) / 2), generate lengthHex from that number, and
only append data.slice(2) when dataLength > 0; apply these changes in the
encodeWrapperData function so it handles undefined or empty wrapper.data without
throwing.
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
|
|
||
| ## Detecting Wrapper Orders | ||
|
|
||
| Wrappers are specified in the order's [`appData`](../reference/core/auctions/schema.md) under the `wrappers` field: |
Author
There was a problem hiding this comment.
I believe the grammar is it is now is correct here. The appData is "possessed" by the order.
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
pretf00d
reviewed
Feb 16, 2026
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Co-authored-by: Federico Giacon <58218759+fedgiac@users.noreply.github.com>
Author
|
requesting re-review since there is only one outstanding comment that is pending non-blocking query |
pretf00d
reviewed
Mar 10, 2026
fedgiac
reviewed
Mar 11, 2026
|
|
||
| 1. Inherit from the `CowWrapper` abstract contract | ||
| 2. Implement `_wrap()` with your pre/post-settlement logic | ||
| 3. Implement `parseWrapperData()` for input validation |
Contributor
There was a problem hiding this comment.
Suggested change
| 3. Implement `parseWrapperData()` for input validation | |
| 3. Implement `validateWrapperData()` for input validation |
Comment on lines
+112
to
+115
| const isValid = await helper.verifyAndBuildWrapperData( | ||
| ["0x1234...", "0x5678..."], // Wrapper addresses | ||
| ["0xabcd...", "0xef01..."] // Wrapper data | ||
| ) |
Contributor
There was a problem hiding this comment.
Inconsistent with the actual function:
function verifyAndBuildWrapperData(WrapperCall[] memory wrapperCalls)
|
|
||
| This checks: | ||
| - All wrappers are allowlisted | ||
| - All wrappers use the same settlement contract |
Contributor
There was a problem hiding this comment.
This isn't the case.
Suggested change
| - All wrappers use the same settlement contract |
| - All wrappers use the same settlement contract | ||
| - Each wrapper can parse its data successfully | ||
|
|
||
| Note: an official deployment of the `CowWrapperHelper` contract does not currently exist. If you would like to use this contract, please deploy it yourself using the [code in the gist](https://gist.github.com/kaze-cow/8c8a49f3305519948b1ec868c7efa5b9). |
Contributor
There was a problem hiding this comment.
Not needed for the docs PR, but why not? We could easily deploy that.
Comment on lines
+148
to
+155
| **Fields:** | ||
| - **`target`**: Address of the wrapper contract (treat as opaque - don't parse) | ||
| - **`data`**: Wrapper-specific data (treat as opaque - don't parse) | ||
| - **`isOmittable`**: Critical flag for solver requirements (see below) | ||
|
|
||
| :::warning | ||
| Wrapper addresses and data should be treated as opaque values. Do not attempt to parse or validate them - simply pass them through in your encoding. | ||
| ::: |
Contributor
There was a problem hiding this comment.
Why are we so strict about this?
There is no real drawback in actually trying to parse if a solver wants to. They might have a good reason for it.
They kind of have to anyway, for example if target isn't an address, what should they do? What if the calldata is literally 0xinvalid?
I think we should just remove all of this and just link to the section ### AppData Structure.
|
|
||
| #### 2. Verify Wrapper Authentication | ||
|
|
||
| All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is recommended to verify wrappers are allowlisted before including them in settlements. |
Contributor
There was a problem hiding this comment.
Here instead it would be good to be strict. We're letting users tell the solver what to call and solvers should be aware of this.
Suggested change
| All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is recommended to verify wrappers are allowlisted before including them in settlements. | |
| All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). | |
| :::warning | |
| The wrapper will be _directly_ called from the solver address and will mediate the settlement. | |
| This value is provided _directly_ by the user and it may be malicious. | |
| ::: |
| #### 2. Verify Wrapper Authentication | ||
|
|
||
| All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is recommended to verify wrappers are allowlisted before including them in settlements. | ||
|
|
Contributor
There was a problem hiding this comment.
I think there should be an extra step here: decide whether to include the order in the settlement or not.
Since wrappers are likely to have complex behaviors, they would have to assess the revert risk based on the concrete wrapper implementation and may decide to skip it or adjust the scoring of the settlement accordingly.
| The `wrapperData` combines individual wrapper data with wrapper addresses: | ||
|
|
||
| ```typescript | ||
| function encodeWrapperData(wrappers: WrapperCall[]): string { |
Contributor
There was a problem hiding this comment.
Can we link to a reference here instead of adding code?
Something I'm worried about is that there's no input validation whatsoever (we actually say "WARNING: don't validate"), then this would introduce super weird behaviors like a user injecting data in the target field and causing inconsistencies like being able to inject other wrappers or calls that aren't part of the expected execution.
We're also making a lot of assumptions, like the data being 0x prefixed. Is it ok if the solvers skips the first byte provided by the user?
I'd say the user data should actually be validated at some point: it should conform to the app data schema, target should be an address, and data should be correctly encoded bytes, all 0x-prefixed.
|
|
||
| ```typescript | ||
| const tx = { | ||
| to: wrappers[0].target, |
Contributor
There was a problem hiding this comment.
It's nice to point out that the first target is missing in the encoding because it appears here.
Comment on lines
+268
to
+282
| ```solidity | ||
| // On-chain encoding and validation | ||
| address[] memory wrapperAddresses = [wrapper1, wrapper2]; | ||
| bytes[] memory wrapperDatas = [data1, data2]; | ||
|
|
||
| bytes memory wrapperData = CowWrapperHelper(HELPER).verifyAndBuildWrapperData( | ||
| wrapperAddresses, | ||
| wrapperDatas | ||
| ); | ||
| ``` | ||
|
|
||
| In addition to producing the correct encoded data, the helper also validates: | ||
| - All wrappers are allowlisted | ||
| - All wrappers use the same settlement contract | ||
| - Each wrapper can parse its data |
Contributor
There was a problem hiding this comment.
I've seen this appearing before, possibly verbatim. We should just add a link, in any case the comments from before apply.
fedgiac
reviewed
Mar 11, 2026
| - **`ICowWrapper`**: Core interface all wrappers must implement | ||
| - **`CowWrapper`**: Abstract base contract providing security and utilities that all wrappers should use | ||
|
|
||
| ```solidity |
Contributor
There was a problem hiding this comment.
Still suggesting to not copy the code here but just have a link.
- I don't believe we'll keep this up-to-date once a change is made, we're going to forget this dependency exists.
- If I were writing a wrapper, I'd like to have a more authoritative/better tracked source for this critical part of the wrapper and not just "I copied this from the textual docs."
Previous discussion here.
|
|
||
| Here's a minimal wrapper implementation to use as a starting point: | ||
|
|
||
| ```solidity |
Contributor
There was a problem hiding this comment.
I don't like to see large swathes of code in the docs.
I'd just like to make the code in the docs as minimal as possible because the docs are not a dev environment. This is better for maintainability, reproducibility, testing. The problems for a reader:
- Is this code up to date? If not, when was this working? What tooling did it use, like, Solidity version and Foundry version?
- I want to make a change for clarity. Does my code still work after that?
- I'm reviewing this code. Am I the one responsible for making sure the code works?
We can create a new repo, "generalized wrapper examples" that we can properly test and keep updated.
Case in point, it doesn't compile.
$ forge build
[⠊] Compiling...
[⠔] Compiling 5 files with Solc 0.8.30
[⠒] Solc 0.8.30 finished in 376.14ms
Error: Compiler run failed:
Error (3656): Contract "MyWrapper" should be marked as abstract.
--> src/MyWrapper.sol:6:1:
|
6 | contract MyWrapper is CowWrapper {
| ^ (Relevant source part starts here and spans across multiple lines).
Note: Missing implementation:
--> src/CowWrapper.sol:80:5:
|
80 | function name() external view returns (string memory);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Error (4649): Invalid type for argument in modifier invocation. Invalid implicit conversion from address to contract ICowSettlement requested.
--> src/MyWrapper.sol:7:48:
|
7 | constructor(address settlement) CowWrapper(settlement) {}
| ^^^^^^^^^^
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
3 participants
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
Add complete documentation for CoW Protocol's generalized wrappers feature across three audience-specific files:
Changes
concepts/order-types/wrappers.md: High-level overview explaining what wrappers are, use cases (Euler leverage, flash loans, TWAP, protocol hooks), benefits, and considerationsintegrate/wrappers.mdx: Practical integration guide with three sections:reference/contracts/periphery/wrapper.mdx: Smart contract reference focused on ICowWrapper interface, CowWrapper abstract contract, implementation patterns, and on-chain behaviorSummary by CodeRabbit