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         /// Transform the `Invoice` into it's unchecked version
1030         pub fn into_signed_raw(self) -> SignedRawInvoice {
1031                 self.signed_invoice
1032         }
1033
1034         /// Check that all mandatory fields are present
1035         fn check_field_counts(&self) -> Result<(), SemanticError> {
1036                 // "A writer MUST include exactly one p field […]."
1037                 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1038                         TaggedField::PaymentHash(_) => true,
1039                         _ => false,
1040                 }).count();
1041                 if payment_hash_cnt < 1 {
1042                         return Err(SemanticError::NoPaymentHash);
1043                 } else if payment_hash_cnt > 1 {
1044                         return Err(SemanticError::MultiplePaymentHashes);
1045                 }
1046
1047                 // "A writer MUST include either exactly one d or exactly one h field."
1048                 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1049                         TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1050                         _ => false,
1051                 }).count();
1052                 if  description_cnt < 1 {
1053                         return Err(SemanticError::NoDescription);
1054                 } else if description_cnt > 1 {
1055                         return  Err(SemanticError::MultipleDescriptions);
1056                 }
1057
1058                 self.check_payment_secret()?;
1059
1060                 Ok(())
1061         }
1062
1063         /// Checks that there is exactly one payment secret field
1064         fn check_payment_secret(&self) -> Result<(), SemanticError> {
1065                 // "A writer MUST include exactly one `s` field."
1066                 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1067                         TaggedField::PaymentSecret(_) => true,
1068                         _ => false,
1069                 }).count();
1070                 if payment_secret_count < 1 {
1071                         return Err(SemanticError::NoPaymentSecret);
1072                 } else if payment_secret_count > 1 {
1073                         return Err(SemanticError::MultiplePaymentSecrets);
1074                 }
1075
1076                 Ok(())
1077         }
1078
1079         /// Check that amount is a whole number of millisatoshis
1080         fn check_amount(&self) -> Result<(), SemanticError> {
1081                 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1082                         if amount_pico_btc % 10 != 0 {
1083                                 return Err(SemanticError::ImpreciseAmount);
1084                         }
1085                 }
1086                 Ok(())
1087         }
1088
1089         /// Check that feature bits are set as required
1090         fn check_feature_bits(&self) -> Result<(), SemanticError> {
1091                 self.check_payment_secret()?;
1092
1093                 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1094                 // (this requirement has been since removed, and we now require the payment secret
1095                 // feature bit always).
1096                 let features = self.tagged_fields().find(|&tf| match *tf {
1097                         TaggedField::Features(_) => true,
1098                         _ => false,
1099                 });
1100                 match features {
1101                         None => Err(SemanticError::InvalidFeatures),
1102                         Some(TaggedField::Features(features)) => {
1103                                 if features.requires_unknown_bits() {
1104                                         Err(SemanticError::InvalidFeatures)
1105                                 } else if !features.supports_payment_secret() {
1106                                         Err(SemanticError::InvalidFeatures)
1107                                 } else {
1108                                         Ok(())
1109                                 }
1110                         },
1111                         Some(_) => unreachable!(),
1112                 }
1113         }
1114
1115         /// Check that the invoice is signed correctly and that key recovery works
1116         pub fn check_signature(&self) -> Result<(), SemanticError> {
1117                 match self.signed_invoice.recover_payee_pub_key() {
1118                         Err(secp256k1::Error::InvalidRecoveryId) =>
1119                                 return Err(SemanticError::InvalidRecoveryId),
1120                         Err(secp256k1::Error::InvalidSignature) =>
1121                                 return Err(SemanticError::InvalidSignature),
1122                         Err(e) => panic!("no other error may occur, got {:?}", e),
1123                         Ok(_) => {},
1124                 }
1125
1126                 if !self.signed_invoice.check_signature() {
1127                         return Err(SemanticError::InvalidSignature);
1128                 }
1129
1130                 Ok(())
1131         }
1132
1133         /// Constructs an `Invoice` from a [`SignedRawInvoice`] by checking all its invariants.
1134         /// ```
1135         /// use lightning_invoice::*;
1136         ///
1137         /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1138         /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1139         /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1140         /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1141         /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1142         /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1143         /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1144         /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1145         /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1146         /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1147         /// j5r6drg6k6zcqj0fcwg";
1148         ///
1149         /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
1150         ///
1151         /// assert!(Invoice::from_signed(signed).is_ok());
1152         /// ```
1153         pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
1154                 let invoice = Invoice {
1155                         signed_invoice,
1156                 };
1157                 invoice.check_field_counts()?;
1158                 invoice.check_feature_bits()?;
1159                 invoice.check_signature()?;
1160                 invoice.check_amount()?;
1161
1162                 Ok(invoice)
1163         }
1164
1165         /// Returns the `Invoice`'s timestamp (should equal its creation time)
1166         #[cfg(feature = "std")]
1167         pub fn timestamp(&self) -> SystemTime {
1168                 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1169         }
1170
1171         /// Returns the `Invoice`'s timestamp as a duration since the Unix epoch
1172         pub fn duration_since_epoch(&self) -> Duration {
1173                 self.signed_invoice.raw_invoice().data.timestamp.0
1174         }
1175
1176         /// Returns an iterator over all tagged fields of this Invoice.
1177         ///
1178         /// (C-not exported) As there is not yet a manual mapping for a FilterMap
1179         pub fn tagged_fields(&self)
1180                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1181                 self.signed_invoice.raw_invoice().known_tagged_fields()
1182         }
1183
1184         /// Returns the hash to which we will receive the preimage on completion of the payment
1185         pub fn payment_hash(&self) -> &sha256::Hash {
1186                 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1187         }
1188
1189         /// Return the description or a hash of it for longer ones
1190         ///
1191         /// (C-not exported) because we don't yet export InvoiceDescription
1192         pub fn description(&self) -> InvoiceDescription {
1193                 if let Some(direct) = self.signed_invoice.description() {
1194                         return InvoiceDescription::Direct(direct);
1195                 } else if let Some(hash) = self.signed_invoice.description_hash() {
1196                         return InvoiceDescription::Hash(hash);
1197                 }
1198                 unreachable!("ensured by constructor");
1199         }
1200
1201         /// Get the payee's public key if one was included in the invoice
1202         pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1203                 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1204         }
1205
1206         /// Get the payment secret if one was included in the invoice
1207         pub fn payment_secret(&self) -> &PaymentSecret {
1208                 self.signed_invoice.payment_secret().expect("was checked by constructor")
1209         }
1210
1211         /// Get the invoice features if they were included in the invoice
1212         pub fn features(&self) -> Option<&InvoiceFeatures> {
1213                 self.signed_invoice.features()
1214         }
1215
1216         /// Recover the payee's public key (only to be used if none was included in the invoice)
1217         pub fn recover_payee_pub_key(&self) -> PublicKey {
1218                 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1219         }
1220
1221         /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1222         pub fn expiry_time(&self) -> Duration {
1223                 self.signed_invoice.expiry_time()
1224                         .map(|x| x.0)
1225                         .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1226         }
1227
1228         /// Returns whether the invoice has expired.
1229         #[cfg(feature = "std")]
1230         pub fn is_expired(&self) -> bool {
1231                 Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
1232         }
1233
1234         /// Returns whether the expiry time from the given epoch has passed.
1235         #[cfg(feature = "std")]
1236         pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
1237                 match epoch.elapsed() {
1238                         Ok(elapsed) => elapsed > expiry_time,
1239                         Err(_) => false,
1240                 }
1241         }
1242
1243         /// Returns whether the expiry time would pass at the given point in time.
1244         /// `at_time` is the timestamp as a duration since the Unix epoch.
1245         pub fn would_expire(&self, at_time: Duration) -> bool {
1246                 self.duration_since_epoch()
1247                         .checked_add(self.expiry_time())
1248                         .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
1249         }
1250
1251         /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
1252         /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
1253         pub fn min_final_cltv_expiry_delta(&self) -> u64 {
1254                 self.signed_invoice.min_final_cltv_expiry_delta()
1255                         .map(|x| x.0)
1256                         .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
1257         }
1258
1259         /// Returns a list of all fallback addresses
1260         ///
1261         /// (C-not exported) as we don't support Vec<&NonOpaqueType>
1262         pub fn fallbacks(&self) -> Vec<&Fallback> {
1263                 self.signed_invoice.fallbacks()
1264         }
1265
1266         /// Returns a list of all routes included in the invoice
1267         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1268                 self.signed_invoice.private_routes()
1269         }
1270
1271         /// Returns a list of all routes included in the invoice as the underlying hints
1272         pub fn route_hints(&self) -> Vec<RouteHint> {
1273                 find_all_extract!(
1274                         self.signed_invoice.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x
1275                 ).map(|route| (**route).clone()).collect()
1276         }
1277
1278         /// Returns the currency for which the invoice was issued
1279         pub fn currency(&self) -> Currency {
1280                 self.signed_invoice.currency()
1281         }
1282
1283         /// Returns the amount if specified in the invoice as millisatoshis.
1284         pub fn amount_milli_satoshis(&self) -> Option<u64> {
1285                 self.signed_invoice.amount_pico_btc().map(|v| v / 10)
1286         }
1287
1288         /// Returns the amount if specified in the invoice as pico BTC.
1289         fn amount_pico_btc(&self) -> Option<u64> {
1290                 self.signed_invoice.amount_pico_btc()
1291         }
1292 }
1293
1294 impl From<TaggedField> for RawTaggedField {
1295         fn from(tf: TaggedField) -> Self {
1296                 RawTaggedField::KnownSemantics(tf)
1297         }
1298 }
1299
1300 impl TaggedField {
1301         /// Numeric representation of the field's tag
1302         pub fn tag(&self) -> u5 {
1303                 let tag = match *self {
1304                         TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1305                         TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1306                         TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1307                         TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1308                         TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1309                         TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
1310                         TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1311                         TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
1312                         TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1313                         TaggedField::Features(_) => constants::TAG_FEATURES,
1314                 };
1315
1316                 u5::try_from_u8(tag).expect("all tags defined are <32")
1317         }
1318 }
1319
1320 impl Description {
1321
1322         /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1323         /// returns [`CreationError::DescriptionTooLong`] otherwise
1324         ///
1325         /// Please note that single characters may use more than one byte due to UTF8 encoding.
1326         pub fn new(description: String) -> Result<Description, CreationError> {
1327                 if description.len() > 639 {
1328                         Err(CreationError::DescriptionTooLong)
1329                 } else {
1330                         Ok(Description(description))
1331                 }
1332         }
1333
1334         /// Returns the underlying description [`String`]
1335         pub fn into_inner(self) -> String {
1336                 self.0
1337         }
1338 }
1339
1340 impl From<Description> for String {
1341         fn from(val: Description) -> Self {
1342                 val.into_inner()
1343         }
1344 }
1345
1346 impl Deref for Description {
1347         type Target = str;
1348
1349         fn deref(&self) -> &str {
1350                 &self.0
1351         }
1352 }
1353
1354 impl From<PublicKey> for PayeePubKey {
1355         fn from(pk: PublicKey) -> Self {
1356                 PayeePubKey(pk)
1357         }
1358 }
1359
1360 impl Deref for PayeePubKey {
1361         type Target = PublicKey;
1362
1363         fn deref(&self) -> &PublicKey {
1364                 &self.0
1365         }
1366 }
1367
1368 impl ExpiryTime {
1369         /// Construct an `ExpiryTime` from seconds.
1370         pub fn from_seconds(seconds: u64) -> ExpiryTime {
1371                 ExpiryTime(Duration::from_secs(seconds))
1372         }
1373
1374         /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
1375         pub fn from_duration(duration: Duration) -> ExpiryTime {
1376                 Self::from_seconds(duration.as_secs())
1377         }
1378
1379         /// Returns the expiry time in seconds
1380         pub fn as_seconds(&self) -> u64 {
1381                 self.0.as_secs()
1382         }
1383
1384         /// Returns a reference to the underlying [`Duration`] (=expiry time)
1385         pub fn as_duration(&self) -> &Duration {
1386                 &self.0
1387         }
1388 }
1389
1390 impl PrivateRoute {
1391         /// Creates a new (partial) route from a list of hops
1392         pub fn new(hops: RouteHint) -> Result<PrivateRoute, CreationError> {
1393                 if hops.0.len() <= 12 {
1394                         Ok(PrivateRoute(hops))
1395                 } else {
1396                         Err(CreationError::RouteTooLong)
1397                 }
1398         }
1399
1400         /// Returns the underlying list of hops
1401         pub fn into_inner(self) -> RouteHint {
1402                 self.0
1403         }
1404 }
1405
1406 impl From<PrivateRoute> for RouteHint {
1407         fn from(val: PrivateRoute) -> Self {
1408                 val.into_inner()
1409         }
1410 }
1411
1412 impl Deref for PrivateRoute {
1413         type Target = RouteHint;
1414
1415         fn deref(&self) -> &RouteHint {
1416                 &self.0
1417         }
1418 }
1419
1420 impl Deref for InvoiceSignature {
1421         type Target = RecoverableSignature;
1422
1423         fn deref(&self) -> &RecoverableSignature {
1424                 &self.0
1425         }
1426 }
1427
1428 impl Deref for SignedRawInvoice {
1429         type Target = RawInvoice;
1430
1431         fn deref(&self) -> &RawInvoice {
1432                 &self.raw_invoice
1433         }
1434 }
1435
1436 /// Errors that may occur when constructing a new [`RawInvoice`] or [`Invoice`]
1437 #[derive(Eq, PartialEq, Debug, Clone)]
1438 pub enum CreationError {
1439         /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
1440         DescriptionTooLong,
1441
1442         /// The specified route has too many hops and can't be encoded
1443         RouteTooLong,
1444
1445         /// The Unix timestamp of the supplied date is less than zero or greater than 35-bits
1446         TimestampOutOfBounds,
1447
1448         /// The supplied millisatoshi amount was greater than the total bitcoin supply.
1449         InvalidAmount,
1450
1451         /// Route hints were required for this invoice and were missing. Applies to
1452         /// [phantom invoices].
1453         ///
1454         /// [phantom invoices]: crate::utils::create_phantom_invoice
1455         MissingRouteHints,
1456
1457         /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
1458         ///
1459         /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
1460         MinFinalCltvExpiryDeltaTooShort,
1461 }
1462
1463 impl Display for CreationError {
1464         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1465                 match self {
1466                         CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1467                         CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1468                         CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
1469                         CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
1470                         CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
1471                         CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
1472                                 "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
1473                 }
1474         }
1475 }
1476
1477 #[cfg(feature = "std")]
1478 impl std::error::Error for CreationError { }
1479
1480 /// Errors that may occur when converting a [`RawInvoice`] to an [`Invoice`]. They relate to the
1481 /// requirements sections in BOLT #11
1482 #[derive(Eq, PartialEq, Debug, Clone)]
1483 pub enum SemanticError {
1484         /// The invoice is missing the mandatory payment hash
1485         NoPaymentHash,
1486
1487         /// The invoice has multiple payment hashes which isn't allowed
1488         MultiplePaymentHashes,
1489
1490         /// No description or description hash are part of the invoice
1491         NoDescription,
1492
1493         /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1494         MultipleDescriptions,
1495
1496         /// The invoice is missing the mandatory payment secret, which all modern lightning nodes
1497         /// should provide.
1498         NoPaymentSecret,
1499
1500         /// The invoice contains multiple payment secrets
1501         MultiplePaymentSecrets,
1502
1503         /// The invoice's features are invalid
1504         InvalidFeatures,
1505
1506         /// The recovery id doesn't fit the signature/pub key
1507         InvalidRecoveryId,
1508
1509         /// The invoice's signature is invalid
1510         InvalidSignature,
1511
1512         /// The invoice's amount was not a whole number of millisatoshis
1513         ImpreciseAmount,
1514 }
1515
1516 impl Display for SemanticError {
1517         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1518                 match self {
1519                         SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1520                         SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1521                         SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1522                         SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1523                         SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
1524                         SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
1525                         SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
1526                         SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1527                         SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1528                         SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
1529                 }
1530         }
1531 }
1532
1533 #[cfg(feature = "std")]
1534 impl std::error::Error for SemanticError { }
1535
1536 /// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
1537 /// may occur.
1538 #[derive(Eq, PartialEq, Debug, Clone)]
1539 pub enum SignOrCreationError<S = ()> {
1540         /// An error occurred during signing
1541         SignError(S),
1542
1543         /// An error occurred while building the transaction
1544         CreationError(CreationError),
1545 }
1546
1547 impl<S> Display for SignOrCreationError<S> {
1548         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1549                 match self {
1550                         SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1551                         SignOrCreationError::CreationError(err) => err.fmt(f),
1552                 }
1553         }
1554 }
1555
1556 #[cfg(feature = "serde")]
1557 impl Serialize for Invoice {
1558         fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer {
1559                 serializer.serialize_str(self.to_string().as_str())
1560         }
1561 }
1562 #[cfg(feature = "serde")]
1563 impl<'de> Deserialize<'de> for Invoice {
1564         fn deserialize<D>(deserializer: D) -> Result<Invoice, D::Error> where D: Deserializer<'de> {
1565                 let bolt11 = String::deserialize(deserializer)?
1566                         .parse::<Invoice>()
1567                         .map_err(|e| D::Error::custom(format!("{:?}", e)))?;
1568
1569                 Ok(bolt11)
1570         }
1571 }
1572
1573 #[cfg(test)]
1574 mod test {
1575         use bitcoin_hashes::hex::FromHex;
1576         use bitcoin_hashes::sha256;
1577
1578         #[test]
1579         fn test_system_time_bounds_assumptions() {
1580                 assert_eq!(
1581                         crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
1582                         Err(crate::CreationError::TimestampOutOfBounds)
1583                 );
1584         }
1585
1586         #[test]
1587         fn test_calc_invoice_hash() {
1588                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1589                 use crate::TaggedField::*;
1590
1591                 let invoice = RawInvoice {
1592                         hrp: RawHrp {
1593                                 currency: Currency::Bitcoin,
1594                                 raw_amount: None,
1595                                 si_prefix: None,
1596                         },
1597                         data: RawDataPart {
1598                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1599                                 tagged_fields: vec![
1600                                         PaymentHash(crate::Sha256(sha256::Hash::from_hex(
1601                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1602                                         ).unwrap())).into(),
1603                                         Description(crate::Description::new(
1604                                                 "Please consider supporting this project".to_owned()
1605                                         ).unwrap()).into(),
1606                                 ],
1607                         },
1608                 };
1609
1610                 let expected_hash = [
1611                         0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1612                         0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1613                         0xd5, 0x18, 0xe1, 0xc9
1614                 ];
1615
1616                 assert_eq!(invoice.signable_hash(), expected_hash)
1617         }
1618
1619         #[test]
1620         fn test_check_signature() {
1621                 use crate::TaggedField::*;
1622                 use secp256k1::Secp256k1;
1623                 use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
1624                 use secp256k1::{SecretKey, PublicKey};
1625                 use crate::{SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
1626                          PositiveTimestamp};
1627
1628                 let invoice = SignedRawInvoice {
1629                         raw_invoice: RawInvoice {
1630                                 hrp: RawHrp {
1631                                         currency: Currency::Bitcoin,
1632                                         raw_amount: None,
1633                                         si_prefix: None,
1634                                 },
1635                                 data: RawDataPart {
1636                                         timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1637                                         tagged_fields: vec ! [
1638                                                 PaymentHash(Sha256(sha256::Hash::from_hex(
1639                                                         "0001020304050607080900010203040506070809000102030405060708090102"
1640                                                 ).unwrap())).into(),
1641                                                 Description(
1642                                                         crate::Description::new(
1643                                                                 "Please consider supporting this project".to_owned()
1644                                                         ).unwrap()
1645                                                 ).into(),
1646                                         ],
1647                                 },
1648                         },
1649                         hash: [
1650                                 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1651                                 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1652                                 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1653                         ],
1654                         signature: InvoiceSignature(RecoverableSignature::from_compact(
1655                                 & [
1656                                         0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1657                                         0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1658                                         0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1659                                         0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1660                                         0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1661                                         0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1662                                 ],
1663                                 RecoveryId::from_i32(0).unwrap()
1664                         ).unwrap()),
1665                 };
1666
1667                 assert!(invoice.check_signature());
1668
1669                 let private_key = SecretKey::from_slice(
1670                         &[
1671                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1672                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1673                                 0x3b, 0x2d, 0xb7, 0x34
1674                         ][..]
1675                 ).unwrap();
1676                 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1677
1678                 assert_eq!(invoice.recover_payee_pub_key(), Ok(crate::PayeePubKey(public_key)));
1679
1680                 let (raw_invoice, _, _) = invoice.into_parts();
1681                 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1682                         Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key))
1683                 }).unwrap();
1684
1685                 assert!(new_signed.check_signature());
1686         }
1687
1688         #[test]
1689         fn test_check_feature_bits() {
1690                 use crate::TaggedField::*;
1691                 use lightning::ln::features::InvoiceFeatures;
1692                 use secp256k1::Secp256k1;
1693                 use secp256k1::SecretKey;
1694                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
1695                          SemanticError};
1696
1697                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
1698                 let payment_secret = lightning::ln::PaymentSecret([21; 32]);
1699                 let invoice_template = RawInvoice {
1700                         hrp: RawHrp {
1701                                 currency: Currency::Bitcoin,
1702                                 raw_amount: None,
1703                                 si_prefix: None,
1704                         },
1705                         data: RawDataPart {
1706                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1707                                 tagged_fields: vec ! [
1708                                         PaymentHash(Sha256(sha256::Hash::from_hex(
1709                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1710                                         ).unwrap())).into(),
1711                                         Description(
1712                                                 crate::Description::new(
1713                                                         "Please consider supporting this project".to_owned()
1714                                                 ).unwrap()
1715                                         ).into(),
1716                                 ],
1717                         },
1718                 };
1719
1720                 // Missing features
1721                 let invoice = {
1722                         let mut invoice = invoice_template.clone();
1723                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1724                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1725                 }.unwrap();
1726                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1727
1728                 // Missing feature bits
1729                 let invoice = {
1730                         let mut invoice = invoice_template.clone();
1731                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1732                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1733                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1734                 }.unwrap();
1735                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1736
1737                 let mut payment_secret_features = InvoiceFeatures::empty();
1738                 payment_secret_features.set_payment_secret_required();
1739
1740                 // Including payment secret and feature bits
1741                 let invoice = {
1742                         let mut invoice = invoice_template.clone();
1743                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1744                         invoice.data.tagged_fields.push(Features(payment_secret_features.clone()).into());
1745                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1746                 }.unwrap();
1747                 assert!(Invoice::from_signed(invoice).is_ok());
1748
1749                 // No payment secret or features
1750                 let invoice = {
1751                         let invoice = invoice_template.clone();
1752                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1753                 }.unwrap();
1754                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1755
1756                 // No payment secret or feature bits
1757                 let invoice = {
1758                         let mut invoice = invoice_template.clone();
1759                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1760                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1761                 }.unwrap();
1762                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1763
1764                 // Missing payment secret
1765                 let invoice = {
1766                         let mut invoice = invoice_template.clone();
1767                         invoice.data.tagged_fields.push(Features(payment_secret_features).into());
1768                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1769                 }.unwrap();
1770                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1771
1772                 // Multiple payment secrets
1773                 let invoice = {
1774                         let mut invoice = invoice_template;
1775                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1776                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1777                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1778                 }.unwrap();
1779                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::MultiplePaymentSecrets));
1780         }
1781
1782         #[test]
1783         fn test_builder_amount() {
1784                 use crate::*;
1785
1786                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1787                         .description("Test".into())
1788                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1789                         .duration_since_epoch(Duration::from_secs(1234567));
1790
1791                 let invoice = builder.clone()
1792                         .amount_milli_satoshis(1500)
1793                         .build_raw()
1794                         .unwrap();
1795
1796                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1797                 assert_eq!(invoice.hrp.raw_amount, Some(15));
1798
1799
1800                 let invoice = builder
1801                         .amount_milli_satoshis(150)
1802                         .build_raw()
1803                         .unwrap();
1804
1805                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1806                 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1807         }
1808
1809         #[test]
1810         fn test_builder_fail() {
1811                 use crate::*;
1812                 use lightning::routing::router::RouteHintHop;
1813                 use std::iter::FromIterator;
1814                 use secp256k1::PublicKey;
1815
1816                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1817                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1818                         .duration_since_epoch(Duration::from_secs(1234567))
1819                         .min_final_cltv_expiry_delta(144);
1820
1821                 let too_long_string = String::from_iter(
1822                         (0..1024).map(|_| '?')
1823                 );
1824
1825                 let long_desc_res = builder.clone()
1826                         .description(too_long_string)
1827                         .build_raw();
1828                 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
1829
1830                 let route_hop = RouteHintHop {
1831                         src_node_id: PublicKey::from_slice(
1832                                         &[
1833                                                 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
1834                                                 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
1835                                                 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
1836                                         ][..]
1837                                 ).unwrap(),
1838                         short_channel_id: 0,
1839                         fees: RoutingFees {
1840                                 base_msat: 0,
1841                                 proportional_millionths: 0,
1842                         },
1843                         cltv_expiry_delta: 0,
1844                         htlc_minimum_msat: None,
1845                         htlc_maximum_msat: None,
1846                 };
1847                 let too_long_route = RouteHint(vec![route_hop; 13]);
1848                 let long_route_res = builder.clone()
1849                         .description("Test".into())
1850                         .private_route(too_long_route)
1851                         .build_raw();
1852                 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
1853
1854                 let sign_error_res = builder
1855                         .description("Test".into())
1856                         .payment_secret(PaymentSecret([0; 32]))
1857                         .try_build_signed(|_| {
1858                                 Err("ImaginaryError")
1859                         });
1860                 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
1861         }
1862
1863         #[test]
1864         fn test_builder_ok() {
1865                 use crate::*;
1866                 use lightning::routing::router::RouteHintHop;
1867                 use secp256k1::Secp256k1;
1868                 use secp256k1::{SecretKey, PublicKey};
1869                 use std::time::{UNIX_EPOCH, Duration};
1870
1871                 let secp_ctx = Secp256k1::new();
1872
1873                 let private_key = SecretKey::from_slice(
1874                         &[
1875                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1876                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1877                                 0x3b, 0x2d, 0xb7, 0x34
1878                         ][..]
1879                 ).unwrap();
1880                 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
1881
1882                 let route_1 = RouteHint(vec![
1883                         RouteHintHop {
1884                                 src_node_id: public_key,
1885                                 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
1886                                 fees: RoutingFees {
1887                                         base_msat: 2,
1888                                         proportional_millionths: 1,
1889                                 },
1890                                 cltv_expiry_delta: 145,
1891                                 htlc_minimum_msat: None,
1892                                 htlc_maximum_msat: None,
1893                         },
1894                         RouteHintHop {
1895                                 src_node_id: public_key,
1896                                 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
1897                                 fees: RoutingFees {
1898                                         base_msat: 3,
1899                                         proportional_millionths: 2,
1900                                 },
1901                                 cltv_expiry_delta: 146,
1902                                 htlc_minimum_msat: None,
1903                                 htlc_maximum_msat: None,
1904                         }
1905                 ]);
1906
1907                 let route_2 = RouteHint(vec![
1908                         RouteHintHop {
1909                                 src_node_id: public_key,
1910                                 short_channel_id: 0,
1911                                 fees: RoutingFees {
1912                                         base_msat: 4,
1913                                         proportional_millionths: 3,
1914                                 },
1915                                 cltv_expiry_delta: 147,
1916                                 htlc_minimum_msat: None,
1917                                 htlc_maximum_msat: None,
1918                         },
1919                         RouteHintHop {
1920                                 src_node_id: public_key,
1921                                 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
1922                                 fees: RoutingFees {
1923                                         base_msat: 5,
1924                                         proportional_millionths: 4,
1925                                 },
1926                                 cltv_expiry_delta: 148,
1927                                 htlc_minimum_msat: None,
1928                                 htlc_maximum_msat: None,
1929                         }
1930                 ]);
1931
1932                 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
1933                         .amount_milli_satoshis(123)
1934                         .duration_since_epoch(Duration::from_secs(1234567))
1935                         .payee_pub_key(public_key)
1936                         .expiry_time(Duration::from_secs(54321))
1937                         .min_final_cltv_expiry_delta(144)
1938                         .fallback(Fallback::PubKeyHash([0;20]))
1939                         .private_route(route_1.clone())
1940                         .private_route(route_2.clone())
1941                         .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
1942                         .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap())
1943                         .payment_secret(PaymentSecret([42; 32]))
1944                         .basic_mpp();
1945
1946                 let invoice = builder.clone().build_signed(|hash| {
1947                         secp_ctx.sign_ecdsa_recoverable(hash, &private_key)
1948                 }).unwrap();
1949
1950                 assert!(invoice.check_signature().is_ok());
1951                 assert_eq!(invoice.tagged_fields().count(), 10);
1952
1953                 assert_eq!(invoice.amount_milli_satoshis(), Some(123));
1954                 assert_eq!(invoice.amount_pico_btc(), Some(1230));
1955                 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
1956                 #[cfg(feature = "std")]
1957                 assert_eq!(
1958                         invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1959                         1234567
1960                 );
1961                 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
1962                 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
1963                 assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
1964                 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
1965                 assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
1966                 assert_eq!(
1967                         invoice.description(),
1968                         InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
1969                 );
1970                 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
1971                 assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
1972
1973                 let mut expected_features = InvoiceFeatures::empty();
1974                 expected_features.set_variable_length_onion_required();
1975                 expected_features.set_payment_secret_required();
1976                 expected_features.set_basic_mpp_optional();
1977                 assert_eq!(invoice.features(), Some(&expected_features));
1978
1979                 let raw_invoice = builder.build_raw().unwrap();
1980                 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
1981         }
1982
1983         #[test]
1984         fn test_default_values() {
1985                 use crate::*;
1986                 use secp256k1::Secp256k1;
1987                 use secp256k1::SecretKey;
1988
1989                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
1990                         .description("Test".into())
1991                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1992                         .payment_secret(PaymentSecret([0; 32]))
1993                         .duration_since_epoch(Duration::from_secs(1234567))
1994                         .build_raw()
1995                         .unwrap()
1996                         .sign::<_, ()>(|hash| {
1997                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
1998                                 let secp_ctx = Secp256k1::new();
1999                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2000                         })
2001                         .unwrap();
2002                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2003
2004                 assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
2005                 assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
2006                 assert!(!invoice.would_expire(Duration::from_secs(1234568)));
2007         }
2008
2009         #[test]
2010         fn test_expiration() {
2011                 use crate::*;
2012                 use secp256k1::Secp256k1;
2013                 use secp256k1::SecretKey;
2014
2015                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2016                         .description("Test".into())
2017                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2018                         .payment_secret(PaymentSecret([0; 32]))
2019                         .duration_since_epoch(Duration::from_secs(1234567))
2020                         .build_raw()
2021                         .unwrap()
2022                         .sign::<_, ()>(|hash| {
2023                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2024                                 let secp_ctx = Secp256k1::new();
2025                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2026                         })
2027                         .unwrap();
2028                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2029
2030                 assert!(invoice.would_expire(Duration::from_secs(1234567 + DEFAULT_EXPIRY_TIME + 1)));
2031         }
2032
2033         #[cfg(feature = "serde")]
2034         #[test]
2035         fn test_serde() {
2036                 let invoice_str = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
2037                         h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
2038                         5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
2039                         h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
2040                         j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
2041                         ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
2042                         guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
2043                         ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
2044                         p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
2045                         8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
2046                         j5r6drg6k6zcqj0fcwg";
2047                 let invoice = invoice_str.parse::<super::Invoice>().unwrap();
2048                 let serialized_invoice = serde_json::to_string(&invoice).unwrap();
2049                 let deserialized_invoice: super::Invoice = serde_json::from_str(serialized_invoice.as_str()).unwrap();
2050                 assert_eq!(invoice, deserialized_invoice);
2051                 assert_eq!(invoice_str, deserialized_invoice.to_string().as_str());
2052                 assert_eq!(invoice_str, serialized_invoice.as_str().trim_matches('\"'));
2053         }
2054 }