feat(payment-processor): propagate mint quote_id to backend

Adds the mint's QuoteId to the three OutgoingPaymentOptions struct variants
so custom payment-method backends can deterministically correlate their
`get_payment_quote` and `make_payment` calls for the same melt.

Today, the gRPC payment-processor proto carries no link between those two
calls for the same melt: a backend's `get_payment_quote` returns a
PaymentQuoteResponse whose `request_lookup_id` the mint stores on the quote,
but the eventual `make_payment` receives an OutgoingPaymentOptions with
neither the stored lookup_id nor the mint's quote_id (`from_melt_quote_with_fee`
in cdk-common drops `extra_json` and has no quote_id field). bolt11/bolt12
backends are insulated by the payment_hash / offer being intrinsically
derivable from the invoice in both calls. Custom backends have no such
anchor, and have to fabricate a derivation — typically hashing `request` —
which forces the wallet to make `request` unique per melt. That's awkward
for any custom rail whose "request" doesn't naturally carry uniqueness
(branch tickets, account IDs, free-text references). With `quote_id`
plumbed through, the backend has the same stable key the mint uses
everywhere else, so correlation is trivial.

Changes:
- cdk-common::payment: add `quote_id: QuoteId` to Bolt11/Bolt12/Custom
  OutgoingPaymentOptions structs. Propagate it in `from_melt_quote_with_fee`
  from `melt_quote.id`.
- cdk::mint::melt: pre-generate the quote_id before each `get_payment_quote`
  call (bolt11, bolt12, custom paths) and pass it both to the backend and to
  `MeltQuote::new`, replacing the previous implicit auto-generation.
- payment_processor.proto: add required `string quote_id` to
  Bolt11/Bolt12/CustomOutgoingPaymentOptions and PaymentQuoteRequest.
  Field-numbers appended (5/6/7/6) to preserve wire compatibility with the
  existing fields.
- cdk-payment-processor server/client: serialize/deserialize quote_id
  directly (no Option wrapping). Empty/invalid values surface as
  `Status::invalid_argument("Invalid quote_id: ...")` from QuoteId::from_str.
- cdk-common: bump PAYMENT_PROCESSOR_PROTOCOL_VERSION 2.0.0 -> 3.0.0. The
  VersionInterceptor's strict equality check means any old mint/backend
  pair will see a clear "Protocol version mismatch" at connection time
  instead of misbehaving silently, which already covers the case where one
  side doesn't know about quote_id.
- cdk-integration-tests: extend the existing custom-payment-processor
  fixture to capture the received quote_id, and add a regression test
  asserting it matches the quote_id surfaced to the wallet.

Existing bolt11/bolt12 backends (cln, lnd, lnbits, ldk-node, fake-wallet)
need no code changes — they continue to correlate via payment_hash / offer
and simply ignore the new field on the OutgoingPaymentOptions struct they
already receive. The struct gains one field; consumers using non-exhaustive
field access (`opts.bolt11`, `opts.melt_options`, etc.) are unaffected.
Only consumers that exhaustively destructure the struct would need to add
the new field to their pattern.

Author: zeugmaster

crates/cdk-common/src/lib.rs

@@ -16,7 +16,7 @@ pub mod auth;
 pub const MINT_RPC_PROTOCOL_VERSION: &str = "1.0.0";
 
 /// Protocol version for gRPC Payment Processor communication
-pub const PAYMENT_PROCESSOR_PROTOCOL_VERSION: &str = "2.0.0";
+pub const PAYMENT_PROCESSOR_PROTOCOL_VERSION: &str = "3.0.0";
 
 #[cfg(feature = "grpc")]
 pub mod grpc;

crates/cdk-common/src/payment.rs

@@ -251,6 +251,11 @@ pub struct Bolt11OutgoingPaymentOptions {
     pub timeout_secs: Option<u64>,
     /// Melt options
     pub melt_options: Option<MeltOptions>,
+    /// The mint's quote id for this melt. Set in both `get_payment_quote`
+    /// and `make_payment` so backends can correlate the two calls. For
+    /// BOLT11 backends the payment_hash already provides correlation, so
+    /// this is informational; it is still required for protocol uniformity.
+    pub quote_id: QuoteId,
 }
 
 /// Options for BOLT12 outgoing payments
@@ -264,6 +269,8 @@ pub struct Bolt12OutgoingPaymentOptions {
     pub timeout_secs: Option<u64>,
     /// Melt options
     pub melt_options: Option<MeltOptions>,
+    /// The mint's quote id for this melt. See [`Bolt11OutgoingPaymentOptions::quote_id`].
+    pub quote_id: QuoteId,
 }
 
 /// Options for custom outgoing payments
@@ -284,6 +291,12 @@ pub struct CustomOutgoingPaymentOptions {
     /// These fields are passed through to the payment processor for
     /// method-specific validation.
     pub extra_json: Option<String>,
+    /// The mint's quote id for this melt. Custom backends should use this
+    /// as the stable correlation key between `get_payment_quote` and
+    /// `make_payment` (and any later `check_outgoing_payment` polls) — it
+    /// is the only field guaranteed to be unique per melt without relying
+    /// on wallet-supplied uniqueness in `request`.
+    pub quote_id: QuoteId,
 }
 
 /// Options for outgoing payments
@@ -303,13 +316,15 @@ impl OutgoingPaymentOptions {
         melt_quote: MeltQuote,
     ) -> Result<OutgoingPaymentOptions, Error> {
         let fee_reserve = melt_quote.fee_reserve();
+        let quote_id = melt_quote.id.clone();
         match &melt_quote.request {
             MeltPaymentRequest::Bolt11 { bolt11 } => Ok(OutgoingPaymentOptions::Bolt11(Box::new(
                 Bolt11OutgoingPaymentOptions {
                     max_fee_amount: Some(fee_reserve),
                     timeout_secs: None,
                     bolt11: bolt11.clone(),
                     melt_options: melt_quote.options,
+                    quote_id,
                 },
             ))),
             MeltPaymentRequest::Bolt12 { offer } => {
@@ -325,6 +340,7 @@ impl OutgoingPaymentOptions {
                         timeout_secs: None,
                         offer: *offer.clone(),
                         melt_options,
+                        quote_id,
                     },
                 )))
             }
@@ -336,6 +352,7 @@ impl OutgoingPaymentOptions {
                     timeout_secs: None,
                     melt_options: melt_quote.options,
                     extra_json: None,
+                    quote_id,
                 }),
             )),
         }

crates/cdk-integration-tests/tests/integration_tests_pure.rs

@@ -2245,8 +2245,18 @@ async fn test_restore_after_keyset_rotation() {
     );
 }
 
-#[derive(Debug)]
-struct CustomPaymentProcessor;
+#[derive(Debug, Default)]
+struct CustomPaymentProcessor {
+    /// Captures the quote_id seen by `get_payment_quote` so tests can assert
+    /// the mint propagates it correctly.
+    last_quote_id: std::sync::Mutex<Option<cdk_common::QuoteId>>,
+}
+
+impl CustomPaymentProcessor {
+    fn last_quote_id(&self) -> Option<cdk_common::QuoteId> {
+        self.last_quote_id.lock().expect("poisoned").clone()
+    }
+}
 
 #[async_trait::async_trait]
 impl MintPayment for CustomPaymentProcessor {
@@ -2282,6 +2292,11 @@ impl MintPayment for CustomPaymentProcessor {
                     Some("{\"request_metadata\":true}".to_string())
                 );
 
+                // Capture the mint-supplied quote_id; the new-in-3.0 protocol
+                // field that lets backends correlate get_payment_quote with the
+                // eventual make_payment.
+                *self.last_quote_id.lock().expect("poisoned") = Some(custom.quote_id.clone());
+
                 Ok(PaymentQuoteResponse {
                     request_lookup_id: Some(PaymentIdentifier::CustomId(
                         "custom-lookup-id".to_string(),
@@ -2368,7 +2383,7 @@ async fn test_custom_melt_quote_status_preserves_extra_json() {
             CurrencyUnit::Sat,
             PaymentMethod::Custom("test-custom".to_string()),
             cdk::mint::MintMeltLimits::new(1, 10_000),
-            Arc::new(CustomPaymentProcessor),
+            Arc::new(CustomPaymentProcessor::default()),
         )
         .await
         .expect("custom payment processor");
@@ -2416,3 +2431,60 @@ async fn test_custom_melt_quote_status_preserves_extra_json() {
         }))
     );
 }
+
+#[tokio::test]
+async fn test_custom_melt_quote_id_propagates_to_payment_processor() {
+    setup_tracing();
+
+    let localstore = Arc::new(cdk_sqlite::mint::memory::empty().await.expect("memory db"));
+    let processor = Arc::new(CustomPaymentProcessor::default());
+
+    let mut mint_builder = cdk::mint::MintBuilder::new(localstore.clone());
+    let mnemonic = Mnemonic::generate(12).expect("mnemonic");
+    mint_builder
+        .add_payment_processor(
+            CurrencyUnit::Sat,
+            PaymentMethod::Custom("test-custom".to_string()),
+            cdk::mint::MintMeltLimits::new(1, 10_000),
+            processor.clone(),
+        )
+        .await
+        .expect("custom payment processor");
+
+    mint_builder = mint_builder
+        .with_name("quote-id propagation test".to_string())
+        .with_description("quote-id propagation test".to_string())
+        .with_urls(vec!["https://example-mint".to_string()])
+        .with_limits(2000, 2000);
+
+    let mint = mint_builder
+        .build_with_seed(localstore.clone(), &mnemonic.to_seed_normalized(""))
+        .await
+        .expect("mint build");
+
+    mint.set_quote_ttl(QuoteTTL::new(10_000, 10_000))
+        .await
+        .expect("quote ttl");
+
+    let response = mint
+        .get_melt_quote(cdk_common::MeltQuoteRequest::Custom(
+            cdk::nuts::MeltQuoteCustomRequest {
+                method: "test-custom".to_string(),
+                request: "custom-request".to_string(),
+                unit: CurrencyUnit::Sat,
+                extra: serde_json::json!({ "request_metadata": true }),
+            },
+        ))
+        .await
+        .expect("custom melt quote");
+
+    let response_quote_id = response.quote().clone();
+    let seen_by_processor = processor
+        .last_quote_id()
+        .expect("processor must have received a quote_id in get_payment_quote");
+
+    assert_eq!(
+        seen_by_processor, response_quote_id,
+        "the quote_id passed to get_payment_quote must equal the quote_id surfaced to the wallet",
+    );
+}

crates/cdk-payment-processor/src/proto/client.rs

@@ -253,13 +253,20 @@ impl MintPayment for PaymentProcessorClient {
             _ => None,
         };
 
+        let quote_id = match &options {
+            cdk_common::payment::OutgoingPaymentOptions::Custom(opts) => opts.quote_id.to_string(),
+            cdk_common::payment::OutgoingPaymentOptions::Bolt11(opts) => opts.quote_id.to_string(),
+            cdk_common::payment::OutgoingPaymentOptions::Bolt12(opts) => opts.quote_id.to_string(),
+        };
+
         let response = inner
             .get_payment_quote(Request::new(PaymentQuoteRequest {
                 request: proto_request,
                 unit: unit.to_string(),
                 options: proto_options.map(Into::into),
                 request_type: request_type.into(),
                 extra_json,
+                quote_id,
             }))
             .await
             .map_err(|err| {
@@ -292,6 +299,7 @@ impl MintPayment for PaymentProcessorClient {
                             timeout_secs: opts.timeout_secs,
                             melt_options: opts.melt_options.map(Into::into),
                             extra_json: opts.extra_json.clone(),
+                            quote_id: opts.quote_id.to_string(),
                         },
                     )),
                 }
@@ -304,6 +312,7 @@ impl MintPayment for PaymentProcessorClient {
                             max_fee_amount: opts.max_fee_amount.into_proto(),
                             timeout_secs: opts.timeout_secs,
                             melt_options: opts.melt_options.map(Into::into),
+                            quote_id: opts.quote_id.to_string(),
                         },
                     )),
                 }
@@ -316,6 +325,7 @@ impl MintPayment for PaymentProcessorClient {
                             max_fee_amount: opts.max_fee_amount.into_proto(),
                             timeout_secs: opts.timeout_secs,
                             melt_options: opts.melt_options.map(Into::into),
+                            quote_id: opts.quote_id.to_string(),
                         },
                     )),
                 }

crates/cdk-payment-processor/src/proto/payment_processor.proto

@@ -134,6 +134,10 @@ message PaymentQuoteRequest {
   // Extra payment-method-specific fields as JSON string
   // For custom payment methods, these fields are passed through for validation
   optional string extra_json = 5;
+  // The mint's quote_id for the melt this payment-quote is for. Required;
+  // backends should use this as the stable correlation key between
+  // get_payment_quote and the eventual make_payment.
+  string quote_id = 6;
 }
 
 enum QuoteState {
@@ -162,13 +166,17 @@ message Bolt11OutgoingPaymentOptions {
   optional AmountMessage max_fee_amount = 2;
   optional uint64 timeout_secs = 3;
   optional MeltOptions melt_options = 4;
+  // The mint's quote_id for this melt. Required.
+  string quote_id = 5;
 }
 
 message Bolt12OutgoingPaymentOptions {
   string offer = 1;
   optional AmountMessage max_fee_amount = 2;
   optional uint64 timeout_secs = 3;
   optional MeltOptions melt_options = 5;
+  // The mint's quote_id for this melt. Required.
+  string quote_id = 6;
 }
 message CustomOutgoingPaymentOptions {
   string offer = 1;
@@ -178,6 +186,9 @@ message CustomOutgoingPaymentOptions {
   // Extra payment-method-specific fields as JSON string
   // These fields are flattened into the JSON representation on the client side
   optional string extra_json = 6;
+  // The mint's quote_id for this melt. Required. Custom backends should use
+  // this as the stable correlation key with the earlier get_payment_quote call.
+  string quote_id = 7;
 }
 
 enum OutgoingPaymentOptionsType {

crates/cdk-payment-processor/src/proto/server.rs

@@ -7,7 +7,7 @@ use std::time::Duration;
 
 use cdk_common::grpc::create_version_check_interceptor;
 use cdk_common::payment::{IncomingPaymentOptions, MintPayment};
-use cdk_common::CurrencyUnit;
+use cdk_common::{CurrencyUnit, QuoteId};
 use futures::{Stream, StreamExt};
 use lightning::offers::offer::Offer;
 use tokio::sync::{mpsc, Notify};
@@ -282,6 +282,8 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
         let unit = CurrencyUnit::from_str(&request.unit)
             .map_err(|_| Status::invalid_argument("Invalid currency unit"))?;
 
+        let quote_id = parse_quote_id(&request.quote_id)?;
+
         let options = match request.request_type() {
             OutgoingPaymentRequestType::Bolt11Invoice => {
                 let bolt11: cdk_common::Bolt11Invoice =
@@ -293,6 +295,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                         max_fee_amount: None,
                         timeout_secs: None,
                         melt_options: request.options.map(Into::into),
+                        quote_id,
                     },
                 ))
             }
@@ -307,6 +310,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                         max_fee_amount: None,
                         timeout_secs: None,
                         melt_options: request.options.map(Into::into),
+                        quote_id,
                     },
                 ))
             }
@@ -320,6 +324,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                         timeout_secs: None,
                         melt_options: request.options.map(Into::into),
                         extra_json: request.extra_json.clone(),
+                        quote_id,
                     },
                 ))
             }
@@ -365,13 +370,15 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                     .max_fee_amount
                     .try_from_proto()
                     .map_err(|_| Status::invalid_argument("Invalid max_fee_amount"))?;
+                let quote_id = parse_quote_id(&opts.quote_id)?;
 
                 cdk_common::payment::OutgoingPaymentOptions::Bolt11(Box::new(
                     cdk_common::payment::Bolt11OutgoingPaymentOptions {
                         bolt11,
                         max_fee_amount,
                         timeout_secs: opts.timeout_secs,
                         melt_options: opts.melt_options.map(Into::into),
+                        quote_id,
                     },
                 ))
             }
@@ -382,13 +389,15 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                     .max_fee_amount
                     .try_from_proto()
                     .map_err(|_| Status::invalid_argument("Invalid max_fee_amount"))?;
+                let quote_id = parse_quote_id(&opts.quote_id)?;
 
                 cdk_common::payment::OutgoingPaymentOptions::Bolt12(Box::new(
                     cdk_common::payment::Bolt12OutgoingPaymentOptions {
                         offer,
                         max_fee_amount,
                         timeout_secs: opts.timeout_secs,
                         melt_options: opts.melt_options.map(Into::into),
+                        quote_id,
                     },
                 ))
             }
@@ -397,6 +406,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                     .max_fee_amount
                     .try_from_proto()
                     .map_err(|_| Status::invalid_argument("Invalid max_fee_amount"))?;
+                let quote_id = parse_quote_id(&opts.quote_id)?;
 
                 cdk_common::payment::OutgoingPaymentOptions::Custom(Box::new(
                     cdk_common::payment::CustomOutgoingPaymentOptions {
@@ -406,6 +416,7 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
                         timeout_secs: opts.timeout_secs,
                         melt_options: opts.melt_options.map(Into::into),
                         extra_json: opts.extra_json,
+                        quote_id,
                     },
                 ))
             }
@@ -528,3 +539,8 @@ impl CdkPaymentProcessor for PaymentProcessorServer {
         ))
     }
 }
+
+fn parse_quote_id(s: &str) -> Result<QuoteId, Status> {
+    s.parse()
+        .map_err(|err| Status::invalid_argument(format!("Invalid quote_id: {err}")))
+}