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