//! published as a QR code to be scanned by a customer. The customer uses the offer to request an
//! invoice from the merchant to be paid.
//!
-//! ```ignore
+//! ```
//! extern crate bitcoin;
//! extern crate core;
//! extern crate lightning;
use crate::io;
use crate::ln::features::OfferFeatures;
use crate::ln::msgs::MAX_VALUE_MSAT;
+use crate::offers::invoice_request::InvoiceRequestBuilder;
use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError};
use crate::onion_message::BlindedPath;
use crate::util::ser::{HighZeroBytesDroppedBigSize, WithoutLength, Writeable, Writer};
let offer = OfferContents {
chains: None, metadata: None, amount: None, description,
features: OfferFeatures::empty(), absolute_expiry: None, issuer: None, paths: None,
- supported_quantity: Quantity::one(), signing_pubkey: Some(signing_pubkey),
+ supported_quantity: Quantity::One, signing_pubkey,
};
OfferBuilder { offer }
}
/// Sets the [`Offer::amount`].
///
/// Successive calls to this method will override the previous setting.
- fn amount(mut self, amount: Amount) -> Self {
+ pub(super) fn amount(mut self, amount: Amount) -> Self {
self.offer.amount = Some(amount);
self
}
- /// Sets the [`Offer::features`].
- ///
- /// Successive calls to this method will override the previous setting.
- #[cfg(test)]
- pub fn features(mut self, features: OfferFeatures) -> Self {
- self.offer.features = features;
- self
- }
-
/// Sets the [`Offer::absolute_expiry`] as seconds since the Unix epoch. Any expiry that has
/// already passed is valid and can be checked for using [`Offer::is_expired`].
///
}
/// Sets the quantity of items for [`Offer::supported_quantity`]. If not called, defaults to
- /// [`Quantity::one`].
+ /// [`Quantity::One`].
///
/// Successive calls to this method will override the previous setting.
pub fn supported_quantity(mut self, quantity: Quantity) -> Self {
}
}
+#[cfg(test)]
+impl OfferBuilder {
+ fn features_unchecked(mut self, features: OfferFeatures) -> Self {
+ self.offer.features = features;
+ self
+ }
+
+ pub(super) fn build_unchecked(self) -> Offer {
+ let mut bytes = Vec::new();
+ self.offer.write(&mut bytes).unwrap();
+
+ Offer { bytes, contents: self.offer }
+ }
+}
+
/// 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 `Invoice` for a specific quantity and using an amount sufficient to
+/// customer may request an [`Invoice`] 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
/// Through the use of [`BlindedPath`]s, offers provide recipient privacy.
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
-#[derive(Clone, Debug)]
+/// [`Invoice`]: crate::offers::invoice::Invoice
+#[derive(Clone, Debug, PartialEq)]
pub struct Offer {
// The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown
// fields.
- bytes: Vec<u8>,
- contents: OfferContents,
+ pub(super) bytes: Vec<u8>,
+ pub(super) contents: OfferContents,
}
-/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an `Invoice`.
+/// The contents of an [`Offer`], which may be shared with an [`InvoiceRequest`] or an [`Invoice`].
///
/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
-#[derive(Clone, Debug)]
+/// [`Invoice`]: crate::offers::invoice::Invoice
+#[derive(Clone, Debug, PartialEq)]
pub(super) struct OfferContents {
chains: Option<Vec<ChainHash>>,
metadata: Option<Vec<u8>>,
issuer: Option<String>,
paths: Option<Vec<BlindedPath>>,
supported_quantity: Quantity,
- signing_pubkey: Option<PublicKey>,
+ signing_pubkey: PublicKey,
}
impl Offer {
self.contents.chains()
}
+ pub(super) fn implied_chain(&self) -> ChainHash {
+ self.contents.implied_chain()
+ }
+
/// Returns whether the given chain is supported by the offer.
pub fn supports_chain(&self, chain: ChainHash) -> bool {
self.contents.supports_chain(chain)
/// Whether the offer has expired.
#[cfg(feature = "std")]
pub fn is_expired(&self) -> bool {
- match self.absolute_expiry() {
- Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
- Ok(elapsed) => elapsed > seconds_from_epoch,
- Err(_) => false,
- },
- None => false,
- }
+ self.contents.is_expired()
}
/// The issuer of the offer, possibly beginning with `user@domain` or `domain`. Intended to be
/// The public key used by the recipient to sign invoices.
pub fn signing_pubkey(&self) -> PublicKey {
- self.contents.signing_pubkey.unwrap()
+ self.contents.signing_pubkey()
+ }
+
+ /// Creates an [`InvoiceRequest`] for the offer with the given `metadata` and `payer_id`, which
+ /// will be reflected in the `Invoice` 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.
+ ///
+ /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+ pub fn request_invoice(
+ &self, metadata: Vec<u8>, payer_id: PublicKey
+ ) -> Result<InvoiceRequestBuilder, SemanticError> {
+ if self.features().requires_unknown_bits() {
+ return Err(SemanticError::UnknownRequiredFeatures);
+ }
+
+ Ok(InvoiceRequestBuilder::new(self, metadata, payer_id))
}
#[cfg(test)]
- fn as_tlv_stream(&self) -> OfferTlvStreamRef {
+ pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
self.contents.as_tlv_stream()
}
}
self.chains().contains(&chain)
}
+ #[cfg(feature = "std")]
+ pub(super) fn is_expired(&self) -> bool {
+ match self.absolute_expiry {
+ Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
+ Ok(elapsed) => elapsed > seconds_from_epoch,
+ Err(_) => false,
+ },
+ None => false,
+ }
+ }
+
pub fn amount(&self) -> Option<&Amount> {
self.amount.as_ref()
}
- pub fn amount_msats(&self) -> u64 {
- match self.amount() {
+ pub(super) fn check_amount_msats_for_quantity(
+ &self, amount_msats: Option<u64>, quantity: Option<u64>
+ ) -> Result<(), SemanticError> {
+ let offer_amount_msats = match self.amount {
None => 0,
- Some(&Amount::Bitcoin { amount_msats }) => amount_msats,
- Some(&Amount::Currency { .. }) => unreachable!(),
+ Some(Amount::Bitcoin { amount_msats }) => amount_msats,
+ Some(Amount::Currency { .. }) => return Err(SemanticError::UnsupportedCurrency),
+ };
+
+ if !self.expects_quantity() || quantity.is_some() {
+ let expected_amount_msats = offer_amount_msats.checked_mul(quantity.unwrap_or(1))
+ .ok_or(SemanticError::InvalidAmount)?;
+ let amount_msats = amount_msats.unwrap_or(expected_amount_msats);
+
+ if amount_msats < expected_amount_msats {
+ return Err(SemanticError::InsufficientAmount);
+ }
+
+ if amount_msats > MAX_VALUE_MSAT {
+ return Err(SemanticError::InvalidAmount);
+ }
}
- }
- pub fn expected_invoice_amount_msats(&self, quantity: u64) -> u64 {
- self.amount_msats() * quantity
+ Ok(())
}
pub fn supported_quantity(&self) -> Quantity {
self.supported_quantity
}
- pub fn is_valid_quantity(&self, quantity: u64) -> bool {
- match self.supported_quantity {
- Quantity::Bounded(n) => {
- let n = n.get();
- if n == 1 { false }
- else { quantity > 0 && quantity <= n }
+ pub(super) fn check_quantity(&self, quantity: Option<u64>) -> Result<(), SemanticError> {
+ let expects_quantity = self.expects_quantity();
+ match quantity {
+ None if expects_quantity => Err(SemanticError::MissingQuantity),
+ Some(_) if !expects_quantity => Err(SemanticError::UnexpectedQuantity),
+ Some(quantity) if !self.is_valid_quantity(quantity) => {
+ Err(SemanticError::InvalidQuantity)
},
+ _ => Ok(()),
+ }
+ }
+
+ fn is_valid_quantity(&self, quantity: u64) -> bool {
+ match self.supported_quantity {
+ Quantity::Bounded(n) => quantity <= n.get(),
Quantity::Unbounded => quantity > 0,
+ Quantity::One => quantity == 1,
}
}
- pub fn expects_quantity(&self) -> bool {
+ fn expects_quantity(&self) -> bool {
match self.supported_quantity {
- Quantity::Bounded(n) => n.get() != 1,
+ Quantity::Bounded(_) => true,
Quantity::Unbounded => true,
+ Quantity::One => false,
}
}
- fn as_tlv_stream(&self) -> OfferTlvStreamRef {
+ pub(super) fn signing_pubkey(&self) -> PublicKey {
+ self.signing_pubkey
+ }
+
+ pub(super) fn as_tlv_stream(&self) -> OfferTlvStreamRef {
let (currency, amount) = match &self.amount {
None => (None, None),
Some(Amount::Bitcoin { amount_msats }) => (None, Some(*amount_msats)),
paths: self.paths.as_ref(),
issuer: self.issuer.as_ref(),
quantity_max: self.supported_quantity.to_tlv_record(),
- node_id: self.signing_pubkey.as_ref(),
+ node_id: Some(&self.signing_pubkey),
}
}
}
/// Quantity of items supported by an [`Offer`].
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Quantity {
- /// Up to a specific number of items (inclusive).
+ /// Up to a specific number of items (inclusive). Use when more than one item can be requested
+ /// but is limited (e.g., because of per customer or inventory limits).
+ ///
+ /// May be used with `NonZeroU64::new(1)` but prefer to use [`Quantity::One`] if only one item
+ /// is supported.
Bounded(NonZeroU64),
- /// One or more items.
+ /// One or more items. Use when more than one item can be requested without any limit.
Unbounded,
+ /// Only one item. Use when only a single item can be requested.
+ One,
}
impl Quantity {
- /// The default quantity of one.
- pub fn one() -> Self {
- Quantity::Bounded(NonZeroU64::new(1).unwrap())
- }
-
fn to_tlv_record(&self) -> Option<u64> {
match self {
- Quantity::Bounded(n) => {
- let n = n.get();
- if n == 1 { None } else { Some(n) }
- },
+ Quantity::Bounded(n) => Some(n.get()),
Quantity::Unbounded => Some(0),
+ Quantity::One => None,
}
}
}
(6, currency: CurrencyCode),
(8, amount: (u64, HighZeroBytesDroppedBigSize)),
(10, description: (String, WithoutLength)),
- (12, features: OfferFeatures),
+ (12, features: (OfferFeatures, WithoutLength)),
(14, absolute_expiry: (u64, HighZeroBytesDroppedBigSize)),
(16, paths: (Vec<BlindedPath>, WithoutLength)),
(18, issuer: (String, WithoutLength)),
.map(|seconds_from_epoch| Duration::from_secs(seconds_from_epoch));
let supported_quantity = match quantity_max {
- None => Quantity::one(),
+ None => Quantity::One,
Some(0) => Quantity::Unbounded,
- Some(1) => return Err(SemanticError::InvalidQuantity),
Some(n) => Quantity::Bounded(NonZeroU64::new(n).unwrap()),
};
- if node_id.is_none() {
- return Err(SemanticError::MissingSigningPubkey);
- }
+ let signing_pubkey = match node_id {
+ None => return Err(SemanticError::MissingSigningPubkey),
+ Some(node_id) => node_id,
+ };
Ok(OfferContents {
chains, metadata, amount, description, features, absolute_expiry, issuer, paths,
- supported_quantity, signing_pubkey: node_id,
+ supported_quantity, signing_pubkey,
})
}
}
#[cfg(test)]
mod tests {
- use super::{Amount, Offer, OfferBuilder, Quantity};
+ use super::{Amount, Offer, OfferBuilder, OfferTlvStreamRef, Quantity};
use bitcoin::blockdata::constants::ChainHash;
use bitcoin::network::constants::Network;
#[test]
fn builds_offer_with_defaults() {
let offer = OfferBuilder::new("foo".into(), pubkey(42)).build().unwrap();
- let tlv_stream = offer.as_tlv_stream();
+
let mut buffer = Vec::new();
offer.write(&mut buffer).unwrap();
assert!(!offer.is_expired());
assert_eq!(offer.paths(), &[]);
assert_eq!(offer.issuer(), None);
- assert_eq!(offer.supported_quantity(), Quantity::one());
+ assert_eq!(offer.supported_quantity(), Quantity::One);
assert_eq!(offer.signing_pubkey(), pubkey(42));
- assert_eq!(tlv_stream.chains, None);
- assert_eq!(tlv_stream.metadata, None);
- assert_eq!(tlv_stream.currency, None);
- assert_eq!(tlv_stream.amount, None);
- assert_eq!(tlv_stream.description, Some(&String::from("foo")));
- assert_eq!(tlv_stream.features, None);
- assert_eq!(tlv_stream.absolute_expiry, None);
- assert_eq!(tlv_stream.paths, None);
- assert_eq!(tlv_stream.issuer, None);
- assert_eq!(tlv_stream.quantity_max, None);
- assert_eq!(tlv_stream.node_id, Some(&pubkey(42)));
+ assert_eq!(
+ offer.as_tlv_stream(),
+ OfferTlvStreamRef {
+ chains: None,
+ metadata: None,
+ currency: None,
+ amount: None,
+ description: Some(&String::from("foo")),
+ features: None,
+ absolute_expiry: None,
+ paths: None,
+ issuer: None,
+ quantity_max: None,
+ node_id: Some(&pubkey(42)),
+ },
+ );
if let Err(e) = Offer::try_from(buffer) {
panic!("error parsing offer: {:?}", e);
#[test]
fn builds_offer_with_features() {
let offer = OfferBuilder::new("foo".into(), pubkey(42))
- .features(OfferFeatures::unknown())
+ .features_unchecked(OfferFeatures::unknown())
.build()
.unwrap();
assert_eq!(offer.features(), &OfferFeatures::unknown());
assert_eq!(offer.as_tlv_stream().features, Some(&OfferFeatures::unknown()));
let offer = OfferBuilder::new("foo".into(), pubkey(42))
- .features(OfferFeatures::unknown())
- .features(OfferFeatures::empty())
+ .features_unchecked(OfferFeatures::unknown())
+ .features_unchecked(OfferFeatures::empty())
.build()
.unwrap();
assert_eq!(offer.features(), &OfferFeatures::empty());
#[test]
fn builds_offer_with_supported_quantity() {
+ let one = NonZeroU64::new(1).unwrap();
let ten = NonZeroU64::new(10).unwrap();
let offer = OfferBuilder::new("foo".into(), pubkey(42))
- .supported_quantity(Quantity::one())
+ .supported_quantity(Quantity::One)
.build()
.unwrap();
let tlv_stream = offer.as_tlv_stream();
- assert_eq!(offer.supported_quantity(), Quantity::one());
+ assert_eq!(offer.supported_quantity(), Quantity::One);
assert_eq!(tlv_stream.quantity_max, None);
let offer = OfferBuilder::new("foo".into(), pubkey(42))
assert_eq!(offer.supported_quantity(), Quantity::Bounded(ten));
assert_eq!(tlv_stream.quantity_max, Some(10));
+ let offer = OfferBuilder::new("foo".into(), pubkey(42))
+ .supported_quantity(Quantity::Bounded(one))
+ .build()
+ .unwrap();
+ let tlv_stream = offer.as_tlv_stream();
+ assert_eq!(offer.supported_quantity(), Quantity::Bounded(one));
+ assert_eq!(tlv_stream.quantity_max, Some(1));
+
let offer = OfferBuilder::new("foo".into(), pubkey(42))
.supported_quantity(Quantity::Bounded(ten))
- .supported_quantity(Quantity::one())
+ .supported_quantity(Quantity::One)
.build()
.unwrap();
let tlv_stream = offer.as_tlv_stream();
- assert_eq!(offer.supported_quantity(), Quantity::one());
+ assert_eq!(offer.supported_quantity(), Quantity::One);
assert_eq!(tlv_stream.quantity_max, None);
}
+ #[test]
+ fn fails_requesting_invoice_with_unknown_required_features() {
+ match OfferBuilder::new("foo".into(), pubkey(42))
+ .features_unchecked(OfferFeatures::unknown())
+ .build().unwrap()
+ .request_invoice(vec![1; 32], pubkey(43))
+ {
+ Ok(_) => panic!("expected error"),
+ Err(e) => assert_eq!(e, SemanticError::UnknownRequiredFeatures),
+ }
+ }
+
#[test]
fn parses_offer_with_chains() {
let offer = OfferBuilder::new("foo".into(), pubkey(42))
#[test]
fn parses_offer_with_quantity() {
let offer = OfferBuilder::new("foo".into(), pubkey(42))
- .supported_quantity(Quantity::one())
+ .supported_quantity(Quantity::One)
.build()
.unwrap();
if let Err(e) = offer.to_string().parse::<Offer>() {
panic!("error parsing offer: {:?}", e);
}
- let mut tlv_stream = offer.as_tlv_stream();
- tlv_stream.quantity_max = Some(1);
-
- let mut encoded_offer = Vec::new();
- tlv_stream.write(&mut encoded_offer).unwrap();
-
- match Offer::try_from(encoded_offer) {
- Ok(_) => panic!("expected error"),
- Err(e) => {
- assert_eq!(e, ParseError::InvalidSemantics(SemanticError::InvalidQuantity));
- },
+ let offer = OfferBuilder::new("foo".into(), pubkey(42))
+ .supported_quantity(Quantity::Bounded(NonZeroU64::new(1).unwrap()))
+ .build()
+ .unwrap();
+ if let Err(e) = offer.to_string().parse::<Offer>() {
+ panic!("error parsing offer: {:?}", e);
}
}
panic!("error parsing offer: {:?}", e);
}
- let mut builder = OfferBuilder::new("foo".into(), pubkey(42));
- builder.offer.signing_pubkey = None;
+ let mut tlv_stream = offer.as_tlv_stream();
+ tlv_stream.node_id = None;
- let offer = builder.build().unwrap();
- match offer.to_string().parse::<Offer>() {
+ let mut encoded_offer = Vec::new();
+ tlv_stream.write(&mut encoded_offer).unwrap();
+
+ match Offer::try_from(encoded_offer) {
Ok(_) => panic!("expected error"),
Err(e) => {
assert_eq!(e, ParseError::InvalidSemantics(SemanticError::MissingSigningPubkey));