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