Rank by surplus driver V3 (#2448)

Replacement for #2406 and
#2421

Implements task 1 from
#2382

Fixes #1494

# Description
Implements surplus and protocol fees calculation, **based on the
solution (received from solvers) trades, which are in a settlement smart
contract format**. This ensures that these values are calculated after
the protocol fee is already applied and the whole settlement is prepared
for settling. This is important because the autopilot (and reward
script) will use the same math so we are aligned 1:1.

The main calculation is in
`crates/driver/src/domain/competition/settled/mod.rs`.

CIP38 scoring is currently called in a read only mode. The score is
calculated but not used.

## How to test
Tested locally with e2e tests. Surplus + protocol fee is always equal to
legacy `quality` - `surplus_fee` which is expected.

crates/driver/src/boundary/settlement.rs

@@ -15,7 +15,7 @@ use {
         infra::Ethereum,
         util::conv::u256::U256Ext,
     },
-    anyhow::{anyhow, Context, Result},
+    anyhow::{anyhow, Context, Ok, Result},
     model::{
         app_data::AppDataHash,
         interaction::InteractionData,
@@ -167,6 +167,7 @@ impl Settlement {
                     gas_amount: None,
                 }
             }
+            competition::SolverScore::Surplus => http_solver::model::Score::Surplus,
         };
 
         Ok(Self {
@@ -211,6 +212,7 @@ impl Settlement {
                 success_probability,
                 ..
             } => competition::SolverScore::RiskAdjusted(success_probability),
+            http_solver::model::Score::Surplus => competition::SolverScore::Surplus,
         }
     }
 

crates/driver/src/domain/competition/auction.rs

@@ -8,7 +8,7 @@ use {
             time,
         },
         infra::{self, blockchain, observe, Ethereum},
-        util,
+        util::{self},
     },
     futures::future::{join_all, BoxFuture, FutureExt, Shared},
     itertools::Itertools,
@@ -112,6 +112,18 @@ impl Auction {
     pub fn score_cap(&self) -> Score {
         self.score_cap
     }
+
+    pub fn prices(&self) -> Prices {
+        self.tokens
+            .0
+            .iter()
+            .filter_map(|(address, token)| token.price.map(|price| (*address, price)))
+            .chain(std::iter::once((
+                eth::ETH_TOKEN,
+                eth::U256::exp10(18).into(),
+            )))
+            .collect()
+    }
 }
 
 #[derive(Clone)]
@@ -418,6 +430,9 @@ impl From<eth::U256> for Price {
     }
 }
 
+/// All auction prices
+pub type Prices = HashMap<eth::TokenAddress, Price>;
+
 #[derive(Debug, Clone, Copy)]
 pub struct Id(pub i64);
 

crates/driver/src/domain/competition/score.rs

@@ -67,6 +67,8 @@ pub enum Error {
     #[error(transparent)]
     RiskAdjusted(#[from] risk::Error),
     #[error(transparent)]
+    Scoring(#[from] super::solution::error::Scoring),
+    #[error(transparent)]
     Boundary(#[from] boundary::Error),
 }
 

crates/driver/src/domain/competition/solution/fee.rs

@@ -34,6 +34,7 @@ use {
         },
         eth,
     },
+    bigdecimal::Zero,
 };
 
 impl Fulfillment {
@@ -50,7 +51,7 @@ impl Fulfillment {
                 Fee::Static
             }
             Some(fee) => {
-                Fee::Dynamic((fee.0.checked_add(protocol_fee).ok_or(Math::Overflow)?).into())
+                Fee::Dynamic((fee.0.checked_add(protocol_fee.0).ok_or(Math::Overflow)?).into())
             }
         };
 
@@ -63,7 +64,7 @@ impl Fulfillment {
             order::Side::Sell => order::TargetAmount(
                 self.executed()
                     .0
-                    .checked_sub(protocol_fee)
+                    .checked_sub(protocol_fee.0)
                     .ok_or(Math::Overflow)?,
             ),
         };
@@ -72,7 +73,7 @@ impl Fulfillment {
     }
 
     /// Computed protocol fee in surplus token.
-    fn protocol_fee(&self, prices: ClearingPrices) -> Result<eth::U256, Error> {
+    fn protocol_fee(&self, prices: ClearingPrices) -> Result<eth::TokenAmount, Error> {
         // TODO: support multiple fee policies
         if self.order().protocol_fees.len() > 1 {
             return Err(Error::MultipleFeePolicies);
@@ -120,7 +121,7 @@ impl Fulfillment {
         prices: ClearingPrices,
         factor: f64,
         max_volume_factor: f64,
-    ) -> Result<eth::U256, Error> {
+    ) -> Result<eth::TokenAmount, Error> {
         let fee_from_surplus =
             self.fee_from_surplus(limit_sell_amount, limit_buy_amount, prices, factor)?;
         let fee_from_volume = self.fee_from_volume(prices, max_volume_factor)?;
@@ -137,45 +138,53 @@ impl Fulfillment {
         buy_amount: eth::U256,
         prices: ClearingPrices,
         factor: f64,
-    ) -> Result<eth::U256, Error> {
+    ) -> Result<eth::TokenAmount, Error> {
         let surplus = self.surplus_over_reference_price(sell_amount, buy_amount, prices)?;
-        apply_factor(surplus, factor)
+        surplus
+            .apply_factor(factor)
+            .ok_or(Math::Overflow)
+            .map_err(Into::into)
     }
 
     /// Computes the volume based fee in surplus token
     ///
     /// The volume is defined as a full sell amount (including fees) for buy
     /// order, or a full buy amount for sell order.
-    fn fee_from_volume(&self, prices: ClearingPrices, factor: f64) -> Result<eth::U256, Error> {
+    fn fee_from_volume(
+        &self,
+        prices: ClearingPrices,
+        factor: f64,
+    ) -> Result<eth::TokenAmount, Error> {
         let volume = match self.order().side {
             Side::Buy => self.sell_amount(&prices)?,
             Side::Sell => self.buy_amount(&prices)?,
         };
-        apply_factor(volume.0, factor)
+        volume
+            .apply_factor(factor)
+            .ok_or(Math::Overflow)
+            .map_err(Into::into)
     }
 
     /// Returns the protocol fee denominated in the sell token.
-    fn protocol_fee_in_sell_token(&self, prices: ClearingPrices) -> Result<eth::U256, Error> {
-        let fee = self.protocol_fee(prices)?;
+    fn protocol_fee_in_sell_token(
+        &self,
+        prices: ClearingPrices,
+    ) -> Result<eth::TokenAmount, Error> {
         let fee_in_sell_token = match self.order().side {
-            Side::Buy => fee,
-            Side::Sell => fee
+            Side::Buy => self.protocol_fee(prices)?,
+            Side::Sell => self
+                .protocol_fee(prices)?
+                .0
                 .checked_mul(prices.buy)
                 .ok_or(Math::Overflow)?
                 .checked_div(prices.sell)
-                .ok_or(Math::DivisionByZero)?,
+                .ok_or(Math::DivisionByZero)?
+                .into(),
         };
         Ok(fee_in_sell_token)
     }
 }
 
-fn apply_factor(amount: eth::U256, factor: f64) -> Result<eth::U256, Error> {
-    Ok(amount
-        .checked_mul(eth::U256::from_f64_lossy(factor * 10000.))
-        .ok_or(Math::Overflow)?
-        / 10000)
-}
-
 /// This function adjusts quote amounts to directly compare them with the
 /// order's limits, ensuring a meaningful comparison for potential price
 /// improvements. It scales quote amounts when necessary, accounting for quote

crates/driver/src/domain/competition/solution/mod.rs

@@ -1,5 +1,6 @@
 use {
     self::trade::ClearingPrices,
+    super::auction,
     crate::{
         boundary,
         domain::{
@@ -21,6 +22,7 @@ use {
 
 pub mod fee;
 pub mod interaction;
+pub mod scoring;
 pub mod settlement;
 pub mod trade;
 
@@ -51,7 +53,7 @@ impl Solution {
         solver: Solver,
         score: SolverScore,
         weth: eth::WethAddress,
-    ) -> Result<Self, SolutionError> {
+    ) -> Result<Self, error::Solution> {
         let solution = Self {
             id,
             trades,
@@ -67,7 +69,7 @@ impl Solution {
             solution.clearing_price(trade.order().sell.token).is_none()
                 || solution.clearing_price(trade.order().buy.token).is_none()
         }) {
-            return Err(SolutionError::InvalidClearingPrices);
+            return Err(error::Solution::InvalidClearingPrices);
         }
 
         // Apply protocol fees
@@ -119,6 +121,63 @@ impl Solution {
         &self.score
     }
 
+    /// JIT score calculation as per CIP38
+    pub fn scoring(&self, prices: &auction::Prices) -> Result<eth::Ether, error::Scoring> {
+        let mut trades = Vec::with_capacity(self.trades.len());
+        for trade in self.user_trades() {
+            // Solver generated fulfillment does not include the fee in the executed amount
+            // for sell orders.
+            let executed = match trade.order().side {
+                order::Side::Sell => (trade.executed().0 + trade.fee().0).into(),
+                order::Side::Buy => trade.executed(),
+            };
+            let uniform_prices = ClearingPrices {
+                sell: *self
+                    .prices
+                    .get(&trade.order().sell.token.wrap(self.weth))
+                    .ok_or(error::Solution::InvalidClearingPrices)?,
+                buy: *self
+                    .prices
+                    .get(&trade.order().buy.token.wrap(self.weth))
+                    .ok_or(error::Solution::InvalidClearingPrices)?,
+            };
+            let custom_prices = scoring::CustomClearingPrices {
+                sell: match trade.order().side {
+                    order::Side::Sell => trade
+                        .executed()
+                        .0
+                        .checked_mul(uniform_prices.sell)
+                        .ok_or(error::Math::Overflow)?
+                        .checked_div(uniform_prices.buy)
+                        .ok_or(error::Math::DivisionByZero)?,
+                    order::Side::Buy => trade.executed().0,
+                },
+                buy: match trade.order().side {
+                    order::Side::Sell => trade.executed().0 + trade.fee().0,
+                    order::Side::Buy => {
+                        (trade.executed().0)
+                            .checked_mul(uniform_prices.buy)
+                            .ok_or(error::Math::Overflow)?
+                            .checked_div(uniform_prices.sell)
+                            .ok_or(error::Math::DivisionByZero)?
+                            + trade.fee().0
+                    }
+                },
+            };
+            trades.push(scoring::Trade::new(
+                trade.order().sell,
+                trade.order().buy,
+                trade.order().side,
+                executed,
+                custom_prices,
+                trade.order().protocol_fees.clone(),
+            ))
+        }
+
+        let scoring = scoring::Scoring::new(trades);
+        Ok(scoring.score(prices)?)
+    }
+
     /// Approval interactions necessary for encoding the settlement.
     pub async fn approvals(
         &self,
@@ -275,6 +334,7 @@ impl std::fmt::Debug for Solution {
 pub enum SolverScore {
     Solver(eth::U256),
     RiskAdjusted(f64),
+    Surplus,
 }
 /// A unique solution ID. This ID is generated by the solver and only needs to
 /// be unique within a single round of competition. This ID is only important in
@@ -326,12 +386,22 @@ pub mod error {
         #[error("division by zero")]
         DivisionByZero,
     }
-}
 
-#[derive(Debug, thiserror::Error)]
-pub enum SolutionError {
-    #[error("invalid clearing prices")]
-    InvalidClearingPrices,
-    #[error(transparent)]
-    ProtocolFee(#[from] fee::Error),
+    #[derive(Debug, thiserror::Error)]
+    pub enum Solution {
+        #[error("invalid clearing prices")]
+        InvalidClearingPrices,
+        #[error(transparent)]
+        ProtocolFee(#[from] fee::Error),
+    }
+
+    #[derive(Debug, thiserror::Error)]
+    pub enum Scoring {
+        #[error(transparent)]
+        Solution(#[from] Solution),
+        #[error(transparent)]
+        Math(#[from] Math),
+        #[error(transparent)]
+        Score(#[from] scoring::Error),
+    }
 }