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

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