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