From c004b38b754967d798a578abbd03c4bb37a3f82c Mon Sep 17 00:00:00 2001 From: Kaze <230549489+kaze-cow@users.noreply.github.com> Date: Fri, 8 May 2026 19:11:11 +0900 Subject: [PATCH] fixes for bundles documentation * all terminology should be "Atomic Bundles" wherever possible * add a section explaining difference between bundles and hooks and when to use each * add a section explaining how to get whitelisted in staging --- .../concepts/order-types/wrappers.md | 34 +++- docs/cow-protocol/integrate/wrappers.mdx | 150 ++++++++++-------- .../reference/contracts/periphery/wrapper.mdx | 36 ++--- 3 files changed, 126 insertions(+), 94 deletions(-) diff --git a/docs/cow-protocol/concepts/order-types/wrappers.md b/docs/cow-protocol/concepts/order-types/wrappers.md index 9fe074f03..4df12e3fd 100644 --- a/docs/cow-protocol/concepts/order-types/wrappers.md +++ b/docs/cow-protocol/concepts/order-types/wrappers.md @@ -4,7 +4,7 @@ sidebar_position: 7 # Atomic Bundles -Atomic Bundles are 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 programmatic orders—all while preserving the security and assurances granted by CoW Protocol. +Atomic Bundles (formerly known as Generalized Wrappers) are 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 programmatic orders—all while preserving the security and assurances granted by CoW Protocol. ## What are Bundles? @@ -12,26 +12,46 @@ Bundles are smart contracts that "wrap" the settlement process, executing custom 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. -## Use Cases +## Example Use Cases -As we begin to roll out Atomic Bundles more widely across our infrastructure, below is an overview of some of the ways Wrappers can be used. +As we begin to roll out Atomic Bundles more widely across our infrastructure, below is an overview of some of the ways Bundles can be used. * **Leveraged Positions:** By bundling the execution context of a CoW settlement, protocols implementing leveraged position opening capabilities can be supported. - This case is utilized by [Euler](https://github.com/cowprotocol/euler-integration-contracts) to open, close, and collateral swap leverage positions with the [Ethereum Vault Connector](https://evc.wtf/) in the flagship implementation of the bundle contracts. * **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 Atomic Bundles, flash loan integration becomes simpler and more flexible. * **Programmatic Orders:** Atomic Bundles can place, gate, or cancel the execution of user orders when authorized, allowing for advanced order types like TWAP, OCO, Stop-Loss/Take-Profit, or DCA with support for every type of wallet. -* **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 that the user may want. Since Atomic Bundles are protocol-approved through the allowlist authenticator, they can implement critical functionality that must execute: +* **Protocol-Approved Hooks:** Unlike [CoW Hooks](./cow-hooks.mdx), which can revert even if the order is executed successfully, bundles provide a way to enforce required pre- and post-settlement operations that the user may want. Since Atomic Bundles are protocol-approved through the allowlist authenticator, they can implement critical functionality that must execute: - Cross chain transfers (pre- or post-transfer) - Deposit in a vault or other bundle contract (swap and stake) -* **Something else:** Anyone can build and submit a new Atomic Bundles contract, and there are few restrictions on what a wrapper can do during execution. +* **Something else:** Anyone can build and submit a new Atomic Bundles contract, and there are few restrictions on what a bundle can do during execution. -## Considerations +## When to Use Atomic Bundles + +Atomic Bundles are a powerful tool, but they come with significant complexity and overhead. Before building one, consider whether a simpler alternative already meets your needs. + +### Consider alternatives first + +For many common use cases, [CoW Hooks](./cow-hooks.mdx) are simpler, require no protocol approval, and do not add the same degree of gas overhead or implementation burden: + +- **Simple pre/post actions that should happen alongside a swap** — e.g. permitting a token with a signature, populating tokens in a deposit contract, or sending tokens cross chain post a swap — are good uses for CoW Hooks. If the action failing doesn't put user funds at risk, a hook is likely sufficient. +- **Anything that can tolerate the action being skipped or reverting independently** of the swap outcome should consider using a hook rather than a bundle. +- **Rapid prototyping or short-lived integrations** are not good candidates for Atomic Bundles, since the DAO approval process is a hard requirement and requires dedication and time. + +If you are unsure which to use, start with [CoW Hooks](./cow-hooks.mdx). Atomic Bundles are the right choice only when hooks genuinely cannot provide the guarantees your integration requires. + +### Use Atomic Bundles when… + +- **You need to mediate the settlement itself.** Atomic Bundles sit in between the solver and the settlement contract, giving them the ability to modify context surrounding the entire settlement in ways hooks cannot. A good example of this is wrapping the settlement inside of a flash loan context. +- **Execution must be guaranteed.** If a pre- or post-settlement action is strictly required for your use case to be safe or correct (e.g. opening a leveraged position, initiating a cross-chain transfer), you need an Atomic Bundle. [CoW Hooks](./cow-hooks.mdx) can revert independently of the order settlement, which means they cannot be relied upon for critical operations. +- **You are building a complex, protocol-level integration.** Use cases like leveraged position management, advanced programmatic order types (TWAP, OCO, DCA), or vault deposit flows that involve multi-step settlement logic are well-suited to Atomic Bundles. + +## Limitations While Atomic Bundles are powerful, there are important considerations to keep in mind: ### Gas Overhead -Atomic Bundles add gas overhead to settlement transactions. This is an important factor in deciding whether to use a Atomic Bundles — see the [Integration Guide](../../integrate/wrappers.mdx#gas-estimation) for benchmarks and estimation guidance. +Atomic Bundles add gas overhead to settlement transactions. This is an important factor in deciding whether to use an Atomic Bundle — see the [Integration Guide](../../integrate/wrappers.mdx#gas-estimation) for benchmarks and estimation guidance. ### Requires Protocol Approval diff --git a/docs/cow-protocol/integrate/wrappers.mdx b/docs/cow-protocol/integrate/wrappers.mdx index c9ef66d12..e530742b8 100644 --- a/docs/cow-protocol/integrate/wrappers.mdx +++ b/docs/cow-protocol/integrate/wrappers.mdx @@ -1,68 +1,80 @@ -# Wrapper Integration +# Atomic Bundle Integration -Generalized wrappers enable custom logic to execute surrounding CoW Protocol settlements. This guide covers both using existing wrappers in your orders and building new wrapper contracts. +Atomic Bundles (formerly known as Generalized Wrappers) enable custom logic to execute surrounding CoW Protocol settlements. This guide covers both using existing bundles in your orders and building new bundle contracts. **Choose your path:** -- **[Building New Wrappers](#for-wrapper-developers)** - Develop custom wrapper contracts for advanced DeFi workflows -- **[Using Existing Wrappers](#for-order-creators-and-frontend-developers)** - Add wrappers to your orders and integrate into your application -- **[Executing Wrappers as a Solver](#for-solvers)** - Everything solvers need to know to execute wrapper orders +- **[Building New Bundles](#for-bundle-developers)** - Develop custom bundle contracts for advanced DeFi workflows +- **[Using Existing Bundles](#for-order-creators-and-frontend-developers)** - Add bundles to your orders and integrate into your application +- **[Executing Bundles as a Solver](#for-solvers)** - Everything solvers need to know to execute bundle orders --- -## For Wrapper Developers +## For Bundle Developers -This section covers building new wrapper contracts from scratch. +This section covers building new bundle contracts from scratch. ### Overview -To build a wrapper, you will: +To build a bundle, you will: 1. Inherit from the `CowWrapper` abstract contract 2. Implement `_wrap()` with your pre/post-settlement logic 3. Implement `validateWrapperData()` for input validation 4. Test thoroughly on testnets -5. Review the [Implementation Requirements](../reference/contracts/periphery/wrapper.mdx#implementation-requirements-for-integrators) to ensure your wrapper meets the acceptance requirements +5. Review the [Implementation Requirements](../reference/contracts/periphery/wrapper.mdx#implementation-requirements-for-integrators) to ensure your bundle meets the acceptance requirements 6. Submit for allowlist approval by the CoW Protocol team -Building a wrapper is a significant undertaking. -An insecure wrapper would put user and protocol funds at risk. +Building a bundle is a significant undertaking. +An insecure bundle would put user and protocol funds at risk. Make sure you understand CoW Protocol well before starting. -A contract audit by a reputable firm is mandatory before a wrapper is considered for approval. -Read more on the details of creating a wrapper from [the wrapper contract information page](../reference/contracts/periphery/wrapper.mdx). +A contract audit by a reputable firm is mandatory before a bundle is considered for approval. +Read more on the details of creating a bundle from [the bundle contract information page](../reference/contracts/periphery/wrapper.mdx). + +### Getting Whitelisted on Staging + +Before a bundle can be used in production it must be approved by CoW DAO, but you can get it whitelisted on the staging environment much earlier to test end-to-end against real infrastructure. + +To get whitelisted on staging: + +1. **Meet the implementation requirements.** Review the [Implementation Requirements](../reference/contracts/periphery/wrapper.mdx#implementation-requirements-for-integrators) and make sure your bundle satisfies all of them. In particular, ensure your contract uses the `CowWrapper` abstract contract, that `validateWrapperData()` is deterministic, and that the bundle is designed defensively. +2. **Reach out to the CoW Protocol team.** Contact the team (e.g. via the [CoW Protocol Discord](https://discord.com/invite/cowprotocol)) to request staging allowlist access. Share your contract which is verified and deployed on Etherscan and a brief description of the intended use case. +3. **Deploy to a supported testnet.** The team will review your contract and, if it meets the requirements, add it to the staging allowlist so you can test your full integration. + +Note that staging whitelisting is not a substitute for the full DAO approval process required for production. Plan for the DAO governance timeline when building towards a mainnet launch. --- ## For Order Creators and Frontend Developers -This section shows you how to use existing wrappers in your orders and integrate wrapper support into your application. +This section shows you how to use existing bundles in your orders and integrate bundle support into your application. -### Adding Wrappers to Orders +### Adding Bundles to Orders -To use a wrapper in your order, add it to the `appData` when creating the order: +To use a bundle in your order, add it to the `appData` when creating the order: ### AppData Structure ```typescript interface WrapperCall { - target: string; // Wrapper contract address (must be allowlisted) - data?: string; // Optional hex-encoded wrapper-specific data - isOmittable?: boolean; // Whether solver can skip this wrapper (default: false) + target: string; // Bundle contract address (must be allowlisted) + data?: string; // Optional hex-encoded bundle-specific data + isOmittable?: boolean; // Whether solver can skip this bundle (default: false) } ``` **Fields:** -- **`target`** (required): Address of the allowlisted wrapper contract -- **`data`** (optional): Hex-encoded data specific to the wrapper. Can be empty or omitted if the wrapper doesn't need custom data. +- **`target`** (required): Address of the allowlisted bundle contract +- **`data`** (optional): Hex-encoded data specific to the bundle. Can be empty or omitted if the bundle doesn't need custom data. - **`isOmittable`** (optional): Defaults to `false` - - `false` = Solver MUST execute the wrapper with exact data or be slashed - - `true` = Solver MAY skip the wrapper if they find a better solution + - `false` = Solver MUST execute the bundle with exact data or be slashed + - `true` = Solver MAY skip the bundle if they find a better solution ### Example: Using the CoW SDK ```typescript import { OrderBookApi, OrderQuoteRequest, OrderCreation } from '@cowprotocol/cow-sdk' -// Create order with wrapper +// Create order with bundle const orderCreation: OrderCreation = { // ... standard order fields (sellToken, buyToken, amounts, etc.) @@ -70,7 +82,7 @@ const orderCreation: OrderCreation = { // ... other appData fields wrappers: [ { - target: "0x1234...", // Flash loan wrapper address + target: "0x1234...", // Flash loan bundle address data: "0xabcd...", // Encoded flash loan params isOmittable: false // Must execute } @@ -82,20 +94,20 @@ const orderCreation: OrderCreation = { const orderId = await orderBookApi.sendOrder(orderCreation) ``` -### Example: Multiple Wrappers (Nested) +### Example: Multiple Bundles (Nested) -You can chain multiple wrappers in a single order: +You can chain multiple bundles in a single order: ```typescript appData: { wrappers: [ { - target: "0x1111...", // Flash loan wrapper + target: "0x1111...", // Flash loan bundle data: "0xaaaa...", isOmittable: false }, { - target: "0x2222...", // Leverage wrapper + target: "0x2222...", // Leverage bundle data: "0xbbbb...", isOmittable: false } @@ -103,11 +115,11 @@ appData: { } ``` -The wrappers execute in sequence: Wrapper1 → Wrapper2 → Settlement → Wrapper2 (post) → Wrapper1 (post). Note that wrappers from other users' orders may be interspersed, though this should generally not affect the execution of the order. +The bundles execute in sequence: Bundle1 → Bundle2 → Settlement → Bundle2 (post) → Bundle1 (post). Note that bundles from other users' orders may be interspersed, though this should generally not affect the execution of the order. -### Validating Wrapper Configuration +### Validating Bundle Configuration -Before submitting an order, you can confirm the wrapper encoding is valid using [`CowWrapperHelpers`](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers). +Before submitting an order, you can confirm the bundle encoding is valid using [`CowWrapperHelpers`](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers). ```typescript // On-chain validation (via Ethers/Viem) @@ -127,8 +139,8 @@ const isValid = await helper.verifyAndBuildWrapperData([ ``` This checks: -- All wrappers are allowlisted -- Each wrapper can parse its data successfully +- All bundles are allowlisted +- Each bundle can parse its data successfully See the [periphery contract reference](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers) for deployment addresses. @@ -136,11 +148,11 @@ See the [periphery contract reference](../reference/contracts/periphery/wrapper. ## For Solvers -This section explains how to execute settlements that include wrapper contracts as part of your solver implementation. +This section explains how to execute settlements that include bundle contracts as part of your solver implementation. -### Detecting Wrapper Orders +### Detecting Bundle Orders -Wrappers are specified in the order's [`appData`](../reference/core/auctions/schema.md) under the `wrappers` field: +Bundles are specified in the order's [`appData`](../reference/core/auctions/schema.md) under the `wrappers` field: ```json { @@ -155,36 +167,36 @@ Wrappers are specified in the order's [`appData`](../reference/core/auctions/sch ``` **Fields:** -- **`target`**: Address of the wrapper contract -- **`data`**: Wrapper-specific data +- **`target`**: Address of the bundle contract +- **`data`**: Bundle-specific data - **`isOmittable`**: Whether the `target` and `data` must be executed unmodified as part of the order execution -`target` may be any address and `data` is arbitrary bytes that will be passed to the target. There is generally no need for decoding the wrapper data since the execution process uses the same opaque format on each wrapper. +`target` may be any address and `data` is arbitrary bytes that will be passed to the target. There is generally no need for decoding the bundle data since the execution process uses the same opaque format on each bundle. ### Solver Requirements -#### 1. Execute Non-Omittable Wrappers +#### 1. Execute Non-Omittable Bundles -Orders with `"isOmittable": false` **MUST** be executed with the specified wrapper. You may be slashed for not doing so. +Orders with `"isOmittable": false` **MUST** be executed with the specified bundle. You may be slashed for not doing so. -If `"isOmittable": true`, you MAY skip the wrapper if you find a better solution without it. +If `"isOmittable": true`, you MAY skip the bundle if you find a better solution without it. -#### 2. Verify Wrapper Authentication and Simulate +#### 2. Verify Bundle Authentication and Simulate -All approved wrappers will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is advised to verify this is the case before attempting to process a wrapper order. +All approved bundles will be approved by the DAO and registered in [`GPv2AllowlistAuthenticator`](../reference/contracts/core/allowlist.md). It is advised to verify this is the case before attempting to process a bundle order. -Additionally, wrappers define additional operations that may revert, so it is strongly recommended to *simulate the settlement transaction* while including the wrapper call to verify its viability. The call trace can also be inspected for any unusual behavior. +Additionally, bundles define additional operations that may revert, so it is strongly recommended to *simulate the settlement transaction* while including the bundle call to verify its viability. The call trace can also be inspected for any unusual behavior. :::warning -The wrapper will be _directly_ called from the solver address and will mediate the settlement. +The bundle will be _directly_ called from the solver address and will mediate the settlement. Since the data is user-supplied, it may be malicious. ::: -#### 3. Include Wrappers in the Solution +#### 3. Include Bundles in the Solution -Whether using the CoW Protocol-provided driver or your own, ensure wrapper information flows from the auction to your final settlement transaction. This data should be passed unmodified from the orders in the auction to the final `Solution` submitted to the API. +Whether using the CoW Protocol-provided driver or your own, ensure bundle information flows from the auction to your final settlement transaction. This data should be passed unmodified from the orders in the auction to the final `Solution` submitted to the API. -### Encoding Wrapper Settlements +### Encoding Bundle Settlements :::info If you're using the driver provided by CoW Protocol, you can skip this section - the driver handles encoding automatically. @@ -192,22 +204,22 @@ If you're using the driver provided by CoW Protocol, you can skip this section - #### Manual Encoding -To execute a settlement with wrappers: +To execute a settlement with bundles: ##### 1. Change Transaction Target -Your transaction should call `wrappedSettle()` on the **first** wrapper (not the settlement contract): +Your transaction should call `wrappedSettle()` on the **first** bundle (not the settlement contract): ```typescript -// Without wrapper +// Without bundle tx = { to: SETTLEMENT_CONTRACT, data: encodeSettle(...) } -// With wrapper +// With bundle tx = { - to: wrappers[0].target, // First wrapper address + to: wrappers[0].target, // First bundle address data: encodeWrappedSettle(...) // See below } ``` @@ -234,7 +246,7 @@ Build `chainedWrapperData` according to the [Calldata Encoding Specification](.. ```typescript const tx = { - // The `chainedWrapperData` does not include the first wrapper to call, + // The `chainedWrapperData` does not include the first bundle to call, // so it is supplied here as the _target_ of the settlement call. to: wrappers[0].target, data: wrapperContract.interface.encodeFunctionData("wrappedSettle", [ @@ -248,19 +260,19 @@ const tx = { `CowWrapperHelpers` is a read-only periphery contract that can be called to validate many important points prior to execution. See the [periphery contract documentation](../reference/contracts/periphery/wrapper.mdx#cowwrapperhelpers). -### Accumulating Wrappers in Solutions +### Accumulating Bundles in Solutions #### Using CoW-Provided Driver -If you're using the CoW Protocol-provided driver, wrappers are handled automatically. Just ensure your solver process includes wrapper information in the solution output. +If you're using the CoW Protocol-provided driver, bundles are handled automatically. Just ensure your solver process includes bundle information in the solution output. #### Custom Implementation If implementing your own solver: -1. **Collect wrappers from orders**: As you process orders in an auction, collect all `wrappers` arrays from order appData -2. **Aggregate for batch**: Combine wrappers needed for all orders in the settlement batch -3. **Include in solution**: Add aggregated wrappers to your solution structure +1. **Collect bundles from orders**: As you process orders in an auction, collect all `wrappers` arrays from order appData +2. **Aggregate for batch**: Combine bundles needed for all orders in the settlement batch +3. **Include in solution**: Add aggregated bundles to your solution structure 4. **Encode transaction**: Use the encoding algorithm above to construct the final transaction **Example (conceptual):** @@ -274,7 +286,7 @@ const solution = { for (const order of auction.orders) { if (order.appData.wrappers) { - // Add wrappers needed for this order + // Add bundles needed for this order solution.wrappers.push(...order.appData.wrappers); } } @@ -283,7 +295,7 @@ for (const order of auction.orders) { // 1. Set tx target to solution.wrappers[0].target // 2. Build settleData from your normal GPv2Settlement.settle() calldata // 3. Build chainedWrapperData per the Calldata Encoding Specification in the reference docs -// 4. Call wrappedSettle(settleData, chainedWrapperData) on the first wrapper +// 4. Call wrappedSettle(settleData, chainedWrapperData) on the first bundle const tx = { to: solution.wrappers[0].target, data: wrapperContract.interface.encodeFunctionData("wrappedSettle", [ @@ -297,19 +309,19 @@ const tx = { #### Gas Estimation -Account for wrapper gas overhead in your bids — see [Gas Overhead](../reference/contracts/periphery/wrapper.mdx#gas-overhead) for benchmarks and scaling factors. The easiest way to estimate overhead for a specific wrapper is to simulate the wrapper transaction against an empty settlement. +Account for bundle gas overhead in your bids — see [Gas Overhead](../reference/contracts/periphery/wrapper.mdx#gas-overhead) for benchmarks and scaling factors. The easiest way to estimate overhead for a specific bundle is to simulate the bundle transaction against an empty settlement. ### Common Issues #### Issue: "Not authorized" error -**Cause**: Wrapper is not allowlisted in `GPv2AllowlistAuthenticator` +**Cause**: Bundle is not allowlisted in `GPv2AllowlistAuthenticator` -**Solution**: Verify wrapper is DAO-approved before including in settlement +**Solution**: Verify bundle is DAO-approved before including in settlement -#### Issue: Settlement reverts in wrapper +#### Issue: Settlement reverts in bundle -**Cause**: Incorrect encoding or wrapper-specific validation failure +**Cause**: Incorrect encoding or bundle-specific validation failure **Solution**: - Verify `settleData` is identical to what you'd send to `GPv2Settlement.settle()` @@ -319,7 +331,7 @@ Account for wrapper gas overhead in your bids — see [Gas Overhead](../referenc ### Solver Resources #### Documentation -- **[Wrapper Concepts](../concepts/order-types/wrappers.md)** - High-level overview +- **[Bundle Concepts](../concepts/order-types/wrappers.md)** - High-level overview - **[Contracts Reference](../reference/contracts/periphery/wrapper.mdx)** - Contract specifications - **[Services PR #3700](https://github.com/cowprotocol/services/pull/3700)** - Reference encoding implementation in production diff --git a/docs/cow-protocol/reference/contracts/periphery/wrapper.mdx b/docs/cow-protocol/reference/contracts/periphery/wrapper.mdx index f5e547830..00245dd8e 100644 --- a/docs/cow-protocol/reference/contracts/periphery/wrapper.mdx +++ b/docs/cow-protocol/reference/contracts/periphery/wrapper.mdx @@ -4,7 +4,7 @@ sidebar_position: 7 # Atomic Bundles -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 (formerly known as 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 bundle system. ## Architecture @@ -38,7 +38,7 @@ sequenceDiagram ### Key Design Principles -1. **Abstract**: There are very few limitations on what a wrapper can/can't do around a settlement transaction +1. **Abstract**: There are very few limitations on what a bundle can/can't do around a settlement transaction 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 @@ -50,7 +50,7 @@ Developers looking to integrate using Atomic Bundles should copy this all-in-one It provides a few base contracts which can serve as the foundation for integration: - **`ICowWrapper`**: Core interface all bundles must implement -- **`CowWrapper`**: Abstract base contract providing security and utilities that all wrappers should use +- **`CowWrapper`**: Abstract base contract providing security and utilities that all bundles should use See the code for [`CowWrapper.sol` on GitHub](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol). @@ -94,7 +94,7 @@ function _wrap(bytes calldata settleData, bytes calldata wrapperData, bytes call #### `validateWrapperData` -Validates wrapper-specific data. Must be deterministic and revert on invalid input. +Validates bundle-specific data. Must be deterministic and revert on invalid input. ```solidity function validateWrapperData( @@ -119,7 +119,7 @@ function _next(bytes calldata settleData, bytes calldata remainingWrapperData) i **Behavior:** - Extracts the next target address (first 20 bytes of `remainingWrapperData`) -- Calls the next wrapper via `wrappedSettle()`, or the settlement contract via `settle()` if no wrappers remain +- Calls the next bundle via `wrappedSettle()`, or the settlement contract via `settle()` if no bundles remain ## Calldata Encoding Specification @@ -134,14 +134,14 @@ The `chainedWrapperData` parameter of `wrappedSettle(settleData, chainedWrapper ``` **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) +- **Len₁**: 2-byte (uint16) length of bundle 1's data +- **Data₁**: Bundle 1's custom data +- **Addr₂**: 20-byte address of bundle 2 +- **Len₂**: 2-byte (uint16) length of bundle 2's data +- **Data₂**: Bundle 2's custom data +... (repeat Addr₂, Len₂, Data₂ for every subsequent bundle) -### Wrapper Public Functions +### Bundle Public Functions #### `wrappedSettle` @@ -149,7 +149,7 @@ Entry point for bundle execution. Validates caller authentication and delegates **Parameters:** - `settleData`: Original `GPv2Settlement.settle(...)` calldata -- `chainedWrapperData`: Encoded wrapper chain — see [Calldata Encoding Specification](#calldata-encoding-specification) +- `chainedWrapperData`: Encoded bundle chain — see [Calldata Encoding Specification](#calldata-encoding-specification) ## CowWrapperHelpers @@ -203,7 +203,7 @@ The bundle contract must be audited by a reputable security firm before submissi 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 +- Safe bundle chain continuation - Sanity checks for the settlement call #### 3. Intermediate Contracts for User Calls @@ -214,7 +214,7 @@ 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 + target.call(data); // User could call anything they want, including the settlement contract, using the bundle's authenticated context } // ✅ SAFE @@ -267,7 +267,7 @@ Atomic Bundle execution adds gas overhead to settlements. | Metric | Value | |--------|-------| | With EmptyWrapper | 217,033 gas | -| Without wrapper | 194,761 gas | +| Without bundle | 194,761 gas | | **Overhead** | **22,272 gas (11.4%)** | **Scaling Factors:** @@ -280,11 +280,11 @@ Atomic Bundle execution adds gas overhead to settlements. ## Resources ### Documentation -- **[Wrapper Concepts](../../../concepts/order-types/wrappers.md)** - High-level overview and use cases +- **[Bundle Concepts](../../../concepts/order-types/wrappers.md)** - High-level overview and use cases - **[Integration Guide](../../../integrate/wrappers.mdx)** - Implementation guide for order creators and developers - **[GPv2Settlement](../core/settlement.md)** - Core settlement contract documentation ### Code - **[CowWrapper.sol](https://github.com/cowprotocol/euler-integration-contracts/blob/master/src/CowWrapper.sol)** - Abstract contract and interfaces - **[EmptyWrapper](https://github.com/cowprotocol/euler-integration-contracts/blob/master/test/EmptyWrapper.sol)** - Minimal reference implementation -- **[Euler Integration](https://github.com/cowprotocol/euler-integration-contracts)** - Complete production wrapper example +- **[Euler Integration](https://github.com/cowprotocol/euler-integration-contracts)** - Complete production bundle example