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

   1 #![deny(rustdoc::broken_intra_doc_links)]
   2 #![deny(rustdoc::private_intra_doc_links)]
   3
   4 #![deny(missing_docs)]
   5 #![deny(non_upper_case_globals)]
   6 #![deny(non_camel_case_types)]
   7 #![deny(non_snake_case)]
   8 #![deny(unused_mut)]
   9
  10 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
  11
  12 #![cfg_attr(feature = "strict", deny(warnings))]
  13 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
  14
  15 //! This crate provides data structures to represent
  16 //! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
  17 //! invoices and functions to create, encode and decode these. If you just want to use the standard
  18 //! en-/decoding functionality this should get you started:
  19 //!
  20 //!   * For parsing use `str::parse::<Bolt11Invoice>(&self)` (see [`Bolt11Invoice::from_str`])
  21 //!   * For constructing invoices use the [`InvoiceBuilder`]
  22 //!   * For serializing invoices use the [`Display`]/[`ToString`] traits
  23 //!
  24 //! [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
  25
  26 #[cfg(not(any(feature = "std", feature = "no-std")))]
  27 compile_error!("at least one of the `std` or `no-std` features must be enabled");
  28
  29 pub mod payment;
  30 pub mod utils;
  31
  32 extern crate bech32;
  33 #[macro_use] extern crate lightning;
  34 extern crate secp256k1;
  35 extern crate alloc;
  36 #[cfg(any(test, feature = "std"))]
  37 extern crate core;
  38 #[cfg(feature = "serde")]
  39 extern crate serde;
  40
  41 #[cfg(feature = "std")]
  42 use std::time::SystemTime;
  43
  44 use bech32::u5;
  45 use bitcoin::{Address, Network, PubkeyHash, ScriptHash};
  46 use bitcoin::address::{Payload, WitnessProgram, WitnessVersion};
  47 use bitcoin::hashes::{Hash, sha256};
  48 use lightning::ln::features::Bolt11InvoiceFeatures;
  49 use lightning::util::invoice::construct_invoice_preimage;
  50
  51 use secp256k1::PublicKey;
  52 use secp256k1::{Message, Secp256k1};
  53 use secp256k1::ecdsa::RecoverableSignature;
  54
  55 use core::cmp::Ordering;
  56 use core::fmt::{Display, Formatter, self};
  57 use core::iter::FilterMap;
  58 use core::num::ParseIntError;
  59 use core::ops::Deref;
  60 use core::slice::Iter;
  61 use core::time::Duration;
  62 use core::str;
  63
  64 #[cfg(feature = "serde")]
  65 use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
  66
  67 #[doc(no_inline)]
  68 pub use lightning::ln::types::PaymentSecret;
  69 #[doc(no_inline)]
  70 pub use lightning::routing::router::{RouteHint, RouteHintHop};
  71 #[doc(no_inline)]
  72 pub use lightning::routing::gossip::RoutingFees;
  73 use lightning::util::string::UntrustedString;
  74
  75 mod de;
  76 mod ser;
  77 mod tb;
  78
  79 #[allow(unused_imports)]
  80 mod prelude {
  81         pub use alloc::{vec, vec::Vec, string::String};
  82
  83         pub use alloc::string::ToString;
  84 }
  85
  86 use crate::prelude::*;
  87
  88 /// Errors that indicate what is wrong with the invoice. They have some granularity for debug
  89 /// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
  90 #[allow(missing_docs)]
  91 #[derive(PartialEq, Eq, Debug, Clone)]
  92 pub enum Bolt11ParseError {
  93         Bech32Error(bech32::Error),
  94         ParseAmountError(ParseIntError),
  95         MalformedSignature(secp256k1::Error),
  96         BadPrefix,
  97         UnknownCurrency,
  98         UnknownSiPrefix,
  99         MalformedHRP,
 100         TooShortDataPart,
 101         UnexpectedEndOfTaggedFields,
 102         DescriptionDecodeError(str::Utf8Error),
 103         PaddingError,
 104         IntegerOverflowError,
 105         InvalidSegWitProgramLength,
 106         InvalidPubKeyHashLength,
 107         InvalidScriptHashLength,
 108         InvalidRecoveryId,
 109         InvalidSliceLength(String),
 110
 111         /// Not an error, but used internally to signal that a part of the invoice should be ignored
 112         /// according to BOLT11
 113         Skip,
 114 }
 115
 116 /// Indicates that something went wrong while parsing or validating the invoice. Parsing errors
 117 /// should be mostly seen as opaque and are only there for debugging reasons. Semantic errors
 118 /// like wrong signatures, missing fields etc. could mean that someone tampered with the invoice.
 119 #[derive(PartialEq, Eq, Debug, Clone)]
 120 pub enum ParseOrSemanticError {
 121         /// The invoice couldn't be decoded
 122         ParseError(Bolt11ParseError),
 123
 124         /// The invoice could be decoded but violates the BOLT11 standard
 125         SemanticError(crate::Bolt11SemanticError),
 126 }
 127
 128 /// The number of bits used to represent timestamps as defined in BOLT 11.
 129 const TIMESTAMP_BITS: usize = 35;
 130
 131 /// The maximum timestamp as [`Duration::as_secs`] since the Unix epoch allowed by [`BOLT 11`].
 132 ///
 133 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 134 pub const MAX_TIMESTAMP: u64 = (1 << TIMESTAMP_BITS) - 1;
 135
 136 /// Default expiry time as defined by [BOLT 11].
 137 ///
 138 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 139 pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
 140
 141 /// Default minimum final CLTV expiry as defined by [BOLT 11].
 142 ///
 143 /// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
 144 /// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
 145 ///
 146 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 147 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
 148 pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
 149
 150 /// Builder for [`Bolt11Invoice`]s. It's the most convenient and advised way to use this library. It
 151 /// ensures that only a semantically and syntactically correct invoice can be built using it.
 152 ///
 153 /// ```
 154 /// extern crate secp256k1;
 155 /// extern crate lightning;
 156 /// extern crate lightning_invoice;
 157 /// extern crate bitcoin;
 158 ///
 159 /// use bitcoin::hashes::Hash;
 160 /// use bitcoin::hashes::sha256;
 161 ///
 162 /// use secp256k1::Secp256k1;
 163 /// use secp256k1::SecretKey;
 164 ///
 165 /// use lightning::ln::types::PaymentSecret;
 166 ///
 167 /// use lightning_invoice::{Currency, InvoiceBuilder};
 168 ///
 169 /// # #[cfg(not(feature = "std"))]
 170 /// # fn main() {}
 171 /// # #[cfg(feature = "std")]
 172 /// # fn main() {
 173 /// let private_key = SecretKey::from_slice(
 174 ///             &[
 175 ///                     0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
 176 ///                     0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
 177 ///             0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
 178 ///     ][..]
 179 ///     ).unwrap();
 180 ///
 181 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
 182 /// let payment_secret = PaymentSecret([42u8; 32]);
 183 ///
 184 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
 185 ///     .description("Coins pls!".into())
 186 ///     .payment_hash(payment_hash)
 187 ///     .payment_secret(payment_secret)
 188 ///     .current_timestamp()
 189 ///     .min_final_cltv_expiry_delta(144)
 190 ///     .build_signed(|hash| {
 191 ///             Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
 192 ///     })
 193 ///     .unwrap();
 194 ///
 195 /// assert!(invoice.to_string().starts_with("lnbc1"));
 196 /// # }
 197 /// ```
 198 ///
 199 /// # Type parameters
 200 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
 201 /// given field:
 202 ///  * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
 203 ///  * `H`: exactly one [`TaggedField::PaymentHash`]
 204 ///  * `T`: the timestamp is set
 205 ///  * `C`: the CLTV expiry is set
 206 ///  * `S`: the payment secret is set
 207 ///  * `M`: payment metadata is set
 208 ///
 209 /// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
 210 #[derive(Eq, PartialEq, Debug, Clone)]
 211 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> {
 212         currency: Currency,
 213         amount: Option<u64>,
 214         si_prefix: Option<SiPrefix>,
 215         timestamp: Option<PositiveTimestamp>,
 216         tagged_fields: Vec<TaggedField>,
 217         error: Option<CreationError>,
 218
 219         phantom_d: core::marker::PhantomData<D>,
 220         phantom_h: core::marker::PhantomData<H>,
 221         phantom_t: core::marker::PhantomData<T>,
 222         phantom_c: core::marker::PhantomData<C>,
 223         phantom_s: core::marker::PhantomData<S>,
 224         phantom_m: core::marker::PhantomData<M>,
 225 }
 226
 227 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
 228 ///
 229 /// There are three ways to construct a `Bolt11Invoice`:
 230 ///  1. using [`InvoiceBuilder`]
 231 ///  2. using [`Bolt11Invoice::from_signed`]
 232 ///  3. using `str::parse::<Bolt11Invoice>(&str)` (see [`Bolt11Invoice::from_str`])
 233 ///
 234 /// [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
 235 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 236 pub struct Bolt11Invoice {
 237         signed_invoice: SignedRawBolt11Invoice,
 238 }
 239
 240 /// Represents the description of an invoice which has to be either a directly included string or
 241 /// a hash of a description provided out of band.
 242 ///
 243 /// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
 244 /// practically impossible to use safely in languages like C.
 245 #[derive(Eq, PartialEq, Debug, Clone, Ord, PartialOrd)]
 246 pub enum Bolt11InvoiceDescription<'f> {
 247         /// Reference to the directly supplied description in the invoice
 248         Direct(&'f Description),
 249
 250         /// Reference to the description's hash included in the invoice
 251         Hash(&'f Sha256),
 252 }
 253
 254 impl<'f> Display for Bolt11InvoiceDescription<'f> {
 255         fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
 256                 match self {
 257                         Bolt11InvoiceDescription::Direct(desc) => write!(f, "{}", desc.0),
 258                         Bolt11InvoiceDescription::Hash(hash) => write!(f, "{}", hash.0),
 259                 }
 260         }
 261 }
 262
 263 /// Represents a signed [`RawBolt11Invoice`] with cached hash. The signature is not checked and may be
 264 /// invalid.
 265 ///
 266 /// # Invariants
 267 /// The hash has to be either from the deserialized invoice or from the serialized [`RawBolt11Invoice`].
 268 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 269 pub struct SignedRawBolt11Invoice {
 270         /// The raw invoice that the signature belongs to
 271         raw_invoice: RawBolt11Invoice,
 272
 273         /// Hash of the [`RawBolt11Invoice`] that will be used to check the signature.
 274         ///
 275         /// * if the `SignedRawBolt11Invoice` was deserialized the hash is of from the original encoded form,
 276         /// since it's not guaranteed that encoding it again will lead to the same result since integers
 277         /// could have been encoded with leading zeroes etc.
 278         /// * if the `SignedRawBolt11Invoice` was constructed manually the hash will be the calculated hash
 279         /// from the [`RawBolt11Invoice`]
 280         hash: [u8; 32],
 281
 282         /// signature of the payment request
 283         signature: Bolt11InvoiceSignature,
 284 }
 285
 286 /// Represents an syntactically correct [`Bolt11Invoice`] for a payment on the lightning network,
 287 /// but without the signature information.
 288 /// Decoding and encoding should not lead to information loss but may lead to different hashes.
 289 ///
 290 /// For methods without docs see the corresponding methods in [`Bolt11Invoice`].
 291 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 292 pub struct RawBolt11Invoice {
 293         /// human readable part
 294         pub hrp: RawHrp,
 295
 296         /// data part
 297         pub data: RawDataPart,
 298 }
 299
 300 /// Data of the [`RawBolt11Invoice`] that is encoded in the human readable part.
 301 ///
 302 /// This is not exported to bindings users as we don't yet support `Option<Enum>`
 303 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 304 pub struct RawHrp {
 305         /// The currency deferred from the 3rd and 4th character of the bech32 transaction
 306         pub currency: Currency,
 307
 308         /// The amount that, multiplied by the SI prefix, has to be payed
 309         pub raw_amount: Option<u64>,
 310
 311         /// SI prefix that gets multiplied with the `raw_amount`
 312         pub si_prefix: Option<SiPrefix>,
 313 }
 314
 315 /// Data of the [`RawBolt11Invoice`] that is encoded in the data part
 316 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 317 pub struct RawDataPart {
 318         /// generation time of the invoice
 319         pub timestamp: PositiveTimestamp,
 320
 321         /// tagged fields of the payment request
 322         pub tagged_fields: Vec<RawTaggedField>,
 323 }
 324
 325 /// A timestamp that refers to a date after 1 January 1970.
 326 ///
 327 /// # Invariants
 328 ///
 329 /// The Unix timestamp representing the stored time has to be positive and no greater than
 330 /// [`MAX_TIMESTAMP`].
 331 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 332 pub struct PositiveTimestamp(Duration);
 333
 334 /// SI prefixes for the human readable part
 335 #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Ord, PartialOrd)]
 336 pub enum SiPrefix {
 337         /// 10^-3
 338         Milli,
 339         /// 10^-6
 340         Micro,
 341         /// 10^-9
 342         Nano,
 343         /// 10^-12
 344         Pico,
 345 }
 346
 347 impl SiPrefix {
 348         /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
 349         /// This is effectively 10^12 * the prefix multiplier
 350         pub fn multiplier(&self) -> u64 {
 351                 match *self {
 352                         SiPrefix::Milli => 1_000_000_000,
 353                         SiPrefix::Micro => 1_000_000,
 354                         SiPrefix::Nano => 1_000,
 355                         SiPrefix::Pico => 1,
 356                 }
 357         }
 358
 359         /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
 360         /// multiplier.
 361         ///
 362         /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
 363         /// isn't the most critical to expose.
 364         pub fn values_desc() -> &'static [SiPrefix] {
 365                 use crate::SiPrefix::*;
 366                 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
 367                 &VALUES
 368         }
 369 }
 370
 371 /// Enum representing the crypto currencies (or networks) supported by this library
 372 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 373 pub enum Currency {
 374         /// Bitcoin mainnet
 375         Bitcoin,
 376
 377         /// Bitcoin testnet
 378         BitcoinTestnet,
 379
 380         /// Bitcoin regtest
 381         Regtest,
 382
 383         /// Bitcoin simnet
 384         Simnet,
 385
 386         /// Bitcoin signet
 387         Signet,
 388 }
 389
 390 impl From<Network> for Currency {
 391         fn from(network: Network) -> Self {
 392                 match network {
 393                         Network::Bitcoin => Currency::Bitcoin,
 394                         Network::Testnet => Currency::BitcoinTestnet,
 395                         Network::Regtest => Currency::Regtest,
 396                         Network::Signet => Currency::Signet,
 397                         _ => {
 398                                 debug_assert!(false, "Need to handle new rust-bitcoin network type");
 399                                 Currency::Regtest
 400                         },
 401                 }
 402         }
 403 }
 404
 405 impl From<Currency> for Network {
 406         fn from(currency: Currency) -> Self {
 407                 match currency {
 408                         Currency::Bitcoin => Network::Bitcoin,
 409                         Currency::BitcoinTestnet => Network::Testnet,
 410                         Currency::Regtest => Network::Regtest,
 411                         Currency::Simnet => Network::Regtest,
 412                         Currency::Signet => Network::Signet,
 413                 }
 414         }
 415 }
 416
 417 /// Tagged field which may have an unknown tag
 418 ///
 419 /// This is not exported to bindings users as we don't currently support TaggedField
 420 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 421 pub enum RawTaggedField {
 422         /// Parsed tagged field with known tag
 423         KnownSemantics(TaggedField),
 424         /// tagged field which was not parsed due to an unknown tag or undefined field semantics
 425         UnknownSemantics(Vec<u5>),
 426 }
 427
 428 /// Tagged field with known tag
 429 ///
 430 /// For descriptions of the enum values please refer to the enclosed type's docs.
 431 ///
 432 /// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
 433 /// in the variant.
 434 #[allow(missing_docs)]
 435 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 436 pub enum TaggedField {
 437         PaymentHash(Sha256),
 438         Description(Description),
 439         PayeePubKey(PayeePubKey),
 440         DescriptionHash(Sha256),
 441         ExpiryTime(ExpiryTime),
 442         MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
 443         Fallback(Fallback),
 444         PrivateRoute(PrivateRoute),
 445         PaymentSecret(PaymentSecret),
 446         PaymentMetadata(Vec<u8>),
 447         Features(Bolt11InvoiceFeatures),
 448 }
 449
 450 /// SHA-256 hash
 451 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 452 pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
 453         pub sha256::Hash);
 454
 455 impl Sha256 {
 456         /// Constructs a new [`Sha256`] from the given bytes, which are assumed to be the output of a
 457         /// single sha256 hash.
 458         #[cfg(c_bindings)]
 459         pub fn from_bytes(bytes: &[u8; 32]) -> Self {
 460                 Self(sha256::Hash::from_slice(bytes).expect("from_slice only fails if len is not 32"))
 461         }
 462 }
 463
 464 /// Description string
 465 ///
 466 /// # Invariants
 467 /// The description can be at most 639 __bytes__ long
 468 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd, Default)]
 469 pub struct Description(UntrustedString);
 470
 471 /// Payee public key
 472 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 473 pub struct PayeePubKey(pub PublicKey);
 474
 475 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
 476 /// expires
 477 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 478 pub struct ExpiryTime(Duration);
 479
 480 /// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
 481 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 482 pub struct MinFinalCltvExpiryDelta(pub u64);
 483
 484 /// Fallback address in case no LN payment is possible
 485 #[allow(missing_docs)]
 486 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 487 pub enum Fallback {
 488         SegWitProgram {
 489                 version: WitnessVersion,
 490                 program: Vec<u8>,
 491         },
 492         PubKeyHash(PubkeyHash),
 493         ScriptHash(ScriptHash),
 494 }
 495
 496 /// Recoverable signature
 497 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
 498 pub struct Bolt11InvoiceSignature(pub RecoverableSignature);
 499
 500 impl PartialOrd for Bolt11InvoiceSignature {
 501         fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
 502                 Some(self.cmp(other))
 503         }
 504 }
 505
 506 impl Ord for Bolt11InvoiceSignature {
 507         fn cmp(&self, other: &Self) -> Ordering {
 508                 self.0.serialize_compact().1.cmp(&other.0.serialize_compact().1)
 509         }
 510 }
 511
 512 /// Private routing information
 513 ///
 514 /// # Invariants
 515 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
 516 ///
 517 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 518 pub struct PrivateRoute(RouteHint);
 519
 520 /// Tag constants as specified in BOLT11
 521 #[allow(missing_docs)]
 522 pub mod constants {
 523         pub const TAG_PAYMENT_HASH: u8 = 1;
 524         pub const TAG_DESCRIPTION: u8 = 13;
 525         pub const TAG_PAYEE_PUB_KEY: u8 = 19;
 526         pub const TAG_DESCRIPTION_HASH: u8 = 23;
 527         pub const TAG_EXPIRY_TIME: u8 = 6;
 528         pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
 529         pub const TAG_FALLBACK: u8 = 9;
 530         pub const TAG_PRIVATE_ROUTE: u8 = 3;
 531         pub const TAG_PAYMENT_SECRET: u8 = 16;
 532         pub const TAG_PAYMENT_METADATA: u8 = 27;
 533         pub const TAG_FEATURES: u8 = 5;
 534 }
 535
 536 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False, tb::False> {
 537         /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
 538         /// `InvoiceBuilder::build(self)` becomes available.
 539         pub fn new(currency: Currency) -> Self {
 540                 InvoiceBuilder {
 541                         currency,
 542                         amount: None,
 543                         si_prefix: None,
 544                         timestamp: None,
 545                         tagged_fields: Vec::with_capacity(8),
 546                         error: None,
 547
 548                         phantom_d: core::marker::PhantomData,
 549                         phantom_h: core::marker::PhantomData,
 550                         phantom_t: core::marker::PhantomData,
 551                         phantom_c: core::marker::PhantomData,
 552                         phantom_s: core::marker::PhantomData,
 553                         phantom_m: core::marker::PhantomData,
 554                 }
 555         }
 556 }
 557
 558 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> {
 559         /// Helper function to set the completeness flags.
 560         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> {
 561                 InvoiceBuilder::<DN, HN, TN, CN, SN, MN> {
 562                         currency: self.currency,
 563                         amount: self.amount,
 564                         si_prefix: self.si_prefix,
 565                         timestamp: self.timestamp,
 566                         tagged_fields: self.tagged_fields,
 567                         error: self.error,
 568
 569                         phantom_d: core::marker::PhantomData,
 570                         phantom_h: core::marker::PhantomData,
 571                         phantom_t: core::marker::PhantomData,
 572                         phantom_c: core::marker::PhantomData,
 573                         phantom_s: core::marker::PhantomData,
 574                         phantom_m: core::marker::PhantomData,
 575                 }
 576         }
 577
 578         /// Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.
 579         pub fn amount_milli_satoshis(mut self, amount_msat: u64) -> Self {
 580                 let amount = match amount_msat.checked_mul(10) { // Invoices are denominated in "pico BTC"
 581                         Some(amt) => amt,
 582                         None => {
 583                                 self.error = Some(CreationError::InvalidAmount);
 584                                 return self
 585                         }
 586                 };
 587                 let biggest_possible_si_prefix = SiPrefix::values_desc()
 588                         .iter()
 589                         .find(|prefix| amount % prefix.multiplier() == 0)
 590                         .expect("Pico should always match");
 591                 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
 592                 self.si_prefix = Some(*biggest_possible_si_prefix);
 593                 self
 594         }
 595
 596         /// Sets the payee's public key.
 597         pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
 598                 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
 599                 self
 600         }
 601
 602         /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
 603         /// invoices).
 604         pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
 605                 self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
 606                 self
 607         }
 608
 609         /// Adds a fallback address.
 610         pub fn fallback(mut self, fallback: Fallback) -> Self {
 611                 self.tagged_fields.push(TaggedField::Fallback(fallback));
 612                 self
 613         }
 614
 615         /// Adds a private route.
 616         pub fn private_route(mut self, hint: RouteHint) -> Self {
 617                 match PrivateRoute::new(hint) {
 618                         Ok(r) => self.tagged_fields.push(TaggedField::PrivateRoute(r)),
 619                         Err(e) => self.error = Some(e),
 620                 }
 621                 self
 622         }
 623 }
 624
 625 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S, M> {
 626         /// Builds a [`RawBolt11Invoice`] if no [`CreationError`] occurred while construction any of the
 627         /// fields.
 628         pub fn build_raw(self) -> Result<RawBolt11Invoice, CreationError> {
 629
 630                 // If an error occurred at any time before, return it now
 631                 if let Some(e) = self.error {
 632                         return Err(e);
 633                 }
 634
 635                 let hrp = RawHrp {
 636                         currency: self.currency,
 637                         raw_amount: self.amount,
 638                         si_prefix: self.si_prefix,
 639                 };
 640
 641                 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
 642
 643                 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
 644                         RawTaggedField::KnownSemantics(tf)
 645                 }).collect::<Vec<_>>();
 646
 647                 let data = RawDataPart {
 648                         timestamp,
 649                         tagged_fields,
 650                 };
 651
 652                 Ok(RawBolt11Invoice {
 653                         hrp,
 654                         data,
 655                 })
 656         }
 657 }
 658
 659 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S, M> {
 660         /// Set the description. This function is only available if no description (hash) was set.
 661         pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
 662                 match Description::new(description) {
 663                         Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
 664                         Err(e) => self.error = Some(e),
 665                 }
 666                 self.set_flags()
 667         }
 668
 669         /// Set the description hash. This function is only available if no description (hash) was set.
 670         pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
 671                 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
 672                 self.set_flags()
 673         }
 674
 675         /// Set the description or description hash. This function is only available if no description (hash) was set.
 676         pub fn invoice_description(self, description: Bolt11InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
 677                 match description {
 678                         Bolt11InvoiceDescription::Direct(desc) => {
 679                                 self.description(desc.clone().into_inner().0)
 680                         }
 681                         Bolt11InvoiceDescription::Hash(hash) => {
 682                                 self.description_hash(hash.0)
 683                         }
 684                 }
 685         }
 686 }
 687
 688 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S, M> {
 689         /// Set the payment hash. This function is only available if no payment hash was set.
 690         pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S, M> {
 691                 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
 692                 self.set_flags()
 693         }
 694 }
 695
 696 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S, M> {
 697         /// Sets the timestamp to a specific [`SystemTime`].
 698         #[cfg(feature = "std")]
 699         pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
 700                 match PositiveTimestamp::from_system_time(time) {
 701                         Ok(t) => self.timestamp = Some(t),
 702                         Err(e) => self.error = Some(e),
 703                 }
 704
 705                 self.set_flags()
 706         }
 707
 708         /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
 709         /// is not representable in BOLT 11 invoices).
 710         pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
 711                 match PositiveTimestamp::from_duration_since_epoch(time) {
 712                         Ok(t) => self.timestamp = Some(t),
 713                         Err(e) => self.error = Some(e),
 714                 }
 715
 716                 self.set_flags()
 717         }
 718
 719         /// Sets the timestamp to the current system time.
 720         #[cfg(feature = "std")]
 721         pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
 722                 let now = PositiveTimestamp::from_system_time(SystemTime::now());
 723                 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
 724                 self.set_flags()
 725         }
 726 }
 727
 728 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S, M> {
 729         /// Sets `min_final_cltv_expiry_delta`.
 730         pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S, M> {
 731                 self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
 732                 self.set_flags()
 733         }
 734 }
 735
 736 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False, M> {
 737         /// Sets the payment secret and relevant features.
 738         pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True, M> {
 739                 let mut found_features = false;
 740                 for field in self.tagged_fields.iter_mut() {
 741                         if let TaggedField::Features(f) = field {
 742                                 found_features = true;
 743                                 f.set_variable_length_onion_required();
 744                                 f.set_payment_secret_required();
 745                         }
 746                 }
 747                 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
 748                 if !found_features {
 749                         let mut features = Bolt11InvoiceFeatures::empty();
 750                         features.set_variable_length_onion_required();
 751                         features.set_payment_secret_required();
 752                         self.tagged_fields.push(TaggedField::Features(features));
 753                 }
 754                 self.set_flags()
 755         }
 756 }
 757
 758 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::False> {
 759         /// Sets the payment metadata.
 760         ///
 761         /// By default features are set to *optionally* allow the sender to include the payment metadata.
 762         /// If you wish to require that the sender include the metadata (and fail to parse the invoice if
 763         /// they don't support payment metadata fields), you need to call
 764         /// [`InvoiceBuilder::require_payment_metadata`] after this.
 765         pub fn payment_metadata(mut self, payment_metadata: Vec<u8>) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
 766                 self.tagged_fields.push(TaggedField::PaymentMetadata(payment_metadata));
 767                 let mut found_features = false;
 768                 for field in self.tagged_fields.iter_mut() {
 769                         if let TaggedField::Features(f) = field {
 770                                 found_features = true;
 771                                 f.set_payment_metadata_optional();
 772                         }
 773                 }
 774                 if !found_features {
 775                         let mut features = Bolt11InvoiceFeatures::empty();
 776                         features.set_payment_metadata_optional();
 777                         self.tagged_fields.push(TaggedField::Features(features));
 778                 }
 779                 self.set_flags()
 780         }
 781 }
 782
 783 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::True> {
 784         /// Sets forwarding of payment metadata as required. A reader of the invoice which does not
 785         /// support sending payment metadata will fail to read the invoice.
 786         pub fn require_payment_metadata(mut self) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
 787                 for field in self.tagged_fields.iter_mut() {
 788                         if let TaggedField::Features(f) = field {
 789                                 f.set_payment_metadata_required();
 790                         }
 791                 }
 792                 self
 793         }
 794 }
 795
 796 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True, M> {
 797         /// Sets the `basic_mpp` feature as optional.
 798         pub fn basic_mpp(mut self) -> Self {
 799                 for field in self.tagged_fields.iter_mut() {
 800                         if let TaggedField::Features(f) = field {
 801                                 f.set_basic_mpp_optional();
 802                         }
 803                 }
 804                 self
 805         }
 806 }
 807
 808 impl<M: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True, M> {
 809         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
 810         /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
 811         /// the included payee public key.
 812         pub fn build_signed<F>(self, sign_function: F) -> Result<Bolt11Invoice, CreationError>
 813                 where F: FnOnce(&Message) -> RecoverableSignature
 814         {
 815                 let invoice = self.try_build_signed::<_, ()>(|hash| {
 816                         Ok(sign_function(hash))
 817                 });
 818
 819                 match invoice {
 820                         Ok(i) => Ok(i),
 821                         Err(SignOrCreationError::CreationError(e)) => Err(e),
 822                         Err(SignOrCreationError::SignError(())) => unreachable!(),
 823                 }
 824         }
 825
 826         /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
 827         /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
 828         /// if applicable also for the included payee public key.
 829         pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Bolt11Invoice, SignOrCreationError<E>>
 830                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
 831         {
 832                 let raw = match self.build_raw() {
 833                         Ok(r) => r,
 834                         Err(e) => return Err(SignOrCreationError::CreationError(e)),
 835                 };
 836
 837                 let signed = match raw.sign(sign_function) {
 838                         Ok(s) => s,
 839                         Err(e) => return Err(SignOrCreationError::SignError(e)),
 840                 };
 841
 842                 let invoice = Bolt11Invoice {
 843                         signed_invoice: signed,
 844                 };
 845
 846                 invoice.check_field_counts().expect("should be ensured by type signature of builder");
 847                 invoice.check_feature_bits().expect("should be ensured by type signature of builder");
 848                 invoice.check_amount().expect("should be ensured by type signature of builder");
 849
 850                 Ok(invoice)
 851         }
 852 }
 853
 854
 855 impl SignedRawBolt11Invoice {
 856         /// Disassembles the `SignedRawBolt11Invoice` into its three parts:
 857         ///  1. raw invoice
 858         ///  2. hash of the raw invoice
 859         ///  3. signature
 860         pub fn into_parts(self) -> (RawBolt11Invoice, [u8; 32], Bolt11InvoiceSignature) {
 861                 (self.raw_invoice, self.hash, self.signature)
 862         }
 863
 864         /// The [`RawBolt11Invoice`] which was signed.
 865         pub fn raw_invoice(&self) -> &RawBolt11Invoice {
 866                 &self.raw_invoice
 867         }
 868
 869         /// The hash of the [`RawBolt11Invoice`] that was signed.
 870         pub fn signable_hash(&self) -> &[u8; 32] {
 871                 &self.hash
 872         }
 873
 874         /// Signature for the invoice.
 875         pub fn signature(&self) -> &Bolt11InvoiceSignature {
 876                 &self.signature
 877         }
 878
 879         /// Recovers the public key used for signing the invoice from the recoverable signature.
 880         pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
 881                 let hash = Message::from_slice(&self.hash[..])
 882                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 883
 884                 Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
 885                         &hash,
 886                         &self.signature
 887                 )?))
 888         }
 889
 890         /// Checks if the signature is valid for the included payee public key or if none exists if it's
 891         /// valid for the recovered signature (which should always be true?).
 892         pub fn check_signature(&self) -> bool {
 893                 let included_pub_key = self.raw_invoice.payee_pub_key();
 894
 895                 let mut recovered_pub_key = Option::None;
 896                 if recovered_pub_key.is_none() {
 897                         let recovered = match self.recover_payee_pub_key() {
 898                                 Ok(pk) => pk,
 899                                 Err(_) => return false,
 900                         };
 901                         recovered_pub_key = Some(recovered);
 902                 }
 903
 904                 let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
 905                         .expect("One is always present");
 906
 907                 let hash = Message::from_slice(&self.hash[..])
 908                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 909
 910                 let secp_context = Secp256k1::new();
 911                 let verification_result = secp_context.verify_ecdsa(
 912                         &hash,
 913                         &self.signature.to_standard(),
 914                         pub_key
 915                 );
 916
 917                 match verification_result {
 918                         Ok(()) => true,
 919                         Err(_) => false,
 920                 }
 921         }
 922 }
 923
 924 /// Finds the first element of an enum stream of a given variant and extracts one member of the
 925 /// variant. If no element was found `None` gets returned.
 926 ///
 927 /// The following example would extract the first B.
 928 ///
 929 /// ```ignore
 930 /// enum Enum {
 931 ///     A(u8),
 932 ///     B(u16)
 933 /// }
 934 ///
 935 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 936 ///
 937 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
 938 /// ```
 939 macro_rules! find_extract {
 940         ($iter:expr, $enm:pat, $enm_var:ident) => {
 941                 find_all_extract!($iter, $enm, $enm_var).next()
 942         };
 943 }
 944
 945 /// Finds the all elements of an enum stream of a given variant and extracts one member of the
 946 /// variant through an iterator.
 947 ///
 948 /// The following example would extract all A.
 949 ///
 950 /// ```ignore
 951 /// enum Enum {
 952 ///     A(u8),
 953 ///     B(u16)
 954 /// }
 955 ///
 956 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 957 ///
 958 /// assert_eq!(
 959 ///     find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
 960 ///     vec![1u8, 2u8, 4u8]
 961 /// );
 962 /// ```
 963 macro_rules! find_all_extract {
 964         ($iter:expr, $enm:pat, $enm_var:ident) => {
 965                 $iter.filter_map(|tf| match *tf {
 966                         $enm => Some($enm_var),
 967                         _ => None,
 968                 })
 969         };
 970 }
 971
 972 #[allow(missing_docs)]
 973 impl RawBolt11Invoice {
 974         /// Hash the HRP as bytes and signatureless data part.
 975         fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
 976                 let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
 977                 let mut hash: [u8; 32] = Default::default();
 978                 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
 979                 hash
 980         }
 981
 982         /// Calculate the hash of the encoded `RawBolt11Invoice` which should be signed.
 983         pub fn signable_hash(&self) -> [u8; 32] {
 984                 use bech32::ToBase32;
 985
 986                 RawBolt11Invoice::hash_from_parts(
 987                         self.hrp.to_string().as_bytes(),
 988                         &self.data.to_base32()
 989                 )
 990         }
 991
 992         /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
 993         /// type `E`. Since the signature of a [`SignedRawBolt11Invoice`] is not required to be valid there
 994         /// are no constraints regarding the validity of the produced signature.
 995         ///
 996         /// This is not exported to bindings users as we don't currently support passing function pointers into methods
 997         /// explicitly.
 998         pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawBolt11Invoice, E>
 999                 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
1000         {
1001                 let raw_hash = self.signable_hash();
1002                 let hash = Message::from_slice(&raw_hash[..])
1003                         .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
1004                 let signature = sign_method(&hash)?;
1005
1006                 Ok(SignedRawBolt11Invoice {
1007                         raw_invoice: self,
1008                         hash: raw_hash,
1009                         signature: Bolt11InvoiceSignature(signature),
1010                 })
1011         }
1012
1013         /// Returns an iterator over all tagged fields with known semantics.
1014         ///
1015         /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1016         pub fn known_tagged_fields(&self)
1017                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
1018         {
1019                 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
1020                 // function's type signature.
1021                 // TODO: refactor once impl Trait is available
1022                 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
1023                         match *raw {
1024                                 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
1025                                 _ => None,
1026                         }
1027                 }
1028
1029                 self.data.tagged_fields.iter().filter_map(match_raw )
1030         }
1031
1032         pub fn payment_hash(&self) -> Option<&Sha256> {
1033                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
1034         }
1035
1036         pub fn description(&self) -> Option<&Description> {
1037                 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
1038         }
1039
1040         pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
1041                 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
1042         }
1043
1044         pub fn description_hash(&self) -> Option<&Sha256> {
1045                 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
1046         }
1047
1048         pub fn expiry_time(&self) -> Option<&ExpiryTime> {
1049                 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
1050         }
1051
1052         pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
1053                 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
1054         }
1055
1056         pub fn payment_secret(&self) -> Option<&PaymentSecret> {
1057                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
1058         }
1059
1060         pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1061                 find_extract!(self.known_tagged_fields(), TaggedField::PaymentMetadata(ref x), x)
1062         }
1063
1064         pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1065                 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
1066         }
1067
1068         /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1069         pub fn fallbacks(&self) -> Vec<&Fallback> {
1070                 find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
1071         }
1072
1073         pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1074                 find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
1075         }
1076
1077         /// Returns `None` if no amount is set or on overflow.
1078         pub fn amount_pico_btc(&self) -> Option<u64> {
1079                 self.hrp.raw_amount.and_then(|v| {
1080                         v.checked_mul(self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() }))
1081                 })
1082         }
1083
1084         pub fn currency(&self) -> Currency {
1085                 self.hrp.currency.clone()
1086         }
1087 }
1088
1089 impl PositiveTimestamp {
1090         /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
1091         ///
1092         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1093         pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
1094                 if unix_seconds <= MAX_TIMESTAMP {
1095                         Ok(Self(Duration::from_secs(unix_seconds)))
1096                 } else {
1097                         Err(CreationError::TimestampOutOfBounds)
1098                 }
1099         }
1100
1101         /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
1102         /// the range `0..=MAX_TIMESTAMP`.
1103         ///
1104         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1105         ///
1106         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1107         #[cfg(feature = "std")]
1108         pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
1109                 time.duration_since(SystemTime::UNIX_EPOCH)
1110                         .map(Self::from_duration_since_epoch)
1111                         .unwrap_or(Err(CreationError::TimestampOutOfBounds))
1112         }
1113
1114         /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
1115         /// `0..=MAX_TIMESTAMP`.
1116         ///
1117         /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1118         ///
1119         /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1120         pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
1121                 Self::from_unix_timestamp(duration.as_secs())
1122         }
1123
1124         /// Returns the Unix timestamp representing the stored time
1125         pub fn as_unix_timestamp(&self) -> u64 {
1126                 self.0.as_secs()
1127         }
1128
1129         /// Returns the duration of the stored time since the Unix epoch
1130         pub fn as_duration_since_epoch(&self) -> Duration {
1131                 self.0
1132         }
1133
1134         /// Returns the [`SystemTime`] representing the stored time
1135         #[cfg(feature = "std")]
1136         pub fn as_time(&self) -> SystemTime {
1137                 SystemTime::UNIX_EPOCH + self.0
1138         }
1139 }
1140
1141 impl From<PositiveTimestamp> for Duration {
1142         fn from(val: PositiveTimestamp) -> Self {
1143                 val.0
1144         }
1145 }
1146
1147 #[cfg(feature = "std")]
1148 impl From<PositiveTimestamp> for SystemTime {
1149         fn from(val: PositiveTimestamp) -> Self {
1150                 SystemTime::UNIX_EPOCH + val.0
1151         }
1152 }
1153
1154 impl Bolt11Invoice {
1155         /// The hash of the [`RawBolt11Invoice`] that was signed.
1156         pub fn signable_hash(&self) -> [u8; 32] {
1157                 self.signed_invoice.hash
1158         }
1159
1160         /// Transform the `Bolt11Invoice` into its unchecked version.
1161         pub fn into_signed_raw(self) -> SignedRawBolt11Invoice {
1162                 self.signed_invoice
1163         }
1164
1165         /// Check that all mandatory fields are present
1166         fn check_field_counts(&self) -> Result<(), Bolt11SemanticError> {
1167                 // "A writer MUST include exactly one p field […]."
1168                 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1169                         TaggedField::PaymentHash(_) => true,
1170                         _ => false,
1171                 }).count();
1172                 if payment_hash_cnt < 1 {
1173                         return Err(Bolt11SemanticError::NoPaymentHash);
1174                 } else if payment_hash_cnt > 1 {
1175                         return Err(Bolt11SemanticError::MultiplePaymentHashes);
1176                 }
1177
1178                 // "A writer MUST include either exactly one d or exactly one h field."
1179                 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1180                         TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1181                         _ => false,
1182                 }).count();
1183                 if  description_cnt < 1 {
1184                         return Err(Bolt11SemanticError::NoDescription);
1185                 } else if description_cnt > 1 {
1186                         return  Err(Bolt11SemanticError::MultipleDescriptions);
1187                 }
1188
1189                 self.check_payment_secret()?;
1190
1191                 Ok(())
1192         }
1193
1194         /// Checks that there is exactly one payment secret field
1195         fn check_payment_secret(&self) -> Result<(), Bolt11SemanticError> {
1196                 // "A writer MUST include exactly one `s` field."
1197                 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1198                         TaggedField::PaymentSecret(_) => true,
1199                         _ => false,
1200                 }).count();
1201                 if payment_secret_count < 1 {
1202                         return Err(Bolt11SemanticError::NoPaymentSecret);
1203                 } else if payment_secret_count > 1 {
1204                         return Err(Bolt11SemanticError::MultiplePaymentSecrets);
1205                 }
1206
1207                 Ok(())
1208         }
1209
1210         /// Check that amount is a whole number of millisatoshis
1211         fn check_amount(&self) -> Result<(), Bolt11SemanticError> {
1212                 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1213                         if amount_pico_btc % 10 != 0 {
1214                                 return Err(Bolt11SemanticError::ImpreciseAmount);
1215                         }
1216                 }
1217                 Ok(())
1218         }
1219
1220         /// Check that feature bits are set as required
1221         fn check_feature_bits(&self) -> Result<(), Bolt11SemanticError> {
1222                 self.check_payment_secret()?;
1223
1224                 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1225                 // (this requirement has been since removed, and we now require the payment secret
1226                 // feature bit always).
1227                 let features = self.tagged_fields().find(|&tf| match *tf {
1228                         TaggedField::Features(_) => true,
1229                         _ => false,
1230                 });
1231                 match features {
1232                         None => Err(Bolt11SemanticError::InvalidFeatures),
1233                         Some(TaggedField::Features(features)) => {
1234                                 if features.requires_unknown_bits() {
1235                                         Err(Bolt11SemanticError::InvalidFeatures)
1236                                 } else if !features.supports_payment_secret() {
1237                                         Err(Bolt11SemanticError::InvalidFeatures)
1238                                 } else {
1239                                         Ok(())
1240                                 }
1241                         },
1242                         Some(_) => unreachable!(),
1243                 }
1244         }
1245
1246         /// Check that the invoice is signed correctly and that key recovery works
1247         pub fn check_signature(&self) -> Result<(), Bolt11SemanticError> {
1248                 match self.signed_invoice.recover_payee_pub_key() {
1249                         Err(secp256k1::Error::InvalidRecoveryId) =>
1250                                 return Err(Bolt11SemanticError::InvalidRecoveryId),
1251                         Err(secp256k1::Error::InvalidSignature) =>
1252                                 return Err(Bolt11SemanticError::InvalidSignature),
1253                         Err(e) => panic!("no other error may occur, got {:?}", e),
1254                         Ok(_) => {},
1255                 }
1256
1257                 if !self.signed_invoice.check_signature() {
1258                         return Err(Bolt11SemanticError::InvalidSignature);
1259                 }
1260
1261                 Ok(())
1262         }
1263
1264         /// Constructs a `Bolt11Invoice` from a [`SignedRawBolt11Invoice`] by checking all its invariants.
1265         /// ```
1266         /// use lightning_invoice::*;
1267         ///
1268         /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1269         /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1270         /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1271         /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1272         /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1273         /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1274         /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1275         /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1276         /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1277         /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1278         /// j5r6drg6k6zcqj0fcwg";
1279         ///
1280         /// let signed = invoice.parse::<SignedRawBolt11Invoice>().unwrap();
1281         ///
1282         /// assert!(Bolt11Invoice::from_signed(signed).is_ok());
1283         /// ```
1284         pub fn from_signed(signed_invoice: SignedRawBolt11Invoice) -> Result<Self, Bolt11SemanticError> {
1285                 let invoice = Bolt11Invoice {
1286                         signed_invoice,
1287                 };
1288                 invoice.check_field_counts()?;
1289                 invoice.check_feature_bits()?;
1290                 invoice.check_signature()?;
1291                 invoice.check_amount()?;
1292
1293                 Ok(invoice)
1294         }
1295
1296         /// Returns the `Bolt11Invoice`'s timestamp (should equal its creation time)
1297         #[cfg(feature = "std")]
1298         pub fn timestamp(&self) -> SystemTime {
1299                 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1300         }
1301
1302         /// Returns the `Bolt11Invoice`'s timestamp as a duration since the Unix epoch
1303         pub fn duration_since_epoch(&self) -> Duration {
1304                 self.signed_invoice.raw_invoice().data.timestamp.0
1305         }
1306
1307         /// Returns an iterator over all tagged fields of this `Bolt11Invoice`.
1308         ///
1309         /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1310         pub fn tagged_fields(&self)
1311                 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1312                 self.signed_invoice.raw_invoice().known_tagged_fields()
1313         }
1314
1315         /// Returns the hash to which we will receive the preimage on completion of the payment
1316         pub fn payment_hash(&self) -> &sha256::Hash {
1317                 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1318         }
1319
1320         /// Return the description or a hash of it for longer ones
1321         ///
1322         /// This is not exported to bindings users because we don't yet export Bolt11InvoiceDescription
1323         pub fn description(&self) -> Bolt11InvoiceDescription {
1324                 if let Some(direct) = self.signed_invoice.description() {
1325                         return Bolt11InvoiceDescription::Direct(direct);
1326                 } else if let Some(hash) = self.signed_invoice.description_hash() {
1327                         return Bolt11InvoiceDescription::Hash(hash);
1328                 }
1329                 unreachable!("ensured by constructor");
1330         }
1331
1332         /// Get the payee's public key if one was included in the invoice
1333         pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1334                 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1335         }
1336
1337         /// Get the payment secret if one was included in the invoice
1338         pub fn payment_secret(&self) -> &PaymentSecret {
1339                 self.signed_invoice.payment_secret().expect("was checked by constructor")
1340         }
1341
1342         /// Get the payment metadata blob if one was included in the invoice
1343         pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1344                 self.signed_invoice.payment_metadata()
1345         }
1346
1347         /// Get the invoice features if they were included in the invoice
1348         pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1349                 self.signed_invoice.features()
1350         }
1351
1352         /// Recover the payee's public key (only to be used if none was included in the invoice)
1353         pub fn recover_payee_pub_key(&self) -> PublicKey {
1354                 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1355         }
1356
1357         /// Recover the payee's public key if one was included in the invoice, otherwise return the
1358         /// recovered public key from the signature
1359         pub fn get_payee_pub_key(&self) -> PublicKey {
1360                 match self.payee_pub_key() {
1361                         Some(pk) => *pk,
1362                         None => self.recover_payee_pub_key()
1363                 }
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::types::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::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: u64::from_be_bytes([123; 8]),
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: u64::from_be_bytes([42; 8]),
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: u64::from_be_bytes([1; 8]),
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(SystemTime::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 }