fix(wallet): handle stale and invalid mint quote accounting

Ignore stale mint quote responses that would move updated_at or accounting counters backwards, derive quote state from canonical amount_paid and amount_issued counters, and treat amount_issued greater than amount_paid as invalid accounting.

Author: thesimplekid

crates/cashu/src/nuts/nut17/mod.rs

@@ -582,7 +582,11 @@ mod tests {
             NotificationPayload::MintQuoteBolt11Response(resp.clone());
 
         let encoded = serde_json::to_string(&payload).unwrap();
-        let decoded: NotificationPayload<String> = serde_json::from_str(&encoded).unwrap();
+        let decoded = deserialize_payload_for_kind::<String, serde_json::Error>(
+            &Kind::Bolt11MintQuote,
+            serde_json::from_str(&encoded).unwrap(),
+        )
+        .unwrap();
 
         match decoded {
             NotificationPayload::MintQuoteBolt11Response(r) => {
@@ -790,6 +794,34 @@ mod tests {
         }
     }
 
+    #[test]
+    fn notification_payload_bolt12_mint_tolerates_unknown_fields() {
+        let encoded = r#"{
+            "quote": "abc",
+            "request": "lno1...",
+            "amount": 100,
+            "unit": "sat",
+            "expiry": 1701704757,
+            "pubkey": "03d56ce4e446a85bbdaa547b4ec2b073d40ff802831352b8272b7dd7a4de5a7cac",
+            "amount_paid": 0,
+            "amount_issued": 0,
+            "some_future_extension": {"nested": true}
+        }"#;
+
+        let decoded = deserialize_payload_for_kind::<String, serde_json::Error>(
+            &Kind::Bolt12MintQuote,
+            serde_json::from_str(encoded).unwrap(),
+        )
+        .unwrap();
+
+        match decoded {
+            NotificationPayload::MintQuoteBolt12Response(r) => {
+                assert_eq!(r.quote, "abc");
+            }
+            other => panic!("expected MintQuoteBolt12Response, got {:?}", other),
+        }
+    }
+
     #[test]
     fn notification_payload_custom_tuple_uses_kind() {
         let encoded = serde_json::json!([

crates/cashu/src/nuts/nut25.rs

@@ -40,15 +40,8 @@ pub struct MintQuoteBolt12Request {
 }
 
 /// Mint quote response [NUT-24]
-///
-/// `deny_unknown_fields` is intentional: the `NotificationPayload` enum is
-/// `#[serde(untagged)]` and Bolt11 mint quotes share the same core fields as
-/// Bolt12 mint quotes. Rejecting unknown fields lets `NotificationPayload`
-/// try the Bolt12 variant before Bolt11 without classifying Bolt11 payloads
-/// that carry a `state` field as Bolt12.
 #[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(bound = "Q: Serialize + for<'a> Deserialize<'a>")]
-#[serde(deny_unknown_fields)]
 pub struct MintQuoteBolt12Response<Q> {
     /// Quote Id
     pub quote: Q,
@@ -243,6 +236,28 @@ mod tests {
         assert_eq!(decoded.method, PaymentMethod::Known(KnownMethod::Bolt12));
     }
 
+    #[test]
+    fn mint_quote_bolt12_response_tolerates_unknown_fields() {
+        let value = json!({
+            "quote": "quote-id",
+            "request": "lno1...",
+            "amount": 10,
+            "unit": "sat",
+            "expiry": 1_701_704_757,
+            "pubkey": "03d56ce4e446a85bbdaa547b4ec2b073d40ff802831352b8272b7dd7a4de5a7cac",
+            "amount_paid": 0,
+            "amount_issued": 0,
+            "future_extension": {
+                "payjoin": "https://payjoin.example/pj"
+            }
+        });
+
+        let decoded: MintQuoteBolt12Response<String> =
+            from_value(value).expect("deserialize response");
+        assert_eq!(decoded.quote, "quote-id");
+        assert_eq!(decoded.method, PaymentMethod::Known(KnownMethod::Bolt12));
+    }
+
     #[test]
     fn melt_quote_bolt12_response_serializes_method() {
         let response = MeltQuoteBolt12Response {

crates/cdk-common/src/mint.rs

@@ -1869,6 +1869,7 @@ mod tests {
         )
         .expect("test pubkey must parse");
         let quote_id = QuoteId::new();
+        let now = unix_time();
         let mint_quote = MintQuote::new(
             Some(quote_id.clone()),
             "lno1testoffer".to_string(),
@@ -1880,7 +1881,8 @@ mod tests {
             Amount::new(10_000, CurrencyUnit::Sat),
             Amount::new(1_000, CurrencyUnit::Sat),
             PaymentMethod::BOLT12,
-            unix_time(),
+            now,
+            now,
             vec![],
             vec![],
             None,

crates/cdk-common/src/mint_quote.rs

@@ -112,6 +112,19 @@ pub enum MintQuoteResponse<Q> {
     },
 }
 
+/// Errors from mint quote accounting validation.
+#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+pub enum MintQuoteAccountingError {
+    /// The response reports more issued ecash than paid amount.
+    #[error("mint quote amount_issued ({amount_issued}) exceeds amount_paid ({amount_paid})")]
+    AmountIssuedExceedsAmountPaid {
+        /// Amount paid to the mint.
+        amount_paid: Amount,
+        /// Amount of ecash issued by the mint.
+        amount_issued: Amount,
+    },
+}
+
 impl<Q> MintQuoteResponse<Q> {
     /// Returns the payment method for this response.
     pub fn method(&self) -> PaymentMethod {
@@ -145,20 +158,24 @@ impl<Q> MintQuoteResponse<Q> {
 
     /// Returns the quote state derived from the response data.
     pub fn state(&self) -> Option<QuoteState> {
+        self.try_state().ok()
+    }
+
+    /// Returns the quote state derived from the response data, validating quote accounting.
+    pub fn try_state(&self) -> Result<QuoteState, MintQuoteAccountingError> {
         match self {
             Self::Bolt11(r) => {
                 if r.amount_paid > Amount::ZERO || r.amount_issued > Amount::ZERO {
-                    Some(quote_state_from_amounts(r.amount_paid, r.amount_issued))
+                    quote_state_from_amounts(r.amount_paid, r.amount_issued)
                 } else {
-                    Some(r.state)
+                    Ok(r.state)
                 }
             }
-            Self::Bolt12(r) => Some(quote_state_from_amounts(r.amount_paid, r.amount_issued)),
-            Self::Onchain(r) => Some(quote_state_from_amounts(r.amount_paid, r.amount_issued)),
-            Self::Custom { response, .. } => Some(quote_state_from_amounts(
-                response.amount_paid,
-                response.amount_issued,
-            )),
+            Self::Bolt12(r) => quote_state_from_amounts(r.amount_paid, r.amount_issued),
+            Self::Onchain(r) => quote_state_from_amounts(r.amount_paid, r.amount_issued),
+            Self::Custom { response, .. } => {
+                quote_state_from_amounts(response.amount_paid, response.amount_issued)
+            }
         }
     }
 
@@ -174,15 +191,26 @@ impl<Q> MintQuoteResponse<Q> {
 }
 
 /// Derive the deprecated single-use mint quote state from canonical quote counters.
-pub fn quote_state_from_amounts(amount_paid: Amount, amount_issued: Amount) -> QuoteState {
+pub fn quote_state_from_amounts(
+    amount_paid: Amount,
+    amount_issued: Amount,
+) -> Result<QuoteState, MintQuoteAccountingError> {
+    if amount_issued > amount_paid {
+        return Err(MintQuoteAccountingError::AmountIssuedExceedsAmountPaid {
+            amount_paid,
+            amount_issued,
+        });
+    }
+
     if amount_paid == Amount::ZERO && amount_issued == Amount::ZERO {
-        return QuoteState::Unpaid;
+        return Ok(QuoteState::Unpaid);
     }
 
-    match amount_paid.cmp(&amount_issued) {
-        std::cmp::Ordering::Less | std::cmp::Ordering::Equal => QuoteState::Issued,
-        std::cmp::Ordering::Greater => QuoteState::Paid,
+    if amount_paid == amount_issued {
+        return Ok(QuoteState::Issued);
     }
+
+    Ok(QuoteState::Paid)
 }
 
 #[cfg(test)]
@@ -222,6 +250,14 @@ mod tests {
             custom_response(Amount::from(100), Amount::from(100)).state(),
             Some(QuoteState::Issued)
         );
+        assert_eq!(
+            custom_response(Amount::from(50), Amount::from(100)).state(),
+            None
+        );
+        assert!(matches!(
+            custom_response(Amount::from(50), Amount::from(100)).try_state(),
+            Err(MintQuoteAccountingError::AmountIssuedExceedsAmountPaid { .. })
+        ));
     }
 
     #[test]

crates/cdk-common/src/wallet/mod.rs

@@ -290,7 +290,7 @@ impl MintQuote {
 
     /// Derive quote state from the tracked payment and issuance counters.
     pub fn state_from_amounts(&self) -> MintQuoteState {
-        quote_state_from_amounts(self.amount_paid, self.amount_issued)
+        quote_state_from_amounts(self.amount_paid, self.amount_issued).unwrap_or(self.state)
     }
 
     /// Update quote state from the tracked payment and issuance counters.

crates/cdk-npubcash/src/types.rs

@@ -168,7 +168,7 @@ impl From<Quote> for MintQuote {
             } else {
                 Amount::ZERO
             },
-            updated_at: quote.paid_at.unwrap_or(quote.created_at),
+            updated_at: quote.paid_at.unwrap_or_default(),
             estimated_blocks: None,
             used_by_operation: None,
             version: 0,
@@ -198,5 +198,27 @@ mod tests {
         let mint_quote = MintQuote::from(quote);
 
         assert_eq!(mint_quote.expiry, u64::MAX);
+        assert_eq!(mint_quote.updated_at, 0);
+    }
+
+    #[test]
+    fn from_paid_quote_uses_paid_at_as_updated_at() {
+        let quote = Quote {
+            id: "paid-quote".to_string(),
+            amount: 1_000,
+            unit: "sat".to_string(),
+            created_at: 100,
+            paid_at: Some(200),
+            expires_at: None,
+            mint_url: None,
+            request: None,
+            state: Some("PAID".to_string()),
+            locked: None,
+        };
+
+        let mint_quote = MintQuote::from(quote);
+
+        assert_eq!(mint_quote.amount_paid, Amount::from(1_000));
+        assert_eq!(mint_quote.updated_at, 200);
     }
 }

crates/cdk-supabase/migrations/supabase/migrations/20260617000000_add_updated_at_to_mint_quote.sql

@@ -0,0 +1,7 @@
+-- Track the last quote update timestamp so wallet quote responses cannot
+-- move amount_paid or amount_issued backwards after stale notifications.
+
+ALTER TABLE mint_quote ADD COLUMN IF NOT EXISTS updated_at BIGINT NOT NULL DEFAULT 0;
+
+INSERT INTO schema_info (key, value) VALUES ('schema_version', '8')
+ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value;

crates/cdk-supabase/src/wallet.rs

@@ -213,7 +213,7 @@ impl SupabaseWalletDatabase {
     /// This must match the latest `schema_version` value set in the migration files.
     /// When adding new migrations, update this constant and set the same value
     /// in the new migration's `INSERT INTO schema_info` statement.
-    pub const REQUIRED_SCHEMA_VERSION: u32 = 7;
+    pub const REQUIRED_SCHEMA_VERSION: u32 = 8;
 
     /// Get the full database schema SQL
     ///