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

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