Volume fees in the orderbook (cowprotocol#3900)

# Description
Adds protocol volume fee support to the orderbook quote API in order to
reflect the auction fees after submitting an order using the same quote.
The quote response now includes `protocolFeeBps` ~~and
`protocolFeeSellAmount`~~ field~~s~~ when volume fees are configured,
allowing users to see the fee before placing orders.

Volume fees are applied to the surplus token (buy token for sell orders,
sell token for buy orders) following the same logic as the driver. The
orderbook adjusts quote amounts so that orders can be signed with
amounts that will be fillable after the driver applies fees during
auction competition.

The PriceImprovement and Surplus fees are based on the quotes, so it
doesn't make any sense to support them in the quote API.

# Changes
- Added `--volume-fee` CLI argument to orderbook (e.g.,
`--volume-fee=0.0002` for 0.02% or 2 basis points)
  - Accepts decimal values in range `[0, 1)` representing the fee factor
- Added optional `protocolFeeBps` (string) ~~and `protocolFeeSellAmount`
(U256)~~ field~~s~~ to `OrderQuoteResponse`
- The field~~s~~ are only present when `--volume-fee` is configured in
the orderbook

# Implementation details

  - Volume fee calculation follows driver logic:

https://github.com/cowprotocol/services/blob/31ea719f35072bc6155fdeb990bbc27c9b8833b3/crates/driver/src/domain/competition/solution/fee.rs#L185-L202
- **Sell orders**: Fee calculated on `buy_amount`, reduces the buy
amount returned in quote
- **Buy orders**: Fee calculated on `sell_amount` + network fee,
increases the sell amount returned in quote
- ~~Fee amounts are always converted to sell token for the
`protocolFeeSellAmount` field~~
- ~~Uses `quote.sell_amount/buy_amount` (final computed amounts after
network fees) rather than
`quote.data.quoted_sell_amount/quoted_buy_amount` (original exchange
rate amounts)~~

## How to test
New unit and e2e tests.


## Further configuration

This feature needs to be enabled only on a specific block. This logic
will be implemented in a follow-up PR.

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 2 people

crates/e2e/tests/e2e/quoting.rs

@@ -39,6 +39,12 @@ async fn local_node_quote_timeout() {
     run_test(quote_timeout).await;
 }
 
+#[tokio::test]
+#[ignore]
+async fn local_node_volume_fee() {
+    run_test(volume_fee).await;
+}
+
 // Test that quoting works as expected, specifically, that we can quote for a
 // token pair and additional gas from ERC-1271 and hooks are included in the
 // quoted fee amount.
@@ -403,3 +409,77 @@ async fn quote_timeout(web3: Web3) {
     assert!(res.unwrap_err().1.contains("NoLiquidity"));
     assert_within_variance(start, MAX_QUOTE_TIME_MS);
 }
+
+/// Test that volume fees are correctly applied to quotes.
+async fn volume_fee(web3: Web3) {
+    let mut onchain = OnchainComponents::deploy(web3).await;
+
+    let [solver] = onchain.make_solvers(to_wei(10)).await;
+    let [trader] = onchain.make_accounts(to_wei(10)).await;
+    let [token] = onchain
+        .deploy_tokens_with_weth_uni_v2_pools(to_wei(1_000), to_wei(1_000))
+        .await;
+
+    onchain
+        .contracts()
+        .weth
+        .approve(onchain.contracts().allowance.into_alloy(), eth(3))
+        .from(trader.address().into_alloy())
+        .send_and_watch()
+        .await
+        .unwrap();
+    onchain
+        .contracts()
+        .weth
+        .deposit()
+        .from(trader.address().into_alloy())
+        .value(eth(3))
+        .send_and_watch()
+        .await
+        .unwrap();
+
+    tracing::info!("Starting services with volume fee.");
+    let services = Services::new(&onchain).await;
+    // Start API with 0.02% (2 bps) volume fee
+    let args = ExtraServiceArgs {
+        api: vec!["--volume-fee-factor=0.0002".to_string()],
+        ..Default::default()
+    };
+    services.start_protocol_with_args(args, solver).await;
+
+    tracing::info!("Testing SELL quote with volume fee");
+    let sell_request = OrderQuoteRequest {
+        from: trader.address(),
+        sell_token: onchain.contracts().weth.address().into_legacy(),
+        buy_token: token.address().into_legacy(),
+        side: OrderQuoteSide::Sell {
+            sell_amount: SellAmount::BeforeFee {
+                value: NonZeroU256::try_from(to_wei(1)).unwrap(),
+            },
+        },
+        ..Default::default()
+    };
+
+    let sell_quote = services.submit_quote(&sell_request).await.unwrap();
+
+    // Verify protocol fee fields are present
+    assert!(sell_quote.protocol_fee_bps.is_some());
+    assert_eq!(sell_quote.protocol_fee_bps.as_ref().unwrap(), "2");
+
+    tracing::info!("Testing BUY quote with volume fee");
+    let buy_request = OrderQuoteRequest {
+        from: trader.address(),
+        sell_token: onchain.contracts().weth.address().into_legacy(),
+        buy_token: token.address().into_legacy(),
+        side: OrderQuoteSide::Buy {
+            buy_amount_after_fee: NonZeroU256::try_from(to_wei(1)).unwrap(),
+        },
+        ..Default::default()
+    };
+
+    let buy_quote = services.submit_quote(&buy_request).await.unwrap();
+
+    // Verify protocol fee fields are present
+    assert!(buy_quote.protocol_fee_bps.is_some());
+    assert_eq!(buy_quote.protocol_fee_bps.as_ref().unwrap(), "2");
+}

crates/model/src/quote.rs

@@ -324,6 +324,7 @@ pub struct OrderQuote {
 
 pub type QuoteId = i64;
 
+#[serde_as]
 #[derive(Clone, Debug, Eq, PartialEq, Deserialize, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct OrderQuoteResponse {
@@ -332,6 +333,9 @@ pub struct OrderQuoteResponse {
     pub expiration: DateTime<Utc>,
     pub id: Option<QuoteId>,
     pub verified: bool,
+    /// Protocol fee in basis points (e.g., "2" for 0.02%)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub protocol_fee_bps: Option<String>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]

crates/orderbook/openapi.yml

@@ -1682,6 +1682,20 @@ components:
             Whether it was possible to verify that the quoted amounts are
             accurate using a simulation.
           type: boolean
+        protocolFeeBps:
+          description: >
+            Protocol fee in basis points (e.g., "2" for 0.02%). This represents
+            the volume-based fee policy. Only present when configured.
+          type: string
+          example: "2"
+        protocolFeeSellAmount:
+          description: >
+            Protocol fee amount in sell token. For SELL orders, this amount is
+            already included in the returned sellAmount. For BUY orders, this
+            amount is applied before network fees are added to sellAmount. Only
+            present when a volume fee is configured.
+          allOf:
+            - $ref: "#/components/schemas/TokenAmount"
       required:
         - quote
         - expiration

crates/orderbook/src/api/post_quote.rs

@@ -318,6 +318,7 @@ mod tests {
             expiration: Utc.timestamp_millis_opt(0).unwrap(),
             id: Some(0),
             verified: false,
+            protocol_fee_bps: Some("2".to_string()),
         };
         let response = convert_json_response::<OrderQuoteResponse, OrderQuoteErrorWrapper>(Ok(
             order_quote_response.clone(),

crates/orderbook/src/arguments.rs

@@ -7,7 +7,7 @@ use {
         http_client,
         price_estimation::{self, NativePriceEstimators},
     },
-    std::{net::SocketAddr, num::NonZeroUsize, time::Duration},
+    std::{net::SocketAddr, num::NonZeroUsize, str::FromStr, time::Duration},
 };
 
 #[derive(clap::Parser)]
@@ -141,6 +141,49 @@ pub struct Arguments {
     /// whether an order is actively being bid on.
     #[clap(long, env, default_value = "5")]
     pub active_order_competition_threshold: u32,
+
+    /// Volume-based protocol fee factor to be applied to quotes.
+    /// This is a decimal value (e.g., 0.0002 for 0.02% or 2 basis points).
+    /// The fee is applied to the surplus token (buy token for sell orders,
+    /// sell token for buy orders).
+    #[clap(long, env)]
+    pub volume_fee_factor: Option<FeeFactor>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct FeeFactor(f64);
+
+impl FeeFactor {
+    /// Number of basis points that make up 100%.
+    pub const MAX_BPS: u32 = 10_000;
+
+    /// Converts the fee factor to basis points (BPS).
+    /// For example, 0.0002 -> 2 BPS
+    pub fn to_bps(&self) -> u64 {
+        (self.0 * f64::from(Self::MAX_BPS)).round() as u64
+    }
+}
+
+/// TryFrom implementation for the cases we want to enforce the constraint [0,
+/// 1)
+impl TryFrom<f64> for FeeFactor {
+    type Error = anyhow::Error;
+
+    fn try_from(value: f64) -> Result<Self, Self::Error> {
+        anyhow::ensure!(
+            (0.0..1.0).contains(&value),
+            "Factor must be in the range [0, 1)"
+        );
+        Ok(FeeFactor(value))
+    }
+}
+
+impl FromStr for FeeFactor {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        s.parse::<f64>().map(FeeFactor::try_from)?
+    }
 }
 
 impl std::fmt::Display for Arguments {
@@ -172,6 +215,7 @@ impl std::fmt::Display for Arguments {
             db_read_url,
             max_gas_per_order,
             active_order_competition_threshold,
+            volume_fee_factor: volume_fee,
         } = self;
 
         write!(f, "{shared}")?;
@@ -225,6 +269,7 @@ impl std::fmt::Display for Arguments {
             f,
             "active_order_competition_threshold: {active_order_competition_threshold}"
         )?;
+        writeln!(f, "volume_fee: {volume_fee:?}")?;
 
         Ok(())
     }