Skip to content

fixes for bundles documentation #625

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 1 commit into
base: main
Choose a base branch
from
+126 −94
Open

fixes for bundles documentation #625

Show file tree
Hide file tree
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
34 changes: 27 additions & 7 deletions docs/cow-protocol/concepts/order-types/wrappers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,54 @@ 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?

Bundles are smart contracts that "wrap" the settlement process, executing custom logic surrounding the settlement contract. When a solver executes a settlement that includes a bundle, they call the bundle contract instead of the settlement contract directly. The bundle 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.

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

@coderabbitai coderabbitai Bot May 8, 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

Replace placeholder “Something else” with a concrete use case title

Line 26 reads like draft placeholder text and weakens this section’s clarity. Please replace it with a specific heading (or remove the bullet until finalized).

Suggested edit 
-* **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.
+* **Custom integrations:** Anyone can build and submit a new Atomic Bundles contract, and there are few restrictions on what a bundle can do during execution.
📝 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
* **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.
* **Custom integrations:** Anyone can build and submit a new Atomic Bundles contract, and there are few restrictions on what a bundle can do during execution.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/cow-protocol/concepts/order-types/wrappers.md` at line 26, Replace the
placeholder bullet title "Something else" with a concrete use-case heading such
as "Third‑party/Custom Atomic Bundles" (so the line reads: "Third‑party/Custom
Atomic Bundles: Anyone can build and submit a new Atomic Bundles contract, and
there are few restrictions on what a bundle can do during execution.") or remove
the entire bullet until a finalized heading is agreed; update the heading text
that currently contains "Something else" to a specific, descriptive title.


## 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

Expand Down
Loading
Loading