Offer parsing from bech32 strings

Add common bech32 parsing for BOLT 12 messages. The encoding is similar
to bech32 only without a checksum and with support for continuing
messages across multiple parts.

Messages implementing Bech32Encode are parsed into a TLV stream, which
is converted to the desired message content while performing semantic
checks. Checking after conversion allows for more elaborate checks of
data composed of multiple TLV records and for more meaningful error
messages.

The parsed bytes are also saved to allow creating messages with mirrored
data, even if TLV records are unknown.

Author: jkczyz

lightning/src/offers/mod.rs

@@ -13,3 +13,4 @@
 //! Offers are a flexible protocol for Lightning payments.
 
 pub mod offer;
+pub mod parse;

lightning/src/offers/offer.rs

@@ -22,9 +22,9 @@
 //! use core::time::Duration;
 //!
 //! use bitcoin::secp256k1::{KeyPair, PublicKey, Secp256k1, SecretKey};
-//! use lightning::offers::offer::{Amount, OfferBuilder};
+//! use lightning::offers::offer::{Amount, Offer, OfferBuilder};
+//! use lightning::offers::parse::ParseError;
 //!
-//! # use bitcoin::secp256k1;
 //! # use lightning::onion_message::BlindedPath;
 //! # #[cfg(feature = "std")]
 //! # use std::time::SystemTime;
@@ -33,9 +33,9 @@
 //! # fn create_another_blinded_path() -> BlindedPath { unimplemented!() }
 //! #
 //! # #[cfg(feature = "std")]
-//! # fn build() -> Result<(), secp256k1::Error> {
+//! # fn build() -> Result<(), ParseError> {
 //! let secp_ctx = Secp256k1::new();
-//! let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32])?);
+//! let keys = KeyPair::from_secret_key(&secp_ctx, &SecretKey::from_slice(&[42; 32]).unwrap());
 //! let pubkey = PublicKey::from(keys);
 //!
 //! let one_item = NonZeroU64::new(1).unwrap();
@@ -49,19 +49,28 @@
 //!     .path(create_another_blinded_path())
 //!     .build()
 //!     .unwrap();
+//!
+//! // Encode as a bech32 string for use in a QR code.
+//! let encoded_offer = offer.to_string();
+//!
+//! // Parse from a bech32 string after scanning from a QR code.
+//! let offer = encoded_offer.parse::<Offer>()?;
 //! # Ok(())
 //! # }
 //! ```
 
 use bitcoin::blockdata::constants::ChainHash;
 use bitcoin::network::constants::Network;
 use bitcoin::secp256k1::PublicKey;
+use core::convert::TryFrom;
 use core::num::NonZeroU64;
 use core::ops::{Bound, RangeBounds};
+use core::str::FromStr;
 use core::time::Duration;
 use io;
 use ln::features::OfferFeatures;
 use ln::msgs::MAX_VALUE_MSAT;
+use offers::parse::{Bech32Encode, ParseError, SemanticError};
 use onion_message::BlindedPath;
 use util::ser::{HighZeroBytesDroppedBigSize, WithoutLength, Writeable, Writer};
 use util::string::PrintableString;
@@ -354,6 +363,12 @@ impl Offer {
 	}
 }
 
+impl AsRef<[u8]> for Offer {
+	fn as_ref(&self) -> &[u8] {
+		&self.bytes
+	}
+}
+
 impl OfferContents {
 	pub fn amount_msats(&self) -> u64 {
 		self.amount.as_ref().map(Amount::as_msats).unwrap_or(0)
@@ -450,6 +465,103 @@ tlv_stream!(OfferTlvStream, OfferTlvStreamRef, {
 	(24, node_id: PublicKey),
 });
 
+impl Bech32Encode for Offer {
+	type TlvStream = OfferTlvStream;
+
+	const BECH32_HRP: &'static str = "lno";
+}
+
+impl FromStr for Offer {
+	type Err = ParseError;
+
+	fn from_str(s: &str) -> Result<Self, <Self as FromStr>::Err> {
+		let (tlv_stream, bytes) = Offer::from_bech32_str(s)?;
+		let contents = OfferContents::try_from(tlv_stream)?;
+		Ok(Offer { bytes, contents })
+	}
+}
+
+impl TryFrom<OfferTlvStream> for OfferContents {
+	type Error = SemanticError;
+
+	fn try_from(tlv_stream: OfferTlvStream) -> Result<Self, Self::Error> {
+		let OfferTlvStream {
+			chains, metadata, currency, amount, description, features, absolute_expiry, paths,
+			issuer, quantity_min, quantity_max, node_id,
+		} = tlv_stream;
+
+		let supported_chains = [
+			ChainHash::using_genesis_block(Network::Bitcoin),
+			ChainHash::using_genesis_block(Network::Testnet),
+			ChainHash::using_genesis_block(Network::Signet),
+			ChainHash::using_genesis_block(Network::Regtest),
+		];
+		let chains = match chains {
+			None => None,
+			Some(chains) => match chains.first() {
+				None => Some(chains),
+				Some(chain) if supported_chains.contains(chain) => Some(chains),
+				_ => return Err(SemanticError::UnsupportedChain),
+			},
+		};
+
+		let amount = match (currency, amount) {
+			(None, None) => None,
+			(None, Some(amount_msats)) => Some(Amount::Bitcoin { amount_msats }),
+			(Some(_), None) => return Err(SemanticError::MissingAmount),
+			(Some(_), Some(_)) => return Err(SemanticError::UnsupportedCurrency),
+		};
+
+		let description = match description {
+			None => return Err(SemanticError::MissingDescription),
+			Some(description) => description,
+		};
+
+		let features = features.unwrap_or_else(OfferFeatures::empty);
+
+		let absolute_expiry = absolute_expiry
+			.map(|seconds_from_epoch| Duration::from_secs(seconds_from_epoch));
+
+		let paths = match paths {
+			Some(paths) if paths.is_empty() => return Err(SemanticError::MissingPaths),
+			paths => paths,
+		};
+
+		if let Some(quantity_min) = quantity_min {
+			if quantity_min < 1 {
+				return Err(SemanticError::InvalidQuantity);
+			}
+
+			if let Some(quantity_max) = quantity_max {
+				if quantity_min > quantity_max {
+					return Err(SemanticError::InvalidQuantity);
+				}
+			}
+		}
+
+		if let Some(quantity_max) = quantity_max {
+			if quantity_max < 1 {
+				return Err(SemanticError::InvalidQuantity);
+			}
+		}
+
+		if node_id.is_none() {
+			return Err(SemanticError::MissingNodeId);
+		}
+
+		Ok(OfferContents {
+			chains, metadata, amount, description, features, absolute_expiry, issuer, paths,
+			quantity_min, quantity_max, signing_pubkey: node_id,
+		})
+	}
+}
+
+impl core::fmt::Display for Offer {
+	fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
+		self.fmt_bech32_str(f)
+	}
+}
+
 #[cfg(test)]
 mod tests {
 	use super::{Amount, OfferBuilder};
@@ -830,3 +942,88 @@ mod tests {
 		);
 	}
 }
+
+#[cfg(test)]
+mod bolt12_tests {
+	use super::{Offer, ParseError};
+	use bitcoin::bech32;
+	use ln::msgs::DecodeError;
+
+	// TODO: Remove once test vectors are updated.
+	#[ignore]
+	#[test]
+	fn encodes_offer_as_bech32_without_checksum() {
+		let encoded_offer = "lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy";
+		let offer = dbg!(encoded_offer.parse::<Offer>().unwrap());
+		let reencoded_offer = offer.to_string();
+		dbg!(reencoded_offer.parse::<Offer>().unwrap());
+		assert_eq!(reencoded_offer, encoded_offer);
+	}
+
+	// TODO: Remove once test vectors are updated.
+	#[ignore]
+	#[test]
+	fn parses_bech32_encoded_offers() {
+		let offers = [
+			// BOLT 12 test vectors
+			"lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+			"l+no1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+			"l+no1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+			"lno1qcp4256ypqpq+86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn0+0fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0+sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qs+y",
+			"lno1qcp4256ypqpq+ 86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn0+  0fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0+\nsqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43l+\r\nastpwuh73k29qs+\r  y",
+			// Two blinded paths
+			"lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0yg06qg2qdd7t628sgykwj5kuc837qmlv9m9gr7sq8ap6erfgacv26nhp8zzcqgzhdvttlk22pw8fmwqqrvzst792mj35ypylj886ljkcmug03wg6heqqsqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq6muh550qsfva9fdes0ruph7ctk2s8aqq06r4jxj3msc448wzwy9sqs9w6ckhlv55zuwnkuqqxc9qhu24h9rggzflyw04l9d3hcslzu340jqpqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+		];
+		for encoded_offer in &offers {
+			if let Err(e) = encoded_offer.parse::<Offer>() {
+				panic!("Invalid offer ({:?}): {}", e, encoded_offer);
+			}
+		}
+	}
+
+	#[test]
+	fn fails_parsing_bech32_encoded_offers_with_invalid_continuations() {
+		let offers = [
+			// BOLT 12 test vectors
+			"lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy+",
+			"lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy+ ",
+			"+lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+			"+ lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+			"ln++o1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy",
+		];
+		for encoded_offer in &offers {
+			match encoded_offer.parse::<Offer>() {
+				Ok(_) => panic!("Valid offer: {}", encoded_offer),
+				Err(e) => assert_eq!(e, ParseError::InvalidContinuation),
+			}
+		}
+
+	}
+
+	#[test]
+	fn fails_parsing_bech32_encoded_offer_with_invalid_hrp() {
+		let encoded_offer = "lni1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsy";
+		match encoded_offer.parse::<Offer>() {
+			Ok(_) => panic!("Valid offer: {}", encoded_offer),
+			Err(e) => assert_eq!(e, ParseError::InvalidBech32Hrp),
+		}
+	}
+
+	#[test]
+	fn fails_parsing_bech32_encoded_offer_with_invalid_bech32_data() {
+		let encoded_offer = "lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qso";
+		match encoded_offer.parse::<Offer>() {
+			Ok(_) => panic!("Valid offer: {}", encoded_offer),
+			Err(e) => assert_eq!(e, ParseError::Bech32(bech32::Error::InvalidChar('o'))),
+		}
+	}
+
+	#[test]
+	fn fails_parsing_bech32_encoded_offer_with_invalid_tlv_data() {
+		let encoded_offer = "lno1qcp4256ypqpq86q2pucnq42ngssx2an9wfujqerp0y2pqun4wd68jtn00fkxzcnn9ehhyec6qgqsz83qfwdpl28qqmc78ymlvhmxcsywdk5wrjnj36jryg488qwlrnzyjczlqsp9nyu4phcg6dqhlhzgxagfu7zh3d9re0sqp9ts2yfugvnnm9gxkcnnnkdpa084a6t520h5zhkxsdnghvpukvd43lastpwuh73k29qsyqqqqq";
+		match encoded_offer.parse::<Offer>() {
+			Ok(_) => panic!("Valid offer: {}", encoded_offer),
+			Err(e) => assert_eq!(e, ParseError::Decode(DecodeError::InvalidValue)),
+		}
+	}
+}

lightning/src/offers/parse.rs

@@ -0,0 +1,110 @@
+// 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.
+
+//! Parsing and formatting for bech32 message encoding.
+
+use bitcoin::bech32;
+use bitcoin::bech32::{FromBase32, ToBase32};
+use core::fmt;
+use ln::msgs::DecodeError;
+use util::ser::Readable;
+
+use prelude::*;
+
+/// Indicates a message can be encoded using bech32.
+pub(crate) trait Bech32Encode: AsRef<[u8]> {
+	/// TLV stream that a bech32-encoded message is parsed into.
+	type TlvStream: Readable;
+
+	/// Human readable part of the message's bech32 encoding.
+	const BECH32_HRP: &'static str;
+
+	/// Parses a bech32-encoded message into a TLV stream.
+	fn from_bech32_str(s: &str) -> Result<(Self::TlvStream, Vec<u8>), ParseError> {
+		// Offer encoding may be split by '+' followed by optional whitespace.
+		for chunk in s.split('+') {
+			let chunk = chunk.trim_start();
+			if chunk.is_empty() || chunk.contains(char::is_whitespace) {
+				return Err(ParseError::InvalidContinuation);
+			}
+		}
+
+		let s = s.chars().filter(|c| *c != '+' && !c.is_whitespace()).collect::<String>();
+		let (hrp, data) = bech32::decode_without_checksum(&s)?;
+
+		if hrp != Self::BECH32_HRP {
+			return Err(ParseError::InvalidBech32Hrp);
+		}
+
+		let data = Vec::<u8>::from_base32(&data)?;
+		Ok((Readable::read(&mut &data[..])?, data))
+	}
+
+	/// Formats the message using bech32-encoding.
+	fn fmt_bech32_str(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
+		bech32::encode_without_checksum_to_fmt(f, Self::BECH32_HRP, self.as_ref().to_base32())
+			.expect("HRP is valid").unwrap();
+
+		Ok(())
+	}
+}
+
+/// Error when parsing a bech32 encoded message using [`str::parse`].
+#[derive(Debug, PartialEq)]
+pub enum ParseError {
+	/// The bech32 encoding does not conform to the BOLT 12 requirements for continuing messages
+	/// across multiple parts (i.e., '+' followed by whitespace).
+	InvalidContinuation,
+	/// The bech32 encoding's human-readable part does not match what was expected for the message
+	/// being parsed.
+	InvalidBech32Hrp,
+	/// The string could not be bech32 decoded.
+	Bech32(bech32::Error),
+	/// The bech32 decoded string could not be decoded as the expected message type.
+	Decode(DecodeError),
+	/// The parsed message has invalid semantics.
+	InvalidSemantics(SemanticError),
+}
+
+/// Error when interpreting a TLV stream as a specific type.
+#[derive(Debug, PartialEq)]
+pub enum SemanticError {
+	/// The provided block hash does not correspond to a supported chain.
+	UnsupportedChain,
+	/// An amount was expected but was missing.
+	MissingAmount,
+	/// A currency was provided that is not supported.
+	UnsupportedCurrency,
+	/// A required description was not provided.
+	MissingDescription,
+	/// A node id was not provided.
+	MissingNodeId,
+	/// An empty set of blinded paths was provided.
+	MissingPaths,
+	/// A quantity representing an empty range or that was outside of a valid range was provided.
+	InvalidQuantity,
+}
+
+impl From<bech32::Error> for ParseError {
+	fn from(error: bech32::Error) -> Self {
+		Self::Bech32(error)
+	}
+}
+
+impl From<DecodeError> for ParseError {
+	fn from(error: DecodeError) -> Self {
+		Self::Decode(error)
+	}
+}
+
+impl From<SemanticError> for ParseError {
+	fn from(error: SemanticError) -> Self {
+		Self::InvalidSemantics(error)
+	}
+}

lightning/src/util/ser_macros.rs

@@ -462,7 +462,7 @@ macro_rules! tlv_stream {
 		$(($type:expr, $field:ident : $fieldty:tt)),* $(,)*
 	}) => {
 		#[derive(Debug)]
-		struct $name {
+		pub(crate) struct $name {
 			$(
 				$field: Option<tlv_record_type!($fieldty)>,
 			)*