Add volume fee overrides (#3976)

# Description

Implements volume fee bucket overrides, allowing custom volume fees for
groups of tokens. This enables us to have different fees for a chosen
set of tokens, e.g. stable coins.

# Changes
<!-- List of detailed changes (how the change is accomplished) -->

- [x] Added `--volume-fee-bucket-overrides` CLI argument
- Format: `"factor:token1,token2,..."` (e.g.,
`"0:0xA0b86...,0x6B175...,0xdAC17..."`)
  - Multiple buckets separated by semicolons
- [x] Both buy and sell tokens must be in the same bucket for the
override to apply
- [x] Adjusts quote (orderbook) and order (autopilot)
- [x] For buy token=sell token no fee applies 

## How to test

```
cargo test --package e2e --test e2e protocol_fee::local_node_volume_fee_overrides
```

---------

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

Author: fafk

crates/autopilot/src/arguments.rs

@@ -1,11 +1,11 @@
 use {
-    crate::{domain::fee::FeeFactor, infra},
+    crate::infra,
     alloy::primitives::{Address, U256},
     anyhow::{Context, anyhow, ensure},
     chrono::{DateTime, Utc},
     clap::ValueEnum,
     shared::{
-        arguments::{display_list, display_option, display_secret_option},
+        arguments::{FeeFactor, display_list, display_option, display_secret_option},
         bad_token::token_owner_finder,
         http_client,
         price_estimation::{self, NativePriceEstimators},

crates/autopilot/src/domain/fee/mod.rs

@@ -15,9 +15,12 @@ use {
     alloy::primitives::{Address, U256},
     app_data::Validator,
     chrono::{DateTime, Utc},
-    derive_more::Into,
     rust_decimal::Decimal,
-    std::{collections::HashSet, str::FromStr},
+    shared::{
+        arguments::{FeeFactor, TokenBucketFeeOverride},
+        fee::VolumeFeePolicy,
+    },
+    std::collections::HashSet,
 };
 
 #[derive(Debug)]
@@ -80,10 +83,20 @@ pub struct ProtocolFees {
     fee_policies: Vec<ProtocolFee>,
     max_partner_fee: FeeFactor,
     upcoming_fee_policies: Option<UpcomingProtocolFees>,
+    volume_fee_policy: VolumeFeePolicy,
 }
 
 impl ProtocolFees {
-    pub fn new(config: &arguments::FeePoliciesConfig) -> Self {
+    pub fn new(
+        config: &arguments::FeePoliciesConfig,
+        volume_fee_bucket_overrides: Vec<TokenBucketFeeOverride>,
+        enable_sell_equals_buy_volume_fee: bool,
+    ) -> Self {
+        let volume_fee_policy = VolumeFeePolicy::new(
+            volume_fee_bucket_overrides,
+            None, // contained within FeePoliciesConfig; vol fee is passed in at callsite
+            enable_sell_equals_buy_volume_fee,
+        );
         Self {
             fee_policies: config
                 .fee_policies
@@ -93,6 +106,7 @@ impl ProtocolFees {
                 .collect(),
             max_partner_fee: config.fee_policy_max_partner_fee,
             upcoming_fee_policies: config.upcoming_fee_policies.clone().into(),
+            volume_fee_policy,
         }
     }
 
@@ -134,7 +148,7 @@ impl ProtocolFees {
             // update the `accumulated` value
             *accumulated += value.min(cap - *accumulated);
 
-            FeeFactor(f64::try_from(value.max(Decimal::ZERO).min(remaining_factor)).unwrap())
+            FeeFactor::new(f64::try_from(value.max(Decimal::ZERO).min(remaining_factor)).unwrap())
         }
 
         fn fee_factor_from_bps(bps: u64) -> FeeFactor {
@@ -236,7 +250,7 @@ impl ProtocolFees {
         });
 
         let partner_fee =
-            Self::get_partner_fee(&order, &reference_quote, self.max_partner_fee.into());
+            Self::get_partner_fee(&order, &reference_quote, self.max_partner_fee.get());
 
         if surplus_capturing_jit_order_owners.contains(&order.metadata.owner) {
             return boundary::order::to_domain(order, partner_fee, quote);
@@ -262,22 +276,23 @@ impl ProtocolFees {
         let protocol_fees = fee_policies
             .iter()
             .filter_map(|fee_policy| Self::protocol_fee_into_policy(&order, &quote, fee_policy))
-            .flat_map(|policy| Self::variant_fee_apply(&order, &quote, policy))
+            .flat_map(|policy| self.variant_fee_apply(&order, &quote, policy))
             .chain(partner_fees)
             .collect::<Vec<_>>();
 
         boundary::order::to_domain(order, protocol_fees, Some(quote))
     }
 
     fn variant_fee_apply(
+        &self,
         order: &boundary::Order,
         quote: &domain::Quote,
         policy: &policy::Policy,
     ) -> Option<Policy> {
         match policy {
             policy::Policy::Surplus(variant) => variant.apply(order),
             policy::Policy::PriceImprovement(variant) => variant.apply(order, quote),
-            policy::Policy::Volume(variant) => variant.apply(order),
+            policy::Policy::Volume(variant) => variant.apply(order, &self.volume_fee_policy),
         }
     }
 
@@ -332,30 +347,6 @@ pub enum Policy {
     },
 }
 
-#[derive(Debug, Clone, Copy, PartialEq, Into)]
-pub struct FeeFactor(f64);
-
-/// 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)?
-    }
-}
-
 #[derive(Debug, Copy, Clone, PartialEq)]
 pub struct Quote {
     /// The amount of the sell token.
@@ -423,10 +414,10 @@ mod test {
             result,
             vec![
                 Policy::Volume {
-                    factor: FeeFactor(0.05),
+                    factor: FeeFactor::try_from(0.05).unwrap(),
                 },
                 Policy::Volume {
-                    factor: FeeFactor(0.2),
+                    factor: FeeFactor::try_from(0.2).unwrap(),
                 }
             ]
         );
@@ -497,7 +488,7 @@ mod test {
         assert_eq!(
             result,
             vec![Policy::Volume {
-                factor: FeeFactor(0.0),
+                factor: FeeFactor::try_from(0.0).unwrap(),
             }]
         );
     }
@@ -542,10 +533,10 @@ mod test {
             result,
             vec![
                 Policy::Volume {
-                    factor: FeeFactor(0.0),
+                    factor: FeeFactor::try_from(0.0).unwrap(),
                 },
                 Policy::Volume {
-                    factor: FeeFactor(0.0),
+                    factor: FeeFactor::try_from(0.0).unwrap(),
                 }
             ]
         );
@@ -586,7 +577,7 @@ mod test {
         assert_eq!(
             result,
             vec![Policy::Volume {
-                factor: FeeFactor(0.3),
+                factor: FeeFactor::try_from(0.3).unwrap(),
             }]
         );
     }
@@ -634,10 +625,10 @@ mod test {
             result,
             vec![
                 Policy::Volume {
-                    factor: FeeFactor(0.1),
+                    factor: FeeFactor::try_from(0.1).unwrap(),
                 },
                 Policy::Volume {
-                    factor: FeeFactor(0.18181818181818182),
+                    factor: FeeFactor::try_from(0.18181818181818182).unwrap(),
                 }
             ]
         );
@@ -691,13 +682,13 @@ mod test {
             result,
             vec![
                 Policy::Volume {
-                    factor: FeeFactor(0.1),
+                    factor: FeeFactor::try_from(0.1).unwrap(),
                 },
                 Policy::Volume {
-                    factor: FeeFactor(0.18181818181818182),
+                    factor: FeeFactor::try_from(0.18181818181818182).unwrap(),
                 },
                 Policy::Volume {
-                    factor: FeeFactor(0.0),
+                    factor: FeeFactor::try_from(0.0).unwrap(),
                 }
             ]
         );

crates/autopilot/src/domain/fee/policy.rs

@@ -1,10 +1,10 @@
-use crate::{
-    arguments,
-    boundary,
-    domain::{
-        self,
-        fee::{FeeFactor, Quote},
+use {
+    crate::{
+        arguments,
+        boundary,
+        domain::{self, fee::Quote},
     },
+    shared::{arguments::FeeFactor, fee::VolumeFeePolicy},
 };
 
 pub enum Policy {
@@ -84,13 +84,24 @@ impl PriceImprovement {
 }
 
 impl Volume {
-    pub fn apply(&self, order: &boundary::Order) -> Option<domain::fee::Policy> {
+    pub fn apply(
+        &self,
+        order: &boundary::Order,
+        volume_fee_policy: &VolumeFeePolicy,
+    ) -> Option<domain::fee::Policy> {
         match order.metadata.class {
             boundary::OrderClass::Market => None,
             boundary::OrderClass::Liquidity => None,
-            boundary::OrderClass::Limit => Some(domain::fee::Policy::Volume {
-                factor: self.factor,
-            }),
+            boundary::OrderClass::Limit => {
+                // Use shared function to determine applicable volume fee factor
+                let factor = volume_fee_policy.get_applicable_volume_fee_factor(
+                    order.data.buy_token,
+                    order.data.sell_token,
+                    Some(self.factor),
+                )?;
+
+                Some(domain::fee::Policy::Volume { factor })
+            }
         }
     }
 }

crates/autopilot/src/domain/settlement/trade/math.rs

@@ -321,8 +321,8 @@ impl Trade {
             } => {
                 let surplus = self.surplus_over_limit_price()?;
                 std::cmp::min(
-                    self.surplus_fee(surplus, (*factor).into())?,
-                    self.volume_fee((*max_volume_factor).into())?,
+                    self.surplus_fee(surplus, (*factor).get())?,
+                    self.volume_fee((*max_volume_factor).get())?,
                 )
             }
             fee::Policy::PriceImprovement {
@@ -332,11 +332,11 @@ impl Trade {
             } => {
                 let price_improvement = self.price_improvement(quote)?;
                 std::cmp::min(
-                    self.surplus_fee(price_improvement, (*factor).into())?,
-                    self.volume_fee((*max_volume_factor).into())?,
+                    self.surplus_fee(price_improvement, (*factor).get())?,
+                    self.volume_fee((*max_volume_factor).get())?,
                 )
             }
-            fee::Policy::Volume { factor } => self.volume_fee((*factor).into())?,
+            fee::Policy::Volume { factor } => self.volume_fee((*factor).get())?,
         };
         Ok(fee)
     }

crates/autopilot/src/infra/persistence/dto/fee_policy.rs

@@ -17,8 +17,8 @@ pub fn from_domain(
             auction_id,
             order_uid: boundary::database::byte_array::ByteArray(order_uid.0),
             kind: FeePolicyKind::Surplus,
-            surplus_factor: Some(factor.into()),
-            surplus_max_volume_factor: Some(max_volume_factor.into()),
+            surplus_factor: Some(factor.get()),
+            surplus_max_volume_factor: Some(max_volume_factor.get()),
             volume_factor: None,
             price_improvement_factor: None,
             price_improvement_max_volume_factor: None,
@@ -29,7 +29,7 @@ pub fn from_domain(
             kind: FeePolicyKind::Volume,
             surplus_factor: None,
             surplus_max_volume_factor: None,
-            volume_factor: Some(factor.into()),
+            volume_factor: Some(factor.get()),
             price_improvement_factor: None,
             price_improvement_max_volume_factor: None,
         },
@@ -44,8 +44,8 @@ pub fn from_domain(
             surplus_factor: None,
             surplus_max_volume_factor: None,
             volume_factor: None,
-            price_improvement_factor: Some(factor.into()),
-            price_improvement_max_volume_factor: Some(max_volume_factor.into()),
+            price_improvement_factor: Some(factor.get()),
+            price_improvement_max_volume_factor: Some(max_volume_factor.get()),
         },
     }
 }

crates/autopilot/src/infra/persistence/dto/order.rs

@@ -1,13 +1,14 @@
 use {
     crate::{
         boundary::{self},
-        domain::{self, OrderUid, eth, fee::FeeFactor},
+        domain::{self, OrderUid, eth},
     },
     alloy::primitives::{Address, U256},
     app_data::AppDataHash,
     number::serialization::HexOrDecimalU256,
     serde::{Deserialize, Serialize},
     serde_with::serde_as,
+    shared::arguments::FeeFactor,
 };
 
 #[serde_as]
@@ -277,16 +278,16 @@ impl FeePolicy {
                 factor,
                 max_volume_factor,
             } => Self::Surplus {
-                factor: factor.into(),
-                max_volume_factor: max_volume_factor.into(),
+                factor: factor.get(),
+                max_volume_factor: max_volume_factor.get(),
             },
             domain::fee::Policy::PriceImprovement {
                 factor,
                 max_volume_factor,
                 quote,
             } => Self::PriceImprovement {
-                factor: factor.into(),
-                max_volume_factor: max_volume_factor.into(),
+                factor: factor.get(),
+                max_volume_factor: max_volume_factor.get(),
                 quote: Quote {
                     sell_amount: quote.sell_amount,
                     buy_amount: quote.buy_amount,
@@ -295,7 +296,7 @@ impl FeePolicy {
                 },
             },
             domain::fee::Policy::Volume { factor } => Self::Volume {
-                factor: factor.into(),
+                factor: factor.get(),
             },
         }
     }

crates/autopilot/src/run.rs

@@ -518,7 +518,11 @@ pub async fn run(args: Arguments, shutdown_controller: ShutdownController) {
         args.limit_order_price_factor
             .try_into()
             .expect("limit order price factor can't be converted to BigDecimal"),
-        domain::ProtocolFees::new(&args.fee_policies_config),
+        domain::ProtocolFees::new(
+            &args.fee_policies_config,
+            args.shared.volume_fee_bucket_overrides.clone(),
+            args.shared.enable_sell_equals_buy_volume_fee,
+        ),
         cow_amm_registry.clone(),
         args.run_loop_native_price_timeout,
         *eth.contracts().settlement().address(),