feat(nut18): support payment request method fees

Replace the flat fee reserve with `sm` method objects carrying optional
`mf` values, and encode them as NUT-26 supported-method sub-TLVs on tag
0x0a.

Apply method fees when paying from an unlisted mint, or from any mint
when the request has no mint list. Select the lowest fee among matching
NUT-05 melt methods and keep requested amounts net of input fees.

Cover the current NUT-18 and NUT-26 spec vectors, including the
preferred-method-fee cases. Accept the standard-base64 NUT-18 vectors
published by the spec while continuing to emit urlsafe CREQ-A strings.

Author: thesimplekid

crates/cashu/examples/payment_request_encoding_benchmark.rs

@@ -95,7 +95,6 @@ fn minimal_comparison() -> Result<(), Box<dyn std::error::Error>> {
         single_use: None,
         mints: vec![MintUrl::from_str("https://mint.example.com")?],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: None,
         transports: vec![],
@@ -114,7 +113,6 @@ fn amount_unit_comparison() -> Result<(), Box<dyn std::error::Error>> {
         single_use: None,
         mints: vec![MintUrl::from_str("https://mint.example.com")?],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: None,
         transports: vec![],
@@ -138,7 +136,6 @@ fn multiple_mints_comparison() -> Result<(), Box<dyn std::error::Error>> {
             MintUrl::from_str("https://backup-mint.cashu.space")?,
         ],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: Some("Payment with multiple mint options".to_string()),
         transports: vec![],
@@ -166,7 +163,6 @@ fn transport_comparison() -> Result<(), Box<dyn std::error::Error>> {
         single_use: Some(true),
         mints: vec![MintUrl::from_str("https://mint.example.com")?],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: Some("Payment with callback transport".to_string()),
         transports: vec![transport],
@@ -206,7 +202,6 @@ fn complete_with_nut10_comparison() -> Result<(), Box<dyn std::error::Error>> {
             MintUrl::from_str("https://mint2.example.com")?,
         ],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: Some("Complete payment with P2PK locking and refund key".to_string()),
         transports: vec![transport],
@@ -261,7 +256,6 @@ fn very_complex_comparison() -> Result<(), Box<dyn std::error::Error>> {
             MintUrl::from_str("https://emergency-mint.example.io")?,
         ],
         mint_preferred: None,
-        fee_reserve: None,
         supported_methods: vec![],
         description: Some("Complex payment with multiple mints and transports".to_string()),
         transports: vec![transport1, transport2],
@@ -522,7 +516,6 @@ mod tests {
             single_use: None,
             mints: vec![MintUrl::from_str("https://mint.example.com").unwrap()],
             mint_preferred: None,
-            fee_reserve: None,
             supported_methods: vec![],
             description: Some("Test".to_string()),
             transports: vec![],

crates/cashu/src/nuts/mod.rs

@@ -73,8 +73,8 @@ pub use nut14::HTLCWitness;
 pub use nut15::{Mpp, MppMethodSettings, Settings as NUT15Settings};
 pub use nut17::NotificationPayload;
 pub use nut18::{
-    Nut10SecretRequest, PaymentRequest, PaymentRequestBuilder, PaymentRequestPayload, Transport,
-    TransportBuilder, TransportType,
+    Nut10SecretRequest, PaymentRequest, PaymentRequestBuilder, PaymentRequestPayload,
+    SupportedMethod, Transport, TransportBuilder, TransportType,
 };
 pub use nut23::{
     MeltOptions, MeltQuoteBolt11Request, MeltQuoteBolt11Response, MintQuoteBolt11Request,

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

@@ -11,6 +11,8 @@ pub mod secret;
 pub mod transport;
 
 pub use error::Error;
-pub use payment_request::{PaymentRequest, PaymentRequestBuilder, PaymentRequestPayload};
+pub use payment_request::{
+    PaymentRequest, PaymentRequestBuilder, PaymentRequestPayload, SupportedMethod,
+};
 pub use secret::Nut10SecretRequest;
 pub use transport::{Transport, TransportBuilder, TransportType};

crates/cashu/src/nuts/nut18/payment_request.rs

@@ -17,6 +17,43 @@ use crate::Amount;
 
 const PAYMENT_REQUEST_PREFIX: &str = "creqA";
 
+/// Payment method accepted by the receiver for a payment request.
+#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+pub struct SupportedMethod {
+    /// Payment method name, such as `bolt11`, `bolt12`, or `onchain`.
+    #[serde(rename = "mn")]
+    pub method: String,
+    /// Additional fee in the request unit for payments from non-preferred mints.
+    #[serde(rename = "mf")]
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fee: Option<Amount>,
+}
+
+impl SupportedMethod {
+    /// Create a supported method without an additional method fee.
+    pub fn new<S>(method: S) -> Self
+    where
+        S: Into<String>,
+    {
+        Self {
+            method: method.into(),
+            fee: None,
+        }
+    }
+
+    /// Create a supported method with an additional method fee.
+    pub fn with_fee<S, A>(method: S, fee: A) -> Self
+    where
+        S: Into<String>,
+        A: Into<Amount>,
+    {
+        Self {
+            method: method.into(),
+            fee: Some(fee.into()),
+        }
+    }
+}
+
 /// NUT-18 payment request.
 ///
 /// A receiver creates this request to tell a payer how much to send, which
@@ -27,7 +64,7 @@ pub struct PaymentRequest {
     /// Payment id to include in the payment payload.
     #[serde(rename = "i")]
     pub payment_id: Option<String>,
-    /// Requested amount.
+    /// Requested amount net of input fees.
     ///
     /// If this is set, [`Self::unit`] must also be set.
     #[serde(rename = "a")]
@@ -55,22 +92,15 @@ pub struct PaymentRequest {
     #[serde(rename = "mp")]
     #[serde(skip_serializing_if = "Option::is_none")]
     pub mint_preferred: Option<bool>,
-    /// Additional fee reserve for payments from outside a preferred mint list.
-    ///
-    /// When [`Self::mints`] is non-empty and [`Self::mint_preferred`] is
-    /// `true`, a payer using a mint outside [`Self::mints`] must add this
-    /// amount to the requested amount. Ignored when the mint list is strict or
-    /// empty.
-    #[serde(rename = "fr")]
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub fee_reserve: Option<Amount>,
     /// Payment methods the payer's mint must support.
     ///
     /// If non-empty, the payer must send ecash from a mint that supports at
-    /// least one listed method, such as `bolt11`, `bolt12`, or `onchain`.
+    /// least one listed method. Each method can carry a fee that only applies
+    /// to payments from non-preferred mints, or from any mint if no mint list is
+    /// set.
     #[serde(rename = "sm")]
     #[serde(skip_serializing_if = "Vec::is_empty", default)]
-    pub supported_methods: Vec<String>,
+    pub supported_methods: Vec<SupportedMethod>,
     /// Human-readable description for the payer to display.
     #[serde(rename = "d")]
     pub description: Option<String>,
@@ -126,7 +156,18 @@ impl FromStr for PaymentRequest {
 
         let decode_config = general_purpose::GeneralPurposeConfig::new()
             .with_decode_padding_mode(bitcoin::base64::engine::DecodePaddingMode::Indifferent);
-        let decoded = GeneralPurpose::new(&alphabet::URL_SAFE, decode_config).decode(s)?;
+        let decoded = match GeneralPurpose::new(&alphabet::URL_SAFE, decode_config).decode(s) {
+            Ok(decoded) => decoded,
+            Err(url_safe_err) => {
+                let decode_config = general_purpose::GeneralPurposeConfig::new()
+                    .with_decode_padding_mode(
+                        bitcoin::base64::engine::DecodePaddingMode::Indifferent,
+                    );
+                GeneralPurpose::new(&alphabet::STANDARD, decode_config)
+                    .decode(s)
+                    .map_err(|_| url_safe_err)?
+            }
+        };
 
         Ok(ciborium::from_reader(&decoded[..])?)
     }
@@ -141,8 +182,7 @@ pub struct PaymentRequestBuilder {
     single_use: Option<bool>,
     mints: Vec<MintUrl>,
     mint_preferred: Option<bool>,
-    fee_reserve: Option<Amount>,
-    supported_methods: Vec<String>,
+    supported_methods: Vec<SupportedMethod>,
     description: Option<String>,
     transports: Vec<Transport>,
     nut10: Option<Nut10SecretRequest>,
@@ -206,18 +246,15 @@ impl PaymentRequestBuilder {
         self
     }
 
-    /// Set fee reserve for payments from outside a preferred mint list.
-    pub fn fee_reserve<A>(mut self, fee_reserve: A) -> Self
-    where
-        A: Into<Amount>,
-    {
-        self.fee_reserve = Some(fee_reserve.into());
+    /// Set payment methods the payer's mint must support.
+    pub fn supported_methods(mut self, methods: Vec<SupportedMethod>) -> Self {
+        self.supported_methods = methods;
         self
     }
 
-    /// Set payment methods the payer's mint must support.
-    pub fn supported_methods(mut self, methods: Vec<String>) -> Self {
-        self.supported_methods = methods;
+    /// Add a payment method the payer's mint must support.
+    pub fn add_supported_method(mut self, method: SupportedMethod) -> Self {
+        self.supported_methods.push(method);
         self
     }
 
@@ -254,7 +291,6 @@ impl PaymentRequestBuilder {
             single_use: self.single_use,
             mints: self.mints,
             mint_preferred: self.mint_preferred,
-            fee_reserve: self.fee_reserve,
             supported_methods: self.supported_methods,
             description: self.description,
             transports: self.transports,
@@ -324,7 +360,6 @@ mod tests {
                 .parse()
                 .expect("valid mint url")],
             mint_preferred: None,
-            fee_reserve: None,
             supported_methods: vec![],
             description: None,
             transports: vec![transport.clone()],
@@ -499,6 +534,38 @@ mod tests {
         assert_eq!(decoded.mint_preferred, Some(false));
     }
 
+    #[test]
+    fn test_supported_methods_serialize_as_method_objects() {
+        let payment_request = PaymentRequestBuilder::default()
+            .add_supported_method(SupportedMethod::new("bolt11"))
+            .add_supported_method(SupportedMethod::with_fee("bolt12", 5))
+            .build();
+
+        let value = serde_json::to_value(&payment_request).unwrap();
+        assert_eq!(
+            value.get("sm"),
+            Some(&serde_json::json!([
+                { "mn": "bolt11" },
+                { "mn": "bolt12", "mf": 5 }
+            ]))
+        );
+
+        let decoded: PaymentRequest = serde_json::from_value(serde_json::json!({
+            "sm": [
+                { "mn": "bolt11" },
+                { "mn": "bolt12", "mf": 5 }
+            ]
+        }))
+        .unwrap();
+        assert_eq!(
+            decoded.supported_methods,
+            vec![
+                SupportedMethod::new("bolt11"),
+                SupportedMethod::with_fee("bolt12", 5),
+            ]
+        );
+    }
+
     #[test]
     fn test_nut10_secret_request_htlc() {
         let bolt11 = "lnbc100n1p5z3a63pp56854ytysg7e5z9fl3w5mgvrlqjfcytnjv8ff5hm5qt6gl6alxesqdqqcqzzsxqyz5vqsp5p0x0dlhn27s63j4emxnk26p7f94u0lyarnfp5yqmac9gzy4ngdss9qxpqysgqne3v0hnzt2lp0hc69xpzckk0cdcar7glvjhq60lsrfe8gejdm8c564prrnsft6ctxxyrewp4jtezrq3gxxqnfjj0f9tw2qs9y0lslmqpfu7et9";
@@ -625,6 +692,72 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_complete_payment_request() {
+        // Complete payment request with all optional fields included
+        let expected_encoded = "creqAqGF0gaNhdGRwb3N0YWF4G2h0dHBzOi8vYXBpLmV4YW1wbGUuY29tL3BheWFn92FpaDQ4NDBmNTFlYWEZA+hhdWNzYXRhbYF4GGh0dHBzOi8vbWludC5leGFtcGxlLmNvbWFkcFByb2R1Y3QgcHVyY2hhc2Vhc/VlbnV0MTCjYWtkUDJQS2FkeEIwM2JhZjBjM2FjMjIwMzY2YzJjMzk3YmY5MzA1NzljNDE2MzQzNTU4NGY1NzNiMTA5MTA5ODdjNTQ0YzU5ZTYxZjFhdIGCZ3B1cnBvc2Vnb2ZmbGluZQ==";
+
+        let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap();
+
+        assert_eq!(decoded_from_spec.payment_id, Some("4840f51e".to_string()));
+        assert_eq!(decoded_from_spec.amount, Some(Amount::from(1000)));
+        assert_eq!(decoded_from_spec.unit, Some(CurrencyUnit::Sat));
+        assert_eq!(decoded_from_spec.single_use, Some(true));
+        assert_eq!(
+            decoded_from_spec.mints,
+            vec![MintUrl::from_str("https://mint.example.com").unwrap()]
+        );
+        assert_eq!(
+            decoded_from_spec.description,
+            Some("Product purchase".to_string())
+        );
+        assert_eq!(decoded_from_spec.transports.len(), 1);
+        assert_eq!(
+            decoded_from_spec.transports[0]._type,
+            TransportType::HttpPost
+        );
+        assert_eq!(
+            decoded_from_spec.transports[0].target,
+            "https://api.example.com/pay"
+        );
+
+        let nut10 = decoded_from_spec.nut10.expect("nut10");
+        assert_eq!(nut10.kind, Kind::P2PK);
+        assert_eq!(
+            nut10.data,
+            "03baf0c3ac220366c2c397bf930579c4163435584f573b10910987c544c59e61f1"
+        );
+        assert_eq!(
+            nut10.tags,
+            Some(vec![vec!["purpose".to_string(), "offline".to_string()]])
+        );
+    }
+
+    #[test]
+    fn test_http_transport_payment_request() {
+        // HTTP POST transport payment request
+        let expected_encoded = "creqApWF0gaNhdGRwb3N0YWF4H2h0dHBzOi8vYXBpLmV4YW1wbGUuY29tL3JlY2VpdmVhZ/dhaWhhMmMxMmY0NWFhGDJhdWNzYXRhbYF4GWh0dHBzOi8vY2FzaHUuZXhhbXBsZS5jb20=";
+
+        let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap();
+
+        assert_eq!(decoded_from_spec.payment_id, Some("a2c12f45".to_string()));
+        assert_eq!(decoded_from_spec.amount, Some(Amount::from(50)));
+        assert_eq!(decoded_from_spec.unit, Some(CurrencyUnit::Sat));
+        assert_eq!(
+            decoded_from_spec.mints,
+            vec![MintUrl::from_str("https://cashu.example.com").unwrap()]
+        );
+        assert_eq!(decoded_from_spec.transports.len(), 1);
+        assert_eq!(
+            decoded_from_spec.transports[0]._type,
+            TransportType::HttpPost
+        );
+        assert_eq!(
+            decoded_from_spec.transports[0].target,
+            "https://api.example.com/receive"
+        );
+    }
+
     #[test]
     fn test_nostr_transport_payment_request() {
         // Nostr transport payment request with multiple mints
@@ -781,6 +914,33 @@ mod tests {
         assert_eq!(decoded_from_spec.payment_id.as_ref().unwrap(), "c9e45d2a");
     }
 
+    #[test]
+    fn test_preferred_mint_list_with_supported_methods() {
+        // Preferred mint list with supported methods and per-method fee
+        let expected_encoded = "creqApmFpdXByZWZlcnJlZF9mZWVfbWV0aG9kc2FhGGRhdWNzYXRhbYF4GGh0dHBzOi8vbWludC5leGFtcGxlLmNvbWJtcPVic22CoWJtbmZib2x0MTGiYm1uZmJvbHQxMmJtZgU=";
+
+        let decoded_from_spec = PaymentRequest::from_str(expected_encoded).unwrap();
+
+        assert_eq!(
+            decoded_from_spec.payment_id,
+            Some("preferred_fee_methods".to_string())
+        );
+        assert_eq!(decoded_from_spec.amount, Some(Amount::from(100)));
+        assert_eq!(decoded_from_spec.unit, Some(CurrencyUnit::Sat));
+        assert_eq!(
+            decoded_from_spec.mints,
+            vec![MintUrl::from_str("https://mint.example.com").unwrap()]
+        );
+        assert_eq!(decoded_from_spec.mint_preferred, Some(true));
+        assert_eq!(
+            decoded_from_spec.supported_methods,
+            vec![
+                SupportedMethod::new("bolt11"),
+                SupportedMethod::with_fee("bolt12", 5),
+            ]
+        );
+    }
+
     #[test]
     fn test_from_str_handles_both_formats() {
         // Create a payment request
@@ -791,7 +951,6 @@ mod tests {
             single_use: None,
             mints: vec![MintUrl::from_str("https://mint.example.com").unwrap()],
             mint_preferred: None,
-            fee_reserve: None,
             supported_methods: vec![],
             description: Some("Test both formats".to_string()),
             transports: vec![],