Skip to content

docs: document approve and bridge project #4

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
anxolin merged 1 commit into from
Jan 20, 2026
Merged

docs: document approve and bridge project #4

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
64 changes: 45 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,66 +1,92 @@
## Foundry
## Approve and bridge
This is a simple reference implementation of a way to bridge tokens using CoW Protocol.

**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
It provides a simple way to bridge assets within the same transaction as the swap by using [post-hooks](https://docs.cow.fi/cow-protocol/reference/core/intents/hooks).

Foundry consists of:
## How it works

- **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
- **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
- **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
- **Chisel**: Fast, utilitarian, and verbose solidity REPL.
The general idea is:
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 that initiated the swap (and not the smart contract wallet used for bridging)
Comment on lines +10 to +12
Copy link

@coderabbitai coderabbitai bot Jan 9, 2026

Choose a reason for hiding this comment

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

⚠️ 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).


## Documentation
## Bridge provider helper contracts
Each bridge provider creates their own helper contract. As a reference [ApproveAndBridge](src/mixin/ApproveAndBridge.sol) abstract contract implements the common logic and defines some `virtual` functions to be overridden by the bridge provider helper contract.

https://book.getfoundry.sh/
The helper contract makes 2 assumptions:
* The contract assumes it is being called using a `delegatecall` from the account that has the proceeds of the swap.
* The balance of the account matches what the user intents to bridge. This is a simple way to handle CoW protocol's `surplus`.
- This can be achieved if the smart contract wallet is only used for bridging and is set as the `recipient` in the order.
- For example, the user sell 100 DAI for 100 USDC, but the solvers manage to give the user 101 USDC, then the contract will have exactly 101 USDC in its balance.

The main logic is defined in `approveAndBridge` function, which:
1. Get the balance of the bridged asset (includes `surplus` from the swap)
2. Performs some validations (like the `minAmount` tokens to bridge)
3. Sets the allowance, so the bridging protocol can pull the bridged amount.
4. Initiate the bridging process. Typically, the assets will be transferred to the bridging protocol.

The bridge provider helper contract overrides the function:
* `bridge`: Implements the specific logic for the bridge provider.
* `bridgeApprovalTarget`: Returns the address of the contract that should be approved to bridge the token.


## Disclaimer

This repository is provided solely as a reference and for informational purposes.

The smart contracts and related materials included here are not audited, may contain vulnerabilities, and must not be relied upon in production or for any security-critical use without independent review and testing.

Certain contracts and examples may be contributed by third parties. Inclusion in this repository does not constitute an endorsement, recommendation, or warranty by the maintainers. The maintainers make no representations or guarantees regarding correctness, security, or fitness for any particular purpose, and disclaim all liability for any loss or damage arising from the use of these materials.

## Usage

### Build

```shell
$ forge build
forge build
```

### Test

```shell
$ forge test
forge test
```

### Format

```shell
$ forge fmt
forge fmt
```

### Gas Snapshots

```shell
$ forge snapshot
forge snapshot
```

### Anvil

```shell
$ anvil
anvil
```

### Deploy

```shell
$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
```

### Cast

```shell
$ cast <subcommand>
cast <subcommand>
```

### Help

```shell
$ forge --help
$ anvil --help
$ cast --help
forge --help
anvil --help
cast --help
```
Loading