Batch Minting Implementation (NUT-XX)

crates/cashu/src/nuts/mod.rs

@@ -25,6 +25,7 @@ pub mod nut19;
 pub mod nut20;
 pub mod nut23;
 pub mod nut25;
+pub mod nutxx;
 
 #[cfg(feature = "auth")]
 mod auth;
@@ -69,3 +70,7 @@ pub use nut23::{
     MintQuoteBolt11Response, QuoteState as MintQuoteState,
 };
 pub use nut25::{MeltQuoteBolt12Request, MintQuoteBolt12Request, MintQuoteBolt12Response};
+pub use nutxx::{
+    BatchMintRequest, BatchMintSettings, BatchQuoteStatusItem, BatchQuoteStatusRequest,
+    BatchQuoteStatusResponse, MintQuoteBolt12BatchStatusResponse,
+};

crates/cashu/src/nuts/nut06.rs

@@ -11,6 +11,7 @@ use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use super::nut01::PublicKey;
 use super::nut17::SupportedMethods;
 use super::nut19::CachedEndpoint;
+use super::nutxx::BatchMintSettings;
 use super::{nut04, nut05, nut15, nut19, MppMethodSettings};
 #[cfg(feature = "auth")]
 use super::{AuthRequired, BlindAuthSettings, ClearAuthSettings, ProtectedEndpoint};
@@ -327,6 +328,11 @@ pub struct Nuts {
     #[serde(default)]
     #[serde(rename = "20")]
     pub nut20: SupportedSettings,
+    /// NUTXX Batch mint settings
+    #[serde(default)]
+    #[serde(rename = "XX")]
+    #[serde(skip_serializing_if = "BatchMintSettings::is_empty")]
+    pub nutxx: BatchMintSettings,
     /// NUT21 Settings
     #[serde(rename = "21")]
     #[serde(skip_serializing_if = "Option::is_none")]

crates/cashu/src/nuts/nut19.rs

@@ -49,6 +49,9 @@ pub enum Path {
     /// Bolt11 Mint
     #[serde(rename = "/v1/mint/bolt11")]
     MintBolt11,
+    /// Bolt11 Batch Mint
+    #[serde(rename = "/v1/mint/bolt11/batch")]
+    MintBolt11Batch,
     /// Bolt11 Melt
     #[serde(rename = "/v1/melt/bolt11")]
     MeltBolt11,
@@ -58,6 +61,9 @@ pub enum Path {
     /// Bolt12 Mint
     #[serde(rename = "/v1/mint/bolt12")]
     MintBolt12,
+    /// Bolt12 Batch Mint
+    #[serde(rename = "/v1/mint/bolt12/batch")]
+    MintBolt12Batch,
     /// Bolt12 Melt
     #[serde(rename = "/v1/melt/bolt12")]
     MeltBolt12,

crates/cashu/src/nuts/nutxx.rs

@@ -0,0 +1,249 @@
+//! NUT-XX: Batch Minting
+//!
+//! Batch minting support for Cashu
+
+use serde::{Deserialize, Serialize};
+
+use super::nut00::{BlindedMessage, PaymentMethod};
+use super::nut23::MintQuoteBolt11Response;
+use super::nut25::MintQuoteBolt12Response;
+use super::MintQuoteState;
+use crate::Amount;
+
+/// Batch Mint Request [NUT-XX]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))]
+pub struct BatchMintRequest {
+    /// Quote IDs
+    pub quotes: Vec<String>,
+    /// Expected amount to mint per quote, in the same order as `quote`
+    #[serde(skip_serializing_if = "Option::is_none", default)]
+    pub quote_amounts: Option<Vec<Amount>>,
+    /// Blinded messages
+    pub outputs: Vec<BlindedMessage>,
+    /// Signatures for NUT-20 locked quotes (optional)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub signatures: Option<Vec<Option<String>>>,
+}
+
+impl BatchMintRequest {
+    /// Total amount of outputs
+    pub fn total_amount(&self) -> Result<Amount, crate::nuts::nut04::Error> {
+        Amount::try_sum(self.outputs.iter().map(|msg| msg.amount))
+            .map_err(|_| crate::nuts::nut04::Error::AmountOverflow)
+    }
+
+    /// Total amount the client expects to mint per quote, if provided
+    pub fn total_quote_amounts(&self) -> Option<Result<Amount, crate::nuts::nut04::Error>> {
+        self.quote_amounts.as_ref().map(|amounts| {
+            Amount::try_sum(amounts.iter().cloned())
+                .map_err(|_| crate::nuts::nut04::Error::AmountOverflow)
+        })
+    }
+}
+
+/// Batch Quote Status Request [NUT-XX]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))]
+pub struct BatchQuoteStatusRequest {
+    /// Quote IDs
+    pub quotes: Vec<String>,
+}
+
+/// Batch minting settings (NUT-XX)
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))]
+pub struct BatchMintSettings {
+    /// Maximum quotes allowed in a batch request
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub max_batch_size: Option<u16>,
+    /// Supported payment methods for batch minting
+    #[serde(default)]
+    pub methods: Vec<PaymentMethod>,
+}
+
+impl Default for BatchMintSettings {
+    fn default() -> Self {
+        Self {
+            max_batch_size: Some(100),
+            methods: Vec::new(),
+        }
+    }
+}
+
+impl BatchMintSettings {
+    /// Returns true when no batch capabilities should be advertised
+    pub fn is_empty(&self) -> bool {
+        self.methods.is_empty()
+    }
+}
+
+/// Bolt12 batch status payload extends the standard Bolt12 quote with a derived state.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))]
+#[serde(bound = "Q: Serialize + for<'a> Deserialize<'a>")]
+pub struct MintQuoteBolt12BatchStatusResponse<Q> {
+    /// Underlying Bolt12 quote payload
+    #[serde(flatten)]
+    pub quote: MintQuoteBolt12Response<Q>,
+    /// Derived quote state (UNPAID, PAID, ISSUED)
+    pub state: MintQuoteState,
+}
+
+impl<Q> MintQuoteBolt12BatchStatusResponse<Q> {
+    fn from_quote(quote: MintQuoteBolt12Response<Q>) -> Self {
+        let state = derive_quote_state(quote.amount_paid, quote.amount_issued);
+        Self { quote, state }
+    }
+
+    /// Current quote state
+    pub fn state(&self) -> MintQuoteState {
+        self.state
+    }
+}
+
+impl<Q> From<MintQuoteBolt12Response<Q>> for MintQuoteBolt12BatchStatusResponse<Q> {
+    fn from(value: MintQuoteBolt12Response<Q>) -> Self {
+        Self::from_quote(value)
+    }
+}
+
+/// Batch quote status entry supporting both Bolt11 and Bolt12 payloads.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema))]
+#[serde(untagged)]
+pub enum BatchQuoteStatusItem {
+    /// Bolt11 quote payload
+    Bolt11(MintQuoteBolt11Response<String>),
+    /// Bolt12 quote payload
+    Bolt12(MintQuoteBolt12BatchStatusResponse<String>),
+}
+
+impl BatchQuoteStatusItem {
+    /// Quote state (UNPAID, PAID, ISSUED)
+    pub fn state(&self) -> MintQuoteState {
+        match self {
+            Self::Bolt11(response) => response.state,
+            Self::Bolt12(response) => response.state(),
+        }
+    }
+}
+
+impl From<MintQuoteBolt11Response<String>> for BatchQuoteStatusItem {
+    fn from(value: MintQuoteBolt11Response<String>) -> Self {
+        Self::Bolt11(value)
+    }
+}
+
+impl From<MintQuoteBolt12Response<String>> for BatchQuoteStatusItem {
+    fn from(value: MintQuoteBolt12Response<String>) -> Self {
+        let batch_response = MintQuoteBolt12BatchStatusResponse::from(value);
+        Self::Bolt12(batch_response)
+    }
+}
+
+impl From<MintQuoteBolt12BatchStatusResponse<String>> for BatchQuoteStatusItem {
+    fn from(value: MintQuoteBolt12BatchStatusResponse<String>) -> Self {
+        Self::Bolt12(value)
+    }
+}
+
+/// Batch Quote Status Response [NUT-XX]
+/// Returns a Vec that should be serialized as a JSON array
+#[derive(Debug, Clone)]
+#[cfg_attr(feature = "swagger", derive(utoipa::ToSchema), schema(transparent))]
+pub struct BatchQuoteStatusResponse(
+    /// Vector of quote status responses as JSON
+    pub Vec<BatchQuoteStatusItem>,
+);
+
+impl Serialize for BatchQuoteStatusResponse {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        self.0.serialize(serializer)
+    }
+}
+
+impl<'de> Deserialize<'de> for BatchQuoteStatusResponse {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: serde::Deserializer<'de>,
+    {
+        Vec::<BatchQuoteStatusItem>::deserialize(deserializer).map(BatchQuoteStatusResponse)
+    }
+}
+
+fn derive_quote_state(amount_paid: Amount, amount_issued: Amount) -> MintQuoteState {
+    if amount_paid == Amount::ZERO && amount_issued == Amount::ZERO {
+        return MintQuoteState::Unpaid;
+    }
+
+    match amount_paid.cmp(&amount_issued) {
+        std::cmp::Ordering::Less => {
+            tracing::error!("Bolt12 quote has issued more than paid");
+            MintQuoteState::Issued
+        }
+        std::cmp::Ordering::Equal => MintQuoteState::Issued,
+        std::cmp::Ordering::Greater => MintQuoteState::Paid,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{CurrencyUnit, PublicKey};
+    use std::str::FromStr;
+
+    #[test]
+    fn batch_quote_status_item_returns_bolt11_state() {
+        let response = MintQuoteBolt11Response {
+            quote: "quote-1".to_string(),
+            request: "bolt11".to_string(),
+            amount: Some(Amount::from(100u64)),
+            unit: Some(CurrencyUnit::Sat),
+            state: MintQuoteState::Paid,
+            expiry: Some(42),
+            pubkey: None,
+        };
+
+        let item: BatchQuoteStatusItem = response.clone().into();
+        assert_eq!(item.state(), MintQuoteState::Paid);
+
+        match item {
+            BatchQuoteStatusItem::Bolt11(inner) => assert_eq!(inner.quote, response.quote),
+            _ => panic!("Expected bolt11 variant"),
+        }
+    }
+
+    #[test]
+    fn batch_quote_status_item_derives_bolt12_state() {
+        let pubkey = PublicKey::from_str(
+            "0279BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798",
+        )
+        .expect("valid pubkey");
+
+        let response = MintQuoteBolt12Response {
+            quote: "quote-2".to_string(),
+            request: "bolt12".to_string(),
+            amount: Some(Amount::from(200u64)),
+            unit: CurrencyUnit::Sat,
+            expiry: Some(100),
+            pubkey,
+            amount_paid: Amount::from(200u64),
+            amount_issued: Amount::from(50u64),
+        };
+
+        let item: BatchQuoteStatusItem = response.into();
+        assert_eq!(item.state(), MintQuoteState::Paid);
+
+        match item {
+            BatchQuoteStatusItem::Bolt12(inner) => {
+                assert_eq!(inner.quote.quote, "quote-2");
+                assert_eq!(inner.state(), MintQuoteState::Paid);
+            }
+            _ => panic!("Expected bolt12 variant"),
+        }
+    }
+}

crates/cdk-axum/src/lib.rs

@@ -49,9 +49,14 @@ mod swagger_imports {
         MeltQuoteBolt11Request, MeltQuoteBolt11Response, MintQuoteBolt11Request,
         MintQuoteBolt11Response,
     };
+    pub use cdk::nuts::nut25::{MintQuoteBolt12Request, MintQuoteBolt12Response};
     #[cfg(feature = "auth")]
     pub use cdk::nuts::MintAuthRequest;
     pub use cdk::nuts::{nut04, nut05, nut15, MeltQuoteState, MintQuoteState};
+    pub use cdk::{
+        BatchQuoteStatusItem, BatchQuoteStatusRequest, BatchQuoteStatusResponse,
+        MintQuoteBolt12BatchStatusResponse,
+    };
 }
 
 #[cfg(feature = "swagger")]
@@ -115,6 +120,9 @@ define_api_doc! {
         BlindedMessage,
         BlindSignature,
         BlindSignatureDleq,
+        BatchQuoteStatusItem,
+        BatchQuoteStatusRequest,
+        BatchQuoteStatusResponse,
         CheckStateRequest,
         CheckStateResponse,
         ContactInfo,
@@ -137,6 +145,9 @@ define_api_doc! {
         MintInfo,
         MintQuoteBolt11Request,
         MintQuoteBolt11Response<String>,
+        MintQuoteBolt12Request,
+        MintQuoteBolt12Response<String>,
+        MintQuoteBolt12BatchStatusResponse<String>,
         MintQuoteState,
         MintMethodSettings,
         MintVersion,
@@ -171,6 +182,9 @@ define_api_doc! {
         BlindedMessage,
         BlindSignature,
         BlindSignatureDleq,
+        BatchQuoteStatusItem,
+        BatchQuoteStatusRequest,
+        BatchQuoteStatusResponse,
         CheckStateRequest,
         CheckStateResponse,
         ContactInfo,
@@ -193,6 +207,9 @@ define_api_doc! {
         MintInfo,
         MintQuoteBolt11Request,
         MintQuoteBolt11Response<String>,
+        MintQuoteBolt12Request,
+        MintQuoteBolt12Response<String>,
+        MintQuoteBolt12BatchStatusResponse<String>,
         MintQuoteState,
         MintMethodSettings,
         MintVersion,
@@ -297,6 +314,8 @@ pub async fn create_mint_router_with_custom_cache(
             get(get_check_mint_bolt11_quote),
         )
         .route("/mint/bolt11", post(cache_post_mint_bolt11))
+        .route("/mint/{method}/check", post(cache_post_batch_check_mint))
+        .route("/mint/{method}/batch", post(cache_post_batch_mint))
         .route("/melt/quote/bolt11", post(post_melt_bolt11_quote))
         .route("/ws", get(ws_handler))
         .route(