Builder based API for `simulator` crate by MartinquaXD · Pull Request #4372 · cowprotocol/services

MartinquaXD · 2026-04-30T16:27:42Z

Description

This new API for the simulator crate approaches the problem from the other side. Instead of starting by making it work first and foremost with the most complicated use case (i.e. trade verification) and building the simpler, more common use cases around that this API starts with the simple stuff and aims to be flexible enough to also support the more complicated things.

Not only does this lead to a cleaner API (IMO) but also actual feature improvements. For example the trade verification logic replaces the user with a helper contract that we puppeteer to set up the necessary pre-conditions for quote verification. That helper contract makes the approach fundamentally incompatible with use cases where a pre-interaction deploys a smart contract that is actually the owner of the order (we did not have a way to know the state and bytecode of this helper contract to fall back to).
The new approach now allows us to easily opt-in to each "faking machinery" individually. So the simulation endpoint will only use balance overrides and allow listing a random address while the trade verification can pull out the big guns (many balance overrides, multiple fake contracts).

Additionally this PR adds the ability to correctly encode flashloans which was previously not supported by the simulator crate.

Changes

new builder based API to construct simulations
replaced all existing use cases of the old API with the new one
removed the old API (2 files)
updated the custom order simulation API to provide all the necessary data to not require the fake EIP 1271 user contract
- this allows simulating orders of counterfactual owners (contracts that have not been deployed yet)
replaced AnyoneAuthenticator approach with exactly overriding only the storage slot to allow list a specific address as a solver

Important

This PR breaks the API for debugging custom orders. Due to supporting more features the request now also has to contain the signature, signingScheme, feeAmount, validTo, appData, and partiallyFillable.

Things to improve

Ultimately I would like the simulator crate also to be the authority when it comes to encoding the calldata of actual settlements (which is why it already handles encoding the auction id). However, this is quite difficult to do nicely because now we have to think about correctly encoding many prices and managing wrappers and hooks from multiple orders.
For simplicity sake the builder currently does not concern itself with that. That's why you can only add wrappers and interactions from 1 appdata string directly and there is no support for encoding prices such that orders get surplus.

How to test

updated existing e2e tests (populating the new fields in the custom order simulation request)

squadgazzz · 2026-05-06T13:36:24Z

+                // GPv2AllowListAuthentication stores `mapping(address => bool) managers`
+                // at storage slot 1. Solidity mapping key: keccak256(address_padded ++
+                // slot_padded).
+                // <https://github.com/cowprotocol/contracts/blob/main/src/contracts/GPv2AllowListAuthentication.sol#L22>


The managers are at slot 0, no?

Suggested change

// GPv2AllowListAuthentication stores `mapping(address => bool) managers`

// at storage slot 1. Solidity mapping key: keccak256(address_padded ++

// slot_padded).

// <https://github.com/cowprotocol/contracts/blob/main/src/contracts/GPv2AllowListAuthentication.sol#L22>

// GPv2AllowListAuthentication stores `address manager` at slot 0

// and `mapping(address => bool) solvers` at slot 1. Solidity

// mapping key: keccak256(address_padded ++ slot_padded).

// <https://github.com/cowprotocol/contracts/blob/main/src/contracts/GPv2AllowListAuthentication.sol#L22>

Yes, the one manager address is at slot 0 but that's irrelevant for this state override so I didn't mention it in the comment.

I read the original comment as managers at storage slot 1

Ahh, now I get it. It should be mapping(address => bool) solvers not mapping(address => bool) managers

squadgazzz · 2026-05-06T13:37:58Z

+            .metadata
+            .full_app_data
+            .clone()
+            .ok_or_else(|| OrderSimulationError::Other(anyhow!("can't find appdata")))?;


Why does it return an error now?

In any case, the error message is pretty vague.

Suggested change

.ok_or_else(|| OrderSimulationError::Other(anyhow!("can't find appdata")))?;

.ok_or_else(|| OrderSimulationError::Other(anyhow!(

"order has no full_app_data stored, cannot simulate hooks/wrappers without it"

)))?;

For some time now we do expect to have the full appdata for all orders in the DB. If we can't find it we can't know whether we simulate the order correctly.
Agree that the error message should be improved. Will do that.

squadgazzz · 2026-05-06T13:40:38Z

+        - signingScheme
+        - signature


OrderSimulationRequest in crates/orderbook/src/dto/mod.rs declares app_data: String, fee_amount: U256, valid_to: u32, partially_fillable: bool - none Option, none #[serde(default)]. Serde will 422 when any is missing.

Suggested change

- signingScheme

- signature

- signingScheme

- signature

- feeAmount

- validTo

- partiallyFillable

squadgazzz · 2026-05-06T14:00:00Z

+                app_data: AppDataHash(app_data_hash.into()),
+                partially_fillable: request.partially_fillable,
+            })
+            .with_signature(request.owner, request.signature)


Did I get it correctly that this endpoint is now a different shape than before? The actual request.signature gets encoded, and the trader is no longer overridden with Trader::DEPLOYED_BYTECODE, so signature verification really runs. Existing callers who POSTed without a signature (relying on the old fake-EIP-1271 override) will start getting reverts.

The PR description hints at this ("not require the fake EIP 1271 user contract"), but it'd be worth being explicit in the changelog / breaking-changes section so nobody gets surprised.

Yes, that's exactly right. The old approach was simply not able to verify a large number of sophisticated flows so it had to be updated. Will make this clearer in the description.

squadgazzz · 2026-05-06T14:01:53Z

+        self.pre_interactions = self.encode_hooks(&protocol.hooks.pre);
+        self.post_interactions = self.encode_hooks(&protocol.hooks.post);


Should this not override the interactions, but extend them?

Suggested change

self.pre_interactions = self.encode_hooks(&protocol.hooks.pre);

self.post_interactions = self.encode_hooks(&protocol.hooks.post);

self.pre_interactions.extend(self.encode_hooks(&protocol.hooks.pre));

self.post_interactions.extend(self.encode_hooks(&protocol.hooks.post));

True. To simplify things for now I dropped interactions from the order completely. This can of worms only needs to be opened when the simulator is tasked with generating the calldata for the actual settlement txs.

If I didn't miss anything, now that Order::pre_interactions is gone, the only way to add pre/post interactions is through the builder. But the builder is inconsistent about what its setters do:

with_pre_interactions / with_post_interactions append to whatever is already there.

parameters_from_app_data replaces whatever is already there.

So if someone uses both, the call order silently decides what survives:

// foo is gone — parameters_from_app_data replaced it with the hooks .with_pre_interactions([foo]).parameters_from_app_data(json)? // foo and the hooks both end up in pre_interactions .parameters_from_app_data(json)?.with_pre_interactions([foo])

Easiest fix is to make parameters_from_app_data also append, so order doesn't matter:

self.pre_interactions.extend(self.encode_hooks(&protocol.hooks.pre)); self.post_interactions.extend(self.encode_hooks(&protocol.hooks.post));

True. That was an oversight in my fix. 👍
Fixed now.

squadgazzz · 2026-05-06T14:50:38Z

+        - signature
+        - feeAmount
+        - validTo
+        - partiallyFillable


appData is missing.

squadgazzz · 2026-05-06T14:53:07Z

+
+    /// Generates 1 interaction executing the given hooks via the trampoline
+    /// contract since executing hooks directly from the settlement contract
+    /// context would give them elevated priviliges that puts funds at risk.


Suggested change

/// context would give them elevated priviliges that puts funds at risk.

/// context would give them elevated privileges that put funds at risk.

jmg-duarte · 2026-05-07T13:58:51Z

+    #[error("overrides use incompatible storage strategies (state vs state_diff)")]
+    StateAndStateDiff,


Wouldn't a better variant name be: "IncompatibleStorageStrategies"?
As is, it's a bit confusing when reading code that returns MergeConflict::State and MergeConflict::StateAndStateDiff

squadgazzz

LGTM

squadgazzz · 2026-05-07T17:36:50Z

+        current_block: CurrentBlockWatcher,
+        tenderly: Option<Arc<dyn tenderly::Api>>,
+    ) -> Result<Self> {
+        let authenticator = Address(settlement.authenticator().call().await?.0);


Nit: I think .call().await? already returns Address here (see solvers/src/infra/config/dex/file.rs:155 which just uses the call result directly), so Address(... .0) is an identity wrap.

let authenticator = settlement.authenticator().call().await?;

The DomainSeparator(...) on the next line is fine, that one actually needs to convert B256 -> [u8; 32].

squadgazzz · 2026-05-07T17:36:50Z

+    Full,
+    /// Fill whatever is still remaining on-chain (queries the settlement
+    /// contract for the already-filled amount and subtracts it). Falls back to
+    /// the full amount if the query fails.


Doc says it falls back to the full amount if the query fails, but executed_amount in encoding.rs propagates the error via BuildError::FilledAmountQuery(...)?. It should either probably be unwrap_or(full) in the code, or the doc needs to be updated to say it errors out.

squadgazzz · 2026-05-07T17:36:50Z

+/// Construct with [`Order::new`] and add optional fields via the builder
+/// methods. Defaults to an EIP-1271 signature (pairs with [`FakeUser`] for
+/// simulations that need to bypass signature verification).
+pub struct Order {


FakeUser doesn't exist in the workspace anymore - looks like a leftover from the old approach. Either drop the parenthetical or point at whatever replaced it (looks like callers are now expected to call with_signature themselves).

MartinquaXD and others added 30 commits April 22, 2026 07:41

initial commit

ab8357b

fixup

76b12c6

fixup

d410031

introduce Solver enum

417c9a0

factory

19926d9

Only allow list specific solver address

9731a30

add function for funding settlement contract

0f03c74

add executed amounts

afedc26

Move flashloan router address into simulator thingy

db932ac

fixup

258539b

simulate(), handle fillable amounts

969ffee

Better handling of block target and executed amount

ae91cf6

Move encoding logic into separate file

2ccedbb

move code around

c1a0fe2

store chain_id and convert to tenderly request

36d46aa

current block watcher in simulator

9259b06

more fixes

fb58a25

fmt

8a0cd78

more fixes

dcdd986

correct tenderly block

6ecd600

comment for idea

93a8dda

extract wrappers from appdata

5c1f7c3

Populate properties from appdata

3f33170

.context() instead of unwrap()

7d0253a

fix tests

764d3e7

remove test log

934da39

Merge branch 'main' into new-api-simulator-crate

67d7a8a

more functionality needed for trade verification

c1aabeb

remove need for native token address in trade verification

29c2254

Nicer API for handling state overrides

9aec495

MartinquaXD added 16 commits May 6, 2026 12:03

import tenderly instead of using fully qualified paths

f7be2aa

cleaner error conversion

ed7ef9a

doc comments

7c0521f

move struct + impl together

3098ef2

move ethcallinputs to simulationbuilder

c74823f

fixup

036ed92

move struct + impl together

a37050b

Function for wrapping hooks in trampoline call

f07d4d1

match instead of ifs

2ef69f7

doc comment

667a4c7

use vec![] instead of pushing into empty vector

4a7f75e

use iterators intead of eagerly collecting into vectors

16cd8f3

Use #[from] over #[source]

e16f2da

better errors

88b8e73

prepare jit orders in separate function

65a4f0f

Merge branch 'main' into new-api-simulator-crate

c05d82c

squadgazzz reviewed May 6, 2026

View reviewed changes

MartinquaXD added 4 commits May 6, 2026 14:17

better error

5b0499c

mark fields as required in openapi spec

4698b86

don't override interactions, remove from order, drop functions

a6ab2f5

drop unnecessary dependency

121fbbc

squadgazzz reviewed May 6, 2026

View reviewed changes

MartinquaXD added 5 commits May 6, 2026 14:58

fix comment

573ae5e

mark appdata as required as well

bd8be29

comment

14e0f06

Merge branch 'main' into new-api-simulator-crate

010b1a1

extend instead over overwrite appdata interactions

edf7993

jmg-duarte reviewed May 7, 2026

View reviewed changes

squadgazzz approved these changes May 7, 2026

View reviewed changes

		self.pre_interactions = self.encode_hooks(&protocol.hooks.pre);
		self.post_interactions = self.encode_hooks(&protocol.hooks.post);

	/// context would give them elevated priviliges that puts funds at risk.
	/// context would give them elevated privileges that put funds at risk.

		#[error("overrides use incompatible storage strategies (state vs state_diff)")]
		StateAndStateDiff,

Conversation

MartinquaXD commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Things to improve

How to test

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

squadgazzz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

squadgazzz May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

MartinquaXD commented Apr 30, 2026 •

edited

Loading

squadgazzz May 7, 2026 •

edited

Loading