refactor(competition): introduce BidPayload for auction bids and update related structures

Author: AryanGodara

crates/autopilot/src/domain/competition/bid.rs

@@ -9,24 +9,20 @@ use {
 pub type Scored = state::Scored<Score>;
 pub type Ranked = state::Ranked<Score>;
 
-/// A solver's auction bid, which includes solution and corresponding driver
-/// data, progressing through the winner selection process.
-///
-/// It uses the type-state pattern to enforce correct state
-/// transitions at compile time. The state parameter tracks progression through
-/// three phases:
-///
-/// 1. **Unscored**: Initial state when the solution is received from the driver
-/// 2. **Scored**: After computing surplus and fees for the solution
-/// 3. **Ranked**: After winner selection determines if this is a winner
+/// Payload carried by [`Bid`]: the solution plus its originating driver.
+/// Accessible directly through the bid via [`winner_selection::Bid`]'s
+/// `Deref` impl, so `bid.solution()` and `bid.driver()` keep working.
 #[derive(Clone)]
-pub struct Bid<State = Ranked> {
+pub struct BidPayload {
     solution: Solution,
     driver: Arc<infra::Driver>,
-    state: State,
 }
 
-impl<T> Bid<T> {
+impl BidPayload {
+    pub fn new(solution: Solution, driver: Arc<infra::Driver>) -> Self {
+        Self { solution, driver }
+    }
+
     pub fn solution(&self) -> &Solution {
         &self.solution
     }
@@ -36,29 +32,7 @@ impl<T> Bid<T> {
     }
 }
 
-impl<State> state::HasState for Bid<State> {
-    type Next<NewState> = Bid<NewState>;
-    type State = State;
-
-    fn with_state<NewState>(self, state: NewState) -> Self::Next<NewState> {
-        Bid {
-            solution: self.solution,
-            driver: self.driver,
-            state,
-        }
-    }
-
-    fn state(&self) -> &Self::State {
-        &self.state
-    }
-}
-
-impl Bid<Unscored> {
-    pub fn new(solution: Solution, driver: Arc<infra::Driver>) -> Self {
-        Self {
-            solution,
-            driver,
-            state: Unscored,
-        }
-    }
-}
+/// A solver's auction bid in the typestate pipeline `Unscored -> Scored ->
+/// Ranked`. State transitions are enforced at compile time via
+/// [`winner_selection::Bid`].
+pub type Bid<State = Ranked> = ::winner_selection::Bid<BidPayload, State>;

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

@@ -11,7 +11,7 @@ use {
 mod bid;
 pub mod winner_selection;
 
-pub use bid::{Bid, RankType, Ranked, Scored, Unscored};
+pub use bid::{Bid, BidPayload, RankType, Ranked, Scored, Unscored};
 
 type SolutionId = u64;
 

crates/autopilot/src/domain/competition/winner_selection.rs

@@ -31,6 +31,7 @@ use {
         competition::{Bid, RankType, Ranked, Score, Solution, TradedOrder, Unscored},
         fee,
     },
+    ::observe::metrics,
     ::winner_selection::state::{HasState, RankedItem, ScoredItem, UnscoredItem},
     eth_domain_types::{self as eth, Address, WrappedNativeToken},
     std::collections::HashMap,
@@ -66,34 +67,39 @@ impl Arbitrator {
                 (bid, solution)
             })
             .collect();
-        let (ws_ranking, mut by_key) = self.0.arbitrate_paired(paired, &auction.into());
+        let rejoined = self.0.arbitrate_paired_and_rejoin(paired, &auction.into());
+
+        // An orphan means two input bids shared a `SolutionKey`. Autopilot
+        // runs one process per chain; panicking here takes auctioning down
+        // until restart. Warn and bump the counter so oncall can alert.
+        if rejoined.orphans > 0 {
+            tracing::warn!(
+                orphans = rejoined.orphans,
+                "ranked solutions had no matching bid; SolutionKey collision suspected",
+            );
+            Metrics::get()
+                .orphan_solutions
+                .inc_by(rejoined.orphans as u64);
+        }
+        debug_assert!(rejoined.orphans == 0, "expected no orphans");
 
-        let reference_scores = self
-            .0
-            .compute_reference_scores(&ws_ranking)
+        let reference_scores = rejoined
+            .reference_scores
             .into_iter()
             .map(|(solver, score)| (solver, Score(eth::Ether(score))))
             .collect();
-
-        let filtered_out = ws_ranking
+        let filtered_out = rejoined
             .filtered_out
             .into_iter()
-            .map(|ws_solution| {
-                let bid = by_key
-                    .remove(&winsel::SolutionKey::from(&ws_solution))
-                    .expect("every filtered-out solution has a matching bid");
+            .map(|(bid, ws_solution)| {
                 bid.with_score(Score(eth::Ether(ws_solution.score())))
                     .with_rank(RankType::FilteredOut)
             })
             .collect();
-
-        let ranked = ws_ranking
+        let ranked = rejoined
             .ranked
             .into_iter()
-            .map(|ws_solution| {
-                let bid = by_key
-                    .remove(&winsel::SolutionKey::from(&ws_solution))
-                    .expect("every ranked solution has a matching bid");
+            .map(|(bid, ws_solution)| {
                 bid.with_score(Score(eth::Ether(ws_solution.score())))
                     .with_rank(ws_solution.state().rank_type)
             })
@@ -107,6 +113,21 @@ impl Arbitrator {
     }
 }
 
+#[derive(prometheus_metric_storage::MetricStorage)]
+#[metric(subsystem = "winner_selection")]
+struct Metrics {
+    /// Arbitrator-returned solutions whose `SolutionKey` had no matching
+    /// bid in the rejoin step. Non-zero indicates a `SolutionKey` collision
+    /// in the input set or an arbitrator invariant violation.
+    orphan_solutions: prometheus::IntCounter,
+}
+
+impl Metrics {
+    fn get() -> &'static Self {
+        Metrics::instance(metrics::get_storage_registry()).unwrap()
+    }
+}
+
 impl From<&domain::Auction> for winsel::AuctionContext {
     fn from(auction: &domain::Auction) -> Self {
         Self {
@@ -260,7 +281,7 @@ mod tests {
                     Price,
                     order::{self, AppDataHash},
                 },
-                competition::{Bid, Solution, TradedOrder, Unscored},
+                competition::{Bid, BidPayload, Solution, TradedOrder, Unscored},
             },
             infra::Driver,
         },
@@ -1194,7 +1215,7 @@ mod tests {
         .await
         .unwrap();
 
-        Bid::new(solution, std::sync::Arc::new(driver))
+        Bid::new(BidPayload::new(solution, std::sync::Arc::new(driver)))
     }
 
     fn amount(value: u128) -> String {

crates/autopilot/src/run_loop.rs

@@ -643,7 +643,10 @@ impl RunLoop {
             .filter_map(|solution| match solution {
                 Ok(solution) => {
                     Metrics::solution_ok(&driver);
-                    Some(competition::Bid::new(solution, driver.clone()))
+                    Some(competition::Bid::new(competition::BidPayload::new(
+                        solution,
+                        driver.clone(),
+                    )))
                 }
                 Err(err) => {
                     Metrics::solution_err(&driver, &err);

crates/autopilot/src/shadow.rs

@@ -11,7 +11,7 @@ use {
     crate::{
         domain::{
             self,
-            competition::{Bid, Score, Unscored, winner_selection},
+            competition::{Bid, BidPayload, Score, Unscored, winner_selection},
         },
         infra::{
             self,
@@ -259,7 +259,7 @@ impl RunLoop {
 
         solutions
             .into_iter()
-            .map(|s| Bid::new(s, Arc::clone(&driver)))
+            .map(|s| Bid::new(BidPayload::new(s, Arc::clone(&driver))))
             .collect()
     }
 

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

@@ -562,18 +562,14 @@ impl Competition {
             lock.truncate(max_to_propose * MAX_CONCURRENT_AUCTIONS);
         }
 
-        // Shadow-mode submission to the pod network. Failures must never affect
-        // the response we return to the autopilot.
-        if let (Some(pm), Some(auction_id), Some((best, _))) =
-            (self.solver.pod_manager(), auction.id, scored.first())
-        {
-            pm.spawn(
-                auction_id,
-                auction.clone(),
-                deadline,
-                best.clone(),
-                self.solver.clone(),
-            );
+        // Shadow-mode submission to pod. Failures and cost must not affect
+        // the response we return to autopilot. `spawn` does its serialization
+        // synchronously from borrowed inputs, so no deep `Auction` clone
+        // happens here. Send the full scored vec so pod and autopilot rank
+        // the same set.
+        if let (Some(pm), Some(auction_id)) = (self.solver.pod_manager(), auction.id) {
+            let solveds: Vec<Solved> = scored.iter().map(|(s, _)| s).cloned().collect();
+            pm.spawn(auction_id, deadline, solveds, auction, self.solver.clone());
         }
 
         // Re-simulate the solution on every new block until the deadline ends to make

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

@@ -1,11 +1,12 @@
 pub use winner_selection::Unscored;
 use {
-    crate::domain::competition::order::FeePolicy,
-    eth_domain_types::{self as eth, Address, Ether, WrappedNativeToken},
+    crate::{domain::competition::order::FeePolicy, infra::api::routes::solve::dto},
+    ::observe::metrics,
+    eth_domain_types::{self as eth, Ether, WrappedNativeToken},
     winner_selection::{
         self as winsel,
         OrderUid,
-        state::{self, HasState, RankedItem, ScoredItem, UnscoredItem},
+        state::{HasState, RankedItem, ScoredItem, UnscoredItem},
     },
 };
 
@@ -37,30 +38,69 @@ impl SolverArbitrator {
         &self,
         bids: Vec<Bid<Unscored>>,
         auction: &crate::domain::competition::Auction,
+    ) -> Vec<Bid> {
+        self.arbitrate_with_context(bids, &auction.into())
+    }
+
+    /// Same as [`Self::arbitrate`] but takes a precomputed
+    /// [`winsel::AuctionContext`]. Use this when the caller has already
+    /// built the context in the foreground, to avoid the per-call
+    /// conversion from `Auction`.
+    pub fn arbitrate_with_context(
+        &self,
+        bids: Vec<Bid<Unscored>>,
+        context: &winsel::AuctionContext,
     ) -> Vec<Bid> {
         let paired = bids
             .into_iter()
             .map(|bid| {
-                let solution: winsel::Solution<winsel::Unscored> = bid.solution().into();
+                let solution: winsel::Solution<winsel::Unscored> = bid.payload().into();
                 (bid, solution)
             })
             .collect();
-        let (ws_ranking, mut by_key) = self.0.arbitrate_paired(paired, &auction.into());
+        let rejoined = self.0.arbitrate_paired_and_rejoin(paired, context);
+
+        // An orphan means two input bids shared a `SolutionKey`. Pod is
+        // open so untrusted input can engineer such collisions. Don't panic
+        // (it would kill the spawned pod task); warn and bump the counter
+        // so oncall can alert.
+        if rejoined.orphans > 0 {
+            tracing::warn!(
+                orphans = rejoined.orphans,
+                "ranked solutions had no matching bid; SolutionKey collision suspected",
+            );
+            Metrics::get()
+                .orphan_solutions
+                .inc_by(rejoined.orphans as u64);
+        }
+        debug_assert!(rejoined.orphans == 0, "expected no orphans");
 
-        ws_ranking
+        rejoined
             .ranked
             .into_iter()
-            .map(|ws_solution| {
-                let bid = by_key
-                    .remove(&winsel::SolutionKey::from(&ws_solution))
-                    .expect("every ranked solution has a matching bid");
+            .map(|(bid, ws_solution)| {
                 bid.with_score(Score(eth::Ether(ws_solution.score())))
                     .with_rank(ws_solution.state().rank_type)
             })
             .collect()
     }
 }
 
+#[derive(prometheus_metric_storage::MetricStorage)]
+#[metric(subsystem = "winner_selection")]
+struct Metrics {
+    /// Arbitrator-returned solutions whose `SolutionKey` had no matching
+    /// bid in the rejoin step. Non-zero indicates a `SolutionKey` collision
+    /// in the input set or an arbitrator invariant violation.
+    orphan_solutions: prometheus::IntCounter,
+}
+
+impl Metrics {
+    fn get() -> &'static Self {
+        Metrics::instance(metrics::get_storage_registry()).unwrap()
+    }
+}
+
 impl From<&crate::domain::competition::Auction> for winsel::AuctionContext {
     fn from(auction: &crate::domain::competition::Auction) -> Self {
         Self {
@@ -156,53 +196,7 @@ impl From<&crate::infra::api::routes::solve::dto::solve_response::Solution>
 pub type Scored = winsel::state::Scored<Score>;
 pub type Ranked = winsel::state::Ranked<Score>;
 
-/// A solver's auction bid, which includes solution and corresponding driver
-/// data, progressing through the winner selection process.
-///
-/// It uses the type-state pattern to enforce correct state
-/// transitions at compile time. The state parameter tracks progression through
-/// three phases:
-///
-/// 1. **Unscored**: Initial state when the solution is received from the driver
-/// 2. **Scored**: After computing surplus and fees for the solution
-/// 3. **Ranked**: After winner selection determines if this is a winner
-#[derive(Clone)]
-pub struct Bid<State = Ranked> {
-    solution: crate::infra::api::routes::solve::dto::solve_response::Solution,
-    state: State,
-}
-
-impl<T> Bid<T> {
-    pub fn solution(&self) -> &crate::infra::api::routes::solve::dto::solve_response::Solution {
-        &self.solution
-    }
-
-    pub fn submission_address(&self) -> &Address {
-        &self.solution.submission_address
-    }
-}
-
-impl<State> state::HasState for Bid<State> {
-    type Next<NewState> = Bid<NewState>;
-    type State = State;
-
-    fn with_state<NewState>(self, state: NewState) -> Self::Next<NewState> {
-        Bid {
-            solution: self.solution,
-            state,
-        }
-    }
-
-    fn state(&self) -> &Self::State {
-        &self.state
-    }
-}
-
-impl Bid<Unscored> {
-    pub fn new(solution: crate::infra::api::routes::solve::dto::solve_response::Solution) -> Self {
-        Self {
-            solution,
-            state: Unscored,
-        }
-    }
-}
+/// A solver's auction bid in the typestate pipeline `Unscored -> Scored ->
+/// Ranked`. State transitions are enforced at compile time via
+/// [`winsel::Bid`].
+pub type Bid<State = Ranked> = winsel::Bid<dto::solve_response::Solution, State>;