Invoice encoding and parsing

Define an interface for BOLT 12 `invoice` messages. The underlying
format consists of the original bytes and the parsed contents.

The bytes are later needed for serialization. This is because it must
mirror all the `offer` and `invoice_request` TLV records, including
unknown ones, which aren't represented in the contents.

Invoices may be created for an Offer (from an InvoiceRequest) or for a
Refund. The primary difference is how the signing pubkey is given -- by
the writer of the offer or the reader of the refund.

Author: jkczyz

lightning/src/offers/invoice.rs

@@ -0,0 +1,392 @@
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Data structures and encoding for `invoice` messages.
+
+use bitcoin::blockdata::constants::ChainHash;
+use bitcoin::network::constants::Network;
+use bitcoin::secp256k1::schnorr::Signature;
+use bitcoin::util::address::{Address, Payload, WitnessVersion};
+use core::convert::TryFrom;
+use core::time::Duration;
+use crate::io;
+use crate::ln::PaymentHash;
+use crate::ln::features::{BlindedHopFeatures, Bolt12InvoiceFeatures};
+use crate::ln::msgs::DecodeError;
+use crate::offers::invoice_request::{InvoiceRequestContents, InvoiceRequestTlvStream};
+use crate::offers::merkle::{SignatureTlvStream, self};
+use crate::offers::offer::OfferTlvStream;
+use crate::offers::parse::{ParseError, ParsedMessage, SemanticError};
+use crate::offers::payer::PayerTlvStream;
+use crate::offers::refund::RefundContents;
+use crate::onion_message::BlindedPath;
+use crate::util::ser::{HighZeroBytesDroppedBigSize, SeekReadable, WithoutLength, Writeable, Writer};
+
+use crate::prelude::*;
+
+#[cfg(feature = "std")]
+use std::time::SystemTime;
+
+const DEFAULT_RELATIVE_EXPIRY: Duration = Duration::from_secs(7200);
+
+const SIGNATURE_TAG: &'static str = concat!("lightning", "invoice", "signature");
+
+/// An `Invoice` is a payment request, typically corresponding to an [`Offer`] or a [`Refund`].
+///
+/// An invoice may be sent in response to an [`InvoiceRequest`] in the case of an offer or sent
+/// directly after scanning a refund. It includes all the information need to pay a recipient.
+///
+/// [`Offer`]: crate::offers::offer::Offer
+/// [`Refund`]: crate::offers::refund::Refund
+/// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
+pub struct Invoice {
+	bytes: Vec<u8>,
+	contents: InvoiceContents,
+	signature: Option<Signature>,
+}
+
+/// The contents of an [`Invoice`] for responding to either an [`Offer`] or a [`Refund`].
+///
+/// [`Offer`]: crate::offers::offer::Offer
+/// [`Refund`]: crate::offers::refund::Refund
+enum InvoiceContents {
+	/// Contents for an [`Invoice`] corresponding to an [`Offer`].
+	///
+	/// [`Offer`]: crate::offers::offer::Offer
+	ForOffer {
+		invoice_request: InvoiceRequestContents,
+		fields: InvoiceFields,
+	},
+	/// Contents for an [`Invoice`] corresponding to a [`Refund`].
+	///
+	/// [`Refund`]: crate::offers::refund::Refund
+	ForRefund {
+		refund: RefundContents,
+		fields: InvoiceFields,
+	},
+}
+
+/// Invoice-specific fields for an `invoice` message.
+struct InvoiceFields {
+	paths: Vec<BlindedPath>,
+	payinfo: Vec<BlindedPayInfo>,
+	created_at: Duration,
+	relative_expiry: Option<Duration>,
+	payment_hash: PaymentHash,
+	amount_msats: u64,
+	fallbacks: Option<Vec<FallbackAddress>>,
+	features: Bolt12InvoiceFeatures,
+	code: Option<String>,
+}
+
+impl Invoice {
+	/// Paths to the recipient originating from publicly reachable nodes. Blinded paths provide
+	/// recipient privacy by obfuscating its node id.
+	pub fn paths(&self) -> &[BlindedPath] {
+		&self.contents.fields().paths[..]
+	}
+
+	/// Information for each hop in [`Invoice::paths`] needed for routing payments across it.
+	pub fn payinfo(&self) -> &[BlindedPayInfo] {
+		&self.contents.fields().payinfo[..]
+	}
+
+	/// Duration since the Unix epoch when the invoice was created.
+	pub fn created_at(&self) -> Duration {
+		self.contents.fields().created_at
+	}
+
+	/// Duration since [`Invoice::created_at`] when the invoice has expired and therefore should no
+	/// longer be paid.
+	pub fn relative_expiry(&self) -> Duration {
+		self.contents.fields().relative_expiry.unwrap_or(DEFAULT_RELATIVE_EXPIRY)
+	}
+
+	/// Whether the invoice has expired.
+	#[cfg(feature = "std")]
+	pub fn is_expired(&self) -> bool {
+		let absolute_expiry = self.created_at().checked_add(self.relative_expiry());
+		match absolute_expiry {
+			Some(seconds_from_epoch) => match SystemTime::UNIX_EPOCH.elapsed() {
+				Ok(elapsed) => elapsed > seconds_from_epoch,
+				Err(_) => false,
+			},
+			None => false,
+		}
+	}
+
+	/// SHA256 hash of the payment preimage that will be given in return for paying the invoice.
+	pub fn payment_hash(&self) -> PaymentHash {
+		self.contents.fields().payment_hash
+	}
+
+	/// The minimum amount required for a successful payment of the invoice.
+	pub fn amount_msats(&self) -> u64 {
+		self.contents.fields().amount_msats
+	}
+
+	/// Fallback addresses for paying the invoice on-chain, in order of most-preferred to
+	/// least-preferred.
+	pub fn fallbacks(&self) -> Vec<Address> {
+		let network = match self.network() {
+			None => return Vec::new(),
+			Some(network) => network,
+		};
+
+		let to_valid_address = |address: &FallbackAddress| {
+			let program = &address.program;
+			if program.len() < 2 || program.len() > 40 {
+				return None;
+			}
+
+			let address = Address {
+				payload: Payload::WitnessProgram {
+					version: address.version,
+					program: address.program.clone(),
+				},
+				network,
+			};
+
+			if !address.is_standard() {
+				return None;
+			}
+
+			Some(address)
+		};
+
+		self.contents.fields().fallbacks
+			.as_ref()
+			.map(|fallbacks| fallbacks.iter().filter_map(to_valid_address).collect())
+			.unwrap_or_else(Vec::new)
+	}
+
+	fn network(&self) -> Option<Network> {
+		let chain = self.contents.chain();
+		if chain == ChainHash::using_genesis_block(Network::Bitcoin) {
+			Some(Network::Bitcoin)
+		} else if chain == ChainHash::using_genesis_block(Network::Testnet) {
+			Some(Network::Testnet)
+		} else if chain == ChainHash::using_genesis_block(Network::Signet) {
+			Some(Network::Signet)
+		} else if chain == ChainHash::using_genesis_block(Network::Regtest) {
+			Some(Network::Regtest)
+		} else {
+			None
+		}
+	}
+
+	/// Features pertaining to paying an invoice.
+	pub fn features(&self) -> &Bolt12InvoiceFeatures {
+		&self.contents.fields().features
+	}
+
+	/// A short string used for verifying the recipient when issuing a refund. The payer should only
+	/// pay the invoice after confirming with recipient out-of-band that this code is correct.
+	pub fn code(&self) -> Option<&str> {
+		self.contents.fields().code.as_ref().map(|code| code.as_str())
+	}
+
+	/// Signature of the invoice using [`signing_pubkey`]. `None` for invoices paying refunds.
+	///
+	/// [`signing_pubkey`]: crate::offers::offer::Offer::signing_pubkey
+	pub fn signature(&self) -> Option<Signature> {
+		self.signature
+	}
+}
+
+impl InvoiceContents {
+	fn chain(&self) -> ChainHash {
+		match self {
+			InvoiceContents::ForOffer { invoice_request, .. } => invoice_request.chain(),
+			InvoiceContents::ForRefund { refund, .. } => refund.chain(),
+		}
+	}
+
+	fn fields(&self) -> &InvoiceFields {
+		match self {
+			InvoiceContents::ForOffer { fields, .. } => fields,
+			InvoiceContents::ForRefund { fields, .. } => fields,
+		}
+	}
+}
+
+impl Writeable for Invoice {
+	fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+		WithoutLength(&self.bytes).write(writer)
+	}
+}
+
+impl TryFrom<Vec<u8>> for Invoice {
+	type Error = ParseError;
+
+	fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error> {
+		let parsed_invoice = ParsedMessage::<FullInvoiceTlvStream>::try_from(bytes)?;
+		Invoice::try_from(parsed_invoice)
+	}
+}
+
+tlv_stream!(InvoiceTlvStream, InvoiceTlvStreamRef, 160..240, {
+	(160, paths: (Vec<BlindedPath>, WithoutLength)),
+	(162, blindedpay: (Vec<BlindedPayInfo>, WithoutLength)),
+	(164, created_at: (u64, HighZeroBytesDroppedBigSize)),
+	(166, relative_expiry: (u32, HighZeroBytesDroppedBigSize)),
+	(168, payment_hash: PaymentHash),
+	(170, amount: (u64, HighZeroBytesDroppedBigSize)),
+	(172, fallbacks: (Vec<FallbackAddress>, WithoutLength)),
+	(174, features: (Bolt12InvoiceFeatures, WithoutLength)),
+	(176, code: (String, WithoutLength)),
+});
+
+/// Information needed to route a payment across a [`BlindedPath`] hop.
+#[derive(Debug, PartialEq)]
+pub struct BlindedPayInfo {
+	fee_base_msat: u32,
+	fee_proportional_millionths: u32,
+	cltv_expiry_delta: u16,
+	htlc_minimum_msat: u64,
+	htlc_maximum_msat: u64,
+	features: BlindedHopFeatures,
+}
+
+impl_writeable!(BlindedPayInfo, {
+	fee_base_msat,
+	fee_proportional_millionths,
+	cltv_expiry_delta,
+	htlc_minimum_msat,
+	htlc_maximum_msat,
+	features
+});
+
+/// Wire representation for an on-chain fallback address.
+#[derive(Debug, PartialEq)]
+pub(super) struct FallbackAddress {
+	version: WitnessVersion,
+	program: Vec<u8>,
+}
+
+impl_writeable!(FallbackAddress, { version, program });
+
+type FullInvoiceTlvStream =
+	(PayerTlvStream, OfferTlvStream, InvoiceRequestTlvStream, InvoiceTlvStream, SignatureTlvStream);
+
+impl SeekReadable for FullInvoiceTlvStream {
+	fn read<R: io::Read + io::Seek>(r: &mut R) -> Result<Self, DecodeError> {
+		let payer = SeekReadable::read(r)?;
+		let offer = SeekReadable::read(r)?;
+		let invoice_request = SeekReadable::read(r)?;
+		let invoice = SeekReadable::read(r)?;
+		let signature = SeekReadable::read(r)?;
+
+		Ok((payer, offer, invoice_request, invoice, signature))
+	}
+}
+
+type PartialInvoiceTlvStream =
+	(PayerTlvStream, OfferTlvStream, InvoiceRequestTlvStream, InvoiceTlvStream);
+
+impl TryFrom<ParsedMessage<FullInvoiceTlvStream>> for Invoice {
+	type Error = ParseError;
+
+	fn try_from(invoice: ParsedMessage<FullInvoiceTlvStream>) -> Result<Self, Self::Error> {
+		let ParsedMessage { bytes, tlv_stream } = invoice;
+		let (
+			payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream, invoice_tlv_stream,
+			SignatureTlvStream { signature },
+		) = tlv_stream;
+		let contents = InvoiceContents::try_from(
+			(payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream, invoice_tlv_stream)
+		)?;
+
+		match &contents {
+			InvoiceContents::ForOffer { invoice_request, .. } => match &signature {
+				None => return Err(ParseError::InvalidSemantics(SemanticError::MissingSignature)),
+				Some(signature) => {
+					let pubkey = invoice_request.offer.signing_pubkey();
+					merkle::verify_signature(signature, SIGNATURE_TAG, &bytes, pubkey)?;
+				},
+			},
+			InvoiceContents::ForRefund { .. } => if let Some(_) = &signature {
+				return Err(ParseError::InvalidSemantics(SemanticError::UnexpectedSignature));
+			},
+		}
+
+		Ok(Invoice { bytes, contents, signature })
+	}
+}
+
+impl TryFrom<PartialInvoiceTlvStream> for InvoiceContents {
+	type Error = SemanticError;
+
+	fn try_from(tlv_stream: PartialInvoiceTlvStream) -> Result<Self, Self::Error> {
+		let (
+			payer_tlv_stream,
+			offer_tlv_stream,
+			invoice_request_tlv_stream,
+			InvoiceTlvStream {
+				paths, blindedpay, created_at, relative_expiry, payment_hash, amount, fallbacks,
+				features, code,
+			},
+		) = tlv_stream;
+
+		let (paths, payinfo) = match (paths, blindedpay) {
+			(None, _) => return Err(SemanticError::MissingPaths),
+			(_, None) => return Err(SemanticError::InvalidPayInfo),
+			(Some(paths), _) if paths.is_empty() => return Err(SemanticError::MissingPaths),
+			(Some(paths), Some(blindedpay)) if paths.len() != blindedpay.len() => {
+				return Err(SemanticError::InvalidPayInfo);
+			},
+			(Some(paths), Some(blindedpay)) => (paths, blindedpay),
+		};
+
+		let created_at = match created_at {
+			None => return Err(SemanticError::MissingCreationTime),
+			Some(timestamp) => Duration::from_secs(timestamp),
+		};
+
+		let relative_expiry = relative_expiry
+			.map(Into::<u64>::into)
+			.map(Duration::from_secs);
+
+		let payment_hash = match payment_hash {
+			None => return Err(SemanticError::MissingPaymentHash),
+			Some(payment_hash) => payment_hash,
+		};
+
+		let amount_msats = match amount {
+			None => return Err(SemanticError::MissingAmount),
+			Some(amount) => amount,
+		};
+
+		let features = features.unwrap_or_else(Bolt12InvoiceFeatures::empty);
+
+		let fields = InvoiceFields {
+			paths, payinfo, created_at, relative_expiry, payment_hash, amount_msats, fallbacks,
+			features, code,
+		};
+
+		match offer_tlv_stream.node_id {
+			Some(_) => {
+				if fields.code.is_some() {
+					return Err(SemanticError::UnexpectedCode);
+				}
+
+				let invoice_request = InvoiceRequestContents::try_from(
+					(payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream)
+				)?;
+				Ok(InvoiceContents::ForOffer { invoice_request, fields })
+			},
+			None => {
+				let refund = RefundContents::try_from(
+					(payer_tlv_stream, offer_tlv_stream, invoice_request_tlv_stream)
+				)?;
+				Ok(InvoiceContents::ForRefund { refund, fields })
+			},
+		}
+	}
+}