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