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