Struct lightning_invoice::InvoiceBuilder

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

Builder for Invoices. 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 secp256k1;
extern crate lightning;
extern crate lightning_invoice;
extern crate bitcoin_hashes;

use bitcoin_hashes::Hash;
use bitcoin_hashes::sha256;

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

use lightning::ln::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(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 Description or DescriptionHash
• H: exactly one PaymentHash
• T: the timestamp is set

(C-not exported) as we likely need to manually select one set of boolean type parameters.

Implementations

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

pub fn new(currrency: 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> InvoiceBuilder<D, H, T, C, S>

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> InvoiceBuilder<D, H, True, C, S>

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

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

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

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

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>

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

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

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

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

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

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

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>

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>

Available on crate feature std only.

Sets the timestamp to the current system time.

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

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

Sets min_final_cltv_expiry.

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

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

Sets the payment secret and relevant features.

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

pub fn basic_mpp(self) -> Self

Sets the basic_mpp feature as optional.

impl InvoiceBuilder<True, True, True, True, True>

pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, 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<Invoice, 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> Clone for InvoiceBuilder<D, H, T, C, S>

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

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> Debug for InvoiceBuilder<D, H, T, C, S>

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> PartialEq<InvoiceBuilder<D, H, T, C, S>> for InvoiceBuilder<D, H, T, C, S>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method 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> Eq for InvoiceBuilder<D, H, T, C, S>

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

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