Module lightning_invoice::payment

A module for paying Lightning invoices and sending spontaneous payments.

Defines an InvoicePayer utility for sending payments, parameterized by Payer and Router traits. Implementations of Payer provide the payer’s node id, channels, and means to send a payment over a Route. Implementations of Router find a Route between payer and payee using information provided by the payer and from the payee’s Invoice, when applicable.

InvoicePayer uses its Router parameterization for optionally notifying scorers upon receiving the Event::PaymentPathFailed and Event::PaymentPathSuccessful events. It also does the same for payment probe failure and success events using Event::ProbeFailed and Event::ProbeSuccessful.

InvoicePayer is capable of retrying failed payments. It accomplishes this by implementing EventHandler which decorates a user-provided handler. It will intercept any Event::PaymentPathFailed events and retry the failed paths for a fixed number of total attempts or until retry is no longer possible. In such a situation, InvoicePayer will pass along the events to the user-provided handler.

Example

let event_handler = |event: &Event| {
    match event {
        Event::PaymentPathFailed { .. } => println!("payment failed after retries"),
        Event::PaymentSent { .. } => println!("payment successful"),
        _ => {},
    }
};
let invoice_payer = InvoicePayer::new(&payer, router, &logger, event_handler, Retry::Attempts(2));

let invoice = "...";
if let Ok(invoice) = invoice.parse::<Invoice>() {
    invoice_payer.pay_invoice(&invoice).unwrap();

    loop {
        event_provider.process_pending_events(&invoice_payer);
    }
}

Note

The Route is computed before each payment attempt. Any updates affecting path finding such as updates to the network graph or changes to channel scores should be applied prior to retries, typically by way of composing EventHandlers accordingly.

Structs

InFlightHtlcs

A map with liquidity value (in msat) keyed by a short channel id and the direction the HTLC is traveling in. The direction boolean is determined by checking if the HTLC source’s public key is less than its destination. See InFlightHtlcs::used_liquidity_msat for more details.

InvoicePayerUsingTime

(C-not exported) generally all users should use the InvoicePayer type alias.

Enums

PaymentError

An error that may occur when making a payment.

Retry

Strategies available to retry payment path failures for an Invoice.

Traits

Payer

A trait defining behavior of an Invoice payer.

Router

A trait defining behavior for routing an Invoice payment.

Type Definitions

InvoicePayer

A utility for paying Invoices and sending spontaneous payments.