Compare federation UTXOs with guardian wallet claims

.gitignore

@@ -5,3 +5,5 @@ fedimint_observer.db
 .direnv
 .pg_dev
 /db_backups
+.pg_dev17
+/delete_old_cluster.sh

fmo_api_types/src/lib.rs

@@ -1,3 +1,5 @@
+use std::collections::BTreeMap;
+
 use bitcoin::address::NetworkUnchecked;
 use chrono::{DateTime, Utc};
 use fedimint_core::config::FederationId;
@@ -41,6 +43,114 @@ pub struct FederationUtxo {
     pub amount: Amount,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FederationUtxosResponse {
+    /// How many guardians must agree before an output counts as held or not
+    /// held: `n - f`, the same threshold the federation itself acts on
+    pub threshold: usize,
+    pub guardians: Vec<GuardianUtxoReport>,
+    /// One row per output, most severe status first, then largest amount first
+    pub utxos: Vec<UtxoComparisonRow>,
+}
+
+/// How a guardian took part in the comparison
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GuardianUtxoReport {
+    pub guardian_id: u16,
+    pub status: GuardianUtxoClaimStatus,
+    /// Session count the guardian reported alongside its wallet summary
+    pub session_count: Option<u64>,
+    pub error: Option<String>,
+    /// Outputs a threshold of guardians agrees the federation holds, but this
+    /// guardian does not list
+    pub missing_outputs: u32,
+    /// Outputs this guardian lists, but a threshold of guardians agrees the
+    /// federation does not hold
+    pub extra_outputs: u32,
+    /// Outputs this guardian lists with another amount than a threshold of
+    /// guardians agrees on
+    pub wrong_amounts: u32,
+}
+
+/// An output as seen by the observer, the guardians and, where needed, the
+/// blockchain
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct UtxoComparisonRow {
+    pub out_point: bitcoin::OutPoint,
+    pub amount: Amount,
+    /// Only known for outputs in the observer's history
+    pub address: Option<bitcoin::Address<NetworkUnchecked>>,
+    /// State each guardian that took part in the comparison lists the output in
+    pub guardian_states: BTreeMap<u16, GuardianClaimedUtxoState>,
+    pub status: UtxoComparisonStatus,
+    pub disagreement: Option<GuardianUtxoDisagreementKind>,
+    pub detail: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum UtxoComparisonStatus {
+    Mismatch,
+    /// Not confirmed yet: in flight, observer lag, or no guardian responded
+    Pending,
+    Verified,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GuardianUtxoClaim {
+    pub guardian_id: u16,
+    pub status: GuardianUtxoClaimStatus,
+    /// Session count the guardian reported alongside its wallet summary
+    pub session_count: Option<u64>,
+    pub utxos: Vec<GuardianClaimedUtxo>,
+    pub error: Option<String>,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianUtxoClaimStatus {
+    Unavailable,
+    Ok,
+    /// Answered, but behind the federation's session count, so its wallet
+    /// summary is stale and left out of the comparison
+    Lagging,
+    Error,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct GuardianClaimedUtxo {
+    pub out_point: bitcoin::OutPoint,
+    pub amount: Amount,
+    pub state: GuardianClaimedUtxoState,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianClaimedUtxoState {
+    Spendable,
+    UnsignedPegOut,
+    UnsignedChange,
+    UnconfirmedPegOut,
+    UnconfirmedChange,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum GuardianUtxoDisagreementKind {
+    /// The observer's amount differs from the one a threshold of guardians
+    /// agrees on, or guardians cannot agree on an amount
+    EvidenceMismatch,
+    /// Guardians cannot reach a threshold on whether the federation holds the
+    /// output, or only a minority lists an output the rest agree is not held
+    InventoryDifference,
+    /// A threshold of guardians agrees, but the observer's history differs,
+    /// usually because it lags behind consensus or a peg-out is still pending
+    ObserverDifference,
+    /// The blockchain contradicts what the observer or guardians report: the
+    /// output is already spent, does not exist, or holds a different amount
+    OnChainConflict,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct GuardianHealth {
     pub avg_uptime: f32,