Update SolverEngine API docs

crates/driver/src/infra/solver/dto/notification.rs

@@ -4,7 +4,7 @@ use {
             competition::{auction, solution},
             eth,
         },
-        infra::{notify, notify::SimulationSucceededAtLeastOnce},
+        infra::notify,
         util::serialize,
     },
     serde::Serialize,
@@ -25,41 +25,39 @@ impl Notification {
             kind: match kind {
                 notify::Kind::Timeout => Kind::Timeout,
                 notify::Kind::EmptySolution => Kind::EmptySolution,
-                notify::Kind::SimulationFailed(block, tx, simulated_once) => {
-                    Kind::SimulationFailed(
-                        block.0,
-                        Tx {
+                notify::Kind::SimulationFailed(block, tx, succeeded_once) => {
+                    Kind::SimulationFailed {
+                        block: block.0,
+                        tx: Tx {
                             from: tx.from.into(),
                             to: tx.to.into(),
                             input: tx.input.into(),
                             value: tx.value.into(),
                             access_list: tx.access_list.into(),
                         },
-                        simulated_once,
-                    )
-                }
-                notify::Kind::ScoringFailed(notify::ScoreKind::ZeroScore) => {
-                    Kind::ScoringFailed(ScoreKind::ZeroScore)
+                        succeeded_once,
+                    }
                 }
+                notify::Kind::ScoringFailed(notify::ScoreKind::ZeroScore) => Kind::ZeroScore,
                 notify::Kind::ScoringFailed(notify::ScoreKind::ScoreHigherThanQuality(
                     score,
                     quality,
-                )) => Kind::ScoringFailed(ScoreKind::ScoreHigherThanQuality {
+                )) => Kind::ScoreHigherThanQuality {
                     score: score.0.get(),
                     quality: quality.0,
-                }),
+                },
                 notify::Kind::ScoringFailed(notify::ScoreKind::SuccessProbabilityOutOfRange(
                     success_probability,
-                )) => Kind::ScoringFailed(ScoreKind::SuccessProbabilityOutOfRange {
+                )) => Kind::SuccessProbabilityOutOfRange {
                     probability: success_probability,
-                }),
+                },
                 notify::Kind::ScoringFailed(notify::ScoreKind::ObjectiveValueNonPositive(
                     quality,
                     gas_cost,
-                )) => Kind::ScoringFailed(ScoreKind::ObjectiveValueNonPositive {
+                )) => Kind::ObjectiveValueNonPositive {
                     quality: quality.0,
                     gas_cost: gas_cost.get().0,
-                }),
+                },
                 notify::Kind::NonBufferableTokensUsed(tokens) => Kind::NonBufferableTokensUsed {
                     tokens: tokens.into_iter().map(|token| token.0 .0).collect(),
                 },
@@ -69,16 +67,16 @@ impl Notification {
                     }
                 }
                 notify::Kind::DuplicatedSolutionId => Kind::DuplicatedSolutionId,
-                notify::Kind::Settled(kind) => Kind::Settled(match kind {
-                    notify::Settlement::Success(hash) => Settlement::Success {
+                notify::Kind::Settled(kind) => match kind {
+                    notify::Settlement::Success(hash) => Kind::Success {
                         transaction: hash.0,
                     },
-                    notify::Settlement::Revert(hash) => Settlement::Revert {
+                    notify::Settlement::Revert(hash) => Kind::Revert {
                         transaction: hash.0,
                     },
-                    notify::Settlement::SimulationRevert => Settlement::SimulationRevert,
-                    notify::Settlement::Fail => Settlement::Fail,
-                }),
+                    notify::Settlement::SimulationRevert => Kind::Cancelled,
+                    notify::Settlement::Fail => Kind::Fail,
+                },
             },
         }
     }
@@ -95,42 +93,17 @@ pub struct Notification {
 
 #[serde_as]
 #[derive(Debug, Serialize)]
-#[serde(rename_all = "lowercase")]
+#[serde(rename_all = "lowercase", tag = "kind")]
 pub enum Kind {
     Timeout,
     EmptySolution,
     DuplicatedSolutionId,
-    SimulationFailed(BlockNo, Tx, SimulationSucceededAtLeastOnce),
-    ScoringFailed(ScoreKind),
-    NonBufferableTokensUsed {
-        tokens: BTreeSet<eth::H160>,
-    },
-    SolverAccountInsufficientBalance {
-        #[serde_as(as = "serialize::U256")]
-        required: eth::U256,
+    #[serde(rename_all = "camelCase")]
+    SimulationFailed {
+        block: BlockNo,
+        tx: Tx,
+        succeeded_once: bool,
     },
-    Settled(Settlement),
-}
-
-type BlockNo = u64;
-
-#[serde_as]
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "camelCase")]
-pub struct Tx {
-    pub from: eth::H160,
-    pub to: eth::H160,
-    #[serde_as(as = "serialize::Hex")]
-    pub input: Vec<u8>,
-    #[serde_as(as = "serialize::U256")]
-    pub value: eth::U256,
-    pub access_list: AccessList,
-}
-
-#[serde_as]
-#[derive(Debug, Serialize)]
-#[serde(rename_all = "lowercase")]
-pub enum ScoreKind {
     ZeroScore,
     ScoreHigherThanQuality {
         #[serde_as(as = "serialize::U256")]
@@ -148,14 +121,34 @@ pub enum ScoreKind {
         #[serde_as(as = "serialize::U256")]
         gas_cost: eth::U256,
     },
+    NonBufferableTokensUsed {
+        tokens: BTreeSet<eth::H160>,
+    },
+    SolverAccountInsufficientBalance {
+        #[serde_as(as = "serialize::U256")]
+        required: eth::U256,
+    },
+    Success {
+        transaction: eth::H256,
+    },
+    Revert {
+        transaction: eth::H256,
+    },
+    Cancelled,
+    Fail,
 }
 
+type BlockNo = u64;
+
 #[serde_as]
 #[derive(Debug, Serialize)]
-#[serde(rename_all = "lowercase")]
-pub enum Settlement {
-    Success { transaction: eth::H256 },
-    Revert { transaction: eth::H256 },
-    SimulationRevert,
-    Fail,
+#[serde(rename_all = "camelCase")]
+pub struct Tx {
+    pub from: eth::H160,
+    pub to: eth::H160,
+    #[serde_as(as = "serialize::Hex")]
+    pub input: Vec<u8>,
+    #[serde_as(as = "serialize::U256")]
+    pub value: eth::U256,
+    pub access_list: AccessList,
 }

crates/shared/src/http_solver/model.rs

@@ -7,7 +7,7 @@ use {
     ethcontract::{Bytes, H160},
     model::{
         auction::AuctionId,
-        order::{Interactions, OrderData, OrderUid},
+        order::{OrderData, OrderUid},
         ratio_as_decimal,
         signature::Signature,
     },
@@ -347,8 +347,6 @@ pub struct NativeLiquidityOrder {
     pub data: OrderData,
     #[serde(flatten)]
     pub signature: Signature,
-    #[serde(default)]
-    pub interactions: Interactions,
 }
 
 #[serde_as]
@@ -1166,7 +1164,6 @@ mod tests {
                         ..Default::default()
                     },
                     signature: Signature::Eip1271(vec![1, 2, 3, 4]),
-                    interactions: Default::default(),
                 },
                 exec_sell_amount: 50.into(),
                 exec_buy_amount: 51.into(),

crates/solver/src/solver/http_solver/settlement.rs

@@ -338,7 +338,7 @@ fn convert_foreign_liquidity_orders(
                 },
                 data: liquidity.order.data,
                 signature: liquidity.order.signature,
-                interactions: liquidity.order.interactions,
+                interactions: Default::default(),
             };
             let converted = order_converter.normalize_limit_order(BalancedOrder::full(order))?;
             Ok(ExecutedLimitOrder {
@@ -609,7 +609,6 @@ mod tests {
                     ..Default::default()
                 },
                 signature: Signature::PreSign,
-                interactions: Default::default(),
             },
             exec_sell_amount: 101.into(),
             exec_buy_amount: 102.into(),

crates/solvers/openapi.yml

@@ -23,13 +23,43 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/Solution"
+                type: array
+                items:
+                  $ref: "#/components/schemas/Solution"
         400:
           description: There is something wrong with the request.
         429:
           description: The solver cannot keep up. It is too busy to handle more requests.
         500:
           description: Something went wrong when handling the request.
+  /notify:
+    post:
+      description: |
+        Receive a status notification about a previously provided solution
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                auctionId:
+                  description: |
+                    The auction ID of the auction that the solution was provided
+                    for.
+                  type: number
+                solutionId:
+                  description: |
+                    The solution ID within the auction for which the notification applies
+                  type: number
+                kind:
+                  description: |
+                    The kind of notification.
+                  type: string
+                  enum: [Timeout, EmptySolution, DuplicatedSolutionId, SimulationFailed, ZeroScore, ScoreHigherThanQuality, SuccessProbabilityOutOfRange, ObjectiveValueNonPositive, NonBufferableTokensUsed, SolverAccountInsufficientBalance, Success, Revert, Cancelled, Failed]
+      responses:
+        200:
+          description: notification successfully received.
 
 components:
   schemas:
@@ -282,6 +312,9 @@ components:
                     $ref: "#/components/schemas/Decimal"
         fee:
           $ref: "#/components/schemas/Decimal"
+        version:
+          type: string
+          enum: ["v0", "v3plus"]
 
     StablePool:
       description: |
@@ -535,6 +568,11 @@ components:
             must be included in the auction input.
           allOf:
             - $ref: "#/components/schemas/OrderUid"
+        fee:
+          description: |
+            The sell token amount that should be taken as a fee for this
+            trade. This only gets returned for partially fillable limit
+            orders and only refers to the actual amount filled by the trade.
 
     JitTrade:
       description: |
@@ -569,11 +607,6 @@ components:
                 "sellToken" for sell orders, and "buyToken" for buy orders.
               allOf:
                 - $ref: "#/components/schemas/TokenAmount"
-            fee:
-              description: |
-                The sell token amount that should be taken as a fee for this
-                trade. This only gets returned for partially fillable limit
-                orders and only refers to the actual amount filled by the trade.
 
     LiquidityInteraction:
       description: |
@@ -630,7 +663,7 @@ components:
         - kind
         - target
         - value
-        - callData
+        - calldata
         - inputs
         - outputs
       properties:
@@ -641,7 +674,7 @@ components:
           $ref: "#/components/schemas/Address"
         value:
           $ref: "#/components/schemas/TokenAmount"
-        callData:
+        calldata:
           description: |
             The EVM calldata bytes.
           type: string
@@ -681,10 +714,15 @@ components:
         The computed solution for a given auction.
       type: object
       required:
+        - id
         - prices
         - trades
         - interactions
+        - score
       properties:
+        id:
+          description: An opaque identifier for the solution.
+          type: number
         prices:
           description: |
             A clearing price map of token address to price. The price can have
@@ -704,3 +742,27 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/Interaction"
+        score:
+          description: |
+            Information required by the driver to score the solution. 
+
+            Can either be a raw score or a revert probability.
+          oneOf:
+            - type: object
+              properties:
+                solver:
+                  type: object
+                  properties:
+                    score:
+                      description: |
+                        The raw score of the solution. This is the score that is
+                        used by the driver to rank solutions.
+                      allOf:
+                        - $ref: "#/components/schemas/Decimal"
+            - type: object
+              properties:
+                riskAdjusted:
+                  description: |
+                    The revert probability of the solution. Used by the driver to compute a risk-adjusted score.
+                  type: number
+                  example: 0.9