Struct Bolt11Payment

pub struct Bolt11Payment { /* private fields */ }

A payment handler allowing to create and pay BOLT 11 invoices.

Should be retrieved by calling Node::bolt11_payment.

Implementations

impl Bolt11Payment

pub fn send( &self, invoice: &Bolt11Invoice, sending_parameters: Option<SendingParameters>, ) -> Result<PaymentId, Error>

Send a payment given an invoice.

If sending_parameters are provided they will override the default as well as the node-wide parameters configured via Config::sending_parameters on a per-field basis.

pub fn send_using_amount( &self, invoice: &Bolt11Invoice, amount_msat: u64, sending_parameters: Option<SendingParameters>, ) -> Result<PaymentId, Error>

Send a payment given an invoice and an amount in millisatoshis.

This will fail if the amount given is less than the value required by the given invoice.

This can be used to pay a so-called “zero-amount” invoice, i.e., an invoice that leaves the amount paid to be determined by the user.

If sending_parameters are provided they will override the default as well as the node-wide parameters configured via Config::sending_parameters on a per-field basis.

pub fn claim_for_hash( &self, payment_hash: PaymentHash, claimable_amount_msat: u64, preimage: PaymentPreimage, ) -> Result<(), Error>

Allows to attempt manually claiming payments with the given preimage that have previously been registered via receive_for_hash or receive_variable_amount_for_hash.

This should be called in reponse to a PaymentClaimable event as soon as the preimage is available.

Will check that the payment is known, and that the given preimage and claimable amount match our expectations before attempting to claim the payment, and will return an error otherwise.

When claiming the payment has succeeded, a PaymentReceived event will be emitted.

pub fn fail_for_hash(&self, payment_hash: PaymentHash) -> Result<(), Error>

Allows to manually fail payments with the given hash that have previously been registered via receive_for_hash or receive_variable_amount_for_hash.

This should be called in reponse to a PaymentClaimable event if the payment needs to be failed back, e.g., if the correct preimage can’t be retrieved in time before the claim deadline has been reached.

Will check that the payment is known before failing the payment, and will return an error otherwise.

pub fn receive( &self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request and receive a payment of the amount given.

The inbound payment will be automatically claimed upon arrival.

pub fn receive_for_hash( &self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32, payment_hash: PaymentHash, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request a payment of the amount given for the given payment hash.

We will register the given payment hash and emit a PaymentClaimable event once the inbound payment arrives.

Note: users MUST handle this event and claim the payment manually via claim_for_hash as soon as they have obtained access to the preimage of the given payment hash. If they’re unable to obtain the preimage, they MUST immediately fail the payment via fail_for_hash.

pub fn receive_variable_amount( &self, description: &Bolt11InvoiceDescription, expiry_secs: u32, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request and receive a payment for which the amount is to be determined by the user, also known as a “zero-amount” invoice.

The inbound payment will be automatically claimed upon arrival.

pub fn receive_variable_amount_for_hash( &self, description: &Bolt11InvoiceDescription, expiry_secs: u32, payment_hash: PaymentHash, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request a payment for the given payment hash and the amount to be determined by the user, also known as a “zero-amount” invoice.

We will register the given payment hash and emit a PaymentClaimable event once the inbound payment arrives.

Note: users MUST handle this event and claim the payment manually via claim_for_hash as soon as they have obtained access to the preimage of the given payment hash. If they’re unable to obtain the preimage, they MUST immediately fail the payment via fail_for_hash.

pub fn receive_via_jit_channel( &self, amount_msat: u64, description: &Bolt11InvoiceDescription, expiry_secs: u32, max_total_lsp_fee_limit_msat: Option<u64>, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request a payment of the amount given and receive it via a newly created just-in-time (JIT) channel.

When the returned invoice is paid, the configured LSPS2-compliant LSP will open a channel to us, supplying just-in-time inbound liquidity.

If set, max_total_lsp_fee_limit_msat will limit how much fee we allow the LSP to take for opening the channel to us. We’ll use its cheapest offer otherwise.

pub fn receive_variable_amount_via_jit_channel( &self, description: &Bolt11InvoiceDescription, expiry_secs: u32, max_proportional_lsp_fee_limit_ppm_msat: Option<u64>, ) -> Result<Bolt11Invoice, Error>

Returns a payable invoice that can be used to request a variable amount payment (also known as “zero-amount” invoice) and receive it via a newly created just-in-time (JIT) channel.

When the returned invoice is paid, the configured LSPS2-compliant LSP will open a channel to us, supplying just-in-time inbound liquidity.

If set, max_proportional_lsp_fee_limit_ppm_msat will limit how much proportional fee, in parts-per-million millisatoshis, we allow the LSP to take for opening the channel to us. We’ll use its cheapest offer otherwise.

pub fn send_probes(&self, invoice: &Bolt11Invoice) -> Result<(), Error>

Sends payment probes over all paths of a route that would be used to pay the given invoice.

This may be used to send “pre-flight” probes, i.e., to train our scorer before conducting the actual payment. Note this is only useful if there likely is sufficient time for the probe to settle before sending out the actual payment, e.g., when waiting for user confirmation in a wallet UI.

Otherwise, there is a chance the probe could take up some liquidity needed to complete the actual payment. Users should therefore be cautious and might avoid sending probes if liquidity is scarce and/or they don’t expect the probe to return before they send the payment. To mitigate this issue, channels with available liquidity less than the required amount times Config::probing_liquidity_limit_multiplier won’t be used to send pre-flight probes.

pub fn send_probes_using_amount( &self, invoice: &Bolt11Invoice, amount_msat: u64, ) -> Result<(), Error>

Sends payment probes over all paths of a route that would be used to pay the given zero-value invoice using the given amount.

This can be used to send pre-flight probes for a so-called “zero-amount” invoice, i.e., an invoice that leaves the amount paid to be determined by the user.

See Self::send_probes for more information.