_ Git - rust-lightning/blob - lightning-invoice/src/lib.rs

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