git.bitcoin.ninja Git - rust-lightning/blob - lightning-invoice/src/lib.rs

   1 // Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
   2 #![deny(broken_intra_doc_links)]
   3 #![deny(private_intra_doc_links)]
   4
   5 #![deny(missing_docs)]
   6 #![deny(non_upper_case_globals)]
   7 #![deny(non_camel_case_types)]
   8 #![deny(non_snake_case)]
   9 #![deny(unused_mut)]
  10
  11 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
  12
  13 #![cfg_attr(feature = "strict", deny(warnings))]
  14 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
  15
  16 //! This crate provides data structures to represent
  17 //! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
  18 //! invoices and functions to create, encode and decode these. If you just want to use the standard
  19 //! en-/decoding functionality this should get you started:
  20 //!
  21 //!   * For parsing use `str::parse::<Invoice>(&self)` (see [`Invoice::from_str`])
  22 //!   * For constructing invoices use the [`InvoiceBuilder`]
  23 //!   * For serializing invoices use the [`Display`]/[`ToString`] traits
  24 //!
  25 //! [`Invoice::from_str`]: crate::Invoice#impl-FromStr
  26
  27 #[cfg(not(any(feature = "std", feature = "no-std")))]
  28 compile_error!("at least one of the `std` or `no-std` features must be enabled");
  29
  30 pub mod payment;
  31 pub mod utils;
  32
  33 pub(crate) mod time_utils;
  34
  35 extern crate bech32;
  36 extern crate bitcoin_hashes;
  37 #[macro_use] extern crate lightning;
  38 extern crate num_traits;
  39 extern crate secp256k1;
  40 extern crate alloc;
  41 #[cfg(any(test, feature = "std"))]
  42 extern crate core;
  43 #[cfg(feature = "serde")]
  44 extern crate serde;
  45
  46 #[cfg(feature = "std")]
  47 use std::time::SystemTime;
  48
  49 use bech32::u5;
  50 use bitcoin_hashes::Hash;
  51 use bitcoin_hashes::sha256;
  52 use lightning::ln::PaymentSecret;
  53 use lightning::ln::features::InvoiceFeatures;
  54 #[cfg(any(doc, test))]
  55 use lightning::routing::gossip::RoutingFees;
  56 use lightning::routing::router::RouteHint;
  57 use lightning::util::invoice::construct_invoice_preimage;
  58
  59 use secp256k1::PublicKey;
  60 use secp256k1::{Message, Secp256k1};
  61 use secp256k1::ecdsa::RecoverableSignature;
  62
  63 use core::fmt::{Display, Formatter, self};
  64 use core::iter::FilterMap;
  65 use core::num::ParseIntError;
  66 use core::ops::Deref;
  67 use core::slice::Iter;
  68 use core::time::Duration;
  69 use core::str;
  70
  71 #[cfg(feature = "serde")]
  72 use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
  73
  74 mod de;
  75 mod ser;
  76 mod tb;
  77
  78 mod prelude {
  79         #[cfg(feature = "hashbrown")]
  80         extern crate hashbrown;
  81
  82         pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
  83         #[cfg(not(feature = "hashbrown"))]
  84         pub use std::collections::{HashMap, HashSet, hash_map};
  85         #[cfg(feature = "hashbrown")]
  86         pub use self::hashbrown::{HashMap, HashSet, hash_map};
  87
  88         pub use alloc::string::ToString;
  89 }
  90
  91 use crate::prelude::*;
  92
  93 /// Sync compat for std/no_std
  94 #[cfg(feature = "std")]
  95 mod sync {
  96         pub use ::std::sync::{Mutex, MutexGuard};
  97 }
  98
  99 /// Sync compat for std/no_std
 100 #[cfg(not(feature = "std"))]
 101 mod sync;
 102
 103 /// Errors that indicate what is wrong with the invoice. They have some granularity for debug
 104 /// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
 105 #[allow(missing_docs)]
 106 #[derive(PartialEq, Eq, Debug, Clone)]
 107 pub enum ParseError {
 108         Bech32Error(bech32::Error),
 109         ParseAmountError(ParseIntError),
 110         MalformedSignature(secp256k1::Error),
 111         BadPrefix,
 112         UnknownCurrency,
 113         UnknownSiPrefix,
 114         MalformedHRP,
 115         TooShortDataPart,
 116         UnexpectedEndOfTaggedFields,
 117         DescriptionDecodeError(str::Utf8Error),
 118         PaddingError,
 119         IntegerOverflowError,
 120         InvalidSegWitProgramLength,
 121         InvalidPubKeyHashLength,
 122         InvalidScriptHashLength,
 123         InvalidRecoveryId,
 124         InvalidSliceLength(String),
 125
 126         /// Not an error, but used internally to signal that a part of the invoice should be ignored
 127         /// according to BOLT11
 128         Skip,
 129 }
 130
 131 /// Indicates that something went wrong while parsing or validating the invoice. Parsing errors
 132 /// should be mostly seen as opaque and are only there for debugging reasons. Semantic errors
 133 /// like wrong signatures, missing fields etc. could mean that someone tampered with the invoice.
 134 #[derive(PartialEq, Eq, Debug, Clone)]
 135 pub enum ParseOrSemanticError {
 136         /// The invoice couldn't be decoded
 137         ParseError(ParseError),
 138
 139         /// The invoice could be decoded but violates the BOLT11 standard
 140         SemanticError(crate::SemanticError),
 141 }
 142
 143 /// The number of bits used to represent timestamps as defined in BOLT 11.
 144 const TIMESTAMP_BITS: usize = 35;
 145
 146 /// The maximum timestamp as [`Duration::as_secs`] since the Unix epoch allowed by [`BOLT 11`].
 147 ///
 148 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 149 pub const MAX_TIMESTAMP: u64 = (1 << TIMESTAMP_BITS) - 1;
 150
 151 /// Default expiry time as defined by [BOLT 11].
 152 ///
 153 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 154 pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
 155
 156 /// Default minimum final CLTV expiry as defined by [BOLT 11].
 157 ///
 158 /// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
 159 /// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
 160 ///
 161 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 162 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
 163 pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
 164
 165 /// Builder for [`Invoice`]s. It's the most convenient and advised way to use this library. It ensures
 166 /// that only a semantically and syntactically correct Invoice can be built using it.
 167 ///
 168 /// ```
 169 /// extern crate secp256k1;
 170 /// extern crate lightning;
 171 /// extern crate lightning_invoice;
 172 /// extern crate bitcoin_hashes;
 173 ///
 174 /// use bitcoin_hashes::Hash;
 175 /// use bitcoin_hashes::sha256;
 176 ///
 177 /// use secp256k1::Secp256k1;
 178 /// use secp256k1::SecretKey;
 179 ///
 180 /// use lightning::ln::PaymentSecret;
 181 ///
 182 /// use lightning_invoice::{Currency, InvoiceBuilder};
 183 ///
 184 /// # #[cfg(not(feature = "std"))]
 185 /// # fn main() {}
 186 /// # #[cfg(feature = "std")]
 187 /// # fn main() {
 188 /// let private_key = SecretKey::from_slice(
 189 ///             &[
 190 ///                     0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
 191 ///                     0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
 192 ///             0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
 193 ///     ][..]
 194 ///     ).unwrap();
 195 ///
 196 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
 197 /// let payment_secret = PaymentSecret([42u8; 32]);
 198 ///
 199 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
 200 ///     .description("Coins pls!".into())
 201 ///     .payment_hash(payment_hash)
 202 ///     .payment_secret(payment_secret)
 203 ///     .current_timestamp()
 204 ///     .min_final_cltv_expiry_delta(144)
 205 ///     .build_signed(|hash| {
 206 ///             Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
 207 ///     })
 208 ///     .unwrap();
 209 ///
 210 /// assert!(invoice.to_string().starts_with("lnbc1"));
 211 /// # }
 212 /// ```
 213 ///
 214 /// # Type parameters
 215 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
 216 /// given field:
 217 ///  * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
 218 ///  * `H`: exactly one [`TaggedField::PaymentHash`]
 219 ///  * `T`: the timestamp is set
 220 ///
 221 /// (C-not exported) as we likely need to manually select one set of boolean type parameters.
 222 #[derive(Eq, PartialEq, Debug, Clone)]
 223 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> {
 224         currency: Currency,
 225         amount: Option<u64>,
 226         si_prefix: Option<SiPrefix>,
 227         timestamp: Option<PositiveTimestamp>,
 228         tagged_fields: Vec<TaggedField>,
 229         error: Option<CreationError>,
 230
 231         phantom_d: core::marker::PhantomData<D>,
 232         phantom_h: core::marker::PhantomData<H>,
 233         phantom_t: core::marker::PhantomData<T>,
 234         phantom_c: core::marker::PhantomData<C>,
 235         phantom_s: core::marker::PhantomData<S>,
 236 }
 237
 238 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
 239 ///
 240 /// There are three ways to construct an `Invoice`:
 241 ///  1. using [`InvoiceBuilder`]
 242 ///  2. using [`Invoice::from_signed`]
 243 ///  3. using `str::parse::<Invoice>(&str)` (see [`Invoice::from_str`])
 244 ///
 245 /// [`Invoice::from_str`]: crate::Invoice#impl-FromStr
 246 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 247 pub struct Invoice {
 248         signed_invoice: SignedRawInvoice,
 249 }
 250
 251 /// Represents the description of an invoice which has to be either a directly included string or
 252 /// a hash of a description provided out of band.
 253 ///
 254 /// (C-not exported) As we don't have a good way to map the reference lifetimes making this
 255 /// practically impossible to use safely in languages like C.
 256 #[derive(Eq, PartialEq, Debug, Clone)]
 257 pub enum InvoiceDescription<'f> {
 258         /// Reference to the directly supplied description in the invoice
 259         Direct(&'f Description),
 260
 261         /// Reference to the description's hash included in the invoice
 262         Hash(&'f Sha256),
 263 }
 264
 265 /// Represents a signed [`RawInvoice`] with cached hash. The signature is not checked and may be
 266 /// invalid.
 267 ///
 268 /// # Invariants
 269 /// The hash has to be either from the deserialized invoice or from the serialized [`RawInvoice`].
 270 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 271 pub struct SignedRawInvoice {
 272         /// The rawInvoice that the signature belongs to
 273         raw_invoice: RawInvoice,
 274
 275         /// Hash of the [`RawInvoice`] that will be used to check the signature.
 276         ///
 277         /// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form,
 278         /// since it's not guaranteed that encoding it again will lead to the same result since integers
 279         /// could have been encoded with leading zeroes etc.
 280         /// * if the `SignedRawInvoice` was constructed manually the hash will be the calculated hash
 281         /// from the [`RawInvoice`]
 282         hash: [u8; 32],
 283
 284         /// signature of the payment request
 285         signature: InvoiceSignature,
 286 }
 287
 288 /// Represents an syntactically correct [`Invoice`] for a payment on the lightning network,
 289 /// but without the signature information.
 290 /// Decoding and encoding should not lead to information loss but may lead to different hashes.
 291 ///
 292 /// For methods without docs see the corresponding methods in [`Invoice`].
 293 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 294 pub struct RawInvoice {
 295         /// human readable part
 296         pub hrp: RawHrp,
 297
 298         /// data part
 299         pub data: RawDataPart,
 300 }
 301
 302 /// Data of the [`RawInvoice`] that is encoded in the human readable part.
 303 ///
 304 /// (C-not exported) As we don't yet support `Option<Enum>`
 305 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 306 pub struct RawHrp {
 307         /// The currency deferred from the 3rd and 4th character of the bech32 transaction
 308         pub currency: Currency,
 309
 310         /// The amount that, multiplied by the SI prefix, has to be payed
 311         pub raw_amount: Option<u64>,
 312
 313         /// SI prefix that gets multiplied with the `raw_amount`
 314         pub si_prefix: Option<SiPrefix>,
 315 }
 316
 317 /// Data of the [`RawInvoice`] that is encoded in the data part
 318 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 319 pub struct RawDataPart {
 320         /// generation time of the invoice
 321         pub timestamp: PositiveTimestamp,
 322
 323         /// tagged fields of the payment request
 324         pub tagged_fields: Vec<RawTaggedField>,
 325 }
 326
 327 /// A timestamp that refers to a date after 1 January 1970.
 328 ///
 329 /// # Invariants
 330 ///
 331 /// The Unix timestamp representing the stored time has to be positive and no greater than
 332 /// [`MAX_TIMESTAMP`].
 333 #[derive(Eq, PartialEq, Debug, Clone, Hash)]
 334 pub struct PositiveTimestamp(Duration);
 335
 336 /// SI prefixes for the human readable part
 337 #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash)]
 338 pub enum SiPrefix {
 339         /// 10^-3
 340         Milli,
 341         /// 10^-6
 342         Micro,
 343         /// 10^-9
 344         Nano,
 345         /// 10^-12
 346         Pico,
 347 }
 348
 349 impl SiPrefix {
 350         /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
 351         /// This is effectively 10^12 * the prefix multiplier
 352         pub fn multiplier(&self) -> u64 {
 353                 match *self {
 354                         SiPrefix::Milli => 1_000_000_000,
 355                         SiPrefix::Micro => 1_000_000,
 356                         SiPrefix::Nano => 1_000,
 357                         SiPrefix::Pico => 1,
 358                 }
 359         }
 360
 361         /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
 362         /// multiplier.
 363         ///
 364         /// (C-not exported) As we don't yet support a slice of enums, and also because this function
 365         /// isn't the most critical to expose.
 366         pub fn values_desc() -> &'static [SiPrefix] {
 367                 use crate::SiPrefix::*;
 368                 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
 369                 &VALUES
 370         }
 371 }
 372
 373 /// Enum representing the crypto currencies (or networks) supported by this library
 374 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 375 pub enum Currency {
 376         /// Bitcoin mainnet
 377         Bitcoin,
 378
 379         /// Bitcoin testnet
 380         BitcoinTestnet,
 381
 382         /// Bitcoin regtest
 383         Regtest,
 384
 385         /// Bitcoin simnet
 386         Simnet,
 387
 388         /// Bitcoin signet
 389         Signet,
 390 }
 391
 392 /// Tagged field which may have an unknown tag
 393 ///
 394 /// (C-not exported) as we don't currently support TaggedField
 395 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 396 pub enum RawTaggedField {
 397         /// Parsed tagged field with known tag
 398         KnownSemantics(TaggedField),
 399         /// tagged field which was not parsed due to an unknown tag or undefined field semantics
 400         UnknownSemantics(Vec<u5>),
 401 }
 402
 403 /// Tagged field with known tag
 404 ///
 405 /// For descriptions of the enum values please refer to the enclosed type's docs.
 406 ///
 407 /// (C-not exported) As we don't yet support enum variants with the same name the struct contained
 408 /// in the variant.
 409 #[allow(missing_docs)]
 410 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 411 pub enum TaggedField {
 412         PaymentHash(Sha256),
 413         Description(Description),
 414         PayeePubKey(PayeePubKey),
 415         DescriptionHash(Sha256),
 416         ExpiryTime(ExpiryTime),
 417         MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
 418         Fallback(Fallback),
 419         PrivateRoute(PrivateRoute),
 420         PaymentSecret(PaymentSecret),
 421         Features(InvoiceFeatures),
 422 }
 423
 424 /// SHA-256 hash
 425 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 426 pub struct Sha256(/// (C-not exported) as the native hash types are not currently mapped
 427         pub sha256::Hash);
 428
 429 /// Description string
 430 ///
 431 /// # Invariants
 432 /// The description can be at most 639 __bytes__ long
 433 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 434 pub struct Description(String);
 435
 436 /// Payee public key
 437 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 438 pub struct PayeePubKey(pub PublicKey);
 439
 440 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
 441 /// expires
 442 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 443 pub struct ExpiryTime(Duration);
 444
 445 /// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
 446 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 447 pub struct MinFinalCltvExpiryDelta(pub u64);
 448
 449 // TODO: better types instead onf byte arrays
 450 /// Fallback address in case no LN payment is possible
 451 #[allow(missing_docs)]
 452 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 453 pub enum Fallback {
 454         SegWitProgram {
 455                 version: u5,
 456                 program: Vec<u8>,
 457         },
 458         PubKeyHash([u8; 20]),
 459         ScriptHash([u8; 20]),
 460 }
 461
 462 /// Recoverable signature
 463 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 464 pub struct InvoiceSignature(pub RecoverableSignature);
 465
 466 /// Private routing information
 467 ///
 468 /// # Invariants
 469 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
 470 ///
 471 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 472 pub struct PrivateRoute(RouteHint);
 473
 474 /// Tag constants as specified in BOLT11
 475 #[allow(missing_docs)]
 476 pub mod constants {
 477         pub const TAG_PAYMENT_HASH: u8 = 1;
 478         pub const TAG_DESCRIPTION: u8 = 13;
 479         pub const TAG_PAYEE_PUB_KEY: u8 = 19;
 480         pub const TAG_DESCRIPTION_HASH: u8 = 23;
 481         pub const TAG_EXPIRY_TIME: u8 = 6;
 482         pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
 483         pub const TAG_FALLBACK: u8 = 9;
 484         pub const TAG_PRIVATE_ROUTE: u8 = 3;
 485         pub const TAG_PAYMENT_SECRET: u8 = 16;
 486         pub const TAG_FEATURES: u8 = 5;
 487 }
 488
 489 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False> {
 490         /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
 491         /// `InvoiceBuilder::build(self)` becomes available.
 492         pub fn new(currrency: Currency) -> Self {
 493                 InvoiceBuilder {
 494                         currency: currrency,
 495                         amount: None,
 496                         si_prefix: None,
 497                         timestamp: None,
 498                         tagged_fields: Vec::new(),
 499                         error: None,
 500
 501                         phantom_d: core::marker::PhantomData,
 502                         phantom_h: core::marker::PhantomData,
 503                         phantom_t: core::marker::PhantomData,
 504                         phantom_c: core::marker::PhantomData,
 505                         phantom_s: core::marker::PhantomData,
 506                 }
 507         }
 508 }
 509
 510 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S> {
 511         /// Helper function to set the completeness flags.
 512         fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN> {
 513                 InvoiceBuilder::<DN, HN, TN, CN, SN> {
 514                         currency: self.currency,
 515                         amount: self.amount,
 516                         si_prefix: self.si_prefix,
 517                         timestamp: self.timestamp,
 518                         tagged_fields: self.tagged_fields,
 519                         error: self.error,
 520
 521                         phantom_d: core::marker::PhantomData,
 522                         phantom_h: core::marker::PhantomData,
 523                         phantom_t: core::marker::PhantomData,
 524                         phantom_c: core::marker::PhantomData,
 525                         phantom_s: core::marker::PhantomData,
 526                 }
 527         }
 528
 529         /// Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.
 530         pub fn amount_milli_satoshis(mut self, amount_msat: u64) -> Self {
 531                 let amount = amount_msat * 10; // Invoices are denominated in "pico BTC"
 532                 let biggest_possible_si_prefix = SiPrefix::values_desc()
 533                         .iter()
 534                         .find(|prefix| amount % prefix.multiplier() == 0)
 535                         .expect("Pico should always match");
 536                 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
 537                 self.si_prefix = Some(*biggest_possible_si_prefix);
 538                 self
 539         }
 540
 541         /// Sets the payee's public key.
 542         pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
 543                 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
 544                 self
 545         }
 546
 547         /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
 548         /// invoices).
 549         pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
 550                 self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
 551                 self
 552         }
 553
 554         /// Adds a fallback address.
 555         pub fn fallback(mut self, fallback: Fallback) -> Self {
 556                 self.tagged_fields.push(TaggedField::Fallback(fallback));
 557                 self
 558         }
 559
 560         /// Adds a private route.
 561         pub fn private_route(mut self, hint: RouteHint) -> Self {
 562                 match PrivateRoute::new(hint) {
 563                         Ok(r) => self.tagged_fields.push(TaggedField::PrivateRoute(r)),
 564                         Err(e) => self.error = Some(e),
 565                 }
 566                 self
 567         }
 568 }
 569
 570 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S> {
 571         /// Builds a [`RawInvoice`] if no [`CreationError`] occurred while construction any of the
 572         /// fields.
 573         pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
 574
 575                 // If an error occurred at any time before, return it now
 576                 if let Some(e) = self.error {
 577                         return Err(e);
 578                 }
 579
 580                 let hrp = RawHrp {
 581                         currency: self.currency,
 582                         raw_amount: self.amount,
 583                         si_prefix: self.si_prefix,
 584                 };
 585
 586                 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
 587
 588                 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
 589                         RawTaggedField::KnownSemantics(tf)
 590                 }).collect::<Vec<_>>();
 591
 592                 let data = RawDataPart {
 593                         timestamp,
 594                         tagged_fields,
 595                 };
 596
 597                 Ok(RawInvoice {
 598                         hrp,
 599                         data,
 600                 })
 601         }
 602 }
 603
 604 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S> {
 605         /// Set the description. This function is only available if no description (hash) was set.
 606         pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S> {
 607                 match Description::new(description) {
 608                         Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
 609                         Err(e) => self.error = Some(e),
 610                 }
 611                 self.set_flags()
 612         }
 613
 614         /// Set the description hash. This function is only available if no description (hash) was set.
 615         pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S> {
 616                 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
 617                 self.set_flags()
 618         }
 619 }
 620
 621 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
 622         /// Set the payment hash. This function is only available if no payment hash was set.
 623         pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S> {
 624                 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
 625                 self.set_flags()
 626         }
 627 }
 628
 629 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
 630         /// Sets the timestamp to a specific [`SystemTime`].
 631         #[cfg(feature = "std")]
 632         pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
 633                 match PositiveTimestamp::from_system_time(time) {
 634                         Ok(t) => self.timestamp = Some(t),
 635                         Err(e) => self.error = Some(e),
 636                 }
 637
 638                 self.set_flags()
 639         }
 640
 641         /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
 642         /// is not representable in BOLT 11 invoices).
 643         pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S> {
 644                 match PositiveTimestamp::from_duration_since_epoch(time) {
 645                         Ok(t) => self.timestamp = Some(t),
 646                         Err(e) => self.error = Some(e),
 647                 }
 648
 649                 self.set_flags()
 650         }
 651
 652         /// Sets the timestamp to the current system time.
 653         #[cfg(feature = "std")]
 654         pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
 655                 let now = PositiveTimestamp::from_system_time(SystemTime::now());
 656                 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
 657                 self.set_flags()
 658         }
 659 }
 660
 661 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
 662         /// Sets `min_final_cltv_expiry_delta`.
 663         pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
 664                 self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
 665                 self.set_flags()
 666         }
 667 }
 668
 669 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False> {
 670         /// Sets the payment secret and relevant features.
 671         pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True> {
 672                 let mut features = InvoiceFeatures::empty();
 673                 features.set_variable_length_onion_required();
 674                 features.set_payment_secret_required();
 675                 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
 676                 self.tagged_fields.push(TaggedField::Features(features));
 677                 self.set_flags()
 678         }
 679 }
 680
 681 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True> {
 682         /// Sets the `basic_mpp` feature as optional.
 683         pub fn basic_mpp(mut self) -> Self {
 684                 for field in self.tagged_fields.iter_mut() {
 685                         if let TaggedField::Features(f) = field {
 686                                 f.set_basic_mpp_optional();
 687                         }
 688                 }
 689                 self
 690         }
 691 }
 692
 693 impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
 694         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
 695         /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
 696         /// the included payee public key.
 697         pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
 698                 where F: FnOnce(&Message) -> RecoverableSignature
 699         {
 700                 let invoice = self.try_build_signed::<_, ()>(|hash| {
 701                         Ok(sign_function(hash))
 702                 });
 703
 704                 match invoice {
 705                         Ok(i) => Ok(i),
 706                         Err(SignOrCreationError::CreationError(e)) => Err(e),
 707                         Err(SignOrCreationError::SignError(())) => unreachable!(),
 708                 }
 709         }
 710
 711         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
 712         /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
 713         /// if applicable also for the included payee public key.
 714         pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Invoice, SignOrCreationError<E>>
 715                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 716         {
 717                 let raw = match self.build_raw() {
 718                         Ok(r) => r,
 719                         Err(e) => return Err(SignOrCreationError::CreationError(e)),
 720                 };
 721
 722                 let signed = match raw.sign(sign_function) {
 723                         Ok(s) => s,
 724                         Err(e) => return Err(SignOrCreationError::SignError(e)),
 725                 };
 726
 727                 let invoice = Invoice {
 728                         signed_invoice: signed,
 729                 };
 730
 731                 invoice.check_field_counts().expect("should be ensured by type signature of builder");
 732                 invoice.check_feature_bits().expect("should be ensured by type signature of builder");
 733                 invoice.check_amount().expect("should be ensured by type signature of builder");
 734
 735                 Ok(invoice)
 736         }
 737 }
 738
 739
 740 impl SignedRawInvoice {
 741         /// Disassembles the `SignedRawInvoice` into its three parts:
 742         ///  1. raw invoice
 743         ///  2. hash of the raw invoice
 744         ///  3. signature
 745         pub fn into_parts(self) -> (RawInvoice, [u8; 32], InvoiceSignature) {
 746                 (self.raw_invoice, self.hash, self.signature)
 747         }
 748
 749         /// The [`RawInvoice`] which was signed.
 750         pub fn raw_invoice(&self) -> &RawInvoice {
 751                 &self.raw_invoice
 752         }
 753
 754         /// The hash of the [`RawInvoice`] that was signed.
 755         pub fn signable_hash(&self) -> &[u8; 32] {
 756                 &self.hash
 757         }
 758
 759         /// Signature for the invoice.
 760         pub fn signature(&self) -> &InvoiceSignature {
 761                 &self.signature
 762         }
 763
 764         /// Recovers the public key used for signing the invoice from the recoverable signature.
 765         pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
 766                 let hash = Message::from_slice(&self.hash[..])
 767                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 768
 769                 Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
 770                         &hash,
 771                         &self.signature
 772                 )?))
 773         }
 774
 775         /// Checks if the signature is valid for the included payee public key or if none exists if it's
 776         /// valid for the recovered signature (which should always be true?).
 777         pub fn check_signature(&self) -> bool {
 778                 let included_pub_key = self.raw_invoice.payee_pub_key();
 779
 780                 let mut recovered_pub_key = Option::None;
 781                 if recovered_pub_key.is_none() {
 782                         let recovered = match self.recover_payee_pub_key() {
 783                                 Ok(pk) => pk,
 784                                 Err(_) => return false,
 785                         };
 786                         recovered_pub_key = Some(recovered);
 787                 }
 788
 789                 let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
 790                         .expect("One is always present");
 791
 792                 let hash = Message::from_slice(&self.hash[..])
 793                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 794
 795                 let secp_context = Secp256k1::new();
 796                 let verification_result = secp_context.verify_ecdsa(
 797                         &hash,
 798                         &self.signature.to_standard(),
 799                         pub_key
 800                 );
 801
 802                 match verification_result {
 803                         Ok(()) => true,
 804                         Err(_) => false,
 805                 }
 806         }
 807 }
 808
 809 /// Finds the first element of an enum stream of a given variant and extracts one member of the
 810 /// variant. If no element was found `None` gets returned.
 811 ///
 812 /// The following example would extract the first B.
 813 ///
 814 /// ```ignore
 815 /// enum Enum {
 816 ///     A(u8),
 817 ///     B(u16)
 818 /// }
 819 ///
 820 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 821 ///
 822 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
 823 /// ```
 824 macro_rules! find_extract {
 825         ($iter:expr, $enm:pat, $enm_var:ident) => {
 826                 find_all_extract!($iter, $enm, $enm_var).next()
 827         };
 828 }
 829
 830 /// Finds the all elements of an enum stream of a given variant and extracts one member of the
 831 /// variant through an iterator.
 832 ///
 833 /// The following example would extract all A.
 834 ///
 835 /// ```ignore
 836 /// enum Enum {
 837 ///     A(u8),
 838 ///     B(u16)
 839 /// }
 840 ///
 841 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 842 ///
 843 /// assert_eq!(
 844 ///     find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
 845 ///     vec![1u8, 2u8, 4u8]
 846 /// );
 847 /// ```
 848 macro_rules! find_all_extract {
 849         ($iter:expr, $enm:pat, $enm_var:ident) => {
 850                 $iter.filter_map(|tf| match *tf {
 851                         $enm => Some($enm_var),
 852                         _ => None,
 853                 })
 854         };
 855 }
 856
 857 #[allow(missing_docs)]
 858 impl RawInvoice {
 859         /// Hash the HRP as bytes and signatureless data part.
 860         fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
 861                 let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
 862                 let mut hash: [u8; 32] = Default::default();
 863                 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
 864                 hash
 865         }
 866
 867         /// Calculate the hash of the encoded `RawInvoice` which should be signed.
 868         pub fn signable_hash(&self) -> [u8; 32] {
 869                 use bech32::ToBase32;
 870
 871                 RawInvoice::hash_from_parts(
 872                         self.hrp.to_string().as_bytes(),
 873                         &self.data.to_base32()
 874                 )
 875         }
 876
 877         /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
 878         /// type `E`. Since the signature of a [`SignedRawInvoice`] is not required to be valid there
 879         /// are no constraints regarding the validity of the produced signature.
 880         ///
 881         /// (C-not exported) As we don't currently support passing function pointers into methods
 882         /// explicitly.
 883         pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
 884                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 885         {
 886                 let raw_hash = self.signable_hash();
 887                 let hash = Message::from_slice(&raw_hash[..])
 888                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 889                 let signature = sign_method(&hash)?;
 890
 891                 Ok(SignedRawInvoice {
 892                         raw_invoice: self,
 893                         hash: raw_hash,
 894                         signature: InvoiceSignature(signature),
 895                 })
 896         }
 897
 898         /// Returns an iterator over all tagged fields with known semantics.
 899         ///
 900         /// (C-not exported) As there is not yet a manual mapping for a FilterMap
 901         pub fn known_tagged_fields(&self)
 902                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
 903         {
 904                 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
 905                 // function's type signature.
 906                 // TODO: refactor once impl Trait is available
 907                 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
 908                         match *raw {
 909                                 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
 910                                 _ => None,
 911                         }
 912                 }
 913
 914                 self.data.tagged_fields.iter().filter_map(match_raw )
 915         }
 916
 917         pub fn payment_hash(&self) -> Option<&Sha256> {
 918                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
 919         }
 920
 921         pub fn description(&self) -> Option<&Description> {
 922                 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
 923         }
 924
 925         pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
 926                 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
 927         }
 928
 929         pub fn description_hash(&self) -> Option<&Sha256> {
 930                 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
 931         }
 932
 933         pub fn expiry_time(&self) -> Option<&ExpiryTime> {
 934                 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
 935         }
 936
 937         pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
 938                 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
 939         }
 940
 941         pub fn payment_secret(&self) -> Option<&PaymentSecret> {
 942                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
 943         }
 944
 945         pub fn features(&self) -> Option<&InvoiceFeatures> {
 946                 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
 947         }
 948
 949         /// (C-not exported) as we don't support Vec<&NonOpaqueType>
 950         pub fn fallbacks(&self) -> Vec<&Fallback> {
 951                 find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
 952         }
 953
 954         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
 955                 find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
 956         }
 957
 958         pub fn amount_pico_btc(&self) -> Option<u64> {
 959                 self.hrp.raw_amount.map(|v| {
 960                         v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
 961                 })
 962         }
 963
 964         pub fn currency(&self) -> Currency {
 965                 self.hrp.currency.clone()
 966         }
 967 }
 968
 969 impl PositiveTimestamp {
 970         /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
 971         ///
 972         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
 973         pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
 974                 if unix_seconds <= MAX_TIMESTAMP {
 975                         Ok(Self(Duration::from_secs(unix_seconds)))
 976                 } else {
 977                         Err(CreationError::TimestampOutOfBounds)
 978                 }
 979         }
 980
 981         /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
 982         /// the range `0..=MAX_TIMESTAMP`.
 983         ///
 984         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
 985         ///
 986         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
 987         #[cfg(feature = "std")]
 988         pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
 989                 time.duration_since(SystemTime::UNIX_EPOCH)
 990                         .map(Self::from_duration_since_epoch)
 991                         .unwrap_or(Err(CreationError::TimestampOutOfBounds))
 992         }
 993
 994         /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
 995         /// `0..=MAX_TIMESTAMP`.
 996         ///
 997         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
 998         ///
 999         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1000         pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
1001                 Self::from_unix_timestamp(duration.as_secs())
1002         }
1003
1004         /// Returns the Unix timestamp representing the stored time
1005         pub fn as_unix_timestamp(&self) -> u64 {
1006                 self.0.as_secs()
1007         }
1008
1009         /// Returns the duration of the stored time since the Unix epoch
1010         pub fn as_duration_since_epoch(&self) -> Duration {
1011                 self.0
1012         }
1013
1014         /// Returns the [`SystemTime`] representing the stored time
1015         #[cfg(feature = "std")]
1016         pub fn as_time(&self) -> SystemTime {
1017                 SystemTime::UNIX_EPOCH + self.0
1018         }
1019 }
1020
1021 #[cfg(feature = "std")]
1022 impl From<PositiveTimestamp> for SystemTime {
1023         fn from(val: PositiveTimestamp) -> Self {
1024                 SystemTime::UNIX_EPOCH + val.0
1025         }
1026 }
1027
1028 impl Invoice {
1029         /// The hash of the [`RawInvoice`] that was signed.
1030         pub fn signable_hash(&self) -> [u8; 32] {
1031                 self.signed_invoice.hash
1032         }
1033
1034         /// Transform the `Invoice` into it's unchecked version
1035         pub fn into_signed_raw(self) -> SignedRawInvoice {
1036                 self.signed_invoice
1037         }
1038
1039         /// Check that all mandatory fields are present
1040         fn check_field_counts(&self) -> Result<(), SemanticError> {
1041                 // "A writer MUST include exactly one p field […]."
1042                 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1043                         TaggedField::PaymentHash(_) => true,
1044                         _ => false,
1045                 }).count();
1046                 if payment_hash_cnt < 1 {
1047                         return Err(SemanticError::NoPaymentHash);
1048                 } else if payment_hash_cnt > 1 {
1049                         return Err(SemanticError::MultiplePaymentHashes);
1050                 }
1051
1052                 // "A writer MUST include either exactly one d or exactly one h field."
1053                 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1054                         TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1055                         _ => false,
1056                 }).count();
1057                 if  description_cnt < 1 {
1058                         return Err(SemanticError::NoDescription);
1059                 } else if description_cnt > 1 {
1060                         return  Err(SemanticError::MultipleDescriptions);
1061                 }
1062
1063                 self.check_payment_secret()?;
1064
1065                 Ok(())
1066         }
1067
1068         /// Checks that there is exactly one payment secret field
1069         fn check_payment_secret(&self) -> Result<(), SemanticError> {
1070                 // "A writer MUST include exactly one `s` field."
1071                 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1072                         TaggedField::PaymentSecret(_) => true,
1073                         _ => false,
1074                 }).count();
1075                 if payment_secret_count < 1 {
1076                         return Err(SemanticError::NoPaymentSecret);
1077                 } else if payment_secret_count > 1 {
1078                         return Err(SemanticError::MultiplePaymentSecrets);
1079                 }
1080
1081                 Ok(())
1082         }
1083
1084         /// Check that amount is a whole number of millisatoshis
1085         fn check_amount(&self) -> Result<(), SemanticError> {
1086                 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1087                         if amount_pico_btc % 10 != 0 {
1088                                 return Err(SemanticError::ImpreciseAmount);
1089                         }
1090                 }
1091                 Ok(())
1092         }
1093
1094         /// Check that feature bits are set as required
1095         fn check_feature_bits(&self) -> Result<(), SemanticError> {
1096                 self.check_payment_secret()?;
1097
1098                 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1099                 // (this requirement has been since removed, and we now require the payment secret
1100                 // feature bit always).
1101                 let features = self.tagged_fields().find(|&tf| match *tf {
1102                         TaggedField::Features(_) => true,
1103                         _ => false,
1104                 });
1105                 match features {
1106                         None => Err(SemanticError::InvalidFeatures),
1107                         Some(TaggedField::Features(features)) => {
1108                                 if features.requires_unknown_bits() {
1109                                         Err(SemanticError::InvalidFeatures)
1110                                 } else if !features.supports_payment_secret() {
1111                                         Err(SemanticError::InvalidFeatures)
1112                                 } else {
1113                                         Ok(())
1114                                 }
1115                         },
1116                         Some(_) => unreachable!(),
1117                 }
1118         }
1119
1120         /// Check that the invoice is signed correctly and that key recovery works
1121         pub fn check_signature(&self) -> Result<(), SemanticError> {
1122                 match self.signed_invoice.recover_payee_pub_key() {
1123                         Err(secp256k1::Error::InvalidRecoveryId) =>
1124                                 return Err(SemanticError::InvalidRecoveryId),
1125                         Err(secp256k1::Error::InvalidSignature) =>
1126                                 return Err(SemanticError::InvalidSignature),
1127                         Err(e) => panic!("no other error may occur, got {:?}", e),
1128                         Ok(_) => {},
1129                 }
1130
1131                 if !self.signed_invoice.check_signature() {
1132                         return Err(SemanticError::InvalidSignature);
1133                 }
1134
1135                 Ok(())
1136         }
1137
1138         /// Constructs an `Invoice` from a [`SignedRawInvoice`] by checking all its invariants.
1139         /// ```
1140         /// use lightning_invoice::*;
1141         ///
1142         /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1143         /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1144         /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1145         /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1146         /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1147         /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1148         /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1149         /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1150         /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1151         /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1152         /// j5r6drg6k6zcqj0fcwg";
1153         ///
1154         /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
1155         ///
1156         /// assert!(Invoice::from_signed(signed).is_ok());
1157         /// ```
1158         pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
1159                 let invoice = Invoice {
1160                         signed_invoice,
1161                 };
1162                 invoice.check_field_counts()?;
1163                 invoice.check_feature_bits()?;
1164                 invoice.check_signature()?;
1165                 invoice.check_amount()?;
1166
1167                 Ok(invoice)
1168         }
1169
1170         /// Returns the `Invoice`'s timestamp (should equal its creation time)
1171         #[cfg(feature = "std")]
1172         pub fn timestamp(&self) -> SystemTime {
1173                 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1174         }
1175
1176         /// Returns the `Invoice`'s timestamp as a duration since the Unix epoch
1177         pub fn duration_since_epoch(&self) -> Duration {
1178                 self.signed_invoice.raw_invoice().data.timestamp.0
1179         }
1180
1181         /// Returns an iterator over all tagged fields of this Invoice.
1182         ///
1183         /// (C-not exported) As there is not yet a manual mapping for a FilterMap
1184         pub fn tagged_fields(&self)
1185                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1186                 self.signed_invoice.raw_invoice().known_tagged_fields()
1187         }
1188
1189         /// Returns the hash to which we will receive the preimage on completion of the payment
1190         pub fn payment_hash(&self) -> &sha256::Hash {
1191                 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1192         }
1193
1194         /// Return the description or a hash of it for longer ones
1195         ///
1196         /// (C-not exported) because we don't yet export InvoiceDescription
1197         pub fn description(&self) -> InvoiceDescription {
1198                 if let Some(direct) = self.signed_invoice.description() {
1199                         return InvoiceDescription::Direct(direct);
1200                 } else if let Some(hash) = self.signed_invoice.description_hash() {
1201                         return InvoiceDescription::Hash(hash);
1202                 }
1203                 unreachable!("ensured by constructor");
1204         }
1205
1206         /// Get the payee's public key if one was included in the invoice
1207         pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1208                 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1209         }
1210
1211         /// Get the payment secret if one was included in the invoice
1212         pub fn payment_secret(&self) -> &PaymentSecret {
1213                 self.signed_invoice.payment_secret().expect("was checked by constructor")
1214         }
1215
1216         /// Get the invoice features if they were included in the invoice
1217         pub fn features(&self) -> Option<&InvoiceFeatures> {
1218                 self.signed_invoice.features()
1219         }
1220
1221         /// Recover the payee's public key (only to be used if none was included in the invoice)
1222         pub fn recover_payee_pub_key(&self) -> PublicKey {
1223                 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1224         }
1225
1226         /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1227         pub fn expiry_time(&self) -> Duration {
1228                 self.signed_invoice.expiry_time()
1229                         .map(|x| x.0)
1230                         .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1231         }
1232
1233         /// Returns whether the invoice has expired.
1234         #[cfg(feature = "std")]
1235         pub fn is_expired(&self) -> bool {
1236                 Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
1237         }
1238
1239         /// Returns whether the expiry time from the given epoch has passed.
1240         #[cfg(feature = "std")]
1241         pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
1242                 match epoch.elapsed() {
1243                         Ok(elapsed) => elapsed > expiry_time,
1244                         Err(_) => false,
1245                 }
1246         }
1247
1248         /// Returns whether the expiry time would pass at the given point in time.
1249         /// `at_time` is the timestamp as a duration since the Unix epoch.
1250         pub fn would_expire(&self, at_time: Duration) -> bool {
1251                 self.duration_since_epoch()
1252                         .checked_add(self.expiry_time())
1253                         .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
1254         }
1255
1256         /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
1257         /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
1258         pub fn min_final_cltv_expiry_delta(&self) -> u64 {
1259                 self.signed_invoice.min_final_cltv_expiry_delta()
1260                         .map(|x| x.0)
1261                         .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
1262         }
1263
1264         /// Returns a list of all fallback addresses
1265         ///
1266         /// (C-not exported) as we don't support Vec<&NonOpaqueType>
1267         pub fn fallbacks(&self) -> Vec<&Fallback> {
1268                 self.signed_invoice.fallbacks()
1269         }
1270
1271         /// Returns a list of all routes included in the invoice
1272         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1273                 self.signed_invoice.private_routes()
1274         }
1275
1276         /// Returns a list of all routes included in the invoice as the underlying hints
1277         pub fn route_hints(&self) -> Vec<RouteHint> {
1278                 find_all_extract!(
1279                         self.signed_invoice.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x
1280                 ).map(|route| (**route).clone()).collect()
1281         }
1282
1283         /// Returns the currency for which the invoice was issued
1284         pub fn currency(&self) -> Currency {
1285                 self.signed_invoice.currency()
1286         }
1287
1288         /// Returns the amount if specified in the invoice as millisatoshis.
1289         pub fn amount_milli_satoshis(&self) -> Option<u64> {
1290                 self.signed_invoice.amount_pico_btc().map(|v| v / 10)
1291         }
1292
1293         /// Returns the amount if specified in the invoice as pico BTC.
1294         fn amount_pico_btc(&self) -> Option<u64> {
1295                 self.signed_invoice.amount_pico_btc()
1296         }
1297 }
1298
1299 impl From<TaggedField> for RawTaggedField {
1300         fn from(tf: TaggedField) -> Self {
1301                 RawTaggedField::KnownSemantics(tf)
1302         }
1303 }
1304
1305 impl TaggedField {
1306         /// Numeric representation of the field's tag
1307         pub fn tag(&self) -> u5 {
1308                 let tag = match *self {
1309                         TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1310                         TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1311                         TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1312                         TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1313                         TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1314                         TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
1315                         TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1316                         TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
1317                         TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1318                         TaggedField::Features(_) => constants::TAG_FEATURES,
1319                 };
1320
1321                 u5::try_from_u8(tag).expect("all tags defined are <32")
1322         }
1323 }
1324
1325 impl Description {
1326
1327         /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1328         /// returns [`CreationError::DescriptionTooLong`] otherwise
1329         ///
1330         /// Please note that single characters may use more than one byte due to UTF8 encoding.
1331         pub fn new(description: String) -> Result<Description, CreationError> {
1332                 if description.len() > 639 {
1333                         Err(CreationError::DescriptionTooLong)
1334                 } else {
1335                         Ok(Description(description))
1336                 }
1337         }
1338
1339         /// Returns the underlying description [`String`]
1340         pub fn into_inner(self) -> String {
1341                 self.0
1342         }
1343 }
1344
1345 impl From<Description> for String {
1346         fn from(val: Description) -> Self {
1347                 val.into_inner()
1348         }
1349 }
1350
1351 impl Deref for Description {
1352         type Target = str;
1353
1354         fn deref(&self) -> &str {
1355                 &self.0
1356         }
1357 }
1358
1359 impl From<PublicKey> for PayeePubKey {
1360         fn from(pk: PublicKey) -> Self {
1361                 PayeePubKey(pk)
1362         }
1363 }
1364
1365 impl Deref for PayeePubKey {
1366         type Target = PublicKey;
1367
1368         fn deref(&self) -> &PublicKey {
1369                 &self.0
1370         }
1371 }
1372
1373 impl ExpiryTime {
1374         /// Construct an `ExpiryTime` from seconds.
1375         pub fn from_seconds(seconds: u64) -> ExpiryTime {
1376                 ExpiryTime(Duration::from_secs(seconds))
1377         }
1378
1379         /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
1380         pub fn from_duration(duration: Duration) -> ExpiryTime {
1381                 Self::from_seconds(duration.as_secs())
1382         }
1383
1384         /// Returns the expiry time in seconds
1385         pub fn as_seconds(&self) -> u64 {
1386                 self.0.as_secs()
1387         }
1388
1389         /// Returns a reference to the underlying [`Duration`] (=expiry time)
1390         pub fn as_duration(&self) -> &Duration {
1391                 &self.0
1392         }
1393 }
1394
1395 impl PrivateRoute {
1396         /// Creates a new (partial) route from a list of hops
1397         pub fn new(hops: RouteHint) -> Result<PrivateRoute, CreationError> {
1398                 if hops.0.len() <= 12 {
1399                         Ok(PrivateRoute(hops))
1400                 } else {
1401                         Err(CreationError::RouteTooLong)
1402                 }
1403         }
1404
1405         /// Returns the underlying list of hops
1406         pub fn into_inner(self) -> RouteHint {
1407                 self.0
1408         }
1409 }
1410
1411 impl From<PrivateRoute> for RouteHint {
1412         fn from(val: PrivateRoute) -> Self {
1413                 val.into_inner()
1414         }
1415 }
1416
1417 impl Deref for PrivateRoute {
1418         type Target = RouteHint;
1419
1420         fn deref(&self) -> &RouteHint {
1421                 &self.0
1422         }
1423 }
1424
1425 impl Deref for InvoiceSignature {
1426         type Target = RecoverableSignature;
1427
1428         fn deref(&self) -> &RecoverableSignature {
1429                 &self.0
1430         }
1431 }
1432
1433 impl Deref for SignedRawInvoice {
1434         type Target = RawInvoice;
1435
1436         fn deref(&self) -> &RawInvoice {
1437                 &self.raw_invoice
1438         }
1439 }
1440
1441 /// Errors that may occur when constructing a new [`RawInvoice`] or [`Invoice`]
1442 #[derive(Eq, PartialEq, Debug, Clone)]
1443 pub enum CreationError {
1444         /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
1445         DescriptionTooLong,
1446
1447         /// The specified route has too many hops and can't be encoded
1448         RouteTooLong,
1449
1450         /// The Unix timestamp of the supplied date is less than zero or greater than 35-bits
1451         TimestampOutOfBounds,
1452
1453         /// The supplied millisatoshi amount was greater than the total bitcoin supply.
1454         InvalidAmount,
1455
1456         /// Route hints were required for this invoice and were missing. Applies to
1457         /// [phantom invoices].
1458         ///
1459         /// [phantom invoices]: crate::utils::create_phantom_invoice
1460         MissingRouteHints,
1461
1462         /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
1463         ///
1464         /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
1465         MinFinalCltvExpiryDeltaTooShort,
1466 }
1467
1468 impl Display for CreationError {
1469         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1470                 match self {
1471                         CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1472                         CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1473                         CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
1474                         CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
1475                         CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
1476                         CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
1477                                 "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
1478                 }
1479         }
1480 }
1481
1482 #[cfg(feature = "std")]
1483 impl std::error::Error for CreationError { }
1484
1485 /// Errors that may occur when converting a [`RawInvoice`] to an [`Invoice`]. They relate to the
1486 /// requirements sections in BOLT #11
1487 #[derive(Eq, PartialEq, Debug, Clone)]
1488 pub enum SemanticError {
1489         /// The invoice is missing the mandatory payment hash
1490         NoPaymentHash,
1491
1492         /// The invoice has multiple payment hashes which isn't allowed
1493         MultiplePaymentHashes,
1494
1495         /// No description or description hash are part of the invoice
1496         NoDescription,
1497
1498         /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1499         MultipleDescriptions,
1500
1501         /// The invoice is missing the mandatory payment secret, which all modern lightning nodes
1502         /// should provide.
1503         NoPaymentSecret,
1504
1505         /// The invoice contains multiple payment secrets
1506         MultiplePaymentSecrets,
1507
1508         /// The invoice's features are invalid
1509         InvalidFeatures,
1510
1511         /// The recovery id doesn't fit the signature/pub key
1512         InvalidRecoveryId,
1513
1514         /// The invoice's signature is invalid
1515         InvalidSignature,
1516
1517         /// The invoice's amount was not a whole number of millisatoshis
1518         ImpreciseAmount,
1519 }
1520
1521 impl Display for SemanticError {
1522         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1523                 match self {
1524                         SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1525                         SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1526                         SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1527                         SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1528                         SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
1529                         SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
1530                         SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
1531                         SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1532                         SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1533                         SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
1534                 }
1535         }
1536 }
1537
1538 #[cfg(feature = "std")]
1539 impl std::error::Error for SemanticError { }
1540
1541 /// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
1542 /// may occur.
1543 #[derive(Eq, PartialEq, Debug, Clone)]
1544 pub enum SignOrCreationError<S = ()> {
1545         /// An error occurred during signing
1546         SignError(S),
1547
1548         /// An error occurred while building the transaction
1549         CreationError(CreationError),
1550 }
1551
1552 impl<S> Display for SignOrCreationError<S> {
1553         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1554                 match self {
1555                         SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1556                         SignOrCreationError::CreationError(err) => err.fmt(f),
1557                 }
1558         }
1559 }
1560
1561 #[cfg(feature = "serde")]
1562 impl Serialize for Invoice {
1563         fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer {
1564                 serializer.serialize_str(self.to_string().as_str())
1565         }
1566 }
1567 #[cfg(feature = "serde")]
1568 impl<'de> Deserialize<'de> for Invoice {
1569         fn deserialize<D>(deserializer: D) -> Result<Invoice, D::Error> where D: Deserializer<'de> {
1570                 let bolt11 = String::deserialize(deserializer)?
1571                         .parse::<Invoice>()
1572                         .map_err(|e| D::Error::custom(format!("{:?}", e)))?;
1573
1574                 Ok(bolt11)
1575         }
1576 }
1577
1578 #[cfg(test)]
1579 mod test {
1580         use bitcoin_hashes::hex::FromHex;
1581         use bitcoin_hashes::sha256;
1582
1583         #[test]
1584         fn test_system_time_bounds_assumptions() {
1585                 assert_eq!(
1586                         crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
1587                         Err(crate::CreationError::TimestampOutOfBounds)
1588                 );
1589         }
1590
1591         #[test]
1592         fn test_calc_invoice_hash() {
1593                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1594                 use crate::TaggedField::*;
1595
1596                 let invoice = RawInvoice {
1597                         hrp: RawHrp {
1598                                 currency: Currency::Bitcoin,
1599                                 raw_amount: None,
1600                                 si_prefix: None,
1601                         },
1602                         data: RawDataPart {
1603                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1604                                 tagged_fields: vec![
1605                                         PaymentHash(crate::Sha256(sha256::Hash::from_hex(
1606                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1607                                         ).unwrap())).into(),
1608                                         Description(crate::Description::new(
1609                                                 "Please consider supporting this project".to_owned()
1610                                         ).unwrap()).into(),
1611                                 ],
1612                         },
1613                 };
1614
1615                 let expected_hash = [
1616                         0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1617                         0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1618                         0xd5, 0x18, 0xe1, 0xc9
1619                 ];
1620
1621                 assert_eq!(invoice.signable_hash(), expected_hash)
1622         }
1623
1624         #[test]
1625         fn test_check_signature() {
1626                 use crate::TaggedField::*;
1627                 use secp256k1::Secp256k1;
1628                 use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
1629                 use secp256k1::{SecretKey, PublicKey};
1630                 use crate::{SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
1631                          PositiveTimestamp};
1632
1633                 let invoice = SignedRawInvoice {
1634                         raw_invoice: RawInvoice {
1635                                 hrp: RawHrp {
1636                                         currency: Currency::Bitcoin,
1637                                         raw_amount: None,
1638                                         si_prefix: None,
1639                                 },
1640                                 data: RawDataPart {
1641                                         timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1642                                         tagged_fields: vec ! [
1643                                                 PaymentHash(Sha256(sha256::Hash::from_hex(
1644                                                         "0001020304050607080900010203040506070809000102030405060708090102"
1645                                                 ).unwrap())).into(),
1646                                                 Description(
1647                                                         crate::Description::new(
1648                                                                 "Please consider supporting this project".to_owned()
1649                                                         ).unwrap()
1650                                                 ).into(),
1651                                         ],
1652                                 },
1653                         },
1654                         hash: [
1655                                 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1656                                 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1657                                 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1658                         ],
1659                         signature: InvoiceSignature(RecoverableSignature::from_compact(
1660                                 & [
1661                                         0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1662                                         0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1663                                         0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1664                                         0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1665                                         0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1666                                         0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1667                                 ],
1668                                 RecoveryId::from_i32(0).unwrap()
1669                         ).unwrap()),
1670                 };
1671
1672                 assert!(invoice.check_signature());
1673
1674                 let private_key = SecretKey::from_slice(
1675                         &[
1676                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1677                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1678                                 0x3b, 0x2d, 0xb7, 0x34
1679                         ][..]
1680                 ).unwrap();
1681                 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1682
1683                 assert_eq!(invoice.recover_payee_pub_key(), Ok(crate::PayeePubKey(public_key)));
1684
1685                 let (raw_invoice, _, _) = invoice.into_parts();
1686                 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1687                         Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key))
1688                 }).unwrap();
1689
1690                 assert!(new_signed.check_signature());
1691         }
1692
1693         #[test]
1694         fn test_check_feature_bits() {
1695                 use crate::TaggedField::*;
1696                 use lightning::ln::features::InvoiceFeatures;
1697                 use secp256k1::Secp256k1;
1698                 use secp256k1::SecretKey;
1699                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
1700                          SemanticError};
1701
1702                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
1703                 let payment_secret = lightning::ln::PaymentSecret([21; 32]);
1704                 let invoice_template = RawInvoice {
1705                         hrp: RawHrp {
1706                                 currency: Currency::Bitcoin,
1707                                 raw_amount: None,
1708                                 si_prefix: None,
1709                         },
1710                         data: RawDataPart {
1711                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1712                                 tagged_fields: vec ! [
1713                                         PaymentHash(Sha256(sha256::Hash::from_hex(
1714                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1715                                         ).unwrap())).into(),
1716                                         Description(
1717                                                 crate::Description::new(
1718                                                         "Please consider supporting this project".to_owned()
1719                                                 ).unwrap()
1720                                         ).into(),
1721                                 ],
1722                         },
1723                 };
1724
1725                 // Missing features
1726                 let invoice = {
1727                         let mut invoice = invoice_template.clone();
1728                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1729                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1730                 }.unwrap();
1731                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1732
1733                 // Missing feature bits
1734                 let invoice = {
1735                         let mut invoice = invoice_template.clone();
1736                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1737                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1738                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1739                 }.unwrap();
1740                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1741
1742                 let mut payment_secret_features = InvoiceFeatures::empty();
1743                 payment_secret_features.set_payment_secret_required();
1744
1745                 // Including payment secret and feature bits
1746                 let invoice = {
1747                         let mut invoice = invoice_template.clone();
1748                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1749                         invoice.data.tagged_fields.push(Features(payment_secret_features.clone()).into());
1750                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1751                 }.unwrap();
1752                 assert!(Invoice::from_signed(invoice).is_ok());
1753
1754                 // No payment secret or features
1755                 let invoice = {
1756                         let invoice = invoice_template.clone();
1757                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1758                 }.unwrap();
1759                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1760
1761                 // No payment secret or feature bits
1762                 let invoice = {
1763                         let mut invoice = invoice_template.clone();
1764                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1765                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1766                 }.unwrap();
1767                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1768
1769                 // Missing payment secret
1770                 let invoice = {
1771                         let mut invoice = invoice_template.clone();
1772                         invoice.data.tagged_fields.push(Features(payment_secret_features).into());
1773                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1774                 }.unwrap();
1775                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1776
1777                 // Multiple payment secrets
1778                 let invoice = {
1779                         let mut invoice = invoice_template;
1780                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1781                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1782                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1783                 }.unwrap();
1784                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::MultiplePaymentSecrets));
1785         }
1786
1787         #[test]
1788         fn test_builder_amount() {
1789                 use crate::*;
1790
1791                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1792                         .description("Test".into())
1793                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1794                         .duration_since_epoch(Duration::from_secs(1234567));
1795
1796                 let invoice = builder.clone()
1797                         .amount_milli_satoshis(1500)
1798                         .build_raw()
1799                         .unwrap();
1800
1801                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1802                 assert_eq!(invoice.hrp.raw_amount, Some(15));
1803
1804
1805                 let invoice = builder
1806                         .amount_milli_satoshis(150)
1807                         .build_raw()
1808                         .unwrap();
1809
1810                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1811                 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1812         }
1813
1814         #[test]
1815         fn test_builder_fail() {
1816                 use crate::*;
1817                 use lightning::routing::router::RouteHintHop;
1818                 use std::iter::FromIterator;
1819                 use secp256k1::PublicKey;
1820
1821                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1822                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1823                         .duration_since_epoch(Duration::from_secs(1234567))
1824                         .min_final_cltv_expiry_delta(144);
1825
1826                 let too_long_string = String::from_iter(
1827                         (0..1024).map(|_| '?')
1828                 );
1829
1830                 let long_desc_res = builder.clone()
1831                         .description(too_long_string)
1832                         .build_raw();
1833                 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
1834
1835                 let route_hop = RouteHintHop {
1836                         src_node_id: PublicKey::from_slice(
1837                                         &[
1838                                                 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
1839                                                 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
1840                                                 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
1841                                         ][..]
1842                                 ).unwrap(),
1843                         short_channel_id: 0,
1844                         fees: RoutingFees {
1845                                 base_msat: 0,
1846                                 proportional_millionths: 0,
1847                         },
1848                         cltv_expiry_delta: 0,
1849                         htlc_minimum_msat: None,
1850                         htlc_maximum_msat: None,
1851                 };
1852                 let too_long_route = RouteHint(vec![route_hop; 13]);
1853                 let long_route_res = builder.clone()
1854                         .description("Test".into())
1855                         .private_route(too_long_route)
1856                         .build_raw();
1857                 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
1858
1859                 let sign_error_res = builder
1860                         .description("Test".into())
1861                         .payment_secret(PaymentSecret([0; 32]))
1862                         .try_build_signed(|_| {
1863                                 Err("ImaginaryError")
1864                         });
1865                 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
1866         }
1867
1868         #[test]
1869         fn test_builder_ok() {
1870                 use crate::*;
1871                 use lightning::routing::router::RouteHintHop;
1872                 use secp256k1::Secp256k1;
1873                 use secp256k1::{SecretKey, PublicKey};
1874                 use std::time::{UNIX_EPOCH, Duration};
1875
1876                 let secp_ctx = Secp256k1::new();
1877
1878                 let private_key = SecretKey::from_slice(
1879                         &[
1880                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1881                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1882                                 0x3b, 0x2d, 0xb7, 0x34
1883                         ][..]
1884                 ).unwrap();
1885                 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
1886
1887                 let route_1 = RouteHint(vec![
1888                         RouteHintHop {
1889                                 src_node_id: public_key,
1890                                 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
1891                                 fees: RoutingFees {
1892                                         base_msat: 2,
1893                                         proportional_millionths: 1,
1894                                 },
1895                                 cltv_expiry_delta: 145,
1896                                 htlc_minimum_msat: None,
1897                                 htlc_maximum_msat: None,
1898                         },
1899                         RouteHintHop {
1900                                 src_node_id: public_key,
1901                                 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
1902                                 fees: RoutingFees {
1903                                         base_msat: 3,
1904                                         proportional_millionths: 2,
1905                                 },
1906                                 cltv_expiry_delta: 146,
1907                                 htlc_minimum_msat: None,
1908                                 htlc_maximum_msat: None,
1909                         }
1910                 ]);
1911
1912                 let route_2 = RouteHint(vec![
1913                         RouteHintHop {
1914                                 src_node_id: public_key,
1915                                 short_channel_id: 0,
1916                                 fees: RoutingFees {
1917                                         base_msat: 4,
1918                                         proportional_millionths: 3,
1919                                 },
1920                                 cltv_expiry_delta: 147,
1921                                 htlc_minimum_msat: None,
1922                                 htlc_maximum_msat: None,
1923                         },
1924                         RouteHintHop {
1925                                 src_node_id: public_key,
1926                                 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
1927                                 fees: RoutingFees {
1928                                         base_msat: 5,
1929                                         proportional_millionths: 4,
1930                                 },
1931                                 cltv_expiry_delta: 148,
1932                                 htlc_minimum_msat: None,
1933                                 htlc_maximum_msat: None,
1934                         }
1935                 ]);
1936
1937                 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
1938                         .amount_milli_satoshis(123)
1939                         .duration_since_epoch(Duration::from_secs(1234567))
1940                         .payee_pub_key(public_key)
1941                         .expiry_time(Duration::from_secs(54321))
1942                         .min_final_cltv_expiry_delta(144)
1943                         .fallback(Fallback::PubKeyHash([0;20]))
1944                         .private_route(route_1.clone())
1945                         .private_route(route_2.clone())
1946                         .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
1947                         .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap())
1948                         .payment_secret(PaymentSecret([42; 32]))
1949                         .basic_mpp();
1950
1951                 let invoice = builder.clone().build_signed(|hash| {
1952                         secp_ctx.sign_ecdsa_recoverable(hash, &private_key)
1953                 }).unwrap();
1954
1955                 assert!(invoice.check_signature().is_ok());
1956                 assert_eq!(invoice.tagged_fields().count(), 10);
1957
1958                 assert_eq!(invoice.amount_milli_satoshis(), Some(123));
1959                 assert_eq!(invoice.amount_pico_btc(), Some(1230));
1960                 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
1961                 #[cfg(feature = "std")]
1962                 assert_eq!(
1963                         invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1964                         1234567
1965                 );
1966                 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
1967                 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
1968                 assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
1969                 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
1970                 assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
1971                 assert_eq!(
1972                         invoice.description(),
1973                         InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
1974                 );
1975                 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
1976                 assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
1977
1978                 let mut expected_features = InvoiceFeatures::empty();
1979                 expected_features.set_variable_length_onion_required();
1980                 expected_features.set_payment_secret_required();
1981                 expected_features.set_basic_mpp_optional();
1982                 assert_eq!(invoice.features(), Some(&expected_features));
1983
1984                 let raw_invoice = builder.build_raw().unwrap();
1985                 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
1986         }
1987
1988         #[test]
1989         fn test_default_values() {
1990                 use crate::*;
1991                 use secp256k1::Secp256k1;
1992                 use secp256k1::SecretKey;
1993
1994                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
1995                         .description("Test".into())
1996                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1997                         .payment_secret(PaymentSecret([0; 32]))
1998                         .duration_since_epoch(Duration::from_secs(1234567))
1999                         .build_raw()
2000                         .unwrap()
2001                         .sign::<_, ()>(|hash| {
2002                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2003                                 let secp_ctx = Secp256k1::new();
2004                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2005                         })
2006                         .unwrap();
2007                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2008
2009                 assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
2010                 assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
2011                 assert!(!invoice.would_expire(Duration::from_secs(1234568)));
2012         }
2013
2014         #[test]
2015         fn test_expiration() {
2016                 use crate::*;
2017                 use secp256k1::Secp256k1;
2018                 use secp256k1::SecretKey;
2019
2020                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2021                         .description("Test".into())
2022                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2023                         .payment_secret(PaymentSecret([0; 32]))
2024                         .duration_since_epoch(Duration::from_secs(1234567))
2025                         .build_raw()
2026                         .unwrap()
2027                         .sign::<_, ()>(|hash| {
2028                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2029                                 let secp_ctx = Secp256k1::new();
2030                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2031                         })
2032                         .unwrap();
2033                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2034
2035                 assert!(invoice.would_expire(Duration::from_secs(1234567 + DEFAULT_EXPIRY_TIME + 1)));
2036         }
2037
2038         #[cfg(feature = "serde")]
2039         #[test]
2040         fn test_serde() {
2041                 let invoice_str = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
2042                         h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
2043                         5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
2044                         h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
2045                         j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
2046                         ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
2047                         guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
2048                         ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
2049                         p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
2050                         8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
2051                         j5r6drg6k6zcqj0fcwg";
2052                 let invoice = invoice_str.parse::<super::Invoice>().unwrap();
2053                 let serialized_invoice = serde_json::to_string(&invoice).unwrap();
2054                 let deserialized_invoice: super::Invoice = serde_json::from_str(serialized_invoice.as_str()).unwrap();
2055                 assert_eq!(invoice, deserialized_invoice);
2056                 assert_eq!(invoice_str, deserialized_invoice.to_string().as_str());
2057                 assert_eq!(invoice_str, serialized_invoice.as_str().trim_matches('\"'));
2058         }
2059 }