Struct InvoiceRequest

pub struct InvoiceRequest { /* private fields */ }

An InvoiceRequest is a request for a Bolt12Invoice formulated from an Offer.

An offer may provide choices such as quantity, amount, chain, features, etc. An invoice request specifies these such that its recipient can send an invoice for payment.

Implementations

impl InvoiceRequest

pub fn chains(&self) -> Vec<ChainHash>

The chains that may be used when paying a requested invoice (e.g., bitcoin mainnet). Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats) for the selected chain.

pub fn metadata(&self) -> Option<&Vec<u8>>

Opaque bytes set by the originator. Useful for authentication and validating fields since it is reflected in invoice_request messages along with all the other fields from the offer.

pub fn amount(&self) -> Option<Amount>

The minimum amount required for a successful payment of a single item.

pub fn description(&self) -> Option<PrintableString<'_>>

A complete description of the purpose of the payment. Intended to be displayed to the user but with the caveat that it has not been verified in any way.

pub fn offer_features(&self) -> &Features<OfferContext>

Features pertaining to the offer.

pub fn absolute_expiry(&self) -> Option<Duration>

Duration since the Unix epoch when an invoice should no longer be requested.

If None, the offer does not expire.

pub fn issuer(&self) -> Option<PrintableString<'_>>

The issuer of the offer, possibly beginning with user@domain or domain. Intended to be displayed to the user but with the caveat that it has not been verified in any way.

pub fn paths(&self) -> &[BlindedMessagePath]

Paths to the recipient originating from publicly reachable nodes. Blinded paths provide recipient privacy by obfuscating its node id.

pub fn supported_quantity(&self) -> Quantity

The quantity of items supported.

pub fn issuer_signing_pubkey(&self) -> Option<PublicKey>

The public key corresponding to the key used by the recipient to sign invoices.

• If Offer::paths is empty, MUST be Some and contain the recipient’s node id for sending an InvoiceRequest.
• If Offer::paths is not empty, MAY be Some and contain a transient id.
• If None, the signing pubkey will be the final blinded node id from the BlindedMessagePath in Offer::paths used to send the InvoiceRequest.

See also Bolt12Invoice::signing_pubkey.

pub fn payer_metadata(&self) -> &[u8]

An unpredictable series of bytes, typically containing information about the derivation of payer_signing_pubkey.

pub fn chain(&self) -> ChainHash

A chain from Offer::chains that the offer is valid for.

pub fn amount_msats(&self) -> Option<u64>

The amount to pay in msats (i.e., the minimum lightning-payable unit for chain), which must be greater than or equal to Offer::amount, converted if necessary.

pub fn has_amount_msats(&self) -> bool

Returns whether an amount was set in the request; otherwise, if amount_msats is Some then it was inferred from the Offer::amount and quantity.

pub fn invoice_request_features(&self) -> &Features<InvoiceRequestContext>

Features pertaining to requesting an invoice.

pub fn quantity(&self) -> Option<u64>

The quantity of the offer’s item conforming to Offer::is_valid_quantity.

pub fn payer_signing_pubkey(&self) -> PublicKey

A possibly transient pubkey used to sign the invoice request.

pub fn payer_note(&self) -> Option<PrintableString<'_>>

A payer-provided note which will be seen by the recipient and reflected back in the invoice response.

pub fn offer_from_hrn(&self) -> &Option<HumanReadableName>

If the Offer was sourced from a BIP 353 Human Readable Name, this should be set by the builder to indicate the original HumanReadableName which was resolved.

pub fn respond_with( &self, payment_paths: Vec<BlindedPaymentPath>, payment_hash: PaymentHash, ) -> Result<InvoiceBuilder<'_, ExplicitSigningPubkey>, Bolt12SemanticError>

Creates an InvoiceBuilder for the request with the given required fields and using the Duration since std::time::SystemTime::UNIX_EPOCH as the creation time.

See InvoiceRequest::respond_with_no_std for further details where the aforementioned creation time is used for the created_at parameter.

pub fn respond_with_no_std( &self, payment_paths: Vec<BlindedPaymentPath>, payment_hash: PaymentHash, created_at: Duration, ) -> Result<InvoiceBuilder<'_, ExplicitSigningPubkey>, Bolt12SemanticError>

Creates an InvoiceBuilder for the request with the given required fields.

Unless InvoiceBuilder::relative_expiry is set, the invoice will expire two hours after created_at, which is used to set Bolt12Invoice::created_at. Useful for non-std builds where std::time::SystemTime is not available.

The caller is expected to remember the preimage of payment_hash in order to claim a payment for the invoice.

The payment_paths parameter is useful for maintaining the payment recipient’s privacy. It must contain one or more elements ordered from most-preferred to least-preferred, if there’s a preference. Note, however, that any privacy is lost if a public node id was used for Offer::issuer_signing_pubkey.

Errors if the request contains unknown required features.

Note

If the originating Offer was created using OfferBuilder::deriving_signing_pubkey, then first use InvoiceRequest::verify_using_metadata or InvoiceRequest::verify_using_recipient_data and then VerifiedInvoiceRequest methods instead.

pub fn verify_using_metadata<T>( self, key: &ExpandedKey, secp_ctx: &Secp256k1<T>, ) -> Result<VerifiedInvoiceRequest, ()>

where T: Signing,

Verifies that the request was for an offer created using the given key by checking the metadata from the offer.

Returns the verified request which contains the derived keys needed to sign a Bolt12Invoice for the request if they could be extracted from the metadata.

pub fn verify_using_recipient_data<T>( self, nonce: Nonce, key: &ExpandedKey, secp_ctx: &Secp256k1<T>, ) -> Result<VerifiedInvoiceRequest, ()>

where T: Signing,

Verifies that the request was for an offer created using the given key by checking a nonce included with the BlindedMessagePath for which the request was sent through.

Returns the verified request which contains the derived keys needed to sign a Bolt12Invoice for the request if they could be extracted from the metadata.

impl InvoiceRequest

pub fn signature(&self) -> Signature

Signature of the invoice request using payer_signing_pubkey.

Trait Implementations

impl Clone for InvoiceRequest

fn clone(&self) -> InvoiceRequest

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for InvoiceRequest

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

Formats the value using the given formatter.

impl Readable for InvoiceRequest

fn read<R>(reader: &mut R) -> Result<InvoiceRequest, DecodeError>

where R: Read,

Reads a Self in from the given Read.

impl TryFrom<Vec<u8>> for InvoiceRequest

type Error = Bolt12ParseError

The type returned in the event of a conversion error.

fn try_from( bytes: Vec<u8>, ) -> Result<InvoiceRequest, <InvoiceRequest as TryFrom<Vec<u8>>>::Error>

Performs the conversion.

impl Writeable for InvoiceRequest

fn write<W>(&self, writer: &mut W) -> Result<(), Error>

where W: Writer,

Writes self out to the given Writer.

fn encode(&self) -> Vec<u8>

Writes self out to a Vec<u8>.

fn serialized_length(&self) -> usize

Gets the length of this object after it has been serialized. This can be overridden to optimize cases where we prepend an object with its length.