Volume fees in the orderbook

Author: squadgazzz

Cargo.lock

@@ -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,106 @@ 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) {
+    tracing::info!("Setting up chain state.");
+    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=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");
+    assert!(sell_quote.protocol_fee_sell_amount.is_some());
+
+    // For SELL orders: buy_amount should be reduced by the protocol fee
+    let protocol_fee_sell_amount = sell_quote
+        .protocol_fee_sell_amount
+        .unwrap()
+        .to_string()
+        .parse::<u128>()
+        .unwrap();
+    assert!(
+        protocol_fee_sell_amount > 0,
+        "Protocol fee should be non-zero"
+    );
+
+    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");
+    assert!(buy_quote.protocol_fee_sell_amount.is_some());
+
+    // For BUY orders: sell_amount should be increased by the protocol fee
+    let protocol_fee_sell_amount_buy = buy_quote
+        .protocol_fee_sell_amount
+        .unwrap()
+        .to_string()
+        .parse::<u128>()
+        .unwrap();
+    assert!(
+        protocol_fee_sell_amount_buy > 0,
+        "Protocol fee should be non-zero for buy orders"
+    );
+
+    tracing::info!("Volume fee test passed");
+}

crates/e2e/tests/e2e/quoting.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,14 @@ 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>,
+    /// Protocol fee amount in sell token, already included in sellAmount for
+    /// SELL orders, or applied before network fees for BUY orders
+    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(as = "Option<HexOrDecimalU256>")]
+    pub protocol_fee_sell_amount: Option<U256>,
 }
 
 #[derive(Debug, Serialize, Deserialize)]

crates/model/src/quote.rs

@@ -27,6 +27,7 @@ chrono = { workspace = true, features = ["clock"] }
 clap = { workspace = true }
 contracts = { workspace = true }
 database = { workspace = true }
+derive_more = { workspace = true }
 ethcontract = { workspace = true }
 ethrpc = { workspace = true }
 futures = { workspace = true }
@@ -59,6 +60,7 @@ warp = { workspace = true }
 
 [dev-dependencies]
 mockall = { workspace = true }
+shared = { workspace = true, features = ["test-util"] }
 tokio = { workspace = true, features = ["test-util"] }
 
 [build-dependencies]

crates/orderbook/Cargo.toml

@@ -1682,6 +1682,19 @@ 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.
+          $ref: "#/components/schemas/TokenAmount"
       required:
         - quote
         - expiration

crates/orderbook/openapi.yml

@@ -105,6 +105,7 @@ mod tests {
             },
         },
         number::nonzero::U256 as NonZeroU256,
+        primitive_types::U256,
         reqwest::StatusCode,
         serde_json::json,
         shared::order_quoting::CalculateQuoteError,
@@ -318,6 +319,8 @@ mod tests {
             expiration: Utc.timestamp_millis_opt(0).unwrap(),
             id: Some(0),
             verified: false,
+            protocol_fee_bps: Some("2".to_string()),
+            protocol_fee_sell_amount: Some(U256::from(20)),
         };
         let response = convert_json_response::<OrderQuoteResponse, OrderQuoteErrorWrapper>(Ok(
             order_quote_response.clone(),

crates/orderbook/src/api/post_quote.rs

@@ -1,13 +1,14 @@
 use {
     alloy::primitives::Address,
+    derive_more::Into,
     reqwest::Url,
     shared::{
         arguments::{display_option, display_secret_option},
         bad_token::token_owner_finder,
         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 +142,48 @@ 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: Option<FeeFactor>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Into)]
+pub struct FeeFactor(f64);
+
+impl FeeFactor {
+    /// Number of basis points that make up 100%.
+    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 constrain [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,
         } = 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(())
     }