X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Foffers%2Foffer.rs;h=d890ab3f642cfb14fffe70f843b3086f8688fdcb;hb=d666eb670009c370289c60ea741997d605e96f63;hp=e57334f316c02745f2d53127ef3c548b3383af47;hpb=03d0a4b497338b29fe9aa8c065edcfe26442e6e0;p=rust-lightning diff --git a/lightning/src/offers/offer.rs b/lightning/src/offers/offer.rs index e57334f3..d890ab3f 100644 --- a/lightning/src/offers/offer.rs +++ b/lightning/src/offers/offer.rs @@ -76,9 +76,10 @@ use core::time::Duration; use crate::io; use crate::ln::features::OfferFeatures; use crate::ln::msgs::MAX_VALUE_MSAT; -use crate::offers::parse::{Bech32Encode, ParseError, SemanticError}; +use crate::offers::invoice_request::InvoiceRequestBuilder; +use crate::offers::parse::{Bech32Encode, ParseError, ParsedMessage, SemanticError}; use crate::onion_message::BlindedPath; -use crate::util::ser::{HighZeroBytesDroppedBigSize, Readable, WithoutLength, Writeable, Writer}; +use crate::util::ser::{HighZeroBytesDroppedBigSize, WithoutLength, Writeable, Writer}; use crate::util::string::PrintableString; use crate::prelude::*; @@ -137,7 +138,7 @@ impl OfferBuilder { /// Sets the [`Offer::amount`] as an [`Amount::Bitcoin`]. /// /// Successive calls to this method will override the previous setting. - pub fn amount_msats(mut self, amount_msats: u64) -> Self { + pub fn amount_msats(self, amount_msats: u64) -> Self { self.amount(Amount::Bitcoin { amount_msats }) } @@ -149,15 +150,6 @@ impl OfferBuilder { 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`]. /// @@ -185,7 +177,8 @@ impl OfferBuilder { self } - /// Sets the quantity of items for [`Offer::supported_quantity`]. + /// Sets the quantity of items for [`Offer::supported_quantity`]. If not called, defaults to + /// [`Quantity::one`]. /// /// Successive calls to this method will override the previous setting. pub fn supported_quantity(mut self, quantity: Quantity) -> Self { @@ -221,9 +214,17 @@ impl OfferBuilder { } } +#[cfg(test)] +impl OfferBuilder { + fn features_unchecked(mut self, features: OfferFeatures) -> Self { + self.offer.features = features; + self + } +} + /// 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 +/// 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 /// cover that quantity (i.e., at least `quantity * amount`). See [`Offer::amount`]. /// @@ -231,17 +232,21 @@ impl OfferBuilder { /// latter. /// /// Through the use of [`BlindedPath`]s, offers provide recipient privacy. +/// +/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest #[derive(Clone, Debug)] pub struct Offer { // The serialized offer. Needed when creating an `InvoiceRequest` if the offer contains unknown // fields. - bytes: Vec, - contents: OfferContents, + pub(super) bytes: Vec, + 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)] -pub(crate) struct OfferContents { +pub(super) struct OfferContents { chains: Option>, metadata: Option>, amount: Option, @@ -262,10 +267,16 @@ impl Offer { /// Payments must be denominated in units of the minimal lightning-payable unit (e.g., msats) /// for the selected chain. pub fn chains(&self) -> Vec { - self.contents.chains - .as_ref() - .cloned() - .unwrap_or_else(|| vec![self.contents.implied_chain()]) + 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) } // TODO: Link to corresponding method in `InvoiceRequest`. @@ -277,7 +288,7 @@ impl Offer { /// The minimum amount required for a successful payment of a single item. pub fn amount(&self) -> Option<&Amount> { - self.contents.amount.as_ref() + self.contents.amount() } /// A complete description of the purpose of the payment. Intended to be displayed to the user @@ -327,11 +338,46 @@ impl Offer { self.contents.supported_quantity() } + /// Returns whether the given quantity is valid for the offer. + pub fn is_valid_quantity(&self, quantity: u64) -> bool { + self.contents.is_valid_quantity(quantity) + } + + /// Returns whether a quantity is expected in an [`InvoiceRequest`] for the offer. + /// + /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest + pub fn expects_quantity(&self) -> bool { + self.contents.expects_quantity() + } + /// The public key used by the recipient to sign invoices. pub fn signing_pubkey(&self) -> PublicKey { self.contents.signing_pubkey.unwrap() } + /// 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, payer_id: PublicKey + ) -> Result { + 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 { self.contents.as_tlv_stream() @@ -345,15 +391,82 @@ impl AsRef<[u8]> for Offer { } impl OfferContents { + pub fn chains(&self) -> Vec { + self.chains.as_ref().cloned().unwrap_or_else(|| vec![self.implied_chain()]) + } + pub fn implied_chain(&self) -> ChainHash { ChainHash::using_genesis_block(Network::Bitcoin) } + pub fn supports_chain(&self, chain: ChainHash) -> bool { + self.chains().contains(&chain) + } + + pub fn amount(&self) -> Option<&Amount> { + self.amount.as_ref() + } + + pub(super) fn check_amount_msats_for_quantity( + &self, amount_msats: Option, quantity: Option + ) -> Result<(), SemanticError> { + let offer_amount_msats = match self.amount { + None => 0, + 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 * quantity.unwrap_or(1); + 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); + } + } + + Ok(()) + } + pub fn supported_quantity(&self) -> Quantity { self.supported_quantity } - fn as_tlv_stream(&self) -> OfferTlvStreamRef { + pub(super) fn check_quantity(&self, quantity: Option) -> 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) => { + let n = n.get(); + if n == 1 { false } + else { quantity > 0 && quantity <= n } + }, + Quantity::Unbounded => quantity > 0, + } + } + + fn expects_quantity(&self) -> bool { + match self.supported_quantity { + Quantity::Bounded(n) => n.get() != 1, + Quantity::Unbounded => true, + } + } + + 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)), @@ -394,15 +507,6 @@ impl Writeable for OfferContents { } } -impl TryFrom> for Offer { - type Error = ParseError; - - fn try_from(bytes: Vec) -> Result { - let tlv_stream: OfferTlvStream = Readable::read(&mut &bytes[..])?; - Offer::try_from((bytes, tlv_stream)) - } -} - /// The minimum amount required for an item in an [`Offer`], denominated in either bitcoin or /// another currency. #[derive(Clone, Debug, PartialEq)] @@ -434,7 +538,8 @@ pub enum Quantity { } impl Quantity { - fn one() -> Self { + /// The default quantity of one. + pub fn one() -> Self { Quantity::Bounded(NonZeroU64::new(1).unwrap()) } @@ -449,7 +554,7 @@ impl Quantity { } } -tlv_stream!(OfferTlvStream, OfferTlvStreamRef, { +tlv_stream!(OfferTlvStream, OfferTlvStreamRef, 1..80, { (2, chains: (Vec, WithoutLength)), (4, metadata: (Vec, WithoutLength)), (6, currency: CurrencyCode), @@ -467,8 +572,6 @@ impl Bech32Encode for Offer { const BECH32_HRP: &'static str = "lno"; } -type ParsedOffer = (Vec, OfferTlvStream); - impl FromStr for Offer { type Err = ParseError; @@ -477,11 +580,12 @@ impl FromStr for Offer { } } -impl TryFrom for Offer { +impl TryFrom> for Offer { type Error = ParseError; - fn try_from(offer: ParsedOffer) -> Result { - let (bytes, tlv_stream) = offer; + fn try_from(bytes: Vec) -> Result { + let offer = ParsedMessage::::try_from(bytes)?; + let ParsedMessage { bytes, tlv_stream } = offer; let contents = OfferContents::try_from(tlv_stream)?; Ok(Offer { bytes, contents }) } @@ -551,10 +655,10 @@ mod tests { use core::num::NonZeroU64; use core::time::Duration; use crate::ln::features::OfferFeatures; - use crate::ln::msgs::MAX_VALUE_MSAT; + use crate::ln::msgs::{DecodeError, MAX_VALUE_MSAT}; use crate::offers::parse::{ParseError, SemanticError}; use crate::onion_message::{BlindedHop, BlindedPath}; - use crate::util::ser::Writeable; + use crate::util::ser::{BigSize, Writeable}; use crate::util::string::PrintableString; fn pubkey(byte: u8) -> PublicKey { @@ -575,6 +679,7 @@ mod tests { assert_eq!(offer.bytes, buffer.as_slice()); assert_eq!(offer.chains(), vec![ChainHash::using_genesis_block(Network::Bitcoin)]); + assert!(offer.supports_chain(ChainHash::using_genesis_block(Network::Bitcoin))); assert_eq!(offer.metadata(), None); assert_eq!(offer.amount(), None); assert_eq!(offer.description(), PrintableString("foo")); @@ -613,6 +718,7 @@ mod tests { .chain(Network::Bitcoin) .build() .unwrap(); + assert!(offer.supports_chain(mainnet)); assert_eq!(offer.chains(), vec![mainnet]); assert_eq!(offer.as_tlv_stream().chains, None); @@ -620,6 +726,7 @@ mod tests { .chain(Network::Testnet) .build() .unwrap(); + assert!(offer.supports_chain(testnet)); assert_eq!(offer.chains(), vec![testnet]); assert_eq!(offer.as_tlv_stream().chains, Some(&vec![testnet])); @@ -628,6 +735,7 @@ mod tests { .chain(Network::Testnet) .build() .unwrap(); + assert!(offer.supports_chain(testnet)); assert_eq!(offer.chains(), vec![testnet]); assert_eq!(offer.as_tlv_stream().chains, Some(&vec![testnet])); @@ -636,6 +744,8 @@ mod tests { .chain(Network::Testnet) .build() .unwrap(); + assert!(offer.supports_chain(mainnet)); + assert!(offer.supports_chain(testnet)); assert_eq!(offer.chains(), vec![mainnet, testnet]); assert_eq!(offer.as_tlv_stream().chains, Some(&vec![mainnet, testnet])); } @@ -702,15 +812,15 @@ mod tests { #[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()); @@ -832,6 +942,18 @@ mod tests { 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)) @@ -1003,6 +1125,22 @@ mod tests { }, } } + + #[test] + fn fails_parsing_offer_with_extra_tlv_records() { + let offer = OfferBuilder::new("foo".into(), pubkey(42)).build().unwrap(); + + let mut encoded_offer = Vec::new(); + offer.write(&mut encoded_offer).unwrap(); + BigSize(80).write(&mut encoded_offer).unwrap(); + BigSize(32).write(&mut encoded_offer).unwrap(); + [42u8; 32].write(&mut encoded_offer).unwrap(); + + match Offer::try_from(encoded_offer) { + Ok(_) => panic!("expected error"), + Err(e) => assert_eq!(e, ParseError::Decode(DecodeError::InvalidValue)), + } + } } #[cfg(test)]