Add block number to order simulation (#4305)

# Description
The order simulation endpoint would always run against the latest block.
It is limiting for investigating already filled or partially filled
orders.

# Changes
Add query parameter to the order simulation endpoint to allow specifying
a block number

## How to test
E2E test creates an order, withdraws trader's sell tokens on block A and
funds the account on block B. The order simulation fails for block A and
succeeds for block B.

---------

Co-authored-by: José Duarte <duarte.gmj@gmail.com>
Co-authored-by: ilya <ilya@cow.fi>

Author: 3 people

Cargo.lock

@@ -1,4 +1,5 @@
 use {
+    alloy::{primitives::Address, providers::Provider},
     configs::test_util::TestDefault,
     e2e::setup::{API_HOST, OnchainComponents, Services, run_test},
     ethrpc::{Web3, alloy::CallBuilderExt},
@@ -18,6 +19,12 @@ async fn local_node_order_simulation() {
     run_test(order_simulation).await;
 }
 
+#[tokio::test]
+#[ignore]
+async fn local_node_order_simulation_block_number() {
+    run_test(order_simulation_block_number).await;
+}
+
 async fn order_simulation(web3: Web3) {
     let mut onchain = OnchainComponents::deploy(web3.clone()).await;
 
@@ -87,3 +94,115 @@ async fn order_simulation(web3: Web3) {
     assert_eq!(tenderly.simulation_type, Some(SimulationType::Full));
     assert_eq!(tenderly.value, None);
 }
+
+async fn order_simulation_block_number(web3: Web3) {
+    let mut onchain = OnchainComponents::deploy(web3.clone()).await;
+
+    let [solver] = onchain.make_solvers(10u64.eth()).await;
+    let [trader] = onchain.make_accounts(10u64.eth()).await;
+    let [token] = onchain
+        .deploy_tokens_with_weth_uni_v2_pools(1_000u64.eth(), 1_000u64.eth())
+        .await;
+
+    // Fund trader so the order passes balance validation at submission time.
+    onchain
+        .contracts()
+        .weth
+        .deposit()
+        .from(trader.address())
+        .value(3u64.eth())
+        .send_and_watch()
+        .await
+        .unwrap();
+    onchain
+        .contracts()
+        .weth
+        .approve(onchain.contracts().allowance, 3u64.eth())
+        .from(trader.address())
+        .send_and_watch()
+        .await
+        .unwrap();
+
+    let services = Services::new(&onchain).await;
+    services
+        .start_protocol_with_args(
+            configs::autopilot::Configuration::test("test_solver", solver.address()),
+            configs::orderbook::Configuration::test_default(),
+            solver,
+        )
+        .await;
+
+    let order = OrderCreation {
+        sell_token: *onchain.contracts().weth.address(),
+        sell_amount: 2u64.eth(),
+        buy_token: *token.address(),
+        buy_amount: 1u64.eth(),
+        valid_to: model::time::now_in_epoch_seconds() + 300,
+        kind: OrderKind::Buy,
+        ..Default::default()
+    }
+    .sign(
+        EcdsaSigningScheme::Eip712,
+        &onchain.contracts().domain_separator,
+        &trader.signer,
+    );
+    let uid = services.create_order(&order).await.unwrap();
+
+    // Transfer all WETH away from the trader — now they have no sell-token
+    // balance. The current block becomes the "no funds" snapshot.
+    let burn = Address::from([0x42u8; 20]);
+    onchain
+        .contracts()
+        .weth
+        .transfer(burn, 3u64.eth())
+        .from(trader.address())
+        .send_and_watch()
+        .await
+        .unwrap();
+    let block_no_funds = web3.provider.get_block_number().await.unwrap();
+
+    // Re-deposit WETH. The current block now has the trader fully funded again.
+    onchain
+        .contracts()
+        .weth
+        .deposit()
+        .from(trader.address())
+        .value(3u64.eth())
+        .send_and_watch()
+        .await
+        .unwrap();
+    let block_with_funds = web3.provider.get_block_number().await.unwrap();
+
+    let client = services.client();
+
+    // Simulation at the block where the trader had no WETH must fail.
+    let response = client
+        .get(format!(
+            "{API_HOST}/api/v1/debug/simulation/{uid}?block_number={block_no_funds}"
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let result = response.json::<OrderSimulationResult>().await.unwrap();
+    assert!(
+        result.error.is_some(),
+        "expected simulation failure at block {block_no_funds} (no funds), got success"
+    );
+
+    // Simulation at the block where the trader has WETH must succeed.
+    let response = client
+        .get(format!(
+            "{API_HOST}/api/v1/debug/simulation/{uid}?block_number={block_with_funds}"
+        ))
+        .send()
+        .await
+        .unwrap();
+    assert_eq!(response.status(), StatusCode::OK);
+    let result = response.json::<OrderSimulationResult>().await.unwrap();
+    assert_eq!(
+        result.error, None,
+        "expected simulation success at block {block_with_funds} (funded), got error: {:?}",
+        result.error
+    );
+}

crates/e2e/tests/e2e/order_simulation.rs

@@ -33,6 +33,7 @@ configs = { workspace = true }
 const-hex = { workspace = true }
 contracts = { workspace = true }
 database = { workspace = true }
+eth-domain-types = { workspace = true }
 ethrpc = { workspace = true }
 futures = { workspace = true }
 gas-price-estimation = { workspace = true }

crates/orderbook/Cargo.toml

@@ -778,6 +778,15 @@ paths:
           schema:
             $ref: "#/components/schemas/UID"
           required: true
+        - in: query
+          name: block_number
+          schema:
+            type: integer
+            format: int64
+          required: false
+          description: >
+            Block number to simulate the order at. If not specified, the
+            simulation uses the latest block.
       responses:
         "200":
           description: Simulation request returned.

crates/orderbook/openapi.yml

@@ -1,19 +1,30 @@
 use {
     crate::{api::AppState, orderbook::OrderSimulationError},
     axum::{
-        extract::{Path, State},
+        extract::{Path, Query, State},
         http::StatusCode,
         response::{IntoResponse, Json, Response},
     },
     model::order::OrderUid,
+    serde::Deserialize,
     std::sync::Arc,
 };
 
+#[derive(Deserialize)]
+pub struct SimulationQuery {
+    pub block_number: Option<u64>,
+}
+
 pub async fn debug_simulation_handler(
     State(state): State<Arc<AppState>>,
     Path(uid): Path<OrderUid>,
+    Query(params): Query<SimulationQuery>,
 ) -> Response {
-    match state.orderbook.simulate_order(&uid).await {
+    match state
+        .orderbook
+        .simulate_order(&uid, params.block_number)
+        .await
+    {
         Ok(Some(result)) => (StatusCode::OK, Json(result)).into_response(),
         Ok(None) => (
             StatusCode::NOT_FOUND,

crates/orderbook/src/api/debug_simulation.rs

@@ -7,6 +7,7 @@ use {
     anyhow::{Context, Result},
     balance_overrides::BalanceOverrideRequest,
     contracts::alloy::support::{AnyoneAuthenticator, Trader},
+    eth_domain_types::BlockNo,
     model::order::Order,
     simulator::{
         encoding::InteractionEncoding,
@@ -81,8 +82,17 @@ impl OrderSimulator {
     /// The result contains the transaction simulation error (if any)
     /// and a full API request object that can be used to resimulate the swap
     /// using Tenderly.
-    pub async fn simulate_swap(&self, swap: EncodedSwap) -> Result<OrderSimulationResult> {
-        let result = self.simulator.simulate_settle_call(swap).await?;
+    pub async fn simulate_swap(
+        &self,
+        swap: EncodedSwap,
+        block_number: Option<u64>,
+    ) -> Result<OrderSimulationResult> {
+        let block_number =
+            block_number.unwrap_or_else(|| self.simulator.current_block.borrow().number);
+        let result = self
+            .simulator
+            .simulate_settle_call(swap, Some(block_number))
+            .await?;
 
         let tenderly_request = simulator::tenderly::dto::Request {
             transaction_index: None,
@@ -92,7 +102,7 @@ impl OrderSimulator {
                 self.chain_id.clone(),
                 &result.tx,
                 result.overrides,
-                None,
+                Some(BlockNo(block_number)),
             )?
         };
 

crates/orderbook/src/order_simulator.rs

@@ -616,6 +616,7 @@ impl Orderbook {
     pub async fn simulate_order(
         &self,
         uid: &OrderUid,
+        block_number: Option<u64>,
     ) -> Result<Option<OrderSimulationResult>, OrderSimulationError> {
         let Some(order_simulator) = &self.order_simulator else {
             return Err(OrderSimulationError::NotEnabled);
@@ -634,7 +635,7 @@ impl Orderbook {
             .map_err(OrderSimulationError::Other)?;
         Ok(Some(
             order_simulator
-                .simulate_swap(swap)
+                .simulate_swap(swap, block_number)
                 .await
                 .map_err(OrderSimulationError::Other)?,
         ))

crates/orderbook/src/orderbook.rs

@@ -235,8 +235,12 @@ impl SwapSimulator {
         })
     }
 
-    pub async fn simulate_settle_call(&self, swap: EncodedSwap) -> Result<SwapSimulation<Bytes>> {
-        let block = *self.current_block.borrow();
+    pub async fn simulate_settle_call(
+        &self,
+        swap: EncodedSwap,
+        block_number: Option<u64>,
+    ) -> Result<SwapSimulation<Bytes>> {
+        let block_number = block_number.unwrap_or_else(|| self.current_block.borrow().number);
         let (settlement_target, calldata) = self.get_target_and_calldata(&swap);
 
         let overrides = swap.overrides;
@@ -253,7 +257,7 @@ impl SwapSimulator {
             .provider
             .call(tx.clone())
             .overrides(overrides.clone())
-            .block(block.number.into())
+            .block(block_number.into())
             .await
             .map_err(|err| anyhow!(err));