2 #![deny(non_upper_case_globals)]
3 #![deny(non_camel_case_types)]
4 #![deny(non_snake_case)]
7 #![cfg_attr(feature = "strict", deny(warnings))]
9 //! This crate provides data structures to represent
10 //! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)
11 //! invoices and functions to create, encode and decode these. If you just want to use the standard
12 //! en-/decoding functionality this should get you started:
14 //! * For parsing use `str::parse::<Invoice>(&self)` (see the docs of `impl FromStr for Invoice`)
15 //! * For constructing invoices use the `InvoiceBuilder`
16 //! * For serializing invoices use the `Display`/`ToString` traits
19 extern crate bitcoin_hashes;
20 extern crate lightning;
21 extern crate num_traits;
22 extern crate secp256k1;
25 use bitcoin_hashes::Hash;
26 use bitcoin_hashes::sha256;
27 use lightning::ln::features::InvoiceFeatures;
28 #[cfg(any(doc, test))]
29 use lightning::routing::network_graph::RoutingFees;
30 use lightning::routing::router::RouteHintHop;
32 use secp256k1::key::PublicKey;
33 use secp256k1::{Message, Secp256k1};
34 use secp256k1::recovery::RecoverableSignature;
37 use std::iter::FilterMap;
39 use std::time::{SystemTime, Duration, UNIX_EPOCH};
40 use std::fmt::{Display, Formatter, self};
46 pub use de::{ParseError, ParseOrSemanticError};
48 // TODO: fix before 2037 (see rust PR #55527)
49 /// Defines the maximum UNIX timestamp that can be represented as `SystemTime`. This is checked by
50 /// one of the unit tests, please run them.
51 const SYSTEM_TIME_MAX_UNIX_TIMESTAMP: u64 = std::i32::MAX as u64;
53 /// Allow the expiry time to be up to one year. Since this reduces the range of possible timestamps
54 /// it should be rather low as long as we still have to support 32bit time representations
55 const MAX_EXPIRY_TIME: u64 = 60 * 60 * 24 * 356;
57 /// Default expiry time as defined by [BOLT 11].
59 /// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
60 const DEFAULT_EXPIRY_TIME: u64 = 3600;
62 /// Default minimum final CLTV expiry as defined by [BOLT 11].
64 /// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
65 const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
67 /// This function is used as a static assert for the size of `SystemTime`. If the crate fails to
68 /// compile due to it this indicates that your system uses unexpected bounds for `SystemTime`. You
69 /// can remove this functions and run the test `test_system_time_bounds_assumptions`. In any case,
70 /// please open an issue. If all tests pass you should be able to use this library safely by just
71 /// removing this function till we patch it accordingly.
72 fn __system_time_size_check() {
73 // Use 2 * sizeof(u64) as expected size since the expected underlying implementation is storing
74 // a `Duration` since `SystemTime::UNIX_EPOCH`.
75 unsafe { std::mem::transmute_copy::<SystemTime, [u8; 16]>(&UNIX_EPOCH); }
79 /// **Call this function on startup to ensure that all assumptions about the platform are valid.**
81 /// Unfortunately we have to make assumptions about the upper bounds of the `SystemTime` type on
82 /// your platform which we can't fully verify at compile time and which isn't part of it's contract.
83 /// To our best knowledge our assumptions hold for all platforms officially supported by rust, but
84 /// since this check is fast we recommend to do it anyway.
86 /// If this function fails this is considered a bug. Please open an issue describing your
87 /// platform and stating your current system time.
90 /// If the check fails this function panics. By calling this function on startup you ensure that
91 /// this wont happen at an arbitrary later point in time.
92 pub fn check_platform() {
93 // The upper and lower bounds of `SystemTime` are not part of its public contract and are
94 // platform specific. That's why we have to test if our assumptions regarding these bounds
95 // hold on the target platform.
97 // If this test fails on your platform, please don't use the library and open an issue
98 // instead so we can resolve the situation. Currently this library is tested on:
100 let fail_date = UNIX_EPOCH + Duration::from_secs(SYSTEM_TIME_MAX_UNIX_TIMESTAMP);
101 let year = Duration::from_secs(60 * 60 * 24 * 365);
103 // Make sure that the library will keep working for another year
104 assert!(fail_date.duration_since(SystemTime::now()).unwrap() > year);
106 let max_ts = PositiveTimestamp::from_unix_timestamp(
107 SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME
109 let max_exp = ::ExpiryTime::from_seconds(MAX_EXPIRY_TIME).unwrap();
112 (*max_ts.as_time() + *max_exp.as_duration()).duration_since(UNIX_EPOCH).unwrap().as_secs(),
113 SYSTEM_TIME_MAX_UNIX_TIMESTAMP
118 /// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures
119 /// that only a semantically and syntactically correct Invoice can be built using it.
122 /// extern crate secp256k1;
123 /// extern crate lightning_invoice;
124 /// extern crate bitcoin_hashes;
126 /// use bitcoin_hashes::Hash;
127 /// use bitcoin_hashes::sha256;
129 /// use secp256k1::Secp256k1;
130 /// use secp256k1::key::SecretKey;
132 /// use lightning_invoice::{Currency, InvoiceBuilder};
135 /// let private_key = SecretKey::from_slice(
137 /// 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
138 /// 0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
139 /// 0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
143 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
145 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
146 /// .description("Coins pls!".into())
147 /// .payment_hash(payment_hash)
148 /// .current_timestamp()
149 /// .min_final_cltv_expiry(144)
150 /// .build_signed(|hash| {
151 /// Secp256k1::new().sign_recoverable(hash, &private_key)
155 /// assert!(invoice.to_string().starts_with("lnbc1"));
159 /// # Type parameters
160 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
162 /// * `D`: exactly one `Description` or `DescriptionHash`
163 /// * `H`: exactly one `PaymentHash`
164 /// * `T`: the timestamp is set
166 /// (C-not exported) as we likely need to manually select one set of boolean type parameters.
167 #[derive(Eq, PartialEq, Debug, Clone)]
168 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> {
171 si_prefix: Option<SiPrefix>,
172 timestamp: Option<PositiveTimestamp>,
173 tagged_fields: Vec<TaggedField>,
174 error: Option<CreationError>,
176 phantom_d: std::marker::PhantomData<D>,
177 phantom_h: std::marker::PhantomData<H>,
178 phantom_t: std::marker::PhantomData<T>,
179 phantom_c: std::marker::PhantomData<C>,
182 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
184 /// There are three ways to construct an `Invoice`:
185 /// 1. using `InvoiceBuilder`
186 /// 2. using `Invoice::from_signed(SignedRawInvoice)`
187 /// 3. using `str::parse::<Invoice>(&str)`
188 #[derive(Eq, PartialEq, Debug, Clone)]
190 signed_invoice: SignedRawInvoice,
193 /// Represents the description of an invoice which has to be either a directly included string or
194 /// a hash of a description provided out of band.
196 /// (C-not exported) As we don't have a good way to map the reference lifetimes making this
197 /// practically impossible to use safely in languages like C.
198 #[derive(Eq, PartialEq, Debug, Clone)]
199 pub enum InvoiceDescription<'f> {
200 /// Reference to the directly supplied description in the invoice
201 Direct(&'f Description),
203 /// Reference to the description's hash included in the invoice
207 /// Represents a signed `RawInvoice` with cached hash. The signature is not checked and may be
211 /// The hash has to be either from the deserialized invoice or from the serialized `raw_invoice`.
212 #[derive(Eq, PartialEq, Debug, Clone)]
213 pub struct SignedRawInvoice {
214 /// The rawInvoice that the signature belongs to
215 raw_invoice: RawInvoice,
217 /// Hash of the `RawInvoice` that will be used to check the signature.
219 /// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form,
220 /// since it's not guaranteed that encoding it again will lead to the same result since integers
221 /// could have been encoded with leading zeroes etc.
222 /// * if the `SignedRawInvoice` was constructed manually the hash will be the calculated hash
223 /// from the `RawInvoice`
226 /// signature of the payment request
227 signature: InvoiceSignature,
230 /// Represents an syntactically correct Invoice for a payment on the lightning network,
231 /// but without the signature information.
232 /// De- and encoding should not lead to information loss but may lead to different hashes.
234 /// For methods without docs see the corresponding methods in `Invoice`.
235 #[derive(Eq, PartialEq, Debug, Clone)]
236 pub struct RawInvoice {
237 /// human readable part
241 pub data: RawDataPart,
244 /// Data of the `RawInvoice` that is encoded in the human readable part
246 /// (C-not exported) As we don't yet support Option<Enum>
247 #[derive(Eq, PartialEq, Debug, Clone)]
249 /// The currency deferred from the 3rd and 4th character of the bech32 transaction
250 pub currency: Currency,
252 /// The amount that, multiplied by the SI prefix, has to be payed
253 pub raw_amount: Option<u64>,
255 /// SI prefix that gets multiplied with the `raw_amount`
256 pub si_prefix: Option<SiPrefix>,
259 /// Data of the `RawInvoice` that is encoded in the data part
260 #[derive(Eq, PartialEq, Debug, Clone)]
261 pub struct RawDataPart {
262 /// generation time of the invoice
263 pub timestamp: PositiveTimestamp,
265 /// tagged fields of the payment request
266 pub tagged_fields: Vec<RawTaggedField>,
269 /// A timestamp that refers to a date after 1 January 1970 which means its representation as UNIX
270 /// timestamp is positive.
273 /// The UNIX timestamp representing the stored time has to be positive and small enough so that
274 /// a `EpiryTime` can be added to it without an overflow.
275 #[derive(Eq, PartialEq, Debug, Clone)]
276 pub struct PositiveTimestamp(SystemTime);
278 /// SI prefixes for the human readable part
279 #[derive(Eq, PartialEq, Debug, Clone, Copy)]
292 /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
293 /// This is effectively 10^12 * the prefix multiplier
294 pub fn multiplier(&self) -> u64 {
296 SiPrefix::Milli => 1_000_000_000,
297 SiPrefix::Micro => 1_000_000,
298 SiPrefix::Nano => 1_000,
303 /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
306 /// (C-not exported) As we don't yet support a slice of enums, and also because this function
307 /// isn't the most critical to expose.
308 pub fn values_desc() -> &'static [SiPrefix] {
310 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
315 /// Enum representing the crypto currencies (or networks) supported by this library
316 #[derive(Eq, PartialEq, Debug, Clone)]
327 /// Bitcoin simnet/signet
331 /// Tagged field which may have an unknown tag
332 #[derive(Eq, PartialEq, Debug, Clone)]
333 pub enum RawTaggedField {
334 /// Parsed tagged field with known tag
335 KnownSemantics(TaggedField),
336 /// tagged field which was not parsed due to an unknown tag or undefined field semantics
337 UnknownSemantics(Vec<u5>),
340 /// Tagged field with known tag
342 /// For descriptions of the enum values please refer to the enclosed type's docs.
343 #[allow(missing_docs)]
344 #[derive(Eq, PartialEq, Debug, Clone)]
345 pub enum TaggedField {
347 Description(Description),
348 PayeePubKey(PayeePubKey),
349 DescriptionHash(Sha256),
350 ExpiryTime(ExpiryTime),
351 MinFinalCltvExpiry(MinFinalCltvExpiry),
354 PaymentSecret(PaymentSecret),
355 Features(InvoiceFeatures),
359 #[derive(Eq, PartialEq, Debug, Clone)]
360 pub struct Sha256(pub sha256::Hash);
362 /// Description string
365 /// The description can be at most 639 __bytes__ long
366 #[derive(Eq, PartialEq, Debug, Clone)]
367 pub struct Description(String);
370 #[derive(Eq, PartialEq, Debug, Clone)]
371 pub struct PayeePubKey(pub PublicKey);
373 /// 256-bit payment secret
374 #[derive(Eq, PartialEq, Debug, Clone)]
375 pub struct PaymentSecret(pub [u8; 32]);
377 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
381 /// The number of seconds this expiry time represents has to be in the range
382 /// `0...(SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)` to avoid overflows when adding it to a
384 #[derive(Eq, PartialEq, Debug, Clone)]
385 pub struct ExpiryTime(Duration);
387 /// `min_final_cltv_expiry` to use for the last HTLC in the route
388 #[derive(Eq, PartialEq, Debug, Clone)]
389 pub struct MinFinalCltvExpiry(pub u64);
391 // TODO: better types instead onf byte arrays
392 /// Fallback address in case no LN payment is possible
393 #[allow(missing_docs)]
394 #[derive(Eq, PartialEq, Debug, Clone)]
400 PubKeyHash([u8; 20]),
401 ScriptHash([u8; 20]),
404 /// Recoverable signature
405 #[derive(Eq, PartialEq, Debug, Clone)]
406 pub struct InvoiceSignature(pub RecoverableSignature);
408 /// Private routing information
411 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
413 #[derive(Eq, PartialEq, Debug, Clone)]
414 pub struct RouteHint(Vec<RouteHintHop>);
416 /// Tag constants as specified in BOLT11
417 #[allow(missing_docs)]
419 pub const TAG_PAYMENT_HASH: u8 = 1;
420 pub const TAG_DESCRIPTION: u8 = 13;
421 pub const TAG_PAYEE_PUB_KEY: u8 = 19;
422 pub const TAG_DESCRIPTION_HASH: u8 = 23;
423 pub const TAG_EXPIRY_TIME: u8 = 6;
424 pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
425 pub const TAG_FALLBACK: u8 = 9;
426 pub const TAG_ROUTE: u8 = 3;
427 pub const TAG_PAYMENT_SECRET: u8 = 16;
428 pub const TAG_FEATURES: u8 = 5;
431 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False> {
432 /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
433 /// `InvoiceBuilder::build(self)` becomes available.
434 pub fn new(currrency: Currency) -> Self {
440 tagged_fields: Vec::new(),
443 phantom_d: std::marker::PhantomData,
444 phantom_h: std::marker::PhantomData,
445 phantom_t: std::marker::PhantomData,
446 phantom_c: std::marker::PhantomData,
451 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C> {
452 /// Helper function to set the completeness flags.
453 fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN> {
454 InvoiceBuilder::<DN, HN, TN, CN> {
455 currency: self.currency,
457 si_prefix: self.si_prefix,
458 timestamp: self.timestamp,
459 tagged_fields: self.tagged_fields,
462 phantom_d: std::marker::PhantomData,
463 phantom_h: std::marker::PhantomData,
464 phantom_t: std::marker::PhantomData,
465 phantom_c: std::marker::PhantomData,
469 /// Sets the amount in pico BTC. The optimal SI prefix is choosen automatically.
470 pub fn amount_pico_btc(mut self, amount: u64) -> Self {
471 let biggest_possible_si_prefix = SiPrefix::values_desc()
473 .find(|prefix| amount % prefix.multiplier() == 0)
474 .expect("Pico should always match");
475 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
476 self.si_prefix = Some(*biggest_possible_si_prefix);
480 /// Sets the payee's public key.
481 pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
482 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
486 /// Sets the payment secret
487 pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> Self {
488 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
492 /// Sets the expiry time
493 pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
494 match ExpiryTime::from_duration(expiry_time) {
495 Ok(t) => self.tagged_fields.push(TaggedField::ExpiryTime(t)),
496 Err(e) => self.error = Some(e),
501 /// Adds a fallback address.
502 pub fn fallback(mut self, fallback: Fallback) -> Self {
503 self.tagged_fields.push(TaggedField::Fallback(fallback));
507 /// Adds a private route.
508 pub fn route(mut self, route: Vec<RouteHintHop>) -> Self {
509 match RouteHint::new(route) {
510 Ok(r) => self.tagged_fields.push(TaggedField::Route(r)),
511 Err(e) => self.error = Some(e),
516 /// Adds a features field which indicates the set of supported protocol extensions which the
517 /// origin node supports.
518 pub fn features(mut self, features: InvoiceFeatures) -> Self {
519 self.tagged_fields.push(TaggedField::Features(features));
524 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, tb::True, C> {
525 /// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields.
526 pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
528 // If an error occurred at any time before, return it now
529 if let Some(e) = self.error {
534 currency: self.currency,
535 raw_amount: self.amount,
536 si_prefix: self.si_prefix,
539 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
541 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
542 RawTaggedField::KnownSemantics(tf)
543 }).collect::<Vec<_>>();
545 let data = RawDataPart {
546 timestamp: timestamp,
547 tagged_fields: tagged_fields,
557 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<tb::False, H, T, C> {
558 /// Set the description. This function is only available if no description (hash) was set.
559 pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C> {
560 match Description::new(description) {
561 Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
562 Err(e) => self.error = Some(e),
567 /// Set the description hash. This function is only available if no description (hash) was set.
568 pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C> {
569 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
574 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, tb::False, T, C> {
575 /// Set the payment hash. This function is only available if no payment hash was set.
576 pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C> {
577 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
582 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, tb::False, C> {
583 /// Sets the timestamp.
584 pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C> {
585 match PositiveTimestamp::from_system_time(time) {
586 Ok(t) => self.timestamp = Some(t),
587 Err(e) => self.error = Some(e),
593 /// Sets the timestamp to the current UNIX timestamp.
594 pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C> {
595 let now = PositiveTimestamp::from_system_time(SystemTime::now());
596 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
601 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool> InvoiceBuilder<D, H, T, tb::False> {
602 /// Sets `min_final_cltv_expiry`.
603 pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True> {
604 self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
609 impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True> {
610 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
611 /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
612 /// the included payee public key.
613 pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
614 where F: FnOnce(&Message) -> RecoverableSignature
616 let invoice = self.try_build_signed::<_, ()>(|hash| {
617 Ok(sign_function(hash))
622 Err(SignOrCreationError::CreationError(e)) => Err(e),
623 Err(SignOrCreationError::SignError(())) => unreachable!(),
627 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
628 /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
629 /// if applicable also for the included payee public key.
630 pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Invoice, SignOrCreationError<E>>
631 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
633 let raw = match self.build_raw() {
635 Err(e) => return Err(SignOrCreationError::CreationError(e)),
638 let signed = match raw.sign(sign_function) {
640 Err(e) => return Err(SignOrCreationError::SignError(e)),
643 let invoice = Invoice {
644 signed_invoice: signed,
647 invoice.check_field_counts().expect("should be ensured by type signature of builder");
654 impl SignedRawInvoice {
655 /// Disassembles the `SignedRawInvoice` into its three parts:
657 /// 2. hash of the raw invoice
659 pub fn into_parts(self) -> (RawInvoice, [u8; 32], InvoiceSignature) {
660 (self.raw_invoice, self.hash, self.signature)
663 /// The `RawInvoice` which was signed.
664 pub fn raw_invoice(&self) -> &RawInvoice {
668 /// The hash of the `RawInvoice` that was signed.
669 pub fn hash(&self) -> &[u8; 32] {
673 /// InvoiceSignature for the invoice.
674 pub fn signature(&self) -> &InvoiceSignature {
678 /// Recovers the public key used for signing the invoice from the recoverable signature.
679 pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
680 let hash = Message::from_slice(&self.hash[..])
681 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
683 Ok(PayeePubKey(Secp256k1::new().recover(
689 /// Checks if the signature is valid for the included payee public key or if none exists if it's
690 /// valid for the recovered signature (which should always be true?).
691 pub fn check_signature(&self) -> bool {
692 let included_pub_key = self.raw_invoice.payee_pub_key();
694 let mut recovered_pub_key = Option::None;
695 if recovered_pub_key.is_none() {
696 let recovered = match self.recover_payee_pub_key() {
698 Err(_) => return false,
700 recovered_pub_key = Some(recovered);
703 let pub_key = included_pub_key.or_else(|| recovered_pub_key.as_ref())
704 .expect("One is always present");
706 let hash = Message::from_slice(&self.hash[..])
707 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
709 let secp_context = Secp256k1::new();
710 let verification_result = secp_context.verify(
712 &self.signature.to_standard(),
716 match verification_result {
723 /// Finds the first element of an enum stream of a given variant and extracts one member of the
724 /// variant. If no element was found `None` gets returned.
726 /// The following example would extract the first
735 /// let elements = vec![A(1), A(2), B(3), A(4)]
737 /// assert_eq!(find_extract!(elements.iter(), Enum::B(ref x), x), Some(3u16))
739 macro_rules! find_extract {
740 ($iter:expr, $enm:pat, $enm_var:ident) => {
741 $iter.filter_map(|tf| match *tf {
742 $enm => Some($enm_var),
748 #[allow(missing_docs)]
750 /// Hash the HRP as bytes and signatureless data part.
751 fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
752 use bech32::FromBase32;
754 let mut preimage = Vec::<u8>::from(hrp_bytes);
756 let mut data_part = Vec::from(data_without_signature);
757 let overhang = (data_part.len() * 5) % 8;
759 // add padding if data does not end at a byte boundary
760 data_part.push(u5::try_from_u8(0).unwrap());
762 // if overhang is in (1..3) we need to add u5(0) padding two times
764 data_part.push(u5::try_from_u8(0).unwrap());
768 preimage.extend_from_slice(&Vec::<u8>::from_base32(&data_part)
769 .expect("No padding error may occur due to appended zero above."));
771 let mut hash: [u8; 32] = Default::default();
772 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
776 /// Calculate the hash of the encoded `RawInvoice`
777 pub fn hash(&self) -> [u8; 32] {
778 use bech32::ToBase32;
780 RawInvoice::hash_from_parts(
781 self.hrp.to_string().as_bytes(),
782 &self.data.to_base32()
786 /// Signs the invoice using the supplied `sign_function`. This function MAY fail with an error
787 /// of type `E`. Since the signature of a `SignedRawInvoice` is not required to be valid there
788 /// are no constraints regarding the validity of the produced signature.
790 /// (C-not exported) As we don't currently support passing function pointers into methods
792 pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
793 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
795 let raw_hash = self.hash();
796 let hash = Message::from_slice(&raw_hash[..])
797 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
798 let signature = sign_method(&hash)?;
800 Ok(SignedRawInvoice {
803 signature: InvoiceSignature(signature),
807 /// Returns an iterator over all tagged fields with known semantics.
809 /// (C-not exported) As there is not yet a manual mapping for a FilterMap
810 pub fn known_tagged_fields(&self)
811 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
813 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
814 // function's type signature.
815 // TODO: refactor once impl Trait is available
816 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
818 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
823 self.data.tagged_fields.iter().filter_map(match_raw )
826 pub fn payment_hash(&self) -> Option<&Sha256> {
827 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
830 pub fn description(&self) -> Option<&Description> {
831 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
834 pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
835 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
838 pub fn description_hash(&self) -> Option<&Sha256> {
839 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
842 pub fn expiry_time(&self) -> Option<&ExpiryTime> {
843 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
846 pub fn min_final_cltv_expiry(&self) -> Option<&MinFinalCltvExpiry> {
847 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
850 pub fn payment_secret(&self) -> Option<&PaymentSecret> {
851 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
854 pub fn features(&self) -> Option<&InvoiceFeatures> {
855 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
858 /// (C-not exported) as we don't support Vec<&NonOpaqueType>
859 pub fn fallbacks(&self) -> Vec<&Fallback> {
860 self.known_tagged_fields().filter_map(|tf| match tf {
861 &TaggedField::Fallback(ref f) => Some(f),
863 }).collect::<Vec<&Fallback>>()
866 pub fn routes(&self) -> Vec<&RouteHint> {
867 self.known_tagged_fields().filter_map(|tf| match tf {
868 &TaggedField::Route(ref r) => Some(r),
870 }).collect::<Vec<&RouteHint>>()
873 pub fn amount_pico_btc(&self) -> Option<u64> {
874 self.hrp.raw_amount.map(|v| {
875 v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
879 pub fn currency(&self) -> Currency {
880 self.hrp.currency.clone()
884 impl PositiveTimestamp {
885 /// Create a new `PositiveTimestamp` from a unix timestamp in the Range
886 /// `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
887 /// `CreationError::TimestampOutOfBounds`.
888 pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
889 if unix_seconds > SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME {
890 Err(CreationError::TimestampOutOfBounds)
892 Ok(PositiveTimestamp(UNIX_EPOCH + Duration::from_secs(unix_seconds)))
896 /// Create a new `PositiveTimestamp` from a `SystemTime` with a corresponding unix timestamp in
897 /// the Range `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
898 /// `CreationError::TimestampOutOfBounds`.
899 pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
901 .duration_since(UNIX_EPOCH)
902 .map(|t| t.as_secs() <= SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)
905 Ok(PositiveTimestamp(time))
907 Err(CreationError::TimestampOutOfBounds)
911 /// Returns the UNIX timestamp representing the stored time
912 pub fn as_unix_timestamp(&self) -> u64 {
913 self.0.duration_since(UNIX_EPOCH)
914 .expect("ensured by type contract/constructors")
918 /// Returns a reference to the internal `SystemTime` time representation
919 pub fn as_time(&self) -> &SystemTime {
924 impl Into<SystemTime> for PositiveTimestamp {
925 fn into(self) -> SystemTime {
930 impl Deref for PositiveTimestamp {
931 type Target = SystemTime;
933 fn deref(&self) -> &Self::Target {
939 /// Transform the `Invoice` into it's unchecked version
940 pub fn into_signed_raw(self) -> SignedRawInvoice {
944 /// Check that all mandatory fields are present
945 fn check_field_counts(&self) -> Result<(), SemanticError> {
946 // "A writer MUST include exactly one p field […]."
947 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
948 TaggedField::PaymentHash(_) => true,
951 if payment_hash_cnt < 1 {
952 return Err(SemanticError::NoPaymentHash);
953 } else if payment_hash_cnt > 1 {
954 return Err(SemanticError::MultiplePaymentHashes);
957 // "A writer MUST include either exactly one d or exactly one h field."
958 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
959 TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
962 if description_cnt < 1 {
963 return Err(SemanticError::NoDescription);
964 } else if description_cnt > 1 {
965 return Err(SemanticError::MultipleDescriptions);
971 /// Check that the invoice is signed correctly and that key recovery works
972 pub fn check_signature(&self) -> Result<(), SemanticError> {
973 match self.signed_invoice.recover_payee_pub_key() {
974 Err(secp256k1::Error::InvalidRecoveryId) =>
975 return Err(SemanticError::InvalidRecoveryId),
976 Err(_) => panic!("no other error may occur"),
980 if !self.signed_invoice.check_signature() {
981 return Err(SemanticError::InvalidSignature);
987 /// Constructs an `Invoice` from a `SignedInvoice` by checking all its invariants.
989 /// use lightning_invoice::*;
991 /// let invoice = "lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp\
992 /// l2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d7\
993 /// 3gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ec\
996 /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
998 /// assert!(Invoice::from_signed(signed).is_ok());
1000 pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
1001 let invoice = Invoice {
1002 signed_invoice: signed_invoice,
1004 invoice.check_field_counts()?;
1005 invoice.check_signature()?;
1010 /// Returns the `Invoice`'s timestamp (should equal it's creation time)
1011 pub fn timestamp(&self) -> &SystemTime {
1012 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1015 /// Returns an iterator over all tagged fields of this Invoice.
1017 /// (C-not exported) As there is not yet a manual mapping for a FilterMap
1018 pub fn tagged_fields(&self)
1019 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1020 self.signed_invoice.raw_invoice().known_tagged_fields()
1023 /// Returns the hash to which we will receive the preimage on completion of the payment
1024 pub fn payment_hash(&self) -> &sha256::Hash {
1025 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1028 /// Return the description or a hash of it for longer ones
1030 /// (C-not exported) because we don't yet export InvoiceDescription
1031 pub fn description(&self) -> InvoiceDescription {
1032 if let Some(ref direct) = self.signed_invoice.description() {
1033 return InvoiceDescription::Direct(direct);
1034 } else if let Some(ref hash) = self.signed_invoice.description_hash() {
1035 return InvoiceDescription::Hash(hash);
1037 unreachable!("ensured by constructor");
1040 /// Get the payee's public key if one was included in the invoice
1041 pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1042 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1045 /// Get the payment secret if one was included in the invoice
1046 pub fn payment_secret(&self) -> Option<&PaymentSecret> {
1047 self.signed_invoice.payment_secret()
1050 /// Get the invoice features if they were included in the invoice
1051 pub fn features(&self) -> Option<&InvoiceFeatures> {
1052 self.signed_invoice.features()
1055 /// Recover the payee's public key (only to be used if none was included in the invoice)
1056 pub fn recover_payee_pub_key(&self) -> PublicKey {
1057 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1060 /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1061 pub fn expiry_time(&self) -> Duration {
1062 self.signed_invoice.expiry_time()
1064 .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1067 /// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
1068 /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
1069 pub fn min_final_cltv_expiry(&self) -> u64 {
1070 self.signed_invoice.min_final_cltv_expiry()
1072 .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
1075 /// Returns a list of all fallback addresses
1077 /// (C-not exported) as we don't support Vec<&NonOpaqueType>
1078 pub fn fallbacks(&self) -> Vec<&Fallback> {
1079 self.signed_invoice.fallbacks()
1082 /// Returns a list of all routes included in the invoice
1083 pub fn routes(&self) -> Vec<&RouteHint> {
1084 self.signed_invoice.routes()
1087 /// Returns the currency for which the invoice was issued
1088 pub fn currency(&self) -> Currency {
1089 self.signed_invoice.currency()
1092 /// Returns the amount if specified in the invoice as pico <currency>.
1093 pub fn amount_pico_btc(&self) -> Option<u64> {
1094 self.signed_invoice.amount_pico_btc()
1098 impl From<TaggedField> for RawTaggedField {
1099 fn from(tf: TaggedField) -> Self {
1100 RawTaggedField::KnownSemantics(tf)
1105 /// Numeric representation of the field's tag
1106 pub fn tag(&self) -> u5 {
1107 let tag = match *self {
1108 TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1109 TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1110 TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1111 TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1112 TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1113 TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY,
1114 TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1115 TaggedField::Route(_) => constants::TAG_ROUTE,
1116 TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1117 TaggedField::Features(_) => constants::TAG_FEATURES,
1120 u5::try_from_u8(tag).expect("all tags defined are <32")
1126 /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1127 /// returns `CreationError::DescriptionTooLong` otherwise
1129 /// Please note that single characters may use more than one byte due to UTF8 encoding.
1130 pub fn new(description: String) -> Result<Description, CreationError> {
1131 if description.len() > 639 {
1132 Err(CreationError::DescriptionTooLong)
1134 Ok(Description(description))
1138 /// Returns the underlying description `String`
1139 pub fn into_inner(self) -> String {
1144 impl Into<String> for Description {
1145 fn into(self) -> String {
1150 impl Deref for Description {
1153 fn deref(&self) -> &str {
1158 impl From<PublicKey> for PayeePubKey {
1159 fn from(pk: PublicKey) -> Self {
1164 impl Deref for PayeePubKey {
1165 type Target = PublicKey;
1167 fn deref(&self) -> &PublicKey {
1173 /// Construct an `ExpiryTime` from seconds. If there exists a `PositiveTimestamp` which would
1174 /// overflow on adding the `EpiryTime` to it then this function will return a
1175 /// `CreationError::ExpiryTimeOutOfBounds`.
1176 pub fn from_seconds(seconds: u64) -> Result<ExpiryTime, CreationError> {
1177 if seconds <= MAX_EXPIRY_TIME {
1178 Ok(ExpiryTime(Duration::from_secs(seconds)))
1180 Err(CreationError::ExpiryTimeOutOfBounds)
1184 /// Construct an `ExpiryTime` from a `Duration`. If there exists a `PositiveTimestamp` which
1185 /// would overflow on adding the `EpiryTime` to it then this function will return a
1186 /// `CreationError::ExpiryTimeOutOfBounds`.
1187 pub fn from_duration(duration: Duration) -> Result<ExpiryTime, CreationError> {
1188 if duration.as_secs() <= MAX_EXPIRY_TIME {
1189 Ok(ExpiryTime(duration))
1191 Err(CreationError::ExpiryTimeOutOfBounds)
1195 /// Returns the expiry time in seconds
1196 pub fn as_seconds(&self) -> u64 {
1200 /// Returns a reference to the underlying `Duration` (=expiry time)
1201 pub fn as_duration(&self) -> &Duration {
1207 /// Create a new (partial) route from a list of hops
1208 pub fn new(hops: Vec<RouteHintHop>) -> Result<RouteHint, CreationError> {
1209 if hops.len() <= 12 {
1212 Err(CreationError::RouteTooLong)
1216 /// Returrn the underlying vector of hops
1217 pub fn into_inner(self) -> Vec<RouteHintHop> {
1222 impl Into<Vec<RouteHintHop>> for RouteHint {
1223 fn into(self) -> Vec<RouteHintHop> {
1228 impl Deref for RouteHint {
1229 type Target = Vec<RouteHintHop>;
1231 fn deref(&self) -> &Vec<RouteHintHop> {
1236 impl Deref for InvoiceSignature {
1237 type Target = RecoverableSignature;
1239 fn deref(&self) -> &RecoverableSignature {
1244 impl Deref for SignedRawInvoice {
1245 type Target = RawInvoice;
1247 fn deref(&self) -> &RawInvoice {
1252 /// Errors that may occur when constructing a new `RawInvoice` or `Invoice`
1253 #[derive(Eq, PartialEq, Debug, Clone)]
1254 pub enum CreationError {
1255 /// The supplied description string was longer than 639 __bytes__ (see [`Description::new(…)`](./struct.Description.html#method.new))
1258 /// The specified route has too many hops and can't be encoded
1261 /// The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`
1262 TimestampOutOfBounds,
1264 /// The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`
1265 ExpiryTimeOutOfBounds,
1268 impl Display for CreationError {
1269 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1271 CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1272 CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1273 CreationError::TimestampOutOfBounds => f.write_str("The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`"),
1274 CreationError::ExpiryTimeOutOfBounds => f.write_str("The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`"),
1279 impl std::error::Error for CreationError { }
1281 /// Errors that may occur when converting a `RawInvoice` to an `Invoice`. They relate to the
1282 /// requirements sections in BOLT #11
1283 #[derive(Eq, PartialEq, Debug, Clone)]
1284 pub enum SemanticError {
1285 /// The invoice is missing the mandatory payment hash
1288 /// The invoice has multiple payment hashes which isn't allowed
1289 MultiplePaymentHashes,
1291 /// No description or description hash are part of the invoice
1294 /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1295 MultipleDescriptions,
1297 /// The recovery id doesn't fit the signature/pub key
1300 /// The invoice's signature is invalid
1304 impl Display for SemanticError {
1305 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1307 SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1308 SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1309 SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1310 SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1311 SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1312 SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1317 impl std::error::Error for SemanticError { }
1319 /// When signing using a fallible method either an user-supplied `SignError` or a `CreationError`
1322 /// (C-not exported) As we don't support unbounded generics
1323 #[derive(Eq, PartialEq, Debug, Clone)]
1324 pub enum SignOrCreationError<S> {
1325 /// An error occurred during signing
1328 /// An error occurred while building the transaction
1329 CreationError(CreationError),
1332 impl<S> Display for SignOrCreationError<S> {
1333 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1335 SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1336 SignOrCreationError::CreationError(err) => err.fmt(f),
1343 use bitcoin_hashes::hex::FromHex;
1344 use bitcoin_hashes::sha256;
1347 fn test_system_time_bounds_assumptions() {
1351 ::PositiveTimestamp::from_unix_timestamp(::SYSTEM_TIME_MAX_UNIX_TIMESTAMP + 1),
1352 Err(::CreationError::TimestampOutOfBounds)
1356 ::ExpiryTime::from_seconds(::MAX_EXPIRY_TIME + 1),
1357 Err(::CreationError::ExpiryTimeOutOfBounds)
1362 fn test_calc_invoice_hash() {
1363 use ::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1364 use ::TaggedField::*;
1366 let invoice = RawInvoice {
1368 currency: Currency::Bitcoin,
1373 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1374 tagged_fields: vec![
1375 PaymentHash(::Sha256(sha256::Hash::from_hex(
1376 "0001020304050607080900010203040506070809000102030405060708090102"
1377 ).unwrap())).into(),
1378 Description(::Description::new(
1379 "Please consider supporting this project".to_owned()
1385 let expected_hash = [
1386 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1387 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1388 0xd5, 0x18, 0xe1, 0xc9
1391 assert_eq!(invoice.hash(), expected_hash)
1395 fn test_check_signature() {
1397 use secp256k1::Secp256k1;
1398 use secp256k1::recovery::{RecoveryId, RecoverableSignature};
1399 use secp256k1::key::{SecretKey, PublicKey};
1400 use {SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
1403 let invoice = SignedRawInvoice {
1404 raw_invoice: RawInvoice {
1406 currency: Currency::Bitcoin,
1411 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1412 tagged_fields: vec ! [
1413 PaymentHash(Sha256(sha256::Hash::from_hex(
1414 "0001020304050607080900010203040506070809000102030405060708090102"
1415 ).unwrap())).into(),
1418 "Please consider supporting this project".to_owned()
1425 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1426 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1427 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1429 signature: InvoiceSignature(RecoverableSignature::from_compact(
1431 0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1432 0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1433 0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1434 0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1435 0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1436 0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1438 RecoveryId::from_i32(0).unwrap()
1442 assert!(invoice.check_signature());
1444 let private_key = SecretKey::from_slice(
1446 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1447 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1448 0x3b, 0x2d, 0xb7, 0x34
1451 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1453 assert_eq!(invoice.recover_payee_pub_key(), Ok(::PayeePubKey(public_key)));
1455 let (raw_invoice, _, _) = invoice.into_parts();
1456 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1457 Ok(Secp256k1::new().sign_recoverable(hash, &private_key))
1460 assert!(new_signed.check_signature());
1464 fn test_builder_amount() {
1467 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1468 .description("Test".into())
1469 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1470 .current_timestamp();
1472 let invoice = builder.clone()
1473 .amount_pico_btc(15000)
1477 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1478 assert_eq!(invoice.hrp.raw_amount, Some(15));
1481 let invoice = builder.clone()
1482 .amount_pico_btc(1500)
1486 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1487 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1491 fn test_builder_fail() {
1493 use std::iter::FromIterator;
1494 use secp256k1::key::PublicKey;
1496 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1497 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1498 .current_timestamp()
1499 .min_final_cltv_expiry(144);
1501 let too_long_string = String::from_iter(
1502 (0..1024).map(|_| '?')
1505 let long_desc_res = builder.clone()
1506 .description(too_long_string)
1508 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
1510 let route_hop = RouteHintHop {
1511 src_node_id: PublicKey::from_slice(
1513 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
1514 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
1515 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
1518 short_channel_id: 0,
1521 proportional_millionths: 0,
1523 cltv_expiry_delta: 0,
1524 htlc_minimum_msat: None,
1525 htlc_maximum_msat: None,
1527 let too_long_route = vec![route_hop; 13];
1528 let long_route_res = builder.clone()
1529 .description("Test".into())
1530 .route(too_long_route)
1532 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
1534 let sign_error_res = builder.clone()
1535 .description("Test".into())
1536 .try_build_signed(|_| {
1537 Err("ImaginaryError")
1539 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
1543 fn test_builder_ok() {
1545 use secp256k1::Secp256k1;
1546 use secp256k1::key::{SecretKey, PublicKey};
1547 use std::time::{UNIX_EPOCH, Duration};
1549 let secp_ctx = Secp256k1::new();
1551 let private_key = SecretKey::from_slice(
1553 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1554 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1555 0x3b, 0x2d, 0xb7, 0x34
1558 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
1562 src_node_id: public_key.clone(),
1563 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
1566 proportional_millionths: 1,
1568 cltv_expiry_delta: 145,
1569 htlc_minimum_msat: None,
1570 htlc_maximum_msat: None,
1573 src_node_id: public_key.clone(),
1574 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
1577 proportional_millionths: 2,
1579 cltv_expiry_delta: 146,
1580 htlc_minimum_msat: None,
1581 htlc_maximum_msat: None,
1587 src_node_id: public_key.clone(),
1588 short_channel_id: 0,
1591 proportional_millionths: 3,
1593 cltv_expiry_delta: 147,
1594 htlc_minimum_msat: None,
1595 htlc_maximum_msat: None,
1598 src_node_id: public_key.clone(),
1599 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
1602 proportional_millionths: 4,
1604 cltv_expiry_delta: 148,
1605 htlc_minimum_msat: None,
1606 htlc_maximum_msat: None,
1610 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
1611 .amount_pico_btc(123)
1612 .timestamp(UNIX_EPOCH + Duration::from_secs(1234567))
1613 .payee_pub_key(public_key.clone())
1614 .expiry_time(Duration::from_secs(54321))
1615 .min_final_cltv_expiry(144)
1616 .fallback(Fallback::PubKeyHash([0;20]))
1617 .route(route_1.clone())
1618 .route(route_2.clone())
1619 .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
1620 .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap());
1622 let invoice = builder.clone().build_signed(|hash| {
1623 secp_ctx.sign_recoverable(hash, &private_key)
1626 assert!(invoice.check_signature().is_ok());
1627 assert_eq!(invoice.tagged_fields().count(), 8);
1629 assert_eq!(invoice.amount_pico_btc(), Some(123));
1630 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
1632 invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1635 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
1636 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
1637 assert_eq!(invoice.min_final_cltv_expiry(), 144);
1638 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
1639 assert_eq!(invoice.routes(), vec![&RouteHint(route_1), &RouteHint(route_2)]);
1641 invoice.description(),
1642 InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
1644 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
1646 let raw_invoice = builder.build_raw().unwrap();
1647 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())