Protocol fee switch-over timestamp (cowprotocol#3907)

# Description
cowprotocol#3900 introduced a way to show the volume fees to users in advance via
quotes. Autopilot should start applying the same policies simultaneously
to avoid situations where the user receives an incorrect quote. This PR
introduces timestamp-based configs in both orderbook and autopilot
crates that control when the volume fee should start applying.

For the orderbook, it is pretty straightforward, which adds an optional
timestamp param to the existing volume fee factor config, and each time
the service tries to apply volume fees, it checks for the current time.
If the timestamp config is None, it means volume fees are applied
unconditionally, which should be useful once switched to a long-lasting
config.

The autopilot config is a bit more sophisticated. It introduces a
separate "upcoming" fee policies config with the effective "from"
timestamp. ~~So, if another order's creation timestamp is after the
configured upcoming fee policy timestamp, the service starts using this
fee policy.~~ Based on [this
discussion](cowprotocol#3907 (comment)),
the volume fee gets applied only based on the current time. This is
useful because the volume fee factor affects price improvement and
surplus fee policy caps, so each time the volume fee factor is updated,
other fee policy configs need to be adjusted accordingly, so we need to
switch to the new fee policies set altogether. The config is also
optional and can be easily switched to permanent.

The major disadvantage of this approach is that orderbook and autopilot
use configs from different sources. A more correct approach would be to
use a shared config via a DB or similar, but this would require many
more changes, and we should probably avoid any mistakes by making deeper
reviews.

## How to test
New e2e tests.

---------

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

Author: 2 people

crates/autopilot/src/arguments.rs

@@ -2,6 +2,7 @@ use {
     crate::{domain::fee::FeeFactor, infra},
     alloy::primitives::Address,
     anyhow::{Context, anyhow, ensure},
+    chrono::{DateTime, Utc},
     clap::ValueEnum,
     primitive_types::{H160, U256},
     shared::{
@@ -194,13 +195,8 @@ pub struct Arguments {
     pub solve_deadline: Duration,
 
     /// Describes how the protocol fees should be calculated.
-    #[clap(long, env, use_value_delimiter = true)]
-    pub fee_policies: Vec<FeePolicy>,
-
-    /// Maximum partner fee allow. If the partner fee specified is greater than
-    /// this maximum, the partner fee will be capped
-    #[clap(long, env, default_value = "0.01")]
-    pub fee_policy_max_partner_fee: FeeFactor,
+    #[clap(flatten)]
+    pub fee_policies_config: FeePoliciesConfig,
 
     /// Arguments for uploading information to S3.
     #[clap(flatten)]
@@ -389,8 +385,7 @@ impl std::fmt::Display for Arguments {
             submission_deadline,
             shadow,
             solve_deadline,
-            fee_policies,
-            fee_policy_max_partner_fee,
+            fee_policies_config,
             order_events_cleanup_interval,
             order_events_cleanup_threshold,
             db_write_url,
@@ -448,11 +443,7 @@ impl std::fmt::Display for Arguments {
         writeln!(f, "submission_deadline: {submission_deadline}")?;
         display_option(f, "shadow", shadow)?;
         writeln!(f, "solve_deadline: {solve_deadline:?}")?;
-        writeln!(f, "fee_policies: {fee_policies:?}")?;
-        writeln!(
-            f,
-            "fee_policy_max_partner_fee: {fee_policy_max_partner_fee:?}"
-        )?;
+        writeln!(f, "fee_policies_config: {fee_policies_config:?}")?;
         writeln!(
             f,
             "order_events_cleanup_interval: {order_events_cleanup_interval:?}"
@@ -585,6 +576,22 @@ impl FromStr for Solver {
     }
 }
 
+#[derive(clap::Parser, Debug, Clone)]
+pub struct FeePoliciesConfig {
+    /// Describes how the protocol fees should be calculated.
+    #[clap(long, env, use_value_delimiter = true)]
+    pub fee_policies: Vec<FeePolicy>,
+
+    /// Maximum partner fee allowed. If the partner fee specified is greater
+    /// than this maximum, the partner fee will be capped
+    #[clap(long, env, default_value = "0.01")]
+    pub fee_policy_max_partner_fee: FeeFactor,
+
+    /// Volume fee policies that will become effective at a future timestamp.
+    #[clap(flatten)]
+    pub upcoming_fee_policies: UpcomingFeePolicies,
+}
+
 /// A fee policy to be used for orders base on it's class.
 /// Examples:
 /// - Surplus with a high enough cap for limit orders: surplus:0.5:0.9:limit
@@ -604,6 +611,24 @@ pub struct FeePolicy {
     pub fee_policy_order_class: FeePolicyOrderClass,
 }
 
+/// Fee policies that will become effective at a future timestamp.
+#[derive(clap::Parser, Debug, Clone)]
+pub struct UpcomingFeePolicies {
+    #[clap(
+        id = "upcoming_fee_policies",
+        long = "upcoming-fee-policies",
+        env = "UPCOMING_FEE_POLICIES",
+        use_value_delimiter = true
+    )]
+    pub fee_policies: Vec<FeePolicy>,
+
+    #[clap(
+        long = "upcoming-fee-policies-timestamp",
+        env = "UPCOMING_FEE_POLICIES_TIMESTAMP"
+    )]
+    pub effective_from_timestamp: Option<DateTime<Utc>>,
+}
+
 #[derive(clap::Parser, Debug, Clone)]
 pub enum FeePolicyKind {
     /// How much of the order's surplus should be taken as a protocol fee.

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

@@ -14,6 +14,7 @@ use {
     },
     alloy::primitives::{Address, U256},
     app_data::Validator,
+    chrono::{DateTime, Utc},
     derive_more::Into,
     ethrpc::alloy::conversions::{IntoAlloy, IntoLegacy},
     primitive_types::H160,
@@ -53,25 +54,47 @@ impl From<arguments::FeePolicy> for ProtocolFee {
     }
 }
 
+pub struct UpcomingProtocolFees {
+    fee_policies: Vec<ProtocolFee>,
+    effective_from_timestamp: DateTime<Utc>,
+}
+
+impl From<arguments::UpcomingFeePolicies> for Option<UpcomingProtocolFees> {
+    fn from(value: arguments::UpcomingFeePolicies) -> Self {
+        value
+            // both config fields must be non-empty
+            .effective_from_timestamp
+            .filter(|_| !value.fee_policies.is_empty())
+            .map(|effective_from_timestamp| UpcomingProtocolFees {
+                fee_policies: value
+                    .fee_policies
+                    .into_iter()
+                    .map(ProtocolFee::from)
+                    .collect::<Vec<_>>(),
+                effective_from_timestamp,
+            })
+    }
+}
+
 pub type ProtocolFeeExemptAddresses = HashSet<H160>;
 
 pub struct ProtocolFees {
     fee_policies: Vec<ProtocolFee>,
     max_partner_fee: FeeFactor,
+    upcoming_fee_policies: Option<UpcomingProtocolFees>,
 }
 
 impl ProtocolFees {
-    pub fn new(
-        fee_policies: &[arguments::FeePolicy],
-        fee_policy_max_partner_fee: FeeFactor,
-    ) -> Self {
+    pub fn new(config: &arguments::FeePoliciesConfig) -> Self {
         Self {
-            fee_policies: fee_policies
+            fee_policies: config
+                .fee_policies
                 .iter()
                 .cloned()
                 .map(ProtocolFee::from)
                 .collect(),
-            max_partner_fee: fee_policy_max_partner_fee,
+            max_partner_fee: config.fee_policy_max_partner_fee,
+            upcoming_fee_policies: config.upcoming_fee_policies.clone().into(),
         }
     }
 
@@ -230,13 +253,21 @@ impl ProtocolFees {
         quote: domain::Quote,
         partner_fees: Vec<Policy>,
     ) -> domain::Order {
-        let protocol_fees = self
-            .fee_policies
+        let now = Utc::now();
+        let fee_policies = self
+            .upcoming_fee_policies
+            .as_ref()
+            .filter(|upcoming| upcoming.effective_from_timestamp <= now)
+            .map(|upcoming| &upcoming.fee_policies)
+            .unwrap_or(&self.fee_policies);
+
+        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))
             .chain(partner_fees)
             .collect::<Vec<_>>();
+
         boundary::order::to_domain(order, protocol_fees, Some(quote))
     }
 

crates/autopilot/src/run.rs

@@ -538,7 +538,7 @@ 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, args.fee_policy_max_partner_fee),
+        domain::ProtocolFees::new(&args.fee_policies_config),
         cow_amm_registry.clone(),
         args.run_loop_native_price_timeout,
         eth.contracts().settlement().address().into_legacy(),

crates/e2e/src/setup/fee.rs

@@ -1,4 +1,16 @@
-pub struct ProtocolFeesConfig(pub Vec<ProtocolFee>);
+use chrono::{DateTime, Utc};
+
+#[derive(Default)]
+pub struct ProtocolFeesConfig {
+    pub protocol_fees: Vec<ProtocolFee>,
+    pub upcoming_protocol_fees: Option<UpcomingProtocolFees>,
+}
+
+#[derive(Clone)]
+pub struct UpcomingProtocolFees {
+    pub fee_policies: Vec<ProtocolFee>,
+    pub effective_from_timestamp: DateTime<Utc>,
+}
 
 #[derive(Clone)]
 pub struct ProtocolFee {
@@ -57,14 +69,31 @@ impl std::fmt::Display for ProtocolFee {
     }
 }
 
-impl std::fmt::Display for ProtocolFeesConfig {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+impl ProtocolFeesConfig {
+    pub fn into_args(self) -> Vec<String> {
+        let mut args = Vec::new();
         let fees_str = self
-            .0
+            .protocol_fees
             .iter()
             .map(|fee| fee.to_string())
             .collect::<Vec<_>>()
             .join(",");
-        write!(f, "--fee-policies={fees_str}")
+        args.push(format!("--fee-policies={fees_str}"));
+
+        if let Some(upcoming_protocol_fees) = &self.upcoming_protocol_fees {
+            let upcoming_fees_str = upcoming_protocol_fees
+                .fee_policies
+                .iter()
+                .map(|fee| fee.to_string())
+                .collect::<Vec<_>>()
+                .join(",");
+            args.push(format!("--upcoming-fee-policies={}", upcoming_fees_str));
+            args.push(format!(
+                "--upcoming-fee-policies-timestamp={}",
+                upcoming_protocol_fees.effective_from_timestamp.to_rfc3339()
+            ));
+        }
+
+        args
     }
 }

crates/e2e/tests/e2e/limit_orders.rs

@@ -1066,32 +1066,36 @@ async fn no_liquidity_limit_order(web3: Web3) {
         .unwrap();
 
     // Setup services
-    let protocol_fees_config = ProtocolFeesConfig(vec![
-        ProtocolFee {
-            policy: fee::FeePolicyKind::Surplus {
-                factor: 0.5,
-                max_volume_factor: 0.01,
+    let protocol_fee_args = ProtocolFeesConfig {
+        protocol_fees: vec![
+            ProtocolFee {
+                policy: fee::FeePolicyKind::Surplus {
+                    factor: 0.5,
+                    max_volume_factor: 0.01,
+                },
+                policy_order_class: FeePolicyOrderClass::Limit,
             },
-            policy_order_class: FeePolicyOrderClass::Limit,
-        },
-        ProtocolFee {
-            policy: fee::FeePolicyKind::PriceImprovement {
-                factor: 0.5,
-                max_volume_factor: 0.01,
+            ProtocolFee {
+                policy: fee::FeePolicyKind::PriceImprovement {
+                    factor: 0.5,
+                    max_volume_factor: 0.01,
+                },
+                policy_order_class: FeePolicyOrderClass::Market,
             },
-            policy_order_class: FeePolicyOrderClass::Market,
-        },
-    ])
-    .to_string();
+        ],
+        ..Default::default()
+    }
+    .into_args();
 
     let services = Services::new(&onchain).await;
     services
         .start_protocol_with_args(
             ExtraServiceArgs {
-                autopilot: vec![
-                    protocol_fees_config,
-                    format!("--unsupported-tokens={:#x}", unsupported.address()),
-                ],
+                autopilot: [
+                    protocol_fee_args,
+                    vec![format!("--unsupported-tokens={:#x}", unsupported.address())],
+                ]
+                .concat(),
                 ..Default::default()
             },
             solver,