Struct lightning_invoice::InvoiceBuilder

pub struct InvoiceBuilder<D: Bool, H: Bool, T: Bool, C: Bool, S: Bool, M: Bool> { /* private fields */ }

Builder for Bolt11Invoices. It’s the most convenient and advised way to use this library. It ensures that only a semantically and syntactically correct invoice can be built using it.

extern crate lightning_invoice;
extern crate bitcoin;

use bitcoin::hashes::Hash;
use bitcoin::hashes::sha256;

use bitcoin::secp256k1::Secp256k1;
use bitcoin::secp256k1::SecretKey;

use lightning_types::payment::PaymentSecret;

use lightning_invoice::{Currency, InvoiceBuilder};

let private_key = SecretKey::from_slice(
	&[
		0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
		0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
		0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
	][..]
).unwrap();

let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
let payment_secret = PaymentSecret([42u8; 32]);

let invoice = InvoiceBuilder::new(Currency::Bitcoin)
	.description("Coins pls!".into())
	.payment_hash(payment_hash)
	.payment_secret(payment_secret)
	.current_timestamp()
	.min_final_cltv_expiry_delta(144)
	.build_signed(|hash| {
		Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
	})
	.unwrap();

assert!(invoice.to_string().starts_with("lnbc1"));

Type parameters

The two parameters D and H signal if the builder already contains the correct amount of the given field:

• D: exactly one TaggedField::Description or TaggedField::DescriptionHash
• H: exactly one TaggedField::PaymentHash
• T: the timestamp is set
• C: the CLTV expiry is set
• S: the payment secret is set
• M: payment metadata is set

This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.

Implementations

impl InvoiceBuilder<False, False, False, False, False, False>

pub fn new(currency: Currency) -> Self

Construct new, empty InvoiceBuilder. All necessary fields have to be filled first before InvoiceBuilder::build(self) becomes available.

impl<D: Bool, H: Bool, T: Bool, C: Bool, S: Bool, M: Bool> InvoiceBuilder<D, H, T, C, S, M>

pub fn amount_milli_satoshis(self, amount_msat: u64) -> Self

Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.

pub fn payee_pub_key(self, pub_key: PublicKey) -> Self

Sets the payee’s public key.

pub fn expiry_time(self, expiry_time: Duration) -> Self

Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11 invoices).

pub fn fallback(self, fallback: Fallback) -> Self

Adds a fallback address.

pub fn private_route(self, hint: RouteHint) -> Self

Adds a private route.

impl<D: Bool, H: Bool, C: Bool, S: Bool, M: Bool> InvoiceBuilder<D, H, True, C, S, M>

pub fn build_raw(self) -> Result<RawBolt11Invoice, CreationError>

Builds a RawBolt11Invoice if no CreationError occurred while construction any of the fields.

impl<H: Bool, T: Bool, C: Bool, S: Bool, M: Bool> InvoiceBuilder<False, H, T, C, S, M>

pub fn description( self, description: String, ) -> InvoiceBuilder<True, H, T, C, S, M>

Set the description. This function is only available if no description (hash) was set.

pub fn description_hash( self, description_hash: Hash, ) -> InvoiceBuilder<True, H, T, C, S, M>

Set the description hash. This function is only available if no description (hash) was set.

pub fn invoice_description( self, description: Bolt11InvoiceDescription<'_>, ) -> InvoiceBuilder<True, H, T, C, S, M>

Set the description or description hash. This function is only available if no description (hash) was set.

impl<D: Bool, T: Bool, C: Bool, S: Bool, M: Bool> InvoiceBuilder<D, False, T, C, S, M>

pub fn payment_hash(self, hash: Hash) -> InvoiceBuilder<D, True, T, C, S, M>

Set the payment hash. This function is only available if no payment hash was set.

impl<D: Bool, H: Bool, C: Bool, S: Bool, M: Bool> InvoiceBuilder<D, H, False, C, S, M>

pub fn timestamp(self, time: SystemTime) -> InvoiceBuilder<D, H, True, C, S, M>

Available on crate feature std only.

Sets the timestamp to a specific SystemTime.

pub fn duration_since_epoch( self, time: Duration, ) -> InvoiceBuilder<D, H, True, C, S, M>

Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which is not representable in BOLT 11 invoices).

pub fn current_timestamp(self) -> InvoiceBuilder<D, H, True, C, S, M>

Available on crate feature std only.

Sets the timestamp to the current system time.

impl<D: Bool, H: Bool, T: Bool, S: Bool, M: Bool> InvoiceBuilder<D, H, T, False, S, M>

pub fn min_final_cltv_expiry_delta( self, min_final_cltv_expiry_delta: u64, ) -> InvoiceBuilder<D, H, T, True, S, M>

Sets min_final_cltv_expiry_delta.

impl<D: Bool, H: Bool, T: Bool, C: Bool, M: Bool> InvoiceBuilder<D, H, T, C, False, M>

pub fn payment_secret( self, payment_secret: PaymentSecret, ) -> InvoiceBuilder<D, H, T, C, True, M>

Sets the payment secret and relevant features.

impl<D: Bool, H: Bool, T: Bool, C: Bool, S: Bool> InvoiceBuilder<D, H, T, C, S, False>

pub fn payment_metadata( self, payment_metadata: Vec<u8>, ) -> InvoiceBuilder<D, H, T, C, S, True>

Sets the payment metadata.

By default features are set to optionally allow the sender to include the payment metadata. If you wish to require that the sender include the metadata (and fail to parse the invoice if they don’t support payment metadata fields), you need to call InvoiceBuilder::require_payment_metadata after this.

impl<D: Bool, H: Bool, T: Bool, C: Bool, S: Bool> InvoiceBuilder<D, H, T, C, S, True>

pub fn require_payment_metadata(self) -> InvoiceBuilder<D, H, T, C, S, True>

Sets forwarding of payment metadata as required. A reader of the invoice which does not support sending payment metadata will fail to read the invoice.

impl<D: Bool, H: Bool, T: Bool, C: Bool, M: Bool> InvoiceBuilder<D, H, T, C, True, M>

pub fn basic_mpp(self) -> Self

Sets the basic_mpp feature as optional.

impl<M: Bool> InvoiceBuilder<True, True, True, True, True, M>

pub fn build_signed<F>( self, sign_function: F, ) -> Result<Bolt11Invoice, CreationError>

where F: FnOnce(&Message) -> RecoverableSignature,

Builds and signs an invoice using the supplied sign_function. This function MAY NOT fail and MUST produce a recoverable signature valid for the given hash and if applicable also for the included payee public key.

pub fn try_build_signed<F, E>( self, sign_function: F, ) -> Result<Bolt11Invoice, SignOrCreationError<E>>

where F: FnOnce(&Message) -> Result<RecoverableSignature, E>,

Builds and signs an invoice using the supplied sign_function. This function MAY fail with an error of type E and MUST produce a recoverable signature valid for the given hash and if applicable also for the included payee public key.

Trait Implementations

impl<D: Clone + Bool, H: Clone + Bool, T: Clone + Bool, C: Clone + Bool, S: Clone + Bool, M: Clone + Bool> Clone for InvoiceBuilder<D, H, T, C, S, M>

fn clone(&self) -> InvoiceBuilder<D, H, T, C, S, M>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<D: Debug + Bool, H: Debug + Bool, T: Debug + Bool, C: Debug + Bool, S: Debug + Bool, M: Debug + Bool> Debug for InvoiceBuilder<D, H, T, C, S, M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<D: PartialEq + Bool, H: PartialEq + Bool, T: PartialEq + Bool, C: PartialEq + Bool, S: PartialEq + Bool, M: PartialEq + Bool> PartialEq for InvoiceBuilder<D, H, T, C, S, M>

fn eq(&self, other: &InvoiceBuilder<D, H, T, C, S, M>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<D: Eq + Bool, H: Eq + Bool, T: Eq + Bool, C: Eq + Bool, S: Eq + Bool, M: Eq + Bool> Eq for InvoiceBuilder<D, H, T, C, S, M>

impl<D: Bool, H: Bool, T: Bool, C: Bool, S: Bool, M: Bool> StructuralPartialEq for InvoiceBuilder<D, H, T, C, S, M>