fixes for bundles documentation#625
Open
kaze-cow wants to merge 1 commit into
Open
Conversation
* 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
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📝 WalkthroughWalkthroughThis pull request rebrands "Generalized Wrappers" to "Atomic Bundles" across CoW Protocol documentation. The concept page introduces the new name and restructures decision guidance with "When to Use" criteria and alternative-first framing. Integration guides add new sections for nested bundle execution and validation. Contract reference updates terminology throughout implementation details and reorganizes resources. ChangesAtomic Bundles Documentation Rebranding
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/cow-protocol/integrate/wrappers.mdx (1)
128-139: ⚡ Quick winRename
isValidin the example to match actual return type
verifyAndBuildWrapperDatareturns encodedchainedWrapperData(bytes), not a boolean. Naming itisValidis misleading in sample code.Suggested edit
-const isValid = await helper.verifyAndBuildWrapperData([ +const chainedWrapperData = await helper.verifyAndBuildWrapperData([ @@ -// Returns encoded chainedWrapperData if valid, reverts if invalid +// Returns encoded chainedWrapperData if valid, reverts if invalid🤖 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/integrate/wrappers.mdx` around lines 128 - 139, The example variable name is misleading: change the variable named isValid to reflect that verifyAndBuildWrapperData returns encoded chainedWrapperData (bytes), e.g., rename isValid to chainedWrapperData or encodedWrapperData; update any subsequent example comments to match the byte return type and clarify that the value is encoded chainedWrapperData returned by verifyAndBuildWrapperData.
🤖 Prompt for all review comments with 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.
Inline comments:
In `@docs/cow-protocol/concepts/order-types/wrappers.md`:
- 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.
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Line 40: Replace the chain/explorer-specific phrase "Etherscan" in the staging
allowlist instruction with a neutral term like "a public block explorer" (so the
sentence that currently reads "verified and deployed on Etherscan" becomes e.g.
"verified and deployed on a public block explorer") to ensure the guidance is
correct across supported testnets and chains; update the sentence in the
docs/cow-protocol/integrate/wrappers.mdx content that mentions verification to
use this generic wording.
---
Nitpick comments:
In `@docs/cow-protocol/integrate/wrappers.mdx`:
- Around line 128-139: The example variable name is misleading: change the
variable named isValid to reflect that verifyAndBuildWrapperData returns encoded
chainedWrapperData (bytes), e.g., rename isValid to chainedWrapperData or
encodedWrapperData; update any subsequent example comments to match the byte
return type and clarify that the value is encoded chainedWrapperData returned by
verifyAndBuildWrapperData.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 297cd7fc-0e11-420d-80db-9ac76a8fc0b0
📒 Files selected for processing (3)
docs/cow-protocol/concepts/order-types/wrappers.mddocs/cow-protocol/integrate/wrappers.mdxdocs/cow-protocol/reference/contracts/periphery/wrapper.mdx
| - 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. |
Contributor
There was a problem hiding this comment.
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.
| 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. |
Contributor
There was a problem hiding this comment.
Avoid hard-coding “Etherscan” in staging-whitelist instructions
Line 40 is chain/explorer-specific. Prefer “verified on a public block explorer” so this stays correct across supported testnets.
Suggested edit
-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.
+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 deployed contract (verified on a public block explorer) and a brief description of the intended use case.🤖 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/integrate/wrappers.mdx` at line 40, Replace the
chain/explorer-specific phrase "Etherscan" in the staging allowlist instruction
with a neutral term like "a public block explorer" (so the sentence that
currently reads "verified and deployed on Etherscan" becomes e.g. "verified and
deployed on a public block explorer") to ensure the guidance is correct across
supported testnets and chains; update the sentence in the
docs/cow-protocol/integrate/wrappers.mdx content that mentions verification to
use this generic wording.
anxolin
approved these changes
May 19, 2026
| 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. |
Contributor
There was a problem hiding this comment.
most projects think they can't tolerate skiped or revert, but at the end of the day they can if, for example, the reverts is for a good reason (meant to happen) and actually prevents the trade from happening
Maybe we should just highlight that hooks calls, can revert and still let the order go through, so dependening on the use case, might require additional consideration if they need to prevent the order from happening.
| - **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. |
| 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. |
Contributor
There was a problem hiding this comment.
@avsavsavs is this the official channel for this? or there's a more direct way?
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
why testnet? if they want to do in mainnet works too, no?
Contributor
Author
There was a problem hiding this comment.
sorry yes. it should say deploy to any CoW-supported network or similar.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Following the release of atomic bundles, we have discovered some additional documentation could be changed, and some of hte terminology hasn't been fully updated.
Changes
Note that the URL of the pages
wrappersremains the same in all cases, and the original source code forCowWrapperor related contract examples also remains the same since we haven't changed the official terminology in the source code yet.Summary by CodeRabbit