Skip to content

Update wrapper.mdx #620

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

Merged
limitofzero merged 1 commit into from
May 1, 2026
+19 −19
Merged

Update wrapper.mdx #620

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
38 changes: 19 additions & 19 deletions docs/cow-protocol/reference/contracts/periphery/wrapper.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
sidebar_position: 7
---

# Generalized Wrappers
# Atomic Bundles

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.
Atomic Bundles 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.
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 1, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Complete the terminology migration in intro sentence.

Line 7 still says “wrapper system,” which conflicts with the new “Atomic Bundles” framing and the PR goal.

Suggested edit 
-Atomic Bundles 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.
+Atomic Bundles 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 bundle system.
📝 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
Atomic Bundles 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.
Atomic Bundles 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 bundle system.
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/cow-protocol/reference/contracts/periphery/wrapper.mdx` at line 7, The
intro sentence still uses the old phrase "wrapper system"; update that sentence
to use the new terminology consistently by replacing "wrapper system" with
"Atomic Bundles" (or rephrasing to "Atomic Bundles system" / "Atomic Bundles
framework") so the line reads e.g. "This reference documents the contract
interfaces, implementation patterns, and on-chain behavior of Atomic Bundles."
Locate the phrase "wrapper system" in the intro sentence and make the wording
change in the wrapper.mdx document to complete the terminology migration.


## Architecture

Expand Down Expand Up @@ -39,24 +39,24 @@ sequenceDiagram
### Key Design Principles

1. **Abstract**: There are very few limitations on what a wrapper can/can't do around a settlement transaction
2. **Efficient Encoding**: Wrapper-specific data appended to minimize gas overhead
3. **Nested Support**: Multiple wrappers chain by encoding addresses sequentially, allowing CoW orders
4. **Authentication**: Only allowlisted wrappers can call settlement contract
2. **Efficient Encoding**: Bundle-specific data appended to minimize gas overhead
3. **Nested Support**: Multiple bundles chain by encoding addresses sequentially, allowing CoW orders
4. **Authentication**: Only allowlisted bundles 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.
Developers looking to integrate using Atomic Bundles 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
- **`ICowWrapper`**: Core interface all bundles must implement
- **`CowWrapper`**: Abstract base contract providing security and utilities that all wrappers should use

See the code for [`CowWrapper.sol` on GitHub](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).

### Quick Start Example

The [`EmptyWrapper`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/test/EmptyWrapper.sol) serves as a good starting point for building a wrapper. Following this, the implementation functions should be filled in as described below.
The [`EmptyWrapper`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/test/EmptyWrapper.sol) serves as a good starting point for building a bundle. Following this, the implementation functions should be filled in as described below.

### Virtual Functions for integrators

Expand All @@ -69,7 +69,7 @@ function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes call
```

**Implementation Requirements:**
- Parse wrapper-specific data from `wrapperData` as required
- Parse bundle-specific data from `wrapperData` as required
- Execute pre-settlement logic
- Call `_next(remainingWrapperData)` to continue chain
- Execute post-settlement logic
Expand Down Expand Up @@ -111,7 +111,7 @@ function validateWrapperData(

#### `_next`

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

```solidity
function _next(bytes calldata settleData, bytes calldata remainingWrapperData) internal;
Expand Down Expand Up @@ -145,15 +145,15 @@ The `chainedWrapperData` parameter of `wrappedSettle(settleData, chainedWrapper

#### `wrappedSettle`

Entry point for wrapper execution. Validates caller authentication and delegates to `_wrap()`--where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
Entry point for bundle execution. Validates caller authentication and delegates to `_wrap()`--where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 1, 2026

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix punctuation around _wrap() clause.

_wrap()--where reads like a typo. Use an em dash (or standard punctuation) for readability.

Suggested edit 
-Entry point for bundle execution. Validates caller authentication and delegates to `_wrap()`--where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
+Entry point for bundle execution. Validates caller authentication and delegates to `_wrap()`—where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
📝 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
Entry point for bundle execution. Validates caller authentication and delegates to `_wrap()`--where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
Entry point for bundle execution. Validates caller authentication and delegates to `_wrap()`—where integrators place their custom logic. See the [full implementation in `CowWrapper.sol`](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol).
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/cow-protocol/reference/contracts/periphery/wrapper.mdx` at line 148, The
sentence uses a double hyphen in "delegates to `_wrap()`--where" which is a
punctuation typo; update the text in wrapper.mdx to replace `_wrap()--where`
with a properly punctuated form such as `_wrap() — where` (em dash with spaces)
or `_wrap(), where` so it reads "delegates to `_wrap()` — where integrators
place their custom logic" (or the comma variant) and ensure the reference to
`_wrap()` remains intact.


**Parameters:**
- `settleData`: Original `GPv2Settlement.settle(...)` calldata
- `chainedWrapperData`: Encoded wrapper chain — see [Calldata Encoding Specification](#calldata-encoding-specification)

## CowWrapperHelpers

A view-only periphery contract for validating and encoding wrapper chains. See the [source code](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapperHelpers.sol) for the complete implementation.
A view-only periphery contract for validating and encoding bundle chains. See the [source code](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapperHelpers.sol) for the complete implementation.

### Deployments

Expand Down Expand Up @@ -196,7 +196,7 @@ contract CowWrapperHelpers {

#### 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.
The bundle 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

Expand Down Expand Up @@ -226,9 +226,9 @@ function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes call

#### 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.
Settlement data can be modified by nested bundles, and solvers can supply arbitrary calldata. If it is important for your bundle to be able to validate the bundle 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.
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 bundle can freely modify `settleData` before passing it along.

#### 5. Deterministic Parsing Required

Expand Down Expand Up @@ -256,11 +256,11 @@ In the example above, your `_wrap` code can always reject deadline past expired

#### 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.
Though a solver would be slashed for doing so, there is no hard guarantee bundle executes even if user specifies it. Additionally, even when a bundle does execute, there is no guarantee that `settle` will eventually be called — an earlier bundle in the chain could skip calling `_next()` entirely. Bundles should not assume that settlement will complete.

### Gas Overhead

Wrapper execution adds gas overhead to settlements.
Atomic Bundle execution adds gas overhead to settlements.

**Benchmark (EmptyWrapper on Ethereum mainnet):**

Expand All @@ -272,8 +272,8 @@ Wrapper execution adds gas overhead to settlements.

**Scaling Factors:**
- Settlement data size (calldata copying)
- Wrapper logic complexity
- Number of nested wrappers
- Bundle logic complexity
- Number of nested bundles

**Methodology:** Single Uniswap V3 WETH→USDC trade. See [services PR #3700](https://github.com/cowprotocol/services/pull/3700).

Expand Down
Loading