cdk_common/
payment.rs

1//! CDK Mint Lightning
2
3use std::convert::Infallible;
4use std::pin::Pin;
5
6use async_trait::async_trait;
7use cashu::util::hex;
8use cashu::{Bolt11Invoice, MeltOptions};
9#[cfg(feature = "prometheus")]
10use cdk_prometheus::MintMetricGuard;
11use futures::Stream;
12use lightning::offers::offer::Offer;
13use lightning_invoice::ParseOrSemanticError;
14use serde::{Deserialize, Serialize};
15use serde_json::Value;
16use thiserror::Error;
17
18use crate::mint::{MeltPaymentRequest, MeltQuote};
19use crate::nuts::nut30::MeltQuoteOnchainFeeOption;
20use crate::nuts::{CurrencyUnit, MeltQuoteState};
21use crate::{Amount, QuoteId};
22
23/// CDK Payment Error
24#[derive(Debug, Error)]
25pub enum Error {
26    /// Invoice already paid
27    #[error("Invoice already paid")]
28    InvoiceAlreadyPaid,
29    /// Invoice pay pending
30    #[error("Invoice pay is pending")]
31    InvoicePaymentPending,
32    /// Unsupported unit
33    #[error("Unsupported unit")]
34    UnsupportedUnit,
35    /// Unsupported payment option
36    #[error("Unsupported payment option")]
37    UnsupportedPaymentOption,
38    /// Payment state is unknown
39    #[error("Payment state is unknown")]
40    UnknownPaymentState,
41    /// Amount mismatch
42    #[error("Amount is not what is expected")]
43    AmountMismatch,
44    /// Invalid expiry
45    #[error("Invalid expiry")]
46    InvalidExpiry,
47    /// Lightning Error
48    #[error(transparent)]
49    Lightning(Box<dyn std::error::Error + Send + Sync>),
50    /// Onchain Error
51    #[error(transparent)]
52    Onchain(Box<dyn std::error::Error + Send + Sync>),
53    /// Serde Error
54    #[error(transparent)]
55    Serde(#[from] serde_json::Error),
56    /// AnyHow Error
57    #[error(transparent)]
58    Anyhow(#[from] anyhow::Error),
59    /// Parse Error
60    #[error(transparent)]
61    Parse(#[from] ParseOrSemanticError),
62    /// Amount Error
63    #[error(transparent)]
64    Amount(#[from] crate::amount::Error),
65    /// NUT04 Error
66    #[error(transparent)]
67    NUT04(#[from] crate::nuts::nut04::Error),
68    /// NUT05 Error
69    #[error(transparent)]
70    NUT05(#[from] crate::nuts::nut05::Error),
71    /// NUT23 Error
72    #[error(transparent)]
73    NUT23(#[from] crate::nuts::nut23::Error),
74    /// Hex error
75    #[error("Hex error")]
76    Hex(#[from] hex::Error),
77    /// Invalid hash
78    #[error("Invalid hash")]
79    InvalidHash,
80    /// Custom
81    #[error("`{0}`")]
82    Custom(String),
83}
84
85impl From<Infallible> for Error {
86    fn from(_: Infallible) -> Self {
87        unreachable!("Infallible cannot be constructed")
88    }
89}
90
91/// Payment identifier types
92#[derive(Clone, Hash, PartialEq, Eq, Deserialize, Serialize)]
93#[serde(tag = "type", content = "value")]
94pub enum PaymentIdentifier {
95    /// Label identifier
96    Label(String),
97    /// Offer ID identifier
98    OfferId(String),
99    /// Payment hash identifier
100    PaymentHash([u8; 32]),
101    /// Bolt12 payment hash
102    Bolt12PaymentHash([u8; 32]),
103    /// Payment id
104    PaymentId([u8; 32]),
105    /// Custom Payment ID
106    CustomId(String),
107    /// Quote ID
108    QuoteId(QuoteId),
109}
110
111impl PaymentIdentifier {
112    /// Create new [`PaymentIdentifier`]
113    pub fn new(kind: &str, identifier: &str) -> Result<Self, Error> {
114        match kind.to_lowercase().as_str() {
115            "label" => Ok(Self::Label(identifier.to_string())),
116            "offer_id" => Ok(Self::OfferId(identifier.to_string())),
117            "payment_hash" => Ok(Self::PaymentHash(
118                hex::decode(identifier)?
119                    .try_into()
120                    .map_err(|_| Error::InvalidHash)?,
121            )),
122            "bolt12_payment_hash" => Ok(Self::Bolt12PaymentHash(
123                hex::decode(identifier)?
124                    .try_into()
125                    .map_err(|_| Error::InvalidHash)?,
126            )),
127            "custom" => Ok(Self::CustomId(identifier.to_string())),
128            "payment_id" => Ok(Self::PaymentId(
129                hex::decode(identifier)?
130                    .try_into()
131                    .map_err(|_| Error::InvalidHash)?,
132            )),
133            "quote_id" => {
134                Ok(Self::QuoteId(identifier.parse().map_err(|_| {
135                    Error::Custom("Invalid QuoteId".to_string())
136                })?))
137            }
138            _ => Err(Error::UnsupportedPaymentOption),
139        }
140    }
141
142    /// Payment id kind
143    pub fn kind(&self) -> String {
144        match self {
145            Self::Label(_) => "label".to_string(),
146            Self::OfferId(_) => "offer_id".to_string(),
147            Self::PaymentHash(_) => "payment_hash".to_string(),
148            Self::Bolt12PaymentHash(_) => "bolt12_payment_hash".to_string(),
149            Self::PaymentId(_) => "payment_id".to_string(),
150            Self::CustomId(_) => "custom".to_string(),
151            Self::QuoteId(_) => "quote_id".to_string(),
152        }
153    }
154}
155
156impl std::fmt::Display for PaymentIdentifier {
157    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
158        match self {
159            Self::Label(l) => write!(f, "{l}"),
160            Self::OfferId(o) => write!(f, "{o}"),
161            Self::PaymentHash(h) => write!(f, "{}", hex::encode(h)),
162            Self::Bolt12PaymentHash(h) => write!(f, "{}", hex::encode(h)),
163            Self::PaymentId(h) => write!(f, "{}", hex::encode(h)),
164            Self::CustomId(c) => write!(f, "{c}"),
165            Self::QuoteId(q) => write!(f, "{q}"),
166        }
167    }
168}
169
170impl std::fmt::Debug for PaymentIdentifier {
171    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
172        match self {
173            PaymentIdentifier::PaymentHash(h) => write!(f, "PaymentHash({})", hex::encode(h)),
174            PaymentIdentifier::Bolt12PaymentHash(h) => {
175                write!(f, "Bolt12PaymentHash({})", hex::encode(h))
176            }
177            PaymentIdentifier::PaymentId(h) => write!(f, "PaymentId({})", hex::encode(h)),
178            PaymentIdentifier::Label(s) => write!(f, "Label({})", s),
179            PaymentIdentifier::OfferId(s) => write!(f, "OfferId({})", s),
180            PaymentIdentifier::CustomId(s) => write!(f, "CustomId({})", s),
181            PaymentIdentifier::QuoteId(q) => write!(f, "QuoteId({})", q),
182        }
183    }
184}
185
186/// Options for creating a BOLT11 incoming payment request
187#[derive(Debug, Clone, PartialEq, Eq, Hash)]
188pub struct Bolt11IncomingPaymentOptions {
189    /// Optional description for the payment request
190    pub description: Option<String>,
191    /// Amount for the payment request in sats
192    pub amount: Amount<CurrencyUnit>,
193    /// Optional expiry time as Unix timestamp in seconds
194    pub unix_expiry: Option<u64>,
195}
196
197impl Default for Bolt11IncomingPaymentOptions {
198    fn default() -> Self {
199        Self {
200            description: None,
201            amount: Amount::new(0, CurrencyUnit::Sat),
202            unix_expiry: None,
203        }
204    }
205}
206
207/// Options for creating a BOLT12 incoming payment request
208#[derive(Debug, Clone, Default, PartialEq, Eq, Hash)]
209pub struct Bolt12IncomingPaymentOptions {
210    /// Optional description for the payment request
211    pub description: Option<String>,
212    /// Optional amount for the payment request in sats
213    pub amount: Option<Amount<CurrencyUnit>>,
214    /// Optional expiry time as Unix timestamp in seconds
215    pub unix_expiry: Option<u64>,
216}
217
218/// Options for creating a custom incoming payment request
219#[derive(Debug, Clone, PartialEq, Eq, Hash)]
220pub struct CustomIncomingPaymentOptions {
221    /// Payment method name (e.g., "paypal", "venmo")
222    pub method: String,
223    /// Optional description for the payment request
224    pub description: Option<String>,
225    /// Amount for the payment request
226    pub amount: Amount<CurrencyUnit>,
227    /// Optional expiry time as Unix timestamp in seconds
228    pub unix_expiry: Option<u64>,
229    /// Extra payment-method-specific fields as JSON string
230    ///
231    /// These fields are passed through to the payment processor for
232    /// method-specific validation (e.g., ehash share).
233    pub extra_json: Option<String>,
234}
235
236/// Options for creating an onchain incoming payment request
237#[derive(Debug, Clone, PartialEq, Eq, Hash)]
238pub struct OnchainIncomingPaymentOptions {
239    /// Quote ID for the incoming payment
240    pub quote_id: QuoteId,
241}
242
243/// Options for incoming payments
244#[derive(Debug, Clone, PartialEq, Eq, Hash)]
245pub enum IncomingPaymentOptions {
246    /// BOLT11 payment request options
247    Bolt11(Bolt11IncomingPaymentOptions),
248    /// BOLT12 payment request options
249    Bolt12(Box<Bolt12IncomingPaymentOptions>),
250    /// Custom payment method options
251    Custom(Box<CustomIncomingPaymentOptions>),
252    /// Onchain payment request options
253    Onchain(OnchainIncomingPaymentOptions),
254}
255
256/// Options for BOLT11 outgoing payments
257#[derive(Debug, Clone, PartialEq, Eq, Hash)]
258pub struct Bolt11OutgoingPaymentOptions {
259    /// Bolt11
260    pub bolt11: Bolt11Invoice,
261    /// Maximum fee amount allowed for the payment
262    pub max_fee_amount: Option<Amount<CurrencyUnit>>,
263    /// Optional timeout in seconds
264    pub timeout_secs: Option<u64>,
265    /// Melt options
266    pub melt_options: Option<MeltOptions>,
267    /// The mint's quote id for this melt. Set in both `get_payment_quote`
268    /// and `make_payment` so backends can correlate the two calls. For
269    /// BOLT11 backends the payment_hash already provides correlation, so
270    /// this is informational; it is still required for protocol uniformity.
271    pub quote_id: QuoteId,
272}
273
274/// Options for BOLT12 outgoing payments
275#[derive(Debug, Clone, PartialEq, Eq, Hash)]
276pub struct Bolt12OutgoingPaymentOptions {
277    /// Offer
278    pub offer: Offer,
279    /// Maximum fee amount allowed for the payment
280    pub max_fee_amount: Option<Amount<CurrencyUnit>>,
281    /// Optional timeout in seconds
282    pub timeout_secs: Option<u64>,
283    /// Melt options
284    pub melt_options: Option<MeltOptions>,
285    /// The mint's quote id for this melt. See [`Bolt11OutgoingPaymentOptions::quote_id`].
286    pub quote_id: QuoteId,
287}
288
289/// Options for custom outgoing payments
290#[derive(Debug, Clone, PartialEq, Eq, Hash)]
291pub struct CustomOutgoingPaymentOptions {
292    /// Payment method name
293    pub method: String,
294    /// Payment request string (method-specific format)
295    pub request: String,
296    /// Maximum fee amount allowed for the payment
297    pub max_fee_amount: Option<Amount<CurrencyUnit>>,
298    /// Optional timeout in seconds
299    pub timeout_secs: Option<u64>,
300    /// Melt options
301    pub melt_options: Option<MeltOptions>,
302    /// Extra payment-method-specific fields as JSON string
303    ///
304    /// These fields are passed through to the payment processor for
305    /// method-specific validation.
306    pub extra_json: Option<String>,
307    /// The mint's quote id for this melt. Custom backends should use this
308    /// as the stable correlation key between `get_payment_quote` and
309    /// `make_payment` (and any later `check_outgoing_payment` polls) — it
310    /// is the only field guaranteed to be unique per melt without relying
311    /// on wallet-supplied uniqueness in `request`.
312    pub quote_id: QuoteId,
313}
314
315/// Options for onchain outgoing payments
316#[derive(Debug, Clone, PartialEq, Eq, Hash)]
317pub struct OnchainOutgoingPaymentOptions {
318    /// Bitcoin address to send to
319    pub address: String,
320    /// Payment amount
321    pub amount: Amount<CurrencyUnit>,
322    /// Maximum fee amount allowed for the payment
323    pub max_fee_amount: Option<Amount<CurrencyUnit>>,
324    /// Opaque stable identifier supplied by the mint.
325    ///
326    /// The mint generates this value and uses it to correlate the quote with
327    /// subsequent `make_payment` and `check_outgoing_payment` calls. Backends
328    /// MUST NOT synthesize or modify this value. Backends MUST persist it
329    /// (for example as the send intent id) and echo it verbatim in
330    /// [`PaymentQuoteResponse::request_lookup_id`] and
331    /// [`MakePaymentResponse::payment_lookup_id`] as
332    /// `PaymentIdentifier::QuoteId(..)`. The mint layer validates the echo
333    /// and will reject quotes whose backend response disagrees with the
334    /// supplied `quote_id` (see
335    /// [`Error::OnchainQuoteLookupIdMismatch`](crate::Error::OnchainQuoteLookupIdMismatch)).
336    pub quote_id: QuoteId,
337    /// Selected fee option index (mirrors the quote's chosen `fee_options[i].fee_index`)
338    pub fee_index: Option<u32>,
339    /// Opaque metadata as a JSON string for future extensions
340    pub metadata: Option<String>,
341}
342
343/// Options for outgoing payments
344#[derive(Debug, Clone, PartialEq, Eq, Hash)]
345pub enum OutgoingPaymentOptions {
346    /// BOLT11 payment options
347    Bolt11(Box<Bolt11OutgoingPaymentOptions>),
348    /// BOLT12 payment options
349    Bolt12(Box<Bolt12OutgoingPaymentOptions>),
350    /// Custom payment method options
351    Custom(Box<CustomOutgoingPaymentOptions>),
352    /// Onchain payment options
353    Onchain(Box<OnchainOutgoingPaymentOptions>),
354}
355
356impl OutgoingPaymentOptions {
357    /// Creates payment options from a melt quote
358    pub fn from_melt_quote_with_fee(
359        melt_quote: MeltQuote,
360    ) -> Result<OutgoingPaymentOptions, Error> {
361        let fee_reserve = melt_quote.fee_reserve();
362        let quote_id = melt_quote.id.clone();
363        match &melt_quote.request {
364            MeltPaymentRequest::Bolt11 { bolt11 } => Ok(OutgoingPaymentOptions::Bolt11(Box::new(
365                Bolt11OutgoingPaymentOptions {
366                    max_fee_amount: Some(fee_reserve),
367                    timeout_secs: None,
368                    bolt11: bolt11.clone(),
369                    melt_options: melt_quote.options,
370                    quote_id,
371                },
372            ))),
373            MeltPaymentRequest::Bolt12 { offer } => {
374                let melt_options = match melt_quote.options {
375                    Some(MeltOptions::Mpp { mpp: _ }) => return Err(Error::UnsupportedUnit),
376                    Some(options) => Some(options),
377                    _ => None,
378                };
379
380                Ok(OutgoingPaymentOptions::Bolt12(Box::new(
381                    Bolt12OutgoingPaymentOptions {
382                        max_fee_amount: Some(fee_reserve),
383                        timeout_secs: None,
384                        offer: *offer.clone(),
385                        melt_options,
386                        quote_id,
387                    },
388                )))
389            }
390            MeltPaymentRequest::Custom { method, request } => Ok(OutgoingPaymentOptions::Custom(
391                Box::new(CustomOutgoingPaymentOptions {
392                    method: method.to_string(),
393                    request: request.to_string(),
394                    max_fee_amount: Some(fee_reserve),
395                    timeout_secs: None,
396                    melt_options: melt_quote.options,
397                    extra_json: melt_quote
398                        .extra_json
399                        .as_ref()
400                        .map(serde_json::Value::to_string),
401                    quote_id,
402                }),
403            )),
404            MeltPaymentRequest::Onchain { address } => Ok(OutgoingPaymentOptions::Onchain(
405                Box::new(OnchainOutgoingPaymentOptions {
406                    address: address.clone(),
407                    amount: melt_quote.amount(),
408                    max_fee_amount: Some(fee_reserve),
409                    quote_id: melt_quote.id,
410                    fee_index: melt_quote.selected_fee_index,
411                    metadata: None,
412                }),
413            )),
414        }
415    }
416}
417
418/// Mint payment trait
419#[async_trait]
420pub trait MintPayment {
421    /// Mint Lightning Error
422    type Err: Into<Error> + From<Error>;
423
424    /// Start the payment processor
425    /// Called when the mint starts up to initialize the payment processor
426    async fn start(&self) -> Result<(), Self::Err> {
427        // Default implementation - do nothing
428        Ok(())
429    }
430
431    /// Stop the payment processor
432    /// Called when the mint shuts down to gracefully stop the payment processor
433    async fn stop(&self) -> Result<(), Self::Err> {
434        // Default implementation - do nothing
435        Ok(())
436    }
437
438    /// Base Settings
439    async fn get_settings(&self) -> Result<SettingsResponse, Self::Err>;
440
441    /// Create a new invoice
442    async fn create_incoming_payment_request(
443        &self,
444        options: IncomingPaymentOptions,
445    ) -> Result<CreateIncomingPaymentResponse, Self::Err>;
446
447    /// Get payment quote
448    /// Used to get fee and amount required for a payment request
449    async fn get_payment_quote(
450        &self,
451        unit: &CurrencyUnit,
452        options: OutgoingPaymentOptions,
453    ) -> Result<PaymentQuoteResponse, Self::Err>;
454
455    /// Pay request
456    async fn make_payment(
457        &self,
458        unit: &CurrencyUnit,
459        options: OutgoingPaymentOptions,
460    ) -> Result<MakePaymentResponse, Self::Err>;
461
462    /// Listen for invoices to be paid to the mint
463    /// Returns a stream of request_lookup_id once invoices are paid
464    async fn wait_payment_event(
465        &self,
466    ) -> Result<Pin<Box<dyn Stream<Item = Event> + Send>>, Self::Err>;
467
468    /// Is the payment event stream active
469    fn is_payment_event_stream_active(&self) -> bool;
470
471    /// Cancel the payment event stream
472    fn cancel_payment_event_stream(&self);
473
474    /// Check the status of an incoming payment
475    async fn check_incoming_payment_status(
476        &self,
477        payment_identifier: &PaymentIdentifier,
478    ) -> Result<Vec<WaitPaymentResponse>, Self::Err>;
479
480    /// Check the status of an outgoing payment
481    async fn check_outgoing_payment(
482        &self,
483        payment_identifier: &PaymentIdentifier,
484    ) -> Result<MakePaymentResponse, Self::Err>;
485}
486
487/// An event emitted which should be handled by the mint
488#[derive(Debug, Clone, Hash)]
489pub enum Event {
490    /// A payment has been received.
491    PaymentReceived(WaitPaymentResponse),
492    /// An outgoing payment has been confirmed.
493    PaymentSuccessful {
494        /// Quote ID linking to the melt quote
495        quote_id: QuoteId,
496        /// Payment response details
497        details: MakePaymentResponse,
498    },
499    /// An outgoing payment has permanently failed.
500    PaymentFailed {
501        /// Quote ID linking to the melt quote
502        quote_id: QuoteId,
503        /// Human-readable reason for the failure
504        reason: String,
505    },
506}
507
508/// Wait any invoice response
509#[derive(Debug, Clone, Hash)]
510pub struct WaitPaymentResponse {
511    /// Request look up id
512    /// Id that relates the quote and payment request
513    pub payment_identifier: PaymentIdentifier,
514    /// Payment amount (typed with unit for compile-time safety)
515    pub payment_amount: Amount<CurrencyUnit>,
516    /// Unique id of payment
517    // Payment hash
518    pub payment_id: String,
519}
520
521impl WaitPaymentResponse {
522    /// Get the currency unit
523    pub fn unit(&self) -> &CurrencyUnit {
524        self.payment_amount.unit()
525    }
526}
527
528/// Create incoming payment response
529#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize)]
530pub struct CreateIncomingPaymentResponse {
531    /// Id that is used to look up the payment from the ln backend
532    pub request_lookup_id: PaymentIdentifier,
533    /// Payment request
534    pub request: String,
535    /// Unix Expiry of Invoice
536    pub expiry: Option<u64>,
537    /// Extra payment-method-specific fields
538    ///
539    /// These fields are flattened into the JSON representation, allowing
540    /// custom payment methods to include additional data without nesting.
541    #[serde(flatten, default)]
542    pub extra_json: Option<serde_json::Value>,
543}
544
545/// Payment response
546#[derive(Debug, Clone, Hash, PartialEq, Eq)]
547pub struct MakePaymentResponse {
548    /// Payment hash
549    ///
550    /// For onchain payments, this MUST be
551    /// `PaymentIdentifier::QuoteId(quote_id)` where `quote_id` is the value
552    /// supplied by the mint in
553    /// [`OnchainOutgoingPaymentOptions::quote_id`]. See that field for the
554    /// full echo contract.
555    pub payment_lookup_id: PaymentIdentifier,
556    /// Payment proof
557    pub payment_proof: Option<String>,
558    /// Status
559    pub status: MeltQuoteState,
560    /// Total amount spent, including fees. Only authoritative when `status`
561    /// is [`MeltQuoteState::Paid`]; otherwise backends return `0`.
562    pub total_spent: Amount<CurrencyUnit>,
563}
564
565impl MakePaymentResponse {
566    /// Get the currency unit
567    pub fn unit(&self) -> &CurrencyUnit {
568        self.total_spent.unit()
569    }
570}
571
572/// Payment quote response
573#[derive(Debug, Clone, Hash, PartialEq, Eq)]
574pub struct PaymentQuoteResponse {
575    /// Request look up id
576    ///
577    /// For onchain quotes, this MUST be
578    /// `Some(PaymentIdentifier::QuoteId(quote_id))` where `quote_id` is the
579    /// value supplied by the mint in
580    /// [`OnchainOutgoingPaymentOptions::quote_id`]. The mint validates this
581    /// echo and rejects mismatches — see
582    /// [`OnchainOutgoingPaymentOptions::quote_id`] for the full contract.
583    pub request_lookup_id: Option<PaymentIdentifier>,
584    /// Amount (typed with unit for compile-time safety)
585    pub amount: Amount<CurrencyUnit>,
586    /// Fee required for melt (typed with unit for compile-time safety)
587    pub fee: Amount<CurrencyUnit>,
588    /// Status
589    pub state: MeltQuoteState,
590    /// Extra payment-method-specific fields
591    pub extra_json: Option<serde_json::Value>,
592    /// Estimated confirmation target in blocks for onchain quotes.
593    ///
594    /// Onchain backends must return explicit `fee_options`; this field remains
595    /// a convenience mirror of the quoted or selected confirmation target.
596    pub estimated_blocks: Option<u32>,
597    /// Explicit onchain fee options the backend is willing to honor.
598    ///
599    /// For onchain melt quotes the mint enforces that `fee_options` is
600    /// non-empty.
601    ///
602    /// Backends assign stable `fee_index` values and must be able to honor the
603    /// selected value later in [`OnchainOutgoingPaymentOptions::fee_index`].
604    /// The mint validates, persists, and exposes these values unchanged.
605    /// Onchain backends must return `Some(vec)` here. Empty vectors produce
606    /// [`Error::OnchainFeeOptionsEmpty`](crate::Error::OnchainFeeOptionsEmpty),
607    /// and the quote is not persisted.
608    pub fee_options: Option<Vec<MeltQuoteOnchainFeeOption>>,
609}
610
611impl PaymentQuoteResponse {
612    /// Get the currency unit
613    pub fn unit(&self) -> &CurrencyUnit {
614        self.amount.unit()
615    }
616}
617
618/// BOLT11 settings
619#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize, Default)]
620pub struct Bolt11Settings {
621    /// Multi-part payment (MPP) supported
622    pub mpp: bool,
623    /// Amountless invoice support
624    pub amountless: bool,
625    /// Invoice description supported
626    pub invoice_description: bool,
627}
628
629/// BOLT12 settings
630#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize, Default)]
631pub struct Bolt12Settings {
632    /// Amountless offer support
633    pub amountless: bool,
634}
635
636/// Onchain settings
637#[derive(Debug, Clone, Hash, PartialEq, Eq, Serialize, Deserialize, Default)]
638pub struct OnchainSettings {
639    /// Number of confirmations required
640    pub confirmations: u32,
641    /// Minimum incoming onchain payment amount accepted by the backend
642    pub min_receive_amount_sat: u64,
643    /// Minimum outgoing onchain payment amount accepted by the backend
644    pub min_send_amount_sat: u64,
645}
646
647/// Payment processor settings response
648/// Mirrors the proto SettingsResponse structure
649#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
650pub struct SettingsResponse {
651    /// Base unit of backend
652    pub unit: String,
653    /// BOLT11 settings (None if not supported)
654    pub bolt11: Option<Bolt11Settings>,
655    /// BOLT12 settings (None if not supported)
656    pub bolt12: Option<Bolt12Settings>,
657    /// Onchain settings (None if not supported)
658    pub onchain: Option<OnchainSettings>,
659    /// Custom payment methods settings (method name -> settings data)
660    #[serde(default)]
661    pub custom: std::collections::HashMap<String, String>,
662}
663
664impl From<SettingsResponse> for Value {
665    fn from(value: SettingsResponse) -> Self {
666        serde_json::to_value(value).unwrap_or(Value::Null)
667    }
668}
669
670impl TryFrom<Value> for SettingsResponse {
671    type Error = crate::error::Error;
672
673    fn try_from(value: Value) -> Result<Self, Self::Error> {
674        serde_json::from_value(value).map_err(|err| err.into())
675    }
676}
677
678/// Metrics wrapper for MintPayment implementations
679///
680/// This wrapper implements the Decorator pattern to collect metrics on all
681/// MintPayment trait methods. It wraps any existing MintPayment implementation
682/// and automatically records timing and operation metrics.
683#[derive(Debug, Clone)]
684#[cfg(feature = "prometheus")]
685pub struct MetricsMintPayment<T> {
686    inner: T,
687}
688#[cfg(feature = "prometheus")]
689impl<T> MetricsMintPayment<T>
690where
691    T: MintPayment,
692{
693    /// Create a new metrics wrapper around a MintPayment implementation
694    pub fn new(inner: T) -> Self {
695        Self { inner }
696    }
697
698    /// Get reference to the underlying implementation
699    pub fn inner(&self) -> &T {
700        &self.inner
701    }
702
703    /// Consume the wrapper and return the inner implementation
704    pub fn into_inner(self) -> T {
705        self.inner
706    }
707}
708
709#[async_trait]
710#[cfg(feature = "prometheus")]
711impl<T> MintPayment for MetricsMintPayment<T>
712where
713    T: MintPayment + Send + Sync,
714{
715    type Err = T::Err;
716
717    async fn start(&self) -> Result<(), Self::Err> {
718        let metrics = MintMetricGuard::new("start");
719
720        let result = self.inner.start().await;
721
722        metrics.record(result.is_ok());
723
724        result
725    }
726
727    async fn stop(&self) -> Result<(), Self::Err> {
728        let metrics = MintMetricGuard::new("stop");
729
730        let result = self.inner.stop().await;
731
732        metrics.record(result.is_ok());
733
734        result
735    }
736    async fn get_settings(&self) -> Result<SettingsResponse, Self::Err> {
737        let metrics = MintMetricGuard::new("get_settings");
738
739        let result = self.inner.get_settings().await;
740
741        metrics.record(result.is_ok());
742
743        result
744    }
745
746    async fn create_incoming_payment_request(
747        &self,
748        options: IncomingPaymentOptions,
749    ) -> Result<CreateIncomingPaymentResponse, Self::Err> {
750        let metrics = MintMetricGuard::new("create_incoming_payment_request");
751
752        let result = self.inner.create_incoming_payment_request(options).await;
753
754        metrics.record(result.is_ok());
755
756        result
757    }
758
759    async fn get_payment_quote(
760        &self,
761        unit: &CurrencyUnit,
762        options: OutgoingPaymentOptions,
763    ) -> Result<PaymentQuoteResponse, Self::Err> {
764        let metrics = MintMetricGuard::new("get_payment_quote");
765
766        let result = self.inner.get_payment_quote(unit, options).await;
767
768        metrics.record(result.is_ok());
769
770        result
771    }
772    async fn wait_payment_event(
773        &self,
774    ) -> Result<Pin<Box<dyn Stream<Item = Event> + Send>>, Self::Err> {
775        let metrics = MintMetricGuard::new("wait_payment_event");
776
777        let result = self.inner.wait_payment_event().await;
778
779        let success = result.is_ok();
780
781        metrics.record(success);
782
783        result
784    }
785
786    async fn make_payment(
787        &self,
788        unit: &CurrencyUnit,
789        options: OutgoingPaymentOptions,
790    ) -> Result<MakePaymentResponse, Self::Err> {
791        let metrics = MintMetricGuard::new("make_payment");
792
793        let result = self.inner.make_payment(unit, options).await;
794
795        let success = result.is_ok();
796
797        metrics.record(success);
798
799        result
800    }
801
802    fn is_payment_event_stream_active(&self) -> bool {
803        self.inner.is_payment_event_stream_active()
804    }
805
806    fn cancel_payment_event_stream(&self) {
807        self.inner.cancel_payment_event_stream()
808    }
809
810    async fn check_incoming_payment_status(
811        &self,
812        payment_identifier: &PaymentIdentifier,
813    ) -> Result<Vec<WaitPaymentResponse>, Self::Err> {
814        let metrics = MintMetricGuard::new("check_incoming_payment_status");
815
816        let result = self
817            .inner
818            .check_incoming_payment_status(payment_identifier)
819            .await;
820
821        metrics.record(result.is_ok());
822
823        result
824    }
825
826    async fn check_outgoing_payment(
827        &self,
828        payment_identifier: &PaymentIdentifier,
829    ) -> Result<MakePaymentResponse, Self::Err> {
830        let metrics = MintMetricGuard::new("check_outgoing_payment");
831
832        let result = self.inner.check_outgoing_payment(payment_identifier).await;
833
834        let success = result.is_ok();
835
836        metrics.record(success);
837
838        result
839    }
840}
841
842/// Type alias for Mint Payment trait
843pub type DynMintPayment = std::sync::Arc<dyn MintPayment<Err = Error> + Send + Sync>;
844
845#[cfg(test)]
846mod tests {
847    use std::str::FromStr;
848
849    use super::*;
850    use crate::QuoteId;
851
852    #[test]
853    fn test_payment_identifier_quote_id_roundtrip() {
854        let quote_id = QuoteId::new();
855        let identifier = PaymentIdentifier::QuoteId(quote_id.clone());
856
857        let kind = identifier.kind();
858        assert_eq!(kind, "quote_id");
859
860        let display = identifier.to_string();
861        assert_eq!(display, quote_id.to_string());
862
863        let debug = format!("{:?}", identifier);
864        assert_eq!(debug, format!("QuoteId({})", quote_id));
865
866        let parsed = PaymentIdentifier::new(&kind, &display).unwrap();
867        assert_eq!(parsed, identifier);
868    }
869
870    #[test]
871    fn test_payment_identifier_quote_id_base64_roundtrip() {
872        let quote_id_str = "SGVsbG8gV29ybGQh"; // Valid Base64
873        let identifier = PaymentIdentifier::QuoteId(QuoteId::from_str(quote_id_str).unwrap());
874
875        let kind = identifier.kind();
876        assert_eq!(kind, "quote_id");
877
878        let display = identifier.to_string();
879        assert_eq!(display, quote_id_str);
880
881        let parsed = PaymentIdentifier::new(&kind, &display).unwrap();
882        assert_eq!(parsed, identifier);
883    }
884
885    #[test]
886    fn test_payment_identifier_unsupported_kind() {
887        let result = PaymentIdentifier::new("unsupported_kind", "123");
888        assert!(matches!(result, Err(Error::UnsupportedPaymentOption)));
889    }
890
891    #[test]
892    fn test_payment_identifier_invalid_quote_id() {
893        // An invalid base64 and invalid UUID string (e.g. spaces and special characters)
894        let result = PaymentIdentifier::new("quote_id", "invalid!@#quote");
895        assert!(matches!(result, Err(Error::Custom(_))));
896    }
897
898    #[test]
899    fn test_payment_identifier_invalid_hash() {
900        // Invalid hex
901        let result_hex = PaymentIdentifier::new("payment_hash", "not_hex!");
902        assert!(matches!(result_hex, Err(Error::Hex(_))));
903
904        // Valid hex, but wrong length (e.g. 1 byte instead of 32)
905        let result_len = PaymentIdentifier::new("payment_hash", "00");
906        assert!(matches!(result_len, Err(Error::InvalidHash)));
907
908        // Invalid length for bolt12_payment_hash
909        let result_bolt12 = PaymentIdentifier::new("bolt12_payment_hash", "00");
910        assert!(matches!(result_bolt12, Err(Error::InvalidHash)));
911    }
912}
913
914#[test]
915fn test_payment_identifier_hash_variants_roundtrip() {
916    let dummy_hash = [1u8; 32];
917    let hex_encoded = hex::encode(dummy_hash);
918
919    // Test Bolt12PaymentHash
920    let bolt12_identifier = PaymentIdentifier::Bolt12PaymentHash(dummy_hash);
921
922    let kind = bolt12_identifier.kind();
923    assert_eq!(kind, "bolt12_payment_hash");
924
925    let display = bolt12_identifier.to_string();
926    assert_eq!(display, hex_encoded);
927
928    let debug = format!("{:?}", bolt12_identifier);
929    assert_eq!(debug, format!("Bolt12PaymentHash({})", hex_encoded));
930
931    let parsed = PaymentIdentifier::new(&kind, &display).unwrap();
932    assert_eq!(parsed, bolt12_identifier);
933
934    // Test PaymentId
935    let dummy_hash_2 = [2u8; 32];
936    let hex_encoded_2 = hex::encode(dummy_hash_2);
937    let payment_id_identifier = PaymentIdentifier::PaymentId(dummy_hash_2);
938
939    let kind = payment_id_identifier.kind();
940    assert_eq!(kind, "payment_id");
941
942    let display = payment_id_identifier.to_string();
943    assert_eq!(display, hex_encoded_2);
944
945    let debug = format!("{:?}", payment_id_identifier);
946    assert_eq!(debug, format!("PaymentId({})", hex_encoded_2));
947
948    let parsed = PaymentIdentifier::new(&kind, &display).unwrap();
949    assert_eq!(parsed, payment_id_identifier);
950}
cdk_common/payment.rs

cdk_common/
payment.rs
