feat: generalized wrappers #3700

kaze-cow · 2025-09-24T08:47:57Z

Description

this introduces the ability for a wrapper contract to be included in the appdata and solutions. A wrapper is a contract which is called with the same parameters as settlement contract settle, but executes a series of operations either/both before or after executing the actual GPv2Settlement contract's settle function. This simplifies integration. see the full info here https://www.notion.so/cownation/Generalized-Wrapper-2798da5f04ca8095a2d4c56b9d17134e

Only approved wrapper contracts will be allowed to call the GPv2Settlement contract (via the current GPv2AllowlistAuthenticator), and it is expected that wrapper contracts will do the necessary validation of solvers on behalf of the settlement contract.

Its expected that generalized wrappers can simplify the implementation of many initiatives, including:

"flashloans" integrations (ex. aave, euler)
enforcable pre- and post-hooks (users can ensure that post actions must at least be attempted, such as deposit to a vault)
- ex: with our current CowShed implementation, if cross chain send were to fail due to ex. insufficient fee, funds can be sent back to the user rather than needing to be recovered from the CowShed contract
TWAP
- currently we are implementing this for EOAs, but its very difficult to ensure funds are only pulled from the users wallet when needed because there is no auth. Since the CowShed could effectively become a wrapper contract, it can pull funds from user and immediately call the necessary settle function afterwards to ensure funds are traded.

Implementation Notes

wrappers is added to the appData so that the frontend can "hint" the necessary flashloan or other required functionality if needed (similar to current flashloans functionality). More than one wrapper can be specified in a single order. A wrapper is combination of address, the address of the wrapper contract to execute, and data, which is any additional data required for the wrapper to execute
wrappers is added to solution so its easy for the driver to encode into a final solution. It is an array in order to accomodate different orders that require different wrappers.
additionally a solver can add their own wrapper if they determine its necessary/useful to get the best result from a trade (some already technically do this)

Potentially further changes required/limitations:

when quoting, how can the use of a wrapper be effectively included in the calculation?
this implements handling in the autopilot and driver, but what will need to happen from the solver side?

How to Test the Wrapper

I have deployed a testing EmptyWrapper to 0x54112E2F481AC239661914691082039d7B05A264. By using this contract as a simple wrapper, created a script to serve as a minimal E2E POC:

This PR can be verified to be working E2E by taking the following steps:

Boot up the playground environment. I used the command: docker compose -f playground/docker-compose.fork.yml up --build
With all the services stabilized and running, open a new terminal and run the provided wrapper test script: ./playground/test_wrapper.sh
In the docker compose logs, observe the order being placed, an auction held, and finally a transaction submitted to chain
The transaction result can be digested with cast:

To get the submitted transaction and all its data fields: cast tx <my transaction hash from logs>
To get the result of executing the transaction on-chain (the receipt): cast receipt <my transaction hash from logs>

It is also possible to see the order information and the active fields for wrapper and wrapperData by opening up https://localhost:8001 (the CoW Explorer) and putting in the printed order ID at the end of script execution.

Related PRs and Documentation

general wiki https://www.notion.so/cownation/Generalized-Wrapper-2798da5f04ca8095a2d4c56b9d17134e
PR on the contract side feat: add wrapper euler-integration-contracts#6

this introduces the ability for a `wrapper` contract to be included in the appdata and solutions. A `wrapper` is a contract which is called with the same parameters as settlement contract `settle`, but executes a series of operations either/both before or after executing the actual GPv2Settlement contract's `settle` function. This simplifies integration. Only approved `wrapper` contracts will be allowed to call the GPv2Settlement contract (via the current GPv2Allow), and it is expected that wrapper contracts will do the necessary validation of solvers on behalf of the settlement contract. Its expected that generalized wrappers can simplify the implementation of many initiatives, including: * flashloans integrations (ex. aave, euler) * enforcable pre- and post-hooks (users can ensure that post actions must at least be attempted, such as deposit to a vault) * ex: with our current CowShed implementation, if cross chain send were to fail due to ex. insufficient fee, funds can be sent back to the user rather than needing to be recovered from the CowShed contract * TWAP * currently we are implementing this for EOAs, but its very difficult to ensure funds are only pulled from the users wallet when needed because there is no auth. Since the CowShed could effectively become a wrapper contract, it can pull funds from user and immediately call the necessary `settle` function afterwards to ensure funds are traded. Implementation notes: * `wrapper` is added to the `appData` so that the frontend can "hint" the necessary flashloan or other required functionality if needed (similar to current `flashloans` functionality) * `wrapper` is added to solution so its easy for the driver to encode into a final solution, * additionally a solver can add their own wrapper if they determine its necessary/useful to get the best result from a trade (some already technically do this) Potentially further changes required/limitations: * when quoting, how can the use of a wrapper be effectively included in the calculation? * what happens if we more than one swap in a batch that requires a wrapper? * since its not possible to supply additional parameters to `settle` on the wrapper, in some cases it may be required to use a `preHook` to apply settings on a `transient` variable as part of the multicall for execution

unfortunately doesn't quite work because of flaws with cargo and the complexity of managing the dependencies. rust-lang/cargo#2644

just need to figure out why the app_data is not populating during the solve

Dockerfile

github-actions · 2025-10-04T00:08:16Z

This pull request has been marked as stale because it has been inactive a while. Please update this pull request or it will be automatically closed.

kaze-cow · 2025-10-04T08:28:43Z

The contracts team is taking a bit of extra time to review the design of the wrappers. Some changes will be coming next week but nothing too serious. Afterwards. We'll be requesting reviews and feedback from the back end team 👍

fleupold

not a real review, just a comment on the structure of the new field

crates/solvers-dto/src/auction.rs

crates/driver/src/domain/competition/solution/encoding.rs

crates/driver/src/domain/competition/solution/mod.rs

crates/driver/src/infra/solver/dto/solution.rs

crates/driver/src/infra/solver/mod.rs

crates/solvers-dto/src/auction.rs

crates/solvers/src/api/routes/solve/dto/solution.rs

Co-authored-by: Martin Magnus <[email protected]>

crates/contracts/artifacts/ICowWrapper.json

crates/driver/src/domain/competition/solution/encoding.rs

crates/driver/src/domain/competition/solution/mod.rs

crates/solvers-dto/src/auction.rs

crates/solvers-dto/src/solution.rs

crates/solvers/src/domain/solution.rs

Co-authored-by: Martin Magnus <[email protected]>

kaze-cow · 2025-10-27T10:24:10Z

crates/driver/src/infra/solver/dto/auction.rs


+pub type WrapperCalls = HashMap<order::Uid, Vec<(H160, Vec<u8>, bool)>>;
+
+#[allow(clippy::too_many_arguments)]


@MartinquaXD I aws just peeking through the changes one more time and I just noticed this. For now is it ok to be overriding clippy here?

Yeah, that's fine. Although for new overrides let's use #[expect(clippy::too_many_arguments)] (see here for more context).

squadgazzz

LGTM, only nits

crates/driver/src/infra/solver/mod.rs

crates/driver/src/infra/solver/dto/auction.rs

crates/driver/src/domain/competition/solution/encoding.rs

for right now its just a fork test. later will probably want to have something more sophisticated

MartinquaXD

Thanks for adding the test. I think after addressing the last nits on the test this is ready to be merged. 🙌

crates/e2e/tests/e2e/wrapper.rs

MartinquaXD · 2025-10-30T16:00:42Z

crates/e2e/tests/e2e/wrapper.rs

+    web3.alloy
+        .anvil_send_impersonated_transaction_with_config(


There is no need to impersonate the trader for this call since we have the PK available. For example the approve call below works just fine without impersonation.

fixed in 1f356b0

crates/e2e/tests/e2e/wrapper.rs

* verify that 2 wrappers nested can be called as expected * verify that auction id can be retrieved

* dont need to impresonate trader to deposit ETH * auction seems to be having issues pulling the trace sometimes * actually check to make sure some expected wrapper calldata is coming through

kaze-cow added 9 commits September 18, 2025 21:13

fix: improve docker builds

1c3c0c3

unfortunately doesn't quite work because of flaws with cargo and the complexity of managing the dependencies. rust-lang/cargo#2644

everything works

ab75508

its close

2250d08

just need to figure out why the app_data is not populating during the solve

successful placement of wrapped order!

6c6340c

undo cargo changes

c24b371

Merge remote-tracking branch 'origin/main' into feat/generalized-wrapper

d248fe4

Merge remote-tracking branch 'origin/main' into feat/generalized-wrapper

b9af257

add gpv2wrapper info

4214939

m-sz reviewed Sep 25, 2025

View reviewed changes

Dockerfile Outdated Show resolved Hide resolved

kaze-cow added 2 commits September 26, 2025 13:08

wrapper_data is close to working but not getting sent somewhere

07ff1a1

all working

fa3a650

kaze-cow mentioned this pull request Sep 26, 2025

feat: implement generic wrapper cowprotocol/contracts#247

Closed

github-actions bot added the stale label Oct 4, 2025

github-actions bot removed the stale label Oct 5, 2025

fleupold reviewed Oct 6, 2025

View reviewed changes

crates/solvers-dto/src/auction.rs Outdated Show resolved Hide resolved

kaze-cow added 3 commits October 6, 2025 23:55

Merge remote-tracking branch 'origin/main' into feat/generalized-wrapper

4e26f52

remove unnecessary wrapper file

2b842d4

clean out superfluous changes

0c5cbb6

kaze-cow force-pushed the feat/generalized-wrapper branch from 10f7352 to 0c5cbb6 Compare October 7, 2025 07:49

format

2b27533

MartinquaXD reviewed Oct 7, 2025

View reviewed changes

kaze-cow mentioned this pull request Oct 7, 2025

feat: add wrapper cowprotocol/euler-integration-contracts#6

Open

kaze-cow and others added 5 commits October 7, 2025 23:29

fix issues, now working

83476ca

Update crates/solvers/src/api/routes/solve/dto/solution.rs

bf69f8e

Co-authored-by: Martin Magnus <[email protected]>

changes in response to comments

56e6118

Update crates/driver/src/infra/solver/dto/solution.rs

866db4b

Co-authored-by: Martin Magnus <[email protected]>

removed all tuple structures

acac299

kaze-cow requested a review from MartinquaXD October 24, 2025 06:25

Merge branch 'main' into feat/generalized-wrapper

f7601b6

MartinquaXD reviewed Oct 27, 2025

View reviewed changes

kaze-cow and others added 8 commits October 27, 2025 18:41

Update crates/solvers/src/domain/solution.rs

d94a5f0

Co-authored-by: Martin Magnus <[email protected]>

Update crates/driver/src/domain/competition/solution/mod.rs

ade0037

Co-authored-by: Martin Magnus <[email protected]>

Update crates/driver/src/domain/competition/solution/encoding.rs

4601ec1

Co-authored-by: Martin Magnus <[email protected]>

Update crates/driver/src/domain/competition/solution/encoding.rs

a203947

Co-authored-by: Martin Magnus <[email protected]>

Update crates/driver/src/domain/competition/solution/encoding.rs

2696ee8

Co-authored-by: Martin Magnus <[email protected]>

just format abi files

abb3a44

fix feedbacks and compile errors

a80ad6b

Merge branch 'main' into feat/generalized-wrapper

afe17c5

kaze-cow commented Oct 27, 2025

View reviewed changes

kaze-cow requested a review from MartinquaXD October 27, 2025 10:25

kaze-cow added 2 commits October 27, 2025 22:29

Merge branch 'main' into feat/generalized-wrapper

e191844

fix test failures

de269d7

squadgazzz approved these changes Oct 29, 2025

View reviewed changes

crates/driver/src/infra/solver/mod.rs Outdated Show resolved Hide resolved

crates/driver/src/infra/solver/dto/auction.rs Outdated Show resolved Hide resolved

crates/driver/src/domain/competition/solution/encoding.rs Show resolved Hide resolved

kaze-cow added 5 commits October 30, 2025 14:44

Merge remote-tracking branch 'origin/main' into feat/generalized-wrapper

7a2ba66

add e2e test for wrapper

447ac7c

for right now its just a fork test. later will probably want to have something more sophisticated

implement feedback

e8d13a9

add safety condition

f392fc1

final changes

e4d4216

MartinquaXD reviewed Oct 30, 2025

View reviewed changes

kaze-cow added 3 commits October 31, 2025 16:21

fix

6e810ca

* verify that 2 wrappers nested can be called as expected * verify that auction id can be retrieved

final test cleanups

1f356b0

* dont need to impresonate trader to deposit ETH * auction seems to be having issues pulling the trace sometimes * actually check to make sure some expected wrapper calldata is coming through

Merge remote-tracking branch 'origin/main' into feat/generalized-wrapper

525224a

kaze-cow enabled auto-merge (squash) October 31, 2025 07:39

make test more reliable

2edbd05

kaze-cow merged commit 91299bd into main Oct 31, 2025
17 checks passed

kaze-cow deleted the feat/generalized-wrapper branch October 31, 2025 08:03

github-actions bot locked and limited conversation to collaborators Oct 31, 2025


		pub type WrapperCalls = HashMap<order::Uid, Vec<(H160, Vec<u8>, bool)>>;

		#[allow(clippy::too_many_arguments)]

feat: generalized wrappers #3700

feat: generalized wrappers #3700

Uh oh!

Conversation

kaze-cow commented Sep 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Implementation Notes

How to Test the Wrapper

Related PRs and Documentation

Uh oh!

Uh oh!

github-actions bot commented Oct 4, 2025

Uh oh!

kaze-cow commented Oct 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fleupold left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kaze-cow Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

MartinquaXD Oct 27, 2025

Choose a reason for hiding this comment

Uh oh!

squadgazzz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MartinquaXD left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

MartinquaXD Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

kaze-cow Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

kaze-cow commented Sep 24, 2025 •

edited

Loading

kaze-cow commented Oct 4, 2025 •

edited

Loading