Skip to main content

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.

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, Wrapper functionality can revert the execution of a transaction, ensuring sensitive user operations such as cross-chain operations can be guarenteed to be completed.

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:

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 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, 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:

  • 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

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 for implementation details, code examples, and security guidelines
  • For technical specs: Consult the Technical Reference for detailed contract documentation and API specifications

To learn more about wrappers and see example implementations:

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.