_ 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 /// This is not exported to bindings users 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 /// This is not exported to bindings users 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 /// This is not exported to bindings users 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         /// This is not exported to bindings users 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 /// This is not exported to bindings users 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 /// This is not exported to bindings users 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(/// This is not exported to bindings users 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         /// Set the description or description hash. This function is only available if no description (hash) was set.
 621         pub fn invoice_description(self, description: InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S> {
 622                 match description {
 623                         InvoiceDescription::Direct(desc) => {
 624                                 self.description(desc.clone().into_inner())
 625                         }
 626                         InvoiceDescription::Hash(hash) => {
 627                                 self.description_hash(hash.0)
 628                         }
 629                 }
 630         }
 631 }
 632
 633 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
 634         /// Set the payment hash. This function is only available if no payment hash was set.
 635         pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S> {
 636                 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
 637                 self.set_flags()
 638         }
 639 }
 640
 641 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
 642         /// Sets the timestamp to a specific [`SystemTime`].
 643         #[cfg(feature = "std")]
 644         pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
 645                 match PositiveTimestamp::from_system_time(time) {
 646                         Ok(t) => self.timestamp = Some(t),
 647                         Err(e) => self.error = Some(e),
 648                 }
 649
 650                 self.set_flags()
 651         }
 652
 653         /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
 654         /// is not representable in BOLT 11 invoices).
 655         pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S> {
 656                 match PositiveTimestamp::from_duration_since_epoch(time) {
 657                         Ok(t) => self.timestamp = Some(t),
 658                         Err(e) => self.error = Some(e),
 659                 }
 660
 661                 self.set_flags()
 662         }
 663
 664         /// Sets the timestamp to the current system time.
 665         #[cfg(feature = "std")]
 666         pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
 667                 let now = PositiveTimestamp::from_system_time(SystemTime::now());
 668                 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
 669                 self.set_flags()
 670         }
 671 }
 672
 673 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
 674         /// Sets `min_final_cltv_expiry_delta`.
 675         pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
 676                 self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
 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::False> {
 682         /// Sets the payment secret and relevant features.
 683         pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True> {
 684                 let mut features = InvoiceFeatures::empty();
 685                 features.set_variable_length_onion_required();
 686                 features.set_payment_secret_required();
 687                 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
 688                 self.tagged_fields.push(TaggedField::Features(features));
 689                 self.set_flags()
 690         }
 691 }
 692
 693 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True> {
 694         /// Sets the `basic_mpp` feature as optional.
 695         pub fn basic_mpp(mut self) -> Self {
 696                 for field in self.tagged_fields.iter_mut() {
 697                         if let TaggedField::Features(f) = field {
 698                                 f.set_basic_mpp_optional();
 699                         }
 700                 }
 701                 self
 702         }
 703 }
 704
 705 impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
 706         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
 707         /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
 708         /// the included payee public key.
 709         pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
 710                 where F: FnOnce(&Message) -> RecoverableSignature
 711         {
 712                 let invoice = self.try_build_signed::<_, ()>(|hash| {
 713                         Ok(sign_function(hash))
 714                 });
 715
 716                 match invoice {
 717                         Ok(i) => Ok(i),
 718                         Err(SignOrCreationError::CreationError(e)) => Err(e),
 719                         Err(SignOrCreationError::SignError(())) => unreachable!(),
 720                 }
 721         }
 722
 723         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
 724         /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
 725         /// if applicable also for the included payee public key.
 726         pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Invoice, SignOrCreationError<E>>
 727                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 728         {
 729                 let raw = match self.build_raw() {
 730                         Ok(r) => r,
 731                         Err(e) => return Err(SignOrCreationError::CreationError(e)),
 732                 };
 733
 734                 let signed = match raw.sign(sign_function) {
 735                         Ok(s) => s,
 736                         Err(e) => return Err(SignOrCreationError::SignError(e)),
 737                 };
 738
 739                 let invoice = Invoice {
 740                         signed_invoice: signed,
 741                 };
 742
 743                 invoice.check_field_counts().expect("should be ensured by type signature of builder");
 744                 invoice.check_feature_bits().expect("should be ensured by type signature of builder");
 745                 invoice.check_amount().expect("should be ensured by type signature of builder");
 746
 747                 Ok(invoice)
 748         }
 749 }
 750
 751
 752 impl SignedRawInvoice {
 753         /// Disassembles the `SignedRawInvoice` into its three parts:
 754         ///  1. raw invoice
 755         ///  2. hash of the raw invoice
 756         ///  3. signature
 757         pub fn into_parts(self) -> (RawInvoice, [u8; 32], InvoiceSignature) {
 758                 (self.raw_invoice, self.hash, self.signature)
 759         }
 760
 761         /// The [`RawInvoice`] which was signed.
 762         pub fn raw_invoice(&self) -> &RawInvoice {
 763                 &self.raw_invoice
 764         }
 765
 766         /// The hash of the [`RawInvoice`] that was signed.
 767         pub fn signable_hash(&self) -> &[u8; 32] {
 768                 &self.hash
 769         }
 770
 771         /// Signature for the invoice.
 772         pub fn signature(&self) -> &InvoiceSignature {
 773                 &self.signature
 774         }
 775
 776         /// Recovers the public key used for signing the invoice from the recoverable signature.
 777         pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
 778                 let hash = Message::from_slice(&self.hash[..])
 779                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 780
 781                 Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
 782                         &hash,
 783                         &self.signature
 784                 )?))
 785         }
 786
 787         /// Checks if the signature is valid for the included payee public key or if none exists if it's
 788         /// valid for the recovered signature (which should always be true?).
 789         pub fn check_signature(&self) -> bool {
 790                 let included_pub_key = self.raw_invoice.payee_pub_key();
 791
 792                 let mut recovered_pub_key = Option::None;
 793                 if recovered_pub_key.is_none() {
 794                         let recovered = match self.recover_payee_pub_key() {
 795                                 Ok(pk) => pk,
 796                                 Err(_) => return false,
 797                         };
 798                         recovered_pub_key = Some(recovered);
 799                 }
 800
 801                 let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
 802                         .expect("One is always present");
 803
 804                 let hash = Message::from_slice(&self.hash[..])
 805                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 806
 807                 let secp_context = Secp256k1::new();
 808                 let verification_result = secp_context.verify_ecdsa(
 809                         &hash,
 810                         &self.signature.to_standard(),
 811                         pub_key
 812                 );
 813
 814                 match verification_result {
 815                         Ok(()) => true,
 816                         Err(_) => false,
 817                 }
 818         }
 819 }
 820
 821 /// Finds the first element of an enum stream of a given variant and extracts one member of the
 822 /// variant. If no element was found `None` gets returned.
 823 ///
 824 /// The following example would extract the first B.
 825 ///
 826 /// ```ignore
 827 /// enum Enum {
 828 ///     A(u8),
 829 ///     B(u16)
 830 /// }
 831 ///
 832 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 833 ///
 834 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
 835 /// ```
 836 macro_rules! find_extract {
 837         ($iter:expr, $enm:pat, $enm_var:ident) => {
 838                 find_all_extract!($iter, $enm, $enm_var).next()
 839         };
 840 }
 841
 842 /// Finds the all elements of an enum stream of a given variant and extracts one member of the
 843 /// variant through an iterator.
 844 ///
 845 /// The following example would extract all A.
 846 ///
 847 /// ```ignore
 848 /// enum Enum {
 849 ///     A(u8),
 850 ///     B(u16)
 851 /// }
 852 ///
 853 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 854 ///
 855 /// assert_eq!(
 856 ///     find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
 857 ///     vec![1u8, 2u8, 4u8]
 858 /// );
 859 /// ```
 860 macro_rules! find_all_extract {
 861         ($iter:expr, $enm:pat, $enm_var:ident) => {
 862                 $iter.filter_map(|tf| match *tf {
 863                         $enm => Some($enm_var),
 864                         _ => None,
 865                 })
 866         };
 867 }
 868
 869 #[allow(missing_docs)]
 870 impl RawInvoice {
 871         /// Hash the HRP as bytes and signatureless data part.
 872         fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
 873                 let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
 874                 let mut hash: [u8; 32] = Default::default();
 875                 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
 876                 hash
 877         }
 878
 879         /// Calculate the hash of the encoded `RawInvoice` which should be signed.
 880         pub fn signable_hash(&self) -> [u8; 32] {
 881                 use bech32::ToBase32;
 882
 883                 RawInvoice::hash_from_parts(
 884                         self.hrp.to_string().as_bytes(),
 885                         &self.data.to_base32()
 886                 )
 887         }
 888
 889         /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
 890         /// type `E`. Since the signature of a [`SignedRawInvoice`] is not required to be valid there
 891         /// are no constraints regarding the validity of the produced signature.
 892         ///
 893         /// This is not exported to bindings users as we don't currently support passing function pointers into methods
 894         /// explicitly.
 895         pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
 896                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 897         {
 898                 let raw_hash = self.signable_hash();
 899                 let hash = Message::from_slice(&raw_hash[..])
 900                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 901                 let signature = sign_method(&hash)?;
 902
 903                 Ok(SignedRawInvoice {
 904                         raw_invoice: self,
 905                         hash: raw_hash,
 906                         signature: InvoiceSignature(signature),
 907                 })
 908         }
 909
 910         /// Returns an iterator over all tagged fields with known semantics.
 911         ///
 912         /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
 913         pub fn known_tagged_fields(&self)
 914                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
 915         {
 916                 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
 917                 // function's type signature.
 918                 // TODO: refactor once impl Trait is available
 919                 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
 920                         match *raw {
 921                                 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
 922                                 _ => None,
 923                         }
 924                 }
 925
 926                 self.data.tagged_fields.iter().filter_map(match_raw )
 927         }
 928
 929         pub fn payment_hash(&self) -> Option<&Sha256> {
 930                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
 931         }
 932
 933         pub fn description(&self) -> Option<&Description> {
 934                 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
 935         }
 936
 937         pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
 938                 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
 939         }
 940
 941         pub fn description_hash(&self) -> Option<&Sha256> {
 942                 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
 943         }
 944
 945         pub fn expiry_time(&self) -> Option<&ExpiryTime> {
 946                 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
 947         }
 948
 949         pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
 950                 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
 951         }
 952
 953         pub fn payment_secret(&self) -> Option<&PaymentSecret> {
 954                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
 955         }
 956
 957         pub fn features(&self) -> Option<&InvoiceFeatures> {
 958                 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
 959         }
 960
 961         /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
 962         pub fn fallbacks(&self) -> Vec<&Fallback> {
 963                 find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
 964         }
 965
 966         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
 967                 find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
 968         }
 969
 970         pub fn amount_pico_btc(&self) -> Option<u64> {
 971                 self.hrp.raw_amount.map(|v| {
 972                         v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
 973                 })
 974         }
 975
 976         pub fn currency(&self) -> Currency {
 977                 self.hrp.currency.clone()
 978         }
 979 }
 980
 981 impl PositiveTimestamp {
 982         /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
 983         ///
 984         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
 985         pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
 986                 if unix_seconds <= MAX_TIMESTAMP {
 987                         Ok(Self(Duration::from_secs(unix_seconds)))
 988                 } else {
 989                         Err(CreationError::TimestampOutOfBounds)
 990                 }
 991         }
 992
 993         /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
 994         /// the range `0..=MAX_TIMESTAMP`.
 995         ///
 996         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
 997         ///
 998         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
 999         #[cfg(feature = "std")]
1000         pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
1001                 time.duration_since(SystemTime::UNIX_EPOCH)
1002                         .map(Self::from_duration_since_epoch)
1003                         .unwrap_or(Err(CreationError::TimestampOutOfBounds))
1004         }
1005
1006         /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
1007         /// `0..=MAX_TIMESTAMP`.
1008         ///
1009         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1010         ///
1011         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1012         pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
1013                 Self::from_unix_timestamp(duration.as_secs())
1014         }
1015
1016         /// Returns the Unix timestamp representing the stored time
1017         pub fn as_unix_timestamp(&self) -> u64 {
1018                 self.0.as_secs()
1019         }
1020
1021         /// Returns the duration of the stored time since the Unix epoch
1022         pub fn as_duration_since_epoch(&self) -> Duration {
1023                 self.0
1024         }
1025
1026         /// Returns the [`SystemTime`] representing the stored time
1027         #[cfg(feature = "std")]
1028         pub fn as_time(&self) -> SystemTime {
1029                 SystemTime::UNIX_EPOCH + self.0
1030         }
1031 }
1032
1033 #[cfg(feature = "std")]
1034 impl From<PositiveTimestamp> for SystemTime {
1035         fn from(val: PositiveTimestamp) -> Self {
1036                 SystemTime::UNIX_EPOCH + val.0
1037         }
1038 }
1039
1040 impl Invoice {
1041         /// The hash of the [`RawInvoice`] that was signed.
1042         pub fn signable_hash(&self) -> [u8; 32] {
1043                 self.signed_invoice.hash
1044         }
1045
1046         /// Transform the `Invoice` into it's unchecked version
1047         pub fn into_signed_raw(self) -> SignedRawInvoice {
1048                 self.signed_invoice
1049         }
1050
1051         /// Check that all mandatory fields are present
1052         fn check_field_counts(&self) -> Result<(), SemanticError> {
1053                 // "A writer MUST include exactly one p field […]."
1054                 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1055                         TaggedField::PaymentHash(_) => true,
1056                         _ => false,
1057                 }).count();
1058                 if payment_hash_cnt < 1 {
1059                         return Err(SemanticError::NoPaymentHash);
1060                 } else if payment_hash_cnt > 1 {
1061                         return Err(SemanticError::MultiplePaymentHashes);
1062                 }
1063
1064                 // "A writer MUST include either exactly one d or exactly one h field."
1065                 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1066                         TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1067                         _ => false,
1068                 }).count();
1069                 if  description_cnt < 1 {
1070                         return Err(SemanticError::NoDescription);
1071                 } else if description_cnt > 1 {
1072                         return  Err(SemanticError::MultipleDescriptions);
1073                 }
1074
1075                 self.check_payment_secret()?;
1076
1077                 Ok(())
1078         }
1079
1080         /// Checks that there is exactly one payment secret field
1081         fn check_payment_secret(&self) -> Result<(), SemanticError> {
1082                 // "A writer MUST include exactly one `s` field."
1083                 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1084                         TaggedField::PaymentSecret(_) => true,
1085                         _ => false,
1086                 }).count();
1087                 if payment_secret_count < 1 {
1088                         return Err(SemanticError::NoPaymentSecret);
1089                 } else if payment_secret_count > 1 {
1090                         return Err(SemanticError::MultiplePaymentSecrets);
1091                 }
1092
1093                 Ok(())
1094         }
1095
1096         /// Check that amount is a whole number of millisatoshis
1097         fn check_amount(&self) -> Result<(), SemanticError> {
1098                 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1099                         if amount_pico_btc % 10 != 0 {
1100                                 return Err(SemanticError::ImpreciseAmount);
1101                         }
1102                 }
1103                 Ok(())
1104         }
1105
1106         /// Check that feature bits are set as required
1107         fn check_feature_bits(&self) -> Result<(), SemanticError> {
1108                 self.check_payment_secret()?;
1109
1110                 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1111                 // (this requirement has been since removed, and we now require the payment secret
1112                 // feature bit always).
1113                 let features = self.tagged_fields().find(|&tf| match *tf {
1114                         TaggedField::Features(_) => true,
1115                         _ => false,
1116                 });
1117                 match features {
1118                         None => Err(SemanticError::InvalidFeatures),
1119                         Some(TaggedField::Features(features)) => {
1120                                 if features.requires_unknown_bits() {
1121                                         Err(SemanticError::InvalidFeatures)
1122                                 } else if !features.supports_payment_secret() {
1123                                         Err(SemanticError::InvalidFeatures)
1124                                 } else {
1125                                         Ok(())
1126                                 }
1127                         },
1128                         Some(_) => unreachable!(),
1129                 }
1130         }
1131
1132         /// Check that the invoice is signed correctly and that key recovery works
1133         pub fn check_signature(&self) -> Result<(), SemanticError> {
1134                 match self.signed_invoice.recover_payee_pub_key() {
1135                         Err(secp256k1::Error::InvalidRecoveryId) =>
1136                                 return Err(SemanticError::InvalidRecoveryId),
1137                         Err(secp256k1::Error::InvalidSignature) =>
1138                                 return Err(SemanticError::InvalidSignature),
1139                         Err(e) => panic!("no other error may occur, got {:?}", e),
1140                         Ok(_) => {},
1141                 }
1142
1143                 if !self.signed_invoice.check_signature() {
1144                         return Err(SemanticError::InvalidSignature);
1145                 }
1146
1147                 Ok(())
1148         }
1149
1150         /// Constructs an `Invoice` from a [`SignedRawInvoice`] by checking all its invariants.
1151         /// ```
1152         /// use lightning_invoice::*;
1153         ///
1154         /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1155         /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1156         /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1157         /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1158         /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1159         /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1160         /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1161         /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1162         /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1163         /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1164         /// j5r6drg6k6zcqj0fcwg";
1165         ///
1166         /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
1167         ///
1168         /// assert!(Invoice::from_signed(signed).is_ok());
1169         /// ```
1170         pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
1171                 let invoice = Invoice {
1172                         signed_invoice,
1173                 };
1174                 invoice.check_field_counts()?;
1175                 invoice.check_feature_bits()?;
1176                 invoice.check_signature()?;
1177                 invoice.check_amount()?;
1178
1179                 Ok(invoice)
1180         }
1181
1182         /// Returns the `Invoice`'s timestamp (should equal its creation time)
1183         #[cfg(feature = "std")]
1184         pub fn timestamp(&self) -> SystemTime {
1185                 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1186         }
1187
1188         /// Returns the `Invoice`'s timestamp as a duration since the Unix epoch
1189         pub fn duration_since_epoch(&self) -> Duration {
1190                 self.signed_invoice.raw_invoice().data.timestamp.0
1191         }
1192
1193         /// Returns an iterator over all tagged fields of this Invoice.
1194         ///
1195         /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1196         pub fn tagged_fields(&self)
1197                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1198                 self.signed_invoice.raw_invoice().known_tagged_fields()
1199         }
1200
1201         /// Returns the hash to which we will receive the preimage on completion of the payment
1202         pub fn payment_hash(&self) -> &sha256::Hash {
1203                 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1204         }
1205
1206         /// Return the description or a hash of it for longer ones
1207         ///
1208         /// This is not exported to bindings users because we don't yet export InvoiceDescription
1209         pub fn description(&self) -> InvoiceDescription {
1210                 if let Some(direct) = self.signed_invoice.description() {
1211                         return InvoiceDescription::Direct(direct);
1212                 } else if let Some(hash) = self.signed_invoice.description_hash() {
1213                         return InvoiceDescription::Hash(hash);
1214                 }
1215                 unreachable!("ensured by constructor");
1216         }
1217
1218         /// Get the payee's public key if one was included in the invoice
1219         pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1220                 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1221         }
1222
1223         /// Get the payment secret if one was included in the invoice
1224         pub fn payment_secret(&self) -> &PaymentSecret {
1225                 self.signed_invoice.payment_secret().expect("was checked by constructor")
1226         }
1227
1228         /// Get the invoice features if they were included in the invoice
1229         pub fn features(&self) -> Option<&InvoiceFeatures> {
1230                 self.signed_invoice.features()
1231         }
1232
1233         /// Recover the payee's public key (only to be used if none was included in the invoice)
1234         pub fn recover_payee_pub_key(&self) -> PublicKey {
1235                 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1236         }
1237
1238         /// Returns the Duration since the Unix epoch at which the invoice expires.
1239         /// Returning None if overflow occurred.
1240         pub fn expires_at(&self) -> Option<Duration> {
1241                 self.duration_since_epoch().checked_add(self.expiry_time())
1242         }
1243
1244         /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1245         pub fn expiry_time(&self) -> Duration {
1246                 self.signed_invoice.expiry_time()
1247                         .map(|x| x.0)
1248                         .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1249         }
1250
1251         /// Returns whether the invoice has expired.
1252         #[cfg(feature = "std")]
1253         pub fn is_expired(&self) -> bool {
1254                 Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
1255         }
1256
1257         /// Returns whether the expiry time from the given epoch has passed.
1258         #[cfg(feature = "std")]
1259         pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
1260                 match epoch.elapsed() {
1261                         Ok(elapsed) => elapsed > expiry_time,
1262                         Err(_) => false,
1263                 }
1264         }
1265
1266         /// Returns the Duration remaining until the invoice expires.
1267         #[cfg(feature = "std")]
1268         pub fn duration_until_expiry(&self) -> Duration {
1269                 SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
1270                         .map(|now| self.expiration_remaining_from_epoch(now))
1271                         .unwrap_or(Duration::from_nanos(0))
1272         }
1273
1274         /// Returns the Duration remaining until the invoice expires given the current time.
1275         /// `time` is the timestamp as a duration since the Unix epoch.
1276         pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
1277                 self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
1278         }
1279
1280         /// Returns whether the expiry time would pass at the given point in time.
1281         /// `at_time` is the timestamp as a duration since the Unix epoch.
1282         pub fn would_expire(&self, at_time: Duration) -> bool {
1283                 self.duration_since_epoch()
1284                         .checked_add(self.expiry_time())
1285                         .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
1286         }
1287
1288         /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
1289         /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
1290         pub fn min_final_cltv_expiry_delta(&self) -> u64 {
1291                 self.signed_invoice.min_final_cltv_expiry_delta()
1292                         .map(|x| x.0)
1293                         .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
1294         }
1295
1296         /// Returns a list of all fallback addresses
1297         ///
1298         /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1299         pub fn fallbacks(&self) -> Vec<&Fallback> {
1300                 self.signed_invoice.fallbacks()
1301         }
1302
1303         /// Returns a list of all routes included in the invoice
1304         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1305                 self.signed_invoice.private_routes()
1306         }
1307
1308         /// Returns a list of all routes included in the invoice as the underlying hints
1309         pub fn route_hints(&self) -> Vec<RouteHint> {
1310                 find_all_extract!(
1311                         self.signed_invoice.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x
1312                 ).map(|route| (**route).clone()).collect()
1313         }
1314
1315         /// Returns the currency for which the invoice was issued
1316         pub fn currency(&self) -> Currency {
1317                 self.signed_invoice.currency()
1318         }
1319
1320         /// Returns the amount if specified in the invoice as millisatoshis.
1321         pub fn amount_milli_satoshis(&self) -> Option<u64> {
1322                 self.signed_invoice.amount_pico_btc().map(|v| v / 10)
1323         }
1324
1325         /// Returns the amount if specified in the invoice as pico BTC.
1326         fn amount_pico_btc(&self) -> Option<u64> {
1327                 self.signed_invoice.amount_pico_btc()
1328         }
1329 }
1330
1331 impl From<TaggedField> for RawTaggedField {
1332         fn from(tf: TaggedField) -> Self {
1333                 RawTaggedField::KnownSemantics(tf)
1334         }
1335 }
1336
1337 impl TaggedField {
1338         /// Numeric representation of the field's tag
1339         pub fn tag(&self) -> u5 {
1340                 let tag = match *self {
1341                         TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1342                         TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1343                         TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1344                         TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1345                         TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1346                         TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
1347                         TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1348                         TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
1349                         TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1350                         TaggedField::Features(_) => constants::TAG_FEATURES,
1351                 };
1352
1353                 u5::try_from_u8(tag).expect("all tags defined are <32")
1354         }
1355 }
1356
1357 impl Description {
1358
1359         /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1360         /// returns [`CreationError::DescriptionTooLong`] otherwise
1361         ///
1362         /// Please note that single characters may use more than one byte due to UTF8 encoding.
1363         pub fn new(description: String) -> Result<Description, CreationError> {
1364                 if description.len() > 639 {
1365                         Err(CreationError::DescriptionTooLong)
1366                 } else {
1367                         Ok(Description(description))
1368                 }
1369         }
1370
1371         /// Returns the underlying description [`String`]
1372         pub fn into_inner(self) -> String {
1373                 self.0
1374         }
1375 }
1376
1377 impl From<Description> for String {
1378         fn from(val: Description) -> Self {
1379                 val.into_inner()
1380         }
1381 }
1382
1383 impl Deref for Description {
1384         type Target = str;
1385
1386         fn deref(&self) -> &str {
1387                 &self.0
1388         }
1389 }
1390
1391 impl From<PublicKey> for PayeePubKey {
1392         fn from(pk: PublicKey) -> Self {
1393                 PayeePubKey(pk)
1394         }
1395 }
1396
1397 impl Deref for PayeePubKey {
1398         type Target = PublicKey;
1399
1400         fn deref(&self) -> &PublicKey {
1401                 &self.0
1402         }
1403 }
1404
1405 impl ExpiryTime {
1406         /// Construct an `ExpiryTime` from seconds.
1407         pub fn from_seconds(seconds: u64) -> ExpiryTime {
1408                 ExpiryTime(Duration::from_secs(seconds))
1409         }
1410
1411         /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
1412         pub fn from_duration(duration: Duration) -> ExpiryTime {
1413                 Self::from_seconds(duration.as_secs())
1414         }
1415
1416         /// Returns the expiry time in seconds
1417         pub fn as_seconds(&self) -> u64 {
1418                 self.0.as_secs()
1419         }
1420
1421         /// Returns a reference to the underlying [`Duration`] (=expiry time)
1422         pub fn as_duration(&self) -> &Duration {
1423                 &self.0
1424         }
1425 }
1426
1427 impl PrivateRoute {
1428         /// Creates a new (partial) route from a list of hops
1429         pub fn new(hops: RouteHint) -> Result<PrivateRoute, CreationError> {
1430                 if hops.0.len() <= 12 {
1431                         Ok(PrivateRoute(hops))
1432                 } else {
1433                         Err(CreationError::RouteTooLong)
1434                 }
1435         }
1436
1437         /// Returns the underlying list of hops
1438         pub fn into_inner(self) -> RouteHint {
1439                 self.0
1440         }
1441 }
1442
1443 impl From<PrivateRoute> for RouteHint {
1444         fn from(val: PrivateRoute) -> Self {
1445                 val.into_inner()
1446         }
1447 }
1448
1449 impl Deref for PrivateRoute {
1450         type Target = RouteHint;
1451
1452         fn deref(&self) -> &RouteHint {
1453                 &self.0
1454         }
1455 }
1456
1457 impl Deref for InvoiceSignature {
1458         type Target = RecoverableSignature;
1459
1460         fn deref(&self) -> &RecoverableSignature {
1461                 &self.0
1462         }
1463 }
1464
1465 impl Deref for SignedRawInvoice {
1466         type Target = RawInvoice;
1467
1468         fn deref(&self) -> &RawInvoice {
1469                 &self.raw_invoice
1470         }
1471 }
1472
1473 /// Errors that may occur when constructing a new [`RawInvoice`] or [`Invoice`]
1474 #[derive(Eq, PartialEq, Debug, Clone)]
1475 pub enum CreationError {
1476         /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
1477         DescriptionTooLong,
1478
1479         /// The specified route has too many hops and can't be encoded
1480         RouteTooLong,
1481
1482         /// The Unix timestamp of the supplied date is less than zero or greater than 35-bits
1483         TimestampOutOfBounds,
1484
1485         /// The supplied millisatoshi amount was greater than the total bitcoin supply.
1486         InvalidAmount,
1487
1488         /// Route hints were required for this invoice and were missing. Applies to
1489         /// [phantom invoices].
1490         ///
1491         /// [phantom invoices]: crate::utils::create_phantom_invoice
1492         MissingRouteHints,
1493
1494         /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
1495         ///
1496         /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
1497         MinFinalCltvExpiryDeltaTooShort,
1498 }
1499
1500 impl Display for CreationError {
1501         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1502                 match self {
1503                         CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1504                         CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1505                         CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
1506                         CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
1507                         CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
1508                         CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
1509                                 "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
1510                 }
1511         }
1512 }
1513
1514 #[cfg(feature = "std")]
1515 impl std::error::Error for CreationError { }
1516
1517 /// Errors that may occur when converting a [`RawInvoice`] to an [`Invoice`]. They relate to the
1518 /// requirements sections in BOLT #11
1519 #[derive(Eq, PartialEq, Debug, Clone)]
1520 pub enum SemanticError {
1521         /// The invoice is missing the mandatory payment hash
1522         NoPaymentHash,
1523
1524         /// The invoice has multiple payment hashes which isn't allowed
1525         MultiplePaymentHashes,
1526
1527         /// No description or description hash are part of the invoice
1528         NoDescription,
1529
1530         /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1531         MultipleDescriptions,
1532
1533         /// The invoice is missing the mandatory payment secret, which all modern lightning nodes
1534         /// should provide.
1535         NoPaymentSecret,
1536
1537         /// The invoice contains multiple payment secrets
1538         MultiplePaymentSecrets,
1539
1540         /// The invoice's features are invalid
1541         InvalidFeatures,
1542
1543         /// The recovery id doesn't fit the signature/pub key
1544         InvalidRecoveryId,
1545
1546         /// The invoice's signature is invalid
1547         InvalidSignature,
1548
1549         /// The invoice's amount was not a whole number of millisatoshis
1550         ImpreciseAmount,
1551 }
1552
1553 impl Display for SemanticError {
1554         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1555                 match self {
1556                         SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1557                         SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1558                         SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1559                         SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1560                         SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
1561                         SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
1562                         SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
1563                         SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1564                         SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1565                         SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
1566                 }
1567         }
1568 }
1569
1570 #[cfg(feature = "std")]
1571 impl std::error::Error for SemanticError { }
1572
1573 /// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
1574 /// may occur.
1575 #[derive(Eq, PartialEq, Debug, Clone)]
1576 pub enum SignOrCreationError<S = ()> {
1577         /// An error occurred during signing
1578         SignError(S),
1579
1580         /// An error occurred while building the transaction
1581         CreationError(CreationError),
1582 }
1583
1584 impl<S> Display for SignOrCreationError<S> {
1585         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1586                 match self {
1587                         SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1588                         SignOrCreationError::CreationError(err) => err.fmt(f),
1589                 }
1590         }
1591 }
1592
1593 #[cfg(feature = "serde")]
1594 impl Serialize for Invoice {
1595         fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer {
1596                 serializer.serialize_str(self.to_string().as_str())
1597         }
1598 }
1599 #[cfg(feature = "serde")]
1600 impl<'de> Deserialize<'de> for Invoice {
1601         fn deserialize<D>(deserializer: D) -> Result<Invoice, D::Error> where D: Deserializer<'de> {
1602                 let bolt11 = String::deserialize(deserializer)?
1603                         .parse::<Invoice>()
1604                         .map_err(|e| D::Error::custom(format!("{:?}", e)))?;
1605
1606                 Ok(bolt11)
1607         }
1608 }
1609
1610 #[cfg(test)]
1611 mod test {
1612         use bitcoin_hashes::hex::FromHex;
1613         use bitcoin_hashes::sha256;
1614
1615         #[test]
1616         fn test_system_time_bounds_assumptions() {
1617                 assert_eq!(
1618                         crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
1619                         Err(crate::CreationError::TimestampOutOfBounds)
1620                 );
1621         }
1622
1623         #[test]
1624         fn test_calc_invoice_hash() {
1625                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1626                 use crate::TaggedField::*;
1627
1628                 let invoice = RawInvoice {
1629                         hrp: RawHrp {
1630                                 currency: Currency::Bitcoin,
1631                                 raw_amount: None,
1632                                 si_prefix: None,
1633                         },
1634                         data: RawDataPart {
1635                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1636                                 tagged_fields: vec![
1637                                         PaymentHash(crate::Sha256(sha256::Hash::from_hex(
1638                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1639                                         ).unwrap())).into(),
1640                                         Description(crate::Description::new(
1641                                                 "Please consider supporting this project".to_owned()
1642                                         ).unwrap()).into(),
1643                                 ],
1644                         },
1645                 };
1646
1647                 let expected_hash = [
1648                         0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1649                         0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1650                         0xd5, 0x18, 0xe1, 0xc9
1651                 ];
1652
1653                 assert_eq!(invoice.signable_hash(), expected_hash)
1654         }
1655
1656         #[test]
1657         fn test_check_signature() {
1658                 use crate::TaggedField::*;
1659                 use secp256k1::Secp256k1;
1660                 use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
1661                 use secp256k1::{SecretKey, PublicKey};
1662                 use crate::{SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
1663                          PositiveTimestamp};
1664
1665                 let invoice = SignedRawInvoice {
1666                         raw_invoice: RawInvoice {
1667                                 hrp: RawHrp {
1668                                         currency: Currency::Bitcoin,
1669                                         raw_amount: None,
1670                                         si_prefix: None,
1671                                 },
1672                                 data: RawDataPart {
1673                                         timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1674                                         tagged_fields: vec ! [
1675                                                 PaymentHash(Sha256(sha256::Hash::from_hex(
1676                                                         "0001020304050607080900010203040506070809000102030405060708090102"
1677                                                 ).unwrap())).into(),
1678                                                 Description(
1679                                                         crate::Description::new(
1680                                                                 "Please consider supporting this project".to_owned()
1681                                                         ).unwrap()
1682                                                 ).into(),
1683                                         ],
1684                                 },
1685                         },
1686                         hash: [
1687                                 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1688                                 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1689                                 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1690                         ],
1691                         signature: InvoiceSignature(RecoverableSignature::from_compact(
1692                                 & [
1693                                         0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1694                                         0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1695                                         0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1696                                         0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1697                                         0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1698                                         0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1699                                 ],
1700                                 RecoveryId::from_i32(0).unwrap()
1701                         ).unwrap()),
1702                 };
1703
1704                 assert!(invoice.check_signature());
1705
1706                 let private_key = SecretKey::from_slice(
1707                         &[
1708                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1709                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1710                                 0x3b, 0x2d, 0xb7, 0x34
1711                         ][..]
1712                 ).unwrap();
1713                 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1714
1715                 assert_eq!(invoice.recover_payee_pub_key(), Ok(crate::PayeePubKey(public_key)));
1716
1717                 let (raw_invoice, _, _) = invoice.into_parts();
1718                 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1719                         Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key))
1720                 }).unwrap();
1721
1722                 assert!(new_signed.check_signature());
1723         }
1724
1725         #[test]
1726         fn test_check_feature_bits() {
1727                 use crate::TaggedField::*;
1728                 use lightning::ln::features::InvoiceFeatures;
1729                 use secp256k1::Secp256k1;
1730                 use secp256k1::SecretKey;
1731                 use crate::{RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
1732                          SemanticError};
1733
1734                 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
1735                 let payment_secret = lightning::ln::PaymentSecret([21; 32]);
1736                 let invoice_template = RawInvoice {
1737                         hrp: RawHrp {
1738                                 currency: Currency::Bitcoin,
1739                                 raw_amount: None,
1740                                 si_prefix: None,
1741                         },
1742                         data: RawDataPart {
1743                                 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1744                                 tagged_fields: vec ! [
1745                                         PaymentHash(Sha256(sha256::Hash::from_hex(
1746                                                 "0001020304050607080900010203040506070809000102030405060708090102"
1747                                         ).unwrap())).into(),
1748                                         Description(
1749                                                 crate::Description::new(
1750                                                         "Please consider supporting this project".to_owned()
1751                                                 ).unwrap()
1752                                         ).into(),
1753                                 ],
1754                         },
1755                 };
1756
1757                 // Missing features
1758                 let invoice = {
1759                         let mut invoice = invoice_template.clone();
1760                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1761                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1762                 }.unwrap();
1763                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1764
1765                 // Missing feature bits
1766                 let invoice = {
1767                         let mut invoice = invoice_template.clone();
1768                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1769                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1770                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1771                 }.unwrap();
1772                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
1773
1774                 let mut payment_secret_features = InvoiceFeatures::empty();
1775                 payment_secret_features.set_payment_secret_required();
1776
1777                 // Including payment secret and feature bits
1778                 let invoice = {
1779                         let mut invoice = invoice_template.clone();
1780                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1781                         invoice.data.tagged_fields.push(Features(payment_secret_features.clone()).into());
1782                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1783                 }.unwrap();
1784                 assert!(Invoice::from_signed(invoice).is_ok());
1785
1786                 // No payment secret or features
1787                 let invoice = {
1788                         let invoice = invoice_template.clone();
1789                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1790                 }.unwrap();
1791                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1792
1793                 // No payment secret or feature bits
1794                 let invoice = {
1795                         let mut invoice = invoice_template.clone();
1796                         invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
1797                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1798                 }.unwrap();
1799                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1800
1801                 // Missing payment secret
1802                 let invoice = {
1803                         let mut invoice = invoice_template.clone();
1804                         invoice.data.tagged_fields.push(Features(payment_secret_features).into());
1805                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1806                 }.unwrap();
1807                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
1808
1809                 // Multiple payment secrets
1810                 let invoice = {
1811                         let mut invoice = invoice_template;
1812                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1813                         invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1814                         invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1815                 }.unwrap();
1816                 assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::MultiplePaymentSecrets));
1817         }
1818
1819         #[test]
1820         fn test_builder_amount() {
1821                 use crate::*;
1822
1823                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1824                         .description("Test".into())
1825                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1826                         .duration_since_epoch(Duration::from_secs(1234567));
1827
1828                 let invoice = builder.clone()
1829                         .amount_milli_satoshis(1500)
1830                         .build_raw()
1831                         .unwrap();
1832
1833                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1834                 assert_eq!(invoice.hrp.raw_amount, Some(15));
1835
1836
1837                 let invoice = builder
1838                         .amount_milli_satoshis(150)
1839                         .build_raw()
1840                         .unwrap();
1841
1842                 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1843                 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1844         }
1845
1846         #[test]
1847         fn test_builder_fail() {
1848                 use crate::*;
1849                 use lightning::routing::router::RouteHintHop;
1850                 use std::iter::FromIterator;
1851                 use secp256k1::PublicKey;
1852
1853                 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1854                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1855                         .duration_since_epoch(Duration::from_secs(1234567))
1856                         .min_final_cltv_expiry_delta(144);
1857
1858                 let too_long_string = String::from_iter(
1859                         (0..1024).map(|_| '?')
1860                 );
1861
1862                 let long_desc_res = builder.clone()
1863                         .description(too_long_string)
1864                         .build_raw();
1865                 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
1866
1867                 let route_hop = RouteHintHop {
1868                         src_node_id: PublicKey::from_slice(
1869                                         &[
1870                                                 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
1871                                                 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
1872                                                 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
1873                                         ][..]
1874                                 ).unwrap(),
1875                         short_channel_id: 0,
1876                         fees: RoutingFees {
1877                                 base_msat: 0,
1878                                 proportional_millionths: 0,
1879                         },
1880                         cltv_expiry_delta: 0,
1881                         htlc_minimum_msat: None,
1882                         htlc_maximum_msat: None,
1883                 };
1884                 let too_long_route = RouteHint(vec![route_hop; 13]);
1885                 let long_route_res = builder.clone()
1886                         .description("Test".into())
1887                         .private_route(too_long_route)
1888                         .build_raw();
1889                 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
1890
1891                 let sign_error_res = builder
1892                         .description("Test".into())
1893                         .payment_secret(PaymentSecret([0; 32]))
1894                         .try_build_signed(|_| {
1895                                 Err("ImaginaryError")
1896                         });
1897                 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
1898         }
1899
1900         #[test]
1901         fn test_builder_ok() {
1902                 use crate::*;
1903                 use lightning::routing::router::RouteHintHop;
1904                 use secp256k1::Secp256k1;
1905                 use secp256k1::{SecretKey, PublicKey};
1906                 use std::time::{UNIX_EPOCH, Duration};
1907
1908                 let secp_ctx = Secp256k1::new();
1909
1910                 let private_key = SecretKey::from_slice(
1911                         &[
1912                                 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1913                                 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1914                                 0x3b, 0x2d, 0xb7, 0x34
1915                         ][..]
1916                 ).unwrap();
1917                 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
1918
1919                 let route_1 = RouteHint(vec![
1920                         RouteHintHop {
1921                                 src_node_id: public_key,
1922                                 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
1923                                 fees: RoutingFees {
1924                                         base_msat: 2,
1925                                         proportional_millionths: 1,
1926                                 },
1927                                 cltv_expiry_delta: 145,
1928                                 htlc_minimum_msat: None,
1929                                 htlc_maximum_msat: None,
1930                         },
1931                         RouteHintHop {
1932                                 src_node_id: public_key,
1933                                 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
1934                                 fees: RoutingFees {
1935                                         base_msat: 3,
1936                                         proportional_millionths: 2,
1937                                 },
1938                                 cltv_expiry_delta: 146,
1939                                 htlc_minimum_msat: None,
1940                                 htlc_maximum_msat: None,
1941                         }
1942                 ]);
1943
1944                 let route_2 = RouteHint(vec![
1945                         RouteHintHop {
1946                                 src_node_id: public_key,
1947                                 short_channel_id: 0,
1948                                 fees: RoutingFees {
1949                                         base_msat: 4,
1950                                         proportional_millionths: 3,
1951                                 },
1952                                 cltv_expiry_delta: 147,
1953                                 htlc_minimum_msat: None,
1954                                 htlc_maximum_msat: None,
1955                         },
1956                         RouteHintHop {
1957                                 src_node_id: public_key,
1958                                 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
1959                                 fees: RoutingFees {
1960                                         base_msat: 5,
1961                                         proportional_millionths: 4,
1962                                 },
1963                                 cltv_expiry_delta: 148,
1964                                 htlc_minimum_msat: None,
1965                                 htlc_maximum_msat: None,
1966                         }
1967                 ]);
1968
1969                 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
1970                         .amount_milli_satoshis(123)
1971                         .duration_since_epoch(Duration::from_secs(1234567))
1972                         .payee_pub_key(public_key)
1973                         .expiry_time(Duration::from_secs(54321))
1974                         .min_final_cltv_expiry_delta(144)
1975                         .fallback(Fallback::PubKeyHash([0;20]))
1976                         .private_route(route_1.clone())
1977                         .private_route(route_2.clone())
1978                         .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
1979                         .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap())
1980                         .payment_secret(PaymentSecret([42; 32]))
1981                         .basic_mpp();
1982
1983                 let invoice = builder.clone().build_signed(|hash| {
1984                         secp_ctx.sign_ecdsa_recoverable(hash, &private_key)
1985                 }).unwrap();
1986
1987                 assert!(invoice.check_signature().is_ok());
1988                 assert_eq!(invoice.tagged_fields().count(), 10);
1989
1990                 assert_eq!(invoice.amount_milli_satoshis(), Some(123));
1991                 assert_eq!(invoice.amount_pico_btc(), Some(1230));
1992                 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
1993                 #[cfg(feature = "std")]
1994                 assert_eq!(
1995                         invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1996                         1234567
1997                 );
1998                 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
1999                 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
2000                 assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
2001                 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
2002                 assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
2003                 assert_eq!(
2004                         invoice.description(),
2005                         InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
2006                 );
2007                 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
2008                 assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
2009
2010                 let mut expected_features = InvoiceFeatures::empty();
2011                 expected_features.set_variable_length_onion_required();
2012                 expected_features.set_payment_secret_required();
2013                 expected_features.set_basic_mpp_optional();
2014                 assert_eq!(invoice.features(), Some(&expected_features));
2015
2016                 let raw_invoice = builder.build_raw().unwrap();
2017                 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
2018         }
2019
2020         #[test]
2021         fn test_default_values() {
2022                 use crate::*;
2023                 use secp256k1::Secp256k1;
2024                 use secp256k1::SecretKey;
2025
2026                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2027                         .description("Test".into())
2028                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2029                         .payment_secret(PaymentSecret([0; 32]))
2030                         .duration_since_epoch(Duration::from_secs(1234567))
2031                         .build_raw()
2032                         .unwrap()
2033                         .sign::<_, ()>(|hash| {
2034                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2035                                 let secp_ctx = Secp256k1::new();
2036                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2037                         })
2038                         .unwrap();
2039                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2040
2041                 assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
2042                 assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
2043                 assert!(!invoice.would_expire(Duration::from_secs(1234568)));
2044         }
2045
2046         #[test]
2047         fn test_expiration() {
2048                 use crate::*;
2049                 use secp256k1::Secp256k1;
2050                 use secp256k1::SecretKey;
2051
2052                 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2053                         .description("Test".into())
2054                         .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2055                         .payment_secret(PaymentSecret([0; 32]))
2056                         .duration_since_epoch(Duration::from_secs(1234567))
2057                         .build_raw()
2058                         .unwrap()
2059                         .sign::<_, ()>(|hash| {
2060                                 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2061                                 let secp_ctx = Secp256k1::new();
2062                                 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2063                         })
2064                         .unwrap();
2065                 let invoice = Invoice::from_signed(signed_invoice).unwrap();
2066
2067                 assert!(invoice.would_expire(Duration::from_secs(1234567 + DEFAULT_EXPIRY_TIME + 1)));
2068         }
2069
2070         #[cfg(feature = "serde")]
2071         #[test]
2072         fn test_serde() {
2073                 let invoice_str = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
2074                         h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
2075                         5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
2076                         h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
2077                         j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
2078                         ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
2079                         guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
2080                         ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
2081                         p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
2082                         8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
2083                         j5r6drg6k6zcqj0fcwg";
2084                 let invoice = invoice_str.parse::<super::Invoice>().unwrap();
2085                 let serialized_invoice = serde_json::to_string(&invoice).unwrap();
2086                 let deserialized_invoice: super::Invoice = serde_json::from_str(serialized_invoice.as_str()).unwrap();
2087                 assert_eq!(invoice, deserialized_invoice);
2088                 assert_eq!(invoice_str, deserialized_invoice.to_string().as_str());
2089                 assert_eq!(invoice_str, serialized_invoice.as_str().trim_matches('\"'));
2090         }
2091 }