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

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