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

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