Generalized Wrappers

Generalized wrappers are smart contracts that enable custom logic to execute before and after CoW Protocol settlement operations. This reference documents the contract interfaces, implementation patterns, and on-chain behavior of the wrapper system.

Architecture

Execution Flow

Key Design Principles

Abstract: There are very few limitations on what a wrapper can/can't do around a settlement transaction
Efficient Encoding: Wrapper-specific data appended to minimize gas overhead
Nested Support: Multiple wrappers chain by encoding addresses sequentially, allowing CoW orders
Authentication: Only allowlisted wrappers can call settlement contract

Implementation

Developers looking to integrate using wrappers should copy this all-in-one solidity file into their project as vendored dependency.

It provides a few base contracts which can serve as the foundation for integration:

ICowWrapper: Core interface all wrappers must implement
CowWrapper: Abstract base contract providing security and utilities that all wrappers should use

See the code for CowWrapper.sol on GitHub.

Quick Start Example

Here's a minimal wrapper implementation to use as a starting point:

// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.0;

import { CowWrapper } from "./CowWrapper.sol";

contract MyWrapper is CowWrapper {
    constructor(address settlement) CowWrapper(settlement) {}

    function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal override {
        // Your custom pre-settlement logic here
        // Example: pull tokens, initiate flash loan, etc.

        // Continue the wrapper chain (calls settlement or next wrapper)
        _next(settleData, remainingWrapperData);

        // Your custom post-settlement logic here
        // Example: repay flash loan, stake tokens, etc.
    }

    function validateWrapperData(bytes calldata wrapperData)
        external
        view
        override
    {
        // Validate wrapper-specific data
        // This must be deterministic - same input always returns same output
        // Revert if data is invalid
    }
}

Wrapper Public Functions

`wrappedSettle`

Entry point for wrapper execution. Validates caller authentication and delegates to _wrap()--where integrators place their custom logic.

function wrappedSettle(
    bytes calldata settleData,
    bytes calldata chainedWrapperData
) external override returns (bytes4) {
    // Verify caller is an authenticated solver
    require(AUTHENTICATOR.isSolver(msg.sender), NotASolver(msg.sender));

    // Find out how long the next wrapper data is supposed to be
    uint256 nextWrapperDataLen = uint256(uint16(bytes2(chainedWrapperData[0:2])));

    // Delegate to the wrapper's custom logic
    uint256 remainingWrapperDataStart = 2 + nextWrapperDataLen;
    _wrap(
        settleData,
        chainedWrapperData[2:remainingWrapperDataStart],
        chainedWrapperData[remainingWrapperDataStart:]
    );

    return ICowWrapper.wrappedSettle.selector;
}

Parameters:

settleData: Original GPv2Settlement.settle(...) calldata
chainedWrapperData:

Chained Wrapper Data Encoding

Each wrapper in the chain consists of:

2 bytes: uint16 length of wrapper-specific data
length bytes: wrapper-specific data for this wrapper
20 bytes: address of next wrapper (or stop here if no wrappers are left) The final wrapper in the chain omits the next wrapper address and calls SETTLEMENT directly.
20 bytes: address of next wrapper (or stop without an address if no wrappers are left)

When no wrapper is left, the final wrapper in the chain calls SETTLEMENT directly. Example:

[0x0005][0xAABBCCDDEE][0x1234567890123456789012345678901234567890][0x0003][0x112233]
↑len    ↑data         ↑next wrapper                               ↑len    ↑data

Each wrapper in the chain will successively pull off their own data and then call the next wrapper address (or the settlement address if no further wrapper data is supplied).

Virtual Functions for integrators

`_wrap`

Contains custom surrounding settlement logic. Must call _next() to continue the chain to the settlement contract.

function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal virtual;

Implementation Requirements:

Parse wrapper-specific data from wrapperData as required
Execute pre-settlement logic
Call _next(remainingWrapperData) to continue chain
Execute post-settlement logic

Example:

function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal override {
    // 1. Parse data
    (address token, uint256 amount) = abi.decode(wrapperData, (address, uint256));

    // 2. Pre-settlement logic. Example, receive tokens from user
    IERC20(token).transferFrom(msg.sender, address(this), amount);

    // 3. Continue chain (REQUIRED)
    _next(settleData, remainingWrapperData);

    // 4. Post-settlement logic. Example: stake tokens to a contract (for swap and stake)
    stakeTokens(token, amount);
}

Internal Functions (Provided)

`_next`

Continues the wrapper chain or calls settlement. Handles all parsing and routing automatically.

function _next(bytes calldata settleData, bytes calldata remainingWrapperData) internal;

Behavior:

Reads next wrapper address from remainingWrapperData
Determines if more wrappers exist or if settlement is next
Makes appropriate call with correct data
Handles wrapper nesting automatically

Implementation Details:

Extracts next target address (first 20 bytes)
Separates settle data from remaining wrapper data
Calls next wrapper via wrappedSettle() or settlement via settle()

Calldata Encoding Specification

The chainedWrapperData parameter of wrappedSettle(settleData, chainedWrapperData) is specially encoded to minimize bit shuffling overhead:

┌──────┬──────────┬──────────┬──────┬──────────┐
│ Len₁ │  Data₁   │  Addr₂   │ Len₂ │  Data₂   │
│(2 B) │ (wrap1)  │ (20 B)   │(2 B) │ (wrap2)  │
└──────┴──────────┴──────────┴──────┴──────────┘
│<─────────── chainedWrapperData ─────────────>│

Components:

Len₁: 2-byte (uint16) length of wrapper 1's data
Data₁: Wrapper 1's custom data
Addr₂: 20-byte address of wrapper 2
Len₂: 2-byte (uint16) length of wrapper 2's data
Data₂: Wrapper 2's custom data ... (repeat Addr₂, Len₂, Data₂ for every subsequent wrapper)

CowWrapperHelper

Utility contract for on-chain validation and encoding.

Interface

contract CowWrapperHelpers {
    /// @notice A definition for a single call to a wrapper
    struct WrapperCall {
        /// @notice The smart contract that will be receiving the call
        address target;

        /// @notice Any additional data which will be required to execute the wrapper call
        bytes data;
    }

    /// @notice Validates a wrapper chain configuration and builds the properly formatted wrapper data
    /// @param wrapperCalls Array of calls in execution order
    /// @return chainedWrapperData The encoded wrapper data ready to be passed to the first wrapper's wrappedSettle
    function verifyAndBuildWrapperData(
        WrapperCall[] memory wrapperCalls
    ) external view returns (bytes memory chainedWrapperData);
}

`CowWrapperHelpers`

To aid external integrators in encoding and verifying wrapper data, an additional view-only contract is provided.

See the CowWrapperHelper contract source code for the complete implementation.

`validateWrapperData`

Validates wrapper-specific data. Must be deterministic and revert on invalid input.

function validateWrapperData(
    bytes calldata wrapperData
) external view override;

Requirements:

Deterministic: Same input must always produce same output. This means you cannot check the timestamp and revert if the order is valid, for example.
View function: Cannot modify state
Revert on invalid: Revert if data is malformed

Implementation Requirements for Integrators

Security Requirements

Critical Requirements

1. Audit by a Reputable Firm

The wrapper contract must be audited by a reputable security firm before submission for allowlist approval. The audit report should be made available to the CoW DAO as part of the approval process.

2. Use CowWrapper Abstract Contract

It is strongly recommended to NOT implement ICowWrapper directly. The CowWrapper abstract contract provides:

Solver authentication checks
Correct calldata parsing and decoding
Safe wrapper chain continuation
Sanity checks for the settlement call

3. Intermediate Contracts for User Calls

If allowing user-defined calls, route through intermediate contracts:

// ❌ DANGEROUS
function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal override {
    (address target, bytes memory data) = abi.decode(wrapperData, (address, bytes));
    target.call(data);  // User could call anything they want, including the settlement contract, using the wrapper's authenticated context
}

// ✅ SAFE
function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal override {
    (address target, bytes memory data) = abi.decode(wrapperData, (address, bytes));
    HooksTrampoline(TRAMPOLINE).execute(target, data);  // Isolated execution
}

4. Assume All Parameters Are Untrusted

Settlement data can be modified by nested wrappers, and solvers can supply arbitrary calldata. If it is important for your wrapper to be able to validate the wrapper it is receiving, only trust signature-protected or on-chain validated parameters.

As a concrete implication: hooks cannot be enforced by inspecting settlement interaction data. Neither checking that a desired hook is present in settleData, nor injecting a hook into the forwarded settleData, provides any guarantee — an intermediate wrapper can freely modify settleData before passing it along.

5. Deterministic Parsing Required

validateWrapperData() must always produce the same result (revert or not) for same input:

// ❌ NOT DETERMINISTIC
function validateWrapperData(bytes calldata wrapperData)
    external view override
{
    uint256 deadline = abi.decode(wrapperData, (uint256));
    require(block.timestamp < deadline, "Expired");  // Changes over time!
}

// ✅ DETERMINISTIC
function validateWrapperData(bytes calldata wrapperData)
    external view override
{
    uint256 deadline = abi.decode(wrapperData, (uint256));
    require(deadline > 0, "Invalid deadline");  // Always same result
}

In the example above, your _wrap code can always reject deadline past expired instead.

6. Defensive Design

Though a solver would be slashed for doing so, there is no hard guarantee wrapper executes even if user specifies it. Additionally, even when a wrapper does execute, there is no guarantee that settle will eventually be called — an earlier wrapper in the chain could skip calling _next() entirely. Wrappers should not assume that settlement will complete.

Gas Overhead

Wrapper execution adds gas overhead to settlements.

Benchmark (EmptyWrapper on Ethereum mainnet):

Metric	Value
With EmptyWrapper	217,033 gas
Without wrapper	194,761 gas
Overhead	22,272 gas (11.4%)

Scaling Factors:

Settlement data size (calldata copying)
Wrapper logic complexity
Number of nested wrappers

Methodology: Single Uniswap V3 WETH→USDC trade. See services PR #3700.

Example Implementations

EmptyWrapper

Minimal wrapper demonstrating the pattern:

contract EmptyWrapper is CowWrapper {
    constructor(address settlement) CowWrapper(settlement) {}

    function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes calldata remainingWrapperData) internal override {
        // No pre-settlement logic
        _next(settleData, remainingWrapperData);  // Pass through
        // No post-settlement logic
    }

    function validateWrapperData(bytes calldata wrapperData)
        external
        view
        override
    {
        // No validation needed
    }
}

Generalized Wrappers

Architecture

Execution Flow

Key Design Principles

Implementation

Quick Start Example

Wrapper Public Functions

`wrappedSettle`

Chained Wrapper Data Encoding

Virtual Functions for integrators

`_wrap`

Internal Functions (Provided)

`_next`

Calldata Encoding Specification

CowWrapperHelper

Interface

`CowWrapperHelpers`

`validateWrapperData`

Implementation Requirements for Integrators

Security Requirements

1. Audit by a Reputable Firm

2. Use CowWrapper Abstract Contract

3. Intermediate Contracts for User Calls

4. Assume All Parameters Are Untrusted

5. Deterministic Parsing Required

6. Defensive Design

Gas Overhead

Example Implementations

EmptyWrapper

Resources

Documentation

Code

Architecture​

Execution Flow​

Key Design Principles​

Implementation​

Quick Start Example​

Wrapper Public Functions​

wrappedSettle​

Chained Wrapper Data Encoding​

Virtual Functions for integrators​

_wrap​

Internal Functions (Provided)​

_next​

Calldata Encoding Specification​

CowWrapperHelper​

Interface​

CowWrapperHelpers​

validateWrapperData​

Implementation Requirements for Integrators​

Security Requirements​

1. Audit by a Reputable Firm​

2. Use CowWrapper Abstract Contract​

3. Intermediate Contracts for User Calls​

4. Assume All Parameters Are Untrusted​

5. Deterministic Parsing Required​

6. Defensive Design​

Gas Overhead​

Example Implementations​

EmptyWrapper​

Resources​

Documentation​

Code​

Architecture

Execution Flow

Key Design Principles

Implementation

Quick Start Example

Wrapper Public Functions

`wrappedSettle`

Chained Wrapper Data Encoding

Virtual Functions for integrators

`_wrap`

Internal Functions (Provided)

`_next`

Calldata Encoding Specification

CowWrapperHelper

Interface

`CowWrapperHelpers`

`validateWrapperData`

Implementation Requirements for Integrators

Security Requirements

1. Audit by a Reputable Firm

2. Use CowWrapper Abstract Contract

3. Intermediate Contracts for User Calls

4. Assume All Parameters Are Untrusted

5. Deterministic Parsing Required

6. Defensive Design

Gas Overhead

Example Implementations

EmptyWrapper

Resources

Documentation

Code