Skip to content

docs: add comprehensive generalized wrappers documentation #595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kaze-cow wants to merge 11 commits into
base: main
Choose a base branch
from
Open

docs: add comprehensive generalized wrappers documentation #595

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9e9d980
docs: add comprehensive generalized wrappers documentation
kaze-cow Feb 12, 2026
4248b8f
fix compile errors
kaze-cow Feb 12, 2026
8e0fcdd
try to clean up wording of the wrapper description
kaze-cow Feb 17, 2026
44a2d3b
wording for guarenteed execution
kaze-cow Feb 17, 2026
5563ab8
fix wordings
kaze-cow Feb 17, 2026
ad8f9e6
use protocol terminology
kaze-cow Feb 17, 2026
3e58601
fix more wording for CoW team
kaze-cow Feb 17, 2026
aba6279
fix wording in periphery guide
kaze-cow Feb 17, 2026
9678bb8
actually embed the code since the gist embed script doesn't seem to work
kaze-cow Feb 17, 2026
e65d348
fix ai comments
kaze-cow Feb 17, 2026
2bc9013
other ai fixes misc
kaze-cow Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 99 additions & 0 deletions docs/cow-protocol/concepts/order-types/wrappers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
sidebar_position: 7
---

# Generalized Wrappers

Generalized wrappers is a new framework to allow custom logic to execute before and/or after order settlement on CoW Protocol. They enable complex DeFi workflows—like flash loans, leveraged positions, and progmatic orders--all while preserving the security and assurances granted by CoW Protocol.

## What are Wrappers?

Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding settlement contract. When a solver executes a settlement that includes a wrapper, they call the wrapper contract instead of the settlement contract directly. The wrapper calls the settlement contract on behalf of the solver.
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Missing article: "surrounding settlement contract" → "surrounding the settlement contract".

-Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding settlement contract.
+Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding the settlement contract.
📝 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
Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding settlement contract. When a solver executes a settlement that includes a wrapper, they call the wrapper contract instead of the settlement contract directly. The wrapper calls the settlement contract on behalf of the solver.
Wrappers are smart contracts that "wrap" the settlement process, executing custom logic surrounding the settlement contract. When a solver executes a settlement that includes a wrapper, they call the wrapper contract instead of the settlement contract directly. The wrapper calls the settlement contract on behalf of the solver.
🤖 Prompt for AI Agents 
In `@docs/cow-protocol/concepts/order-types/wrappers.md` at 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.


This mechanism extends CoW Protocol's functionality in a modular way, allowing new features and integrations to be added without modifying the core settlement contract or requiring any changes to solver implementations.

### 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.
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

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.


### Wrapper Nesting

One of the powerful features of wrappers is their ability to be nested. Multiple wrappers can be chained together in a single settlement transaction, allowing different orders in the same batch to each use their required wrapper functionality. For example, one order might need a flash loan wrapper while another needs a leverage wrapper—both can be executed in the same settlement through wrapper nesting.

## Use Cases

Wrappers enable a wide variety of advanced trading and DeFi operations:
Copy link
Contributor

@fedgiac fedgiac Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should make it clear that these are hypothetical and there isn't a corresponding feature out. Overall, I get the feeling this section should be much shorter since most of the people don't need a detailed description of hypothetical use cases, a bullet list would be enough. Later, we can link here to the concrete Euler implementation.


### Leverage Positions

By wrapping the execution context of a CoW settlement, protocols implementing leveraged position opening capabilities can be supported.

As the flagship GW implementation, Euler demonstrates a quintessential implementation of this use case. The wrapper:

1. Coordinates with Euler's Ethereum Vault Connector (EVC) batch execution system
2. Executes the necessary EVC batch operations before settlement
3. Performs the settlement to acquire the leveraged asset
4. Completes the position setup after settlement

This enables users to open leveraged positions on Euler through a single CoW Protocol order, with all the complexity handled by the wrapper. Leveraged positions are associated with high-volume trading, so CoW benefits from increased revenue from such integrations.

### Flash Loan Integration

Currently, CoW Protocol uses a dedicated `FlashLoanRouter` contract for flash loan functionality. However, this implementation comes with additional implementation effort from both the solvers and the CoW Protocol backend infrastructure. With generalized wrappers, flash loan integration becomes simpler and more flexible.

### Progmatic Orders

By introducing a wrapped order type combined with [composable-cow](../../reference/contracts/periphery/composable_cow.md) conditional order generators, it is possible for any account (EOA or smart contract wallet) to authorize delayed orders that can be triggered at a specified time. The wrapper contract provides the signing authentication, the conditional order contract controls the logic for when the order can execute, and the CoW Settlement contract protects the execution of the swap generated by the conditional order.

### Protocol-Approved Hooks

Unlike [CoW Hooks](./cow-hooks.mdx), which can revert even if the order is executed successfully, wrappers provide a way to enforce required pre- and post-settlement operations. Since wrappers are protocol-approved through the allowlist authenticator, they can implement critical functionality that must execute:

- Compliance checks (e.g., OFAC screening)
- Cross chain transfers (pre- or post- transfer)
- Deposit in a vault or other wrapper contract (swap and stake)

The key difference from hooks is that if a wrapper is required for an order, the settlement cannot proceed without it—making wrappers ideal for functionality that must not be skipped that is also approved.

## Considerations

While wrappers are powerful, there are important considerations to keep in mind:

### Gas Overhead

Wrappers add gas overhead to settlement transactions. Benchmarks show that even an empty wrapper (one that does nothing but pass through to settlement) adds approximately 22,272 gas, or about 11.4% overhead. The actual overhead depends on:
Copy link
Contributor

@fedgiac fedgiac Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Huh, that's a lot, I expect much less for an empty wrapper. Sure, we can get any number here if the calldata is large enough. How was the number computed?
Anyway, I think we should try to be more specific here. It would be nice to try a few different settlement data size, which should be the only real parameter in the case of an empty wrapper. (Something like this.)

Copy link
Contributor

@fedgiac fedgiac Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, maybe this is too specific for this very general page, but then I'd remove the concrete gas amount and do a more detailed analysis in another page.


- The complexity of the wrapper's logic
- The size of the settlement data being passed through
- The number of nested wrappers in the chain

For many use cases, this overhead is acceptable given the functionality unlocked, but it's an important factor in deciding whether to use a wrapper.

### Requires Protocol Approval

Wrappers cannot be deployed and used immediately—they must be approved by the CoW DAO through the allowlist authenticator. This approval process ensures high quality wrapper implementations and safety for solvers, but means there's a roadblock for developers looking to extend CoW Protocol. Developers should plan for this approval process when building wrapper-based integrations.

### Execution Not Enforced by the on-chain Protocol

Despite official rules enforcing the execution of wrappers when required by the user, a solver could still not execute a wrapper with an order. This means wrappers must be designed defensively:

- If a wrapper is strictly required, the order should fail to settle without it
- Wrappers should validate all input data and fail in cases where a user's funds could be at risk

Copy link
Contributor

@fedgiac fedgiac Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needed section: something like

### On-Chain Protocol Does Not Validate Settlement

where we say that a malicious solver can change the settlement data and that a wrapper should not trust that to be executed.

### Encoding Complexity

To improve gas performance, wrapper data is encoded in a condensed format. Constructing wrapper calldata correctly can be complex, especially when nesting multiple wrappers. While the protocol provides helper contracts like `CowWrapperHelper` to simplify this, developers need to understand the encoding scheme to build robust integrations.

## Getting Started

Wrappers are a powerful tool for advanced integrations on CoW Protocol. To start building with wrappers:

- **For developers**: See the [Integration Guide](../../integrate/wrappers.mdx) for implementation details, code examples, and security guidelines
- **For technical specs**: Consult the [Technical Reference](../../reference/contracts/periphery/wrapper.mdx) for detailed contract documentation and API specifications

To learn more about wrappers and see example implementations:

- [Euler Integration Contracts Repository](https://github.com/cowprotocol/euler-integration-contracts) - Contains the `CowWrapper` abstract contract and example implementations
- [Services Repository PR #3700](https://github.com/cowprotocol/services/pull/3700) - Backend integration implementation. Good reference for solvers looking to support wrappers.
Copy link
Contributor

@fedgiac fedgiac Feb 25, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To be extra clear, I'd mention that this isn't needed for people looking to implement wrappers.


Wrappers represent a significant evolution in CoW Protocol's capabilities, enabling complex DeFi workflows while maintaining security and simplicity for solvers. As more wrappers are developed and approved, they will continue to expand what's possible with intent-based trading.
Loading