1 // This file is Copyright its original authors, visible in version control
4 // This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
5 // or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
6 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
7 // You may not use this file except in accordance with one or both of these
10 //! Parsing and formatting for bech32 message encoding.
13 use bitcoin::secp256k1;
14 use core::convert::TryFrom;
16 use crate::ln::msgs::DecodeError;
17 use crate::util::ser::SeekReadable;
19 #[allow(unused_imports)]
20 use crate::prelude::*;
23 pub(super) use sealed::Bech32Encode;
26 pub use sealed::Bech32Encode;
30 use bitcoin::bech32::{FromBase32, ToBase32};
31 use core::convert::TryFrom;
33 use super::Bolt12ParseError;
35 #[allow(unused_imports)]
36 use crate::prelude::*;
38 /// Indicates a message can be encoded using bech32.
39 pub trait Bech32Encode: AsRef<[u8]> + TryFrom<Vec<u8>, Error=Bolt12ParseError> {
40 /// Human readable part of the message's bech32 encoding.
41 const BECH32_HRP: &'static str;
43 /// Parses a bech32-encoded message into a TLV stream.
44 fn from_bech32_str(s: &str) -> Result<Self, Bolt12ParseError> {
45 // Offer encoding may be split by '+' followed by optional whitespace.
46 let encoded = match s.split('+').skip(1).next() {
48 for chunk in s.split('+') {
49 let chunk = chunk.trim_start();
50 if chunk.is_empty() || chunk.contains(char::is_whitespace) {
51 return Err(Bolt12ParseError::InvalidContinuation);
55 let s: String = s.chars().filter(|c| *c != '+' && !c.is_whitespace()).collect();
56 Bech32String::Owned(s)
58 None => Bech32String::Borrowed(s),
61 let (hrp, data) = bech32::decode_without_checksum(encoded.as_ref())?;
63 if hrp != Self::BECH32_HRP {
64 return Err(Bolt12ParseError::InvalidBech32Hrp);
67 let data = Vec::<u8>::from_base32(&data)?;
71 /// Formats the message using bech32-encoding.
72 fn fmt_bech32_str(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
73 bech32::encode_without_checksum_to_fmt(f, Self::BECH32_HRP, self.as_ref().to_base32())
74 .expect("HRP is invalid").unwrap();
80 // Used to avoid copying a bech32 string not containing the continuation character (+).
81 enum Bech32String<'a> {
86 impl<'a> AsRef<str> for Bech32String<'a> {
87 fn as_ref(&self) -> &str {
89 Bech32String::Borrowed(s) => s,
90 Bech32String::Owned(s) => s,
96 /// A wrapper for reading a message as a TLV stream `T` from a byte sequence, while still
97 /// maintaining ownership of the bytes for later use.
98 pub(super) struct ParsedMessage<T: SeekReadable> {
103 impl<T: SeekReadable> TryFrom<Vec<u8>> for ParsedMessage<T> {
104 type Error = DecodeError;
106 fn try_from(bytes: Vec<u8>) -> Result<Self, Self::Error> {
107 let mut cursor = io::Cursor::new(bytes);
108 let tlv_stream: T = SeekReadable::read(&mut cursor)?;
110 // Ensure that there are no more TLV records left to parse.
111 if cursor.position() < cursor.get_ref().len() as u64 {
112 return Err(DecodeError::InvalidValue);
115 let bytes = cursor.into_inner();
116 Ok(Self { bytes, tlv_stream })
120 /// Error when parsing a bech32 encoded message using [`str::parse`].
121 #[derive(Clone, Debug, PartialEq)]
122 pub enum Bolt12ParseError {
123 /// The bech32 encoding does not conform to the BOLT 12 requirements for continuing messages
124 /// across multiple parts (i.e., '+' followed by whitespace).
126 /// The bech32 encoding's human-readable part does not match what was expected for the message
129 /// The string could not be bech32 decoded.
130 Bech32(bech32::Error),
131 /// The bech32 decoded string could not be decoded as the expected message type.
133 /// The parsed message has invalid semantics.
134 InvalidSemantics(Bolt12SemanticError),
135 /// The parsed message has an invalid signature.
136 InvalidSignature(secp256k1::Error),
139 /// Error when interpreting a TLV stream as a specific type.
140 #[derive(Clone, Debug, PartialEq)]
141 pub enum Bolt12SemanticError {
142 /// The current [`std::time::SystemTime`] is past the offer or invoice's expiration.
144 /// The provided chain hash does not correspond to a supported chain.
146 /// A chain was provided but was not expected.
148 /// An amount was expected but was missing.
150 /// The amount exceeded the total bitcoin supply.
152 /// An amount was provided but was not sufficient in value.
154 /// An amount was provided but was not expected.
156 /// A currency was provided that is not supported.
158 /// A feature was required but is unknown.
159 UnknownRequiredFeatures,
160 /// Features were provided but were not expected.
162 /// A required description was not provided.
164 /// A signing pubkey was not provided.
165 MissingSigningPubkey,
166 /// A signing pubkey was provided but a different one was expected.
167 InvalidSigningPubkey,
168 /// A signing pubkey was provided but was not expected.
169 UnexpectedSigningPubkey,
170 /// A quantity was expected but was missing.
172 /// An unsupported quantity was provided.
174 /// A quantity or quantity bounds was provided but was not expected.
176 /// Metadata could not be used to verify the offers message.
178 /// Metadata was provided but was not expected.
180 /// Payer metadata was expected but was missing.
181 MissingPayerMetadata,
182 /// A payer id was expected but was missing.
184 /// The payment id for a refund or request is already in use.
186 /// Blinded paths were expected but were missing.
188 /// The blinded payinfo given does not match the number of blinded path hops.
190 /// An invoice creation time was expected but was missing.
192 /// An invoice payment hash was expected but was missing.
194 /// A signature was expected but was missing.
198 impl From<bech32::Error> for Bolt12ParseError {
199 fn from(error: bech32::Error) -> Self {
204 impl From<DecodeError> for Bolt12ParseError {
205 fn from(error: DecodeError) -> Self {
210 impl From<Bolt12SemanticError> for Bolt12ParseError {
211 fn from(error: Bolt12SemanticError) -> Self {
212 Self::InvalidSemantics(error)
216 impl From<secp256k1::Error> for Bolt12ParseError {
217 fn from(error: secp256k1::Error) -> Self {
218 Self::InvalidSignature(error)
224 use super::Bolt12ParseError;
225 use crate::offers::offer::Offer;
228 fn encodes_offer_as_bech32_without_checksum() {
229 let encoded_offer = "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg";
230 let offer = dbg!(encoded_offer.parse::<Offer>().unwrap());
231 let reencoded_offer = offer.to_string();
232 dbg!(reencoded_offer.parse::<Offer>().unwrap());
233 assert_eq!(reencoded_offer, encoded_offer);
237 fn parses_bech32_encoded_offers() {
239 // A complete string is valid
240 "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg",
242 // + can join anywhere
243 "l+no1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg",
245 // Multiple + can join
246 "lno1pqps7sjqpgt+yzm3qv4uxzmtsd3jjqer9wd3hy6tsw3+5k7msjzfpy7nz5yqcn+ygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd+5xvxg",
248 // + can be followed by whitespace
249 "lno1pqps7sjqpgt+ yzm3qv4uxzmtsd3jjqer9wd3hy6tsw3+ 5k7msjzfpy7nz5yqcn+\nygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd+\r\n 5xvxg",
251 for encoded_offer in &offers {
252 if let Err(e) = encoded_offer.parse::<Offer>() {
253 panic!("Invalid offer ({:?}): {}", e, encoded_offer);
259 fn fails_parsing_bech32_encoded_offers_with_invalid_continuations() {
261 // + must be surrounded by bech32 characters
262 "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg+",
263 "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg+ ",
264 "+lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg",
265 "+ lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg",
266 "ln++o1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg",
268 for encoded_offer in &offers {
269 match encoded_offer.parse::<Offer>() {
270 Ok(_) => panic!("Valid offer: {}", encoded_offer),
271 Err(e) => assert_eq!(e, Bolt12ParseError::InvalidContinuation),
279 use super::Bolt12ParseError;
281 use crate::ln::msgs::DecodeError;
282 use crate::offers::offer::Offer;
285 fn fails_parsing_bech32_encoded_offer_with_invalid_hrp() {
286 let encoded_offer = "lni1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxg";
287 match encoded_offer.parse::<Offer>() {
288 Ok(_) => panic!("Valid offer: {}", encoded_offer),
289 Err(e) => assert_eq!(e, Bolt12ParseError::InvalidBech32Hrp),
294 fn fails_parsing_bech32_encoded_offer_with_invalid_bech32_data() {
295 let encoded_offer = "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxo";
296 match encoded_offer.parse::<Offer>() {
297 Ok(_) => panic!("Valid offer: {}", encoded_offer),
298 Err(e) => assert_eq!(e, Bolt12ParseError::Bech32(bech32::Error::InvalidChar('o'))),
303 fn fails_parsing_bech32_encoded_offer_with_invalid_tlv_data() {
304 let encoded_offer = "lno1pqps7sjqpgtyzm3qv4uxzmtsd3jjqer9wd3hy6tsw35k7msjzfpy7nz5yqcnygrfdej82um5wf5k2uckyypwa3eyt44h6txtxquqh7lz5djge4afgfjn7k4rgrkuag0jsd5xvxgqqqqq";
305 match encoded_offer.parse::<Offer>() {
306 Ok(_) => panic!("Valid offer: {}", encoded_offer),
307 Err(e) => assert_eq!(e, Bolt12ParseError::Decode(DecodeError::InvalidValue)),