docs: document approve and bridge project

[anxolin]

This PR adds some basic documentation for this project giving some context for bridge providers and adding a disclaimer https://github.com/cowprotocol/approve-and-bridge/tree/documet-readme

Summary by CodeRabbit

• Documentation
  • Revamped documentation to describe the Approve-and-Bridge pattern for token bridging via CoW Protocol.
  • Clarified the 4-step transaction flow and recipient behavior across chains.
  • Added comprehensive guide on bridge provider helper contracts with extension points.
  • Included disclaimer on reference implementation status and audit information.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The README.md has been significantly restructured to replace Foundry tooling documentation with CoW Protocol post-hooks bridging explanation. Changes include a new 4-step bridge flow narrative, "ApproveAndBridge" pattern section with implementation details, bridge provider override specifications, and safety disclaimer. Net change: +45 lines, -19 lines.

Changes

Cohort / File(s)

Summary

Documentation Restructuring README.md

Replaced top-level introduction with CoW Protocol bridging overview; transformed "Foundry" section into "How it works" 4-step flow; added "Bridge provider helper contracts" section detailing ApproveAndBridge abstract pattern with delegatecall context, surplus handling, and workflow steps; specified bridge provider override extension points; added disclaimer regarding reference nature and lack of audits; updated command formatting for consistency

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A bridge of tokens, neat and clean,
The grandest approval flow I've seen!
CoW's post-hooks make the magic true,
One transaction for me and you!
Documentation hops along with glee, ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: document approve and bridge project' directly describes the main change: adding documentation for the approve-and-bridge project. It aligns with the file modifications (README.md updates) and PR objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In @README.md:
- Around line 10-12: Update the phrasing in the documented steps: change "user
controlled wallet" to "user-controlled wallet" (add hyphen) and replace "the
user that initiated the swap" with "the user who initiated the swap" to use
correct relative pronoun; apply these edits in the block containing the numbered
steps (lines referencing the CoW settlement and bridging post-hook).

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0875fce and 787fa92.

📒 Files selected for processing (1)

• README.md

🧰 Additional context used

🪛 LanguageTool

README.md

[grammar] ~10-~10: Use a hyphen to join words.
Context: ...ed)). 2. The swap executes, and the user controlled wallet receives the buy amoun...

(QB_NEW_EN_HYPHEN)

---

[style] ~12-~12: Consider using “who” when you are referring to a person instead of an object.
Context: ... the target chain is typically the user that initiated the swap (and not the smart c...

(THAT_WHO)

🔇 Additional comments (1)

README.md (1)

1-40: Excellent documentation of the approve-and-bridge pattern.

The restructured README clearly explains the CoW Protocol post-hooks bridging approach with:

• A concise introduction linking to CoW Protocol docs
• A well-articulated 4-step flow showing the end-to-end bridging process
• Clear documentation of the abstract helper contract pattern, including assumptions (delegatecall context, balance handling) and override points
• A comprehensive disclaimer appropriately cautioning users about the reference nature and lack of audits

The documentation is well-organized and should effectively guide bridge providers implementing their own helper contracts. Once the minor grammar issues above are fixed, this is ready.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix grammar issues for user-facing documentation.

Two minor grammar/style issues should be corrected:

• Line 10: "user controlled" should be hyphenated as "user-controlled"
• Line 12: Use "who" instead of "that" when referring to a person: "the user who initiated the swap"

✏️ Proposed fixes

- 1. A user creates an order where the `recipient` is modified to a smart contract wallet they control (for example, a 1-1 Safe or a [cow-shed](https://github.com/cowdao-grants/cow-shed)).
- 2. The swap executes, and the user controlled wallet receives the buy amount (including the surplus).
+ 1. A user creates an order where the `recipient` is modified to a smart contract wallet they control (for example, a 1-1 Safe or a [cow-shed](https://github.com/cowdao-grants/cow-shed)).
+ 2. The swap executes, and the user-controlled wallet receives the buy amount (including the surplus).

- 4. Eventually, the bridge will be completed. The recipient of the buy tokens in the target chain is typically the user that initiated the swap (and not the smart contract wallet used for bridging)
+ 4. Eventually, the bridge will be completed. The recipient of the buy tokens in the target chain is typically the user who initiated the swap (and not the smart contract wallet used for bridging)

📝 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

	2. The swap executes, and the user controlled wallet receives the buy amount (including the surplus).
	3. Within the same CoW settlement transaction, a [post-hooks](https://docs.cow.fi/cow-protocol/reference/core/intents/hooks) executes initiating the bridging process for the full amount.
	4. Eventually, the bridge will be completed. The recipient of the buy tokens in the target chain is typically the user that initiated the swap (and not the smart contract wallet used for bridging)
	1. A user creates an order where the `recipient` is modified to a smart contract wallet they control (for example, a 1-1 Safe or a [cow-shed](https://github.com/cowdao-grants/cow-shed)).
	2. The swap executes, and the user-controlled wallet receives the buy amount (including the surplus).
	3. Within the same CoW settlement transaction, a [post-hooks](https://docs.cow.fi/cow-protocol/reference/core/intents/hooks) executes initiating the bridging process for the full amount.
	4. Eventually, the bridge will be completed. The recipient of the buy tokens in the target chain is typically the user who initiated the swap (and not the smart contract wallet used for bridging)

🧰 Tools

🪛 LanguageTool

[grammar] ~10-~10: Use a hyphen to join words.
Context: ...ed)). 2. The swap executes, and the user controlled wallet receives the buy amoun...

(QB_NEW_EN_HYPHEN)

---

[style] ~12-~12: Consider using “who” when you are referring to a person instead of an object.
Context: ... the target chain is typically the user that initiated the swap (and not the smart c...

(THAT_WHO)

🤖 Prompt for AI Agents

In @README.md around lines 10 - 12, Update the phrasing in the documented steps:
change "user controlled wallet" to "user-controlled wallet" (add hyphen) and
replace "the user that initiated the swap" with "the user who initiated the
swap" to use correct relative pronoun; apply these edits in the block containing
the numbered steps (lines referencing the CoW settlement and bridging
post-hook).

[anxolin]

@fedgiac I will merge this as its improves the README, but happy to address comments if there's any in a different PR