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

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