Struct lightning::offers::offer::Offer

pub struct Offer { /* private fields */ }

An Offer is a potentially long-lived proposal for payment of a good or service.

An offer is a precursor to an InvoiceRequest. A merchant publishes an offer from which a customer may request an Bolt12Invoice for a specific quantity and using an amount sufficient to cover that quantity (i.e., at least quantity * amount). See Offer::amount.

Offers may be denominated in currency other than bitcoin but are ultimately paid using the latter.

Through the use of BlindedPaths, offers provide recipient privacy.

Implementations

impl Offer

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) -> &OfferFeatures

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) -> &[BlindedPath]

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 signing_pubkey(&self) -> Option<PublicKey>

The public key used by the recipient to sign invoices.

pub fn id(&self) -> OfferId

Returns the id of the offer.

pub fn supports_chain(&self, chain: ChainHash) -> bool

Returns whether the given chain is supported by the offer.

pub fn is_expired(&self) -> bool

Available on crate feature std only.

Whether the offer has expired.

pub fn is_expired_no_std(&self, duration_since_epoch: Duration) -> bool

Whether the offer has expired given the duration since the Unix epoch.

pub fn is_valid_quantity(&self, quantity: u64) -> bool

Returns whether the given quantity is valid for the offer.

pub fn expects_quantity(&self) -> bool

Returns whether a quantity is expected in an InvoiceRequest for the offer.

impl Offer

pub fn request_invoice_deriving_payer_id<'a, 'b, ES: Deref, T: Signing>( &'a self, expanded_key: &ExpandedKey, entropy_source: ES, secp_ctx: &'b Secp256k1<T>, payment_id: PaymentId ) -> Result<InvoiceRequestBuilder<'a, 'b, DerivedPayerId, T>, Bolt12SemanticError>

where ES::Target: EntropySource,

Available on non-c_bindings only.

Similar to Offer::request_invoice except it:

• derives the InvoiceRequest::payer_id such that a different key can be used for each request,
• sets InvoiceRequest::payer_metadata when InvoiceRequestBuilder::build is called such that it can be used by Bolt12Invoice::verify to determine if the invoice was requested using a base ExpandedKey from which the payer id was derived, and
• includes the PaymentId encrypted in InvoiceRequest::payer_metadata so that it can be used when sending the payment for the requested invoice.

Useful to protect the sender’s privacy.

pub fn request_invoice_deriving_metadata<ES: Deref>( &self, payer_id: PublicKey, expanded_key: &ExpandedKey, entropy_source: ES, payment_id: PaymentId ) -> Result<InvoiceRequestBuilder<'_, '_, ExplicitPayerId, SignOnly>, Bolt12SemanticError>

where ES::Target: EntropySource,

Available on non-c_bindings only.

Similar to Offer::request_invoice_deriving_payer_id except uses payer_id for the InvoiceRequest::payer_id instead of deriving a different key for each request.

Useful for recurring payments using the same payer_id with different invoices.

pub fn request_invoice( &self, metadata: Vec<u8>, payer_id: PublicKey ) -> Result<InvoiceRequestBuilder<'_, '_, ExplicitPayerId, SignOnly>, Bolt12SemanticError>

Available on non-c_bindings only.

Creates an InvoiceRequestBuilder for the offer with the given metadata and payer_id, which will be reflected in the Bolt12Invoice response.

The metadata is useful for including information about the derivation of payer_id such that invoice response handling can be stateless. Also serves as payer-provided entropy while hashing in the signature calculation.

This should not leak any information such as by using a simple BIP-32 derivation path. Otherwise, payments may be correlated.

Errors if the offer contains unknown required features.

Trait Implementations

impl AsRef<[u8]> for Offer

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for Offer

fn clone(&self) -> Offer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Offer

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

Formats the value using the given formatter.

impl Display for Offer

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

Formats the value using the given formatter.

impl FromStr for Offer

type Err = Bolt12ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err>

Parses a string s to return a value of this type.

impl Hash for Offer

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Offer

fn eq(&self, other: &Self) -> 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 TryFrom<Vec<u8>> for Offer

type Error = Bolt12ParseError

The type returned in the event of a conversion error.

fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error>

Performs the conversion.

impl Writeable for Offer

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

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.

impl Eq for Offer