1 #![deny(rustdoc::broken_intra_doc_links)]
2 #![deny(rustdoc::private_intra_doc_links)]
5 #![deny(non_upper_case_globals)]
6 #![deny(non_camel_case_types)]
7 #![deny(non_snake_case)]
10 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
12 #![cfg_attr(feature = "strict", deny(warnings))]
13 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
15 //! This crate provides data structures to represent
16 //! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
17 //! invoices and functions to create, encode and decode these. If you just want to use the standard
18 //! en-/decoding functionality this should get you started:
20 //! * For parsing use `str::parse::<Bolt11Invoice>(&self)` (see [`Bolt11Invoice::from_str`])
21 //! * For constructing invoices use the [`InvoiceBuilder`]
22 //! * For serializing invoices use the [`Display`]/[`ToString`] traits
24 //! [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
26 #[cfg(not(any(feature = "std", feature = "no-std")))]
27 compile_error!("at least one of the `std` or `no-std` features must be enabled");
33 extern crate bitcoin_hashes;
34 #[macro_use] extern crate lightning;
35 extern crate num_traits;
36 extern crate secp256k1;
38 #[cfg(any(test, feature = "std"))]
40 #[cfg(feature = "serde")]
43 #[cfg(feature = "std")]
44 use std::time::SystemTime;
47 use bitcoin::{Address, Network, PubkeyHash, ScriptHash};
48 use bitcoin::address::{Payload, WitnessProgram, WitnessVersion};
49 use bitcoin_hashes::{Hash, sha256};
50 use lightning::ln::features::Bolt11InvoiceFeatures;
51 use lightning::util::invoice::construct_invoice_preimage;
53 use secp256k1::PublicKey;
54 use secp256k1::{Message, Secp256k1};
55 use secp256k1::ecdsa::RecoverableSignature;
57 use core::cmp::Ordering;
58 use core::fmt::{Display, Formatter, self};
59 use core::iter::FilterMap;
60 use core::num::ParseIntError;
62 use core::slice::Iter;
63 use core::time::Duration;
66 #[cfg(feature = "serde")]
67 use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
70 pub use lightning::ln::PaymentSecret;
72 pub use lightning::routing::router::{RouteHint, RouteHintHop};
74 pub use lightning::routing::gossip::RoutingFees;
75 use lightning::util::string::UntrustedString;
82 #[cfg(feature = "hashbrown")]
83 extern crate hashbrown;
85 pub use alloc::{vec, vec::Vec, string::String};
86 #[cfg(not(feature = "hashbrown"))]
87 pub use std::collections::{HashMap, hash_map};
88 #[cfg(feature = "hashbrown")]
89 pub use self::hashbrown::{HashMap, HashSet, hash_map};
91 pub use alloc::string::ToString;
94 use crate::prelude::*;
96 /// Sync compat for std/no_std
97 #[cfg(not(feature = "std"))]
100 /// Errors that indicate what is wrong with the invoice. They have some granularity for debug
101 /// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
102 #[allow(missing_docs)]
103 #[derive(PartialEq, Eq, Debug, Clone)]
104 pub enum Bolt11ParseError {
105 Bech32Error(bech32::Error),
106 ParseAmountError(ParseIntError),
107 MalformedSignature(secp256k1::Error),
113 UnexpectedEndOfTaggedFields,
114 DescriptionDecodeError(str::Utf8Error),
116 IntegerOverflowError,
117 InvalidSegWitProgramLength,
118 InvalidPubKeyHashLength,
119 InvalidScriptHashLength,
121 InvalidSliceLength(String),
123 /// Not an error, but used internally to signal that a part of the invoice should be ignored
124 /// according to BOLT11
128 /// Indicates that something went wrong while parsing or validating the invoice. Parsing errors
129 /// should be mostly seen as opaque and are only there for debugging reasons. Semantic errors
130 /// like wrong signatures, missing fields etc. could mean that someone tampered with the invoice.
131 #[derive(PartialEq, Eq, Debug, Clone)]
132 pub enum ParseOrSemanticError {
133 /// The invoice couldn't be decoded
134 ParseError(Bolt11ParseError),
136 /// The invoice could be decoded but violates the BOLT11 standard
137 SemanticError(crate::Bolt11SemanticError),
140 /// The number of bits used to represent timestamps as defined in BOLT 11.
141 const TIMESTAMP_BITS: usize = 35;
143 /// The maximum timestamp as [`Duration::as_secs`] since the Unix epoch allowed by [`BOLT 11`].
145 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
146 pub const MAX_TIMESTAMP: u64 = (1 << TIMESTAMP_BITS) - 1;
148 /// Default expiry time as defined by [BOLT 11].
150 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
151 pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
153 /// Default minimum final CLTV expiry as defined by [BOLT 11].
155 /// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
156 /// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
158 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
159 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
160 pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
162 /// Builder for [`Bolt11Invoice`]s. It's the most convenient and advised way to use this library. It
163 /// ensures that only a semantically and syntactically correct invoice can be built using it.
166 /// extern crate secp256k1;
167 /// extern crate lightning;
168 /// extern crate lightning_invoice;
169 /// extern crate bitcoin_hashes;
171 /// use bitcoin_hashes::Hash;
172 /// use bitcoin_hashes::sha256;
174 /// use secp256k1::Secp256k1;
175 /// use secp256k1::SecretKey;
177 /// use lightning::ln::PaymentSecret;
179 /// use lightning_invoice::{Currency, InvoiceBuilder};
181 /// # #[cfg(not(feature = "std"))]
183 /// # #[cfg(feature = "std")]
185 /// let private_key = SecretKey::from_slice(
187 /// 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
188 /// 0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
189 /// 0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
193 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
194 /// let payment_secret = PaymentSecret([42u8; 32]);
196 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
197 /// .description("Coins pls!".into())
198 /// .payment_hash(payment_hash)
199 /// .payment_secret(payment_secret)
200 /// .current_timestamp()
201 /// .min_final_cltv_expiry_delta(144)
202 /// .build_signed(|hash| {
203 /// Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
207 /// assert!(invoice.to_string().starts_with("lnbc1"));
211 /// # Type parameters
212 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
214 /// * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
215 /// * `H`: exactly one [`TaggedField::PaymentHash`]
216 /// * `T`: the timestamp is set
217 /// * `C`: the CLTV expiry is set
218 /// * `S`: the payment secret is set
219 /// * `M`: payment metadata is set
221 /// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
222 #[derive(Eq, PartialEq, Debug, Clone)]
223 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> {
226 si_prefix: Option<SiPrefix>,
227 timestamp: Option<PositiveTimestamp>,
228 tagged_fields: Vec<TaggedField>,
229 error: Option<CreationError>,
231 phantom_d: core::marker::PhantomData<D>,
232 phantom_h: core::marker::PhantomData<H>,
233 phantom_t: core::marker::PhantomData<T>,
234 phantom_c: core::marker::PhantomData<C>,
235 phantom_s: core::marker::PhantomData<S>,
236 phantom_m: core::marker::PhantomData<M>,
239 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
241 /// There are three ways to construct a `Bolt11Invoice`:
242 /// 1. using [`InvoiceBuilder`]
243 /// 2. using [`Bolt11Invoice::from_signed`]
244 /// 3. using `str::parse::<Bolt11Invoice>(&str)` (see [`Bolt11Invoice::from_str`])
246 /// [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
247 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
248 pub struct Bolt11Invoice {
249 signed_invoice: SignedRawBolt11Invoice,
252 /// Represents the description of an invoice which has to be either a directly included string or
253 /// a hash of a description provided out of band.
255 /// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
256 /// practically impossible to use safely in languages like C.
257 #[derive(Eq, PartialEq, Debug, Clone, Ord, PartialOrd)]
258 pub enum Bolt11InvoiceDescription<'f> {
259 /// Reference to the directly supplied description in the invoice
260 Direct(&'f Description),
262 /// Reference to the description's hash included in the invoice
266 impl<'f> Display for Bolt11InvoiceDescription<'f> {
267 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
269 Bolt11InvoiceDescription::Direct(desc) => write!(f, "{}", desc.0),
270 Bolt11InvoiceDescription::Hash(hash) => write!(f, "{}", hash.0),
275 /// Represents a signed [`RawBolt11Invoice`] with cached hash. The signature is not checked and may be
279 /// The hash has to be either from the deserialized invoice or from the serialized [`RawBolt11Invoice`].
280 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
281 pub struct SignedRawBolt11Invoice {
282 /// The raw invoice that the signature belongs to
283 raw_invoice: RawBolt11Invoice,
285 /// Hash of the [`RawBolt11Invoice`] that will be used to check the signature.
287 /// * if the `SignedRawBolt11Invoice` was deserialized the hash is of from the original encoded form,
288 /// since it's not guaranteed that encoding it again will lead to the same result since integers
289 /// could have been encoded with leading zeroes etc.
290 /// * if the `SignedRawBolt11Invoice` was constructed manually the hash will be the calculated hash
291 /// from the [`RawBolt11Invoice`]
294 /// signature of the payment request
295 signature: Bolt11InvoiceSignature,
298 /// Represents an syntactically correct [`Bolt11Invoice`] for a payment on the lightning network,
299 /// but without the signature information.
300 /// Decoding and encoding should not lead to information loss but may lead to different hashes.
302 /// For methods without docs see the corresponding methods in [`Bolt11Invoice`].
303 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
304 pub struct RawBolt11Invoice {
305 /// human readable part
309 pub data: RawDataPart,
312 /// Data of the [`RawBolt11Invoice`] that is encoded in the human readable part.
314 /// This is not exported to bindings users as we don't yet support `Option<Enum>`
315 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
317 /// The currency deferred from the 3rd and 4th character of the bech32 transaction
318 pub currency: Currency,
320 /// The amount that, multiplied by the SI prefix, has to be payed
321 pub raw_amount: Option<u64>,
323 /// SI prefix that gets multiplied with the `raw_amount`
324 pub si_prefix: Option<SiPrefix>,
327 /// Data of the [`RawBolt11Invoice`] that is encoded in the data part
328 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
329 pub struct RawDataPart {
330 /// generation time of the invoice
331 pub timestamp: PositiveTimestamp,
333 /// tagged fields of the payment request
334 pub tagged_fields: Vec<RawTaggedField>,
337 /// A timestamp that refers to a date after 1 January 1970.
341 /// The Unix timestamp representing the stored time has to be positive and no greater than
342 /// [`MAX_TIMESTAMP`].
343 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
344 pub struct PositiveTimestamp(Duration);
346 /// SI prefixes for the human readable part
347 #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Ord, PartialOrd)]
360 /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
361 /// This is effectively 10^12 * the prefix multiplier
362 pub fn multiplier(&self) -> u64 {
364 SiPrefix::Milli => 1_000_000_000,
365 SiPrefix::Micro => 1_000_000,
366 SiPrefix::Nano => 1_000,
371 /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
374 /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
375 /// isn't the most critical to expose.
376 pub fn values_desc() -> &'static [SiPrefix] {
377 use crate::SiPrefix::*;
378 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
383 /// Enum representing the crypto currencies (or networks) supported by this library
384 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
402 impl From<Network> for Currency {
403 fn from(network: Network) -> Self {
405 Network::Bitcoin => Currency::Bitcoin,
406 Network::Testnet => Currency::BitcoinTestnet,
407 Network::Regtest => Currency::Regtest,
408 Network::Signet => Currency::Signet,
410 debug_assert!(false, "Need to handle new rust-bitcoin network type");
417 impl From<Currency> for Network {
418 fn from(currency: Currency) -> Self {
420 Currency::Bitcoin => Network::Bitcoin,
421 Currency::BitcoinTestnet => Network::Testnet,
422 Currency::Regtest => Network::Regtest,
423 Currency::Simnet => Network::Regtest,
424 Currency::Signet => Network::Signet,
429 /// Tagged field which may have an unknown tag
431 /// This is not exported to bindings users as we don't currently support TaggedField
432 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
433 pub enum RawTaggedField {
434 /// Parsed tagged field with known tag
435 KnownSemantics(TaggedField),
436 /// tagged field which was not parsed due to an unknown tag or undefined field semantics
437 UnknownSemantics(Vec<u5>),
440 /// Tagged field with known tag
442 /// For descriptions of the enum values please refer to the enclosed type's docs.
444 /// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
446 #[allow(missing_docs)]
447 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
448 pub enum TaggedField {
450 Description(Description),
451 PayeePubKey(PayeePubKey),
452 DescriptionHash(Sha256),
453 ExpiryTime(ExpiryTime),
454 MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
456 PrivateRoute(PrivateRoute),
457 PaymentSecret(PaymentSecret),
458 PaymentMetadata(Vec<u8>),
459 Features(Bolt11InvoiceFeatures),
463 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
464 pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
468 /// Constructs a new [`Sha256`] from the given bytes, which are assumed to be the output of a
469 /// single sha256 hash.
471 pub fn from_bytes(bytes: &[u8; 32]) -> Self {
472 Self(sha256::Hash::from_slice(bytes).expect("from_slice only fails if len is not 32"))
476 /// Description string
479 /// The description can be at most 639 __bytes__ long
480 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd, Default)]
481 pub struct Description(UntrustedString);
484 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
485 pub struct PayeePubKey(pub PublicKey);
487 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
489 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
490 pub struct ExpiryTime(Duration);
492 /// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
493 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
494 pub struct MinFinalCltvExpiryDelta(pub u64);
496 /// Fallback address in case no LN payment is possible
497 #[allow(missing_docs)]
498 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
501 version: WitnessVersion,
504 PubKeyHash(PubkeyHash),
505 ScriptHash(ScriptHash),
508 /// Recoverable signature
509 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
510 pub struct Bolt11InvoiceSignature(pub RecoverableSignature);
512 impl PartialOrd for Bolt11InvoiceSignature {
513 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
514 Some(self.cmp(other))
518 impl Ord for Bolt11InvoiceSignature {
519 fn cmp(&self, other: &Self) -> Ordering {
520 self.0.serialize_compact().1.cmp(&other.0.serialize_compact().1)
524 /// Private routing information
527 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
529 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
530 pub struct PrivateRoute(pub RouteHint);
532 /// Tag constants as specified in BOLT11
533 #[allow(missing_docs)]
535 pub const TAG_PAYMENT_HASH: u8 = 1;
536 pub const TAG_DESCRIPTION: u8 = 13;
537 pub const TAG_PAYEE_PUB_KEY: u8 = 19;
538 pub const TAG_DESCRIPTION_HASH: u8 = 23;
539 pub const TAG_EXPIRY_TIME: u8 = 6;
540 pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
541 pub const TAG_FALLBACK: u8 = 9;
542 pub const TAG_PRIVATE_ROUTE: u8 = 3;
543 pub const TAG_PAYMENT_SECRET: u8 = 16;
544 pub const TAG_PAYMENT_METADATA: u8 = 27;
545 pub const TAG_FEATURES: u8 = 5;
548 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False, tb::False> {
549 /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
550 /// `InvoiceBuilder::build(self)` becomes available.
551 pub fn new(currency: Currency) -> Self {
557 tagged_fields: Vec::new(),
560 phantom_d: core::marker::PhantomData,
561 phantom_h: core::marker::PhantomData,
562 phantom_t: core::marker::PhantomData,
563 phantom_c: core::marker::PhantomData,
564 phantom_s: core::marker::PhantomData,
565 phantom_m: core::marker::PhantomData,
570 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, S, M> {
571 /// Helper function to set the completeness flags.
572 fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool, MN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN, MN> {
573 InvoiceBuilder::<DN, HN, TN, CN, SN, MN> {
574 currency: self.currency,
576 si_prefix: self.si_prefix,
577 timestamp: self.timestamp,
578 tagged_fields: self.tagged_fields,
581 phantom_d: core::marker::PhantomData,
582 phantom_h: core::marker::PhantomData,
583 phantom_t: core::marker::PhantomData,
584 phantom_c: core::marker::PhantomData,
585 phantom_s: core::marker::PhantomData,
586 phantom_m: core::marker::PhantomData,
590 /// Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.
591 pub fn amount_milli_satoshis(mut self, amount_msat: u64) -> Self {
592 let amount = amount_msat * 10; // Invoices are denominated in "pico BTC"
593 let biggest_possible_si_prefix = SiPrefix::values_desc()
595 .find(|prefix| amount % prefix.multiplier() == 0)
596 .expect("Pico should always match");
597 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
598 self.si_prefix = Some(*biggest_possible_si_prefix);
602 /// Sets the payee's public key.
603 pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
604 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
608 /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
610 pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
611 self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
615 /// Adds a fallback address.
616 pub fn fallback(mut self, fallback: Fallback) -> Self {
617 self.tagged_fields.push(TaggedField::Fallback(fallback));
621 /// Adds a private route.
622 pub fn private_route(mut self, hint: RouteHint) -> Self {
623 match PrivateRoute::new(hint) {
624 Ok(r) => self.tagged_fields.push(TaggedField::PrivateRoute(r)),
625 Err(e) => self.error = Some(e),
631 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S, M> {
632 /// Builds a [`RawBolt11Invoice`] if no [`CreationError`] occurred while construction any of the
634 pub fn build_raw(self) -> Result<RawBolt11Invoice, CreationError> {
636 // If an error occurred at any time before, return it now
637 if let Some(e) = self.error {
642 currency: self.currency,
643 raw_amount: self.amount,
644 si_prefix: self.si_prefix,
647 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
649 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
650 RawTaggedField::KnownSemantics(tf)
651 }).collect::<Vec<_>>();
653 let data = RawDataPart {
658 Ok(RawBolt11Invoice {
665 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S, M> {
666 /// Set the description. This function is only available if no description (hash) was set.
667 pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
668 match Description::new(description) {
669 Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
670 Err(e) => self.error = Some(e),
675 /// Set the description hash. This function is only available if no description (hash) was set.
676 pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
677 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
681 /// Set the description or description hash. This function is only available if no description (hash) was set.
682 pub fn invoice_description(self, description: Bolt11InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
684 Bolt11InvoiceDescription::Direct(desc) => {
685 self.description(desc.clone().into_inner().0)
687 Bolt11InvoiceDescription::Hash(hash) => {
688 self.description_hash(hash.0)
694 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S, M> {
695 /// Set the payment hash. This function is only available if no payment hash was set.
696 pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S, M> {
697 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
702 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S, M> {
703 /// Sets the timestamp to a specific [`SystemTime`].
704 #[cfg(feature = "std")]
705 pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
706 match PositiveTimestamp::from_system_time(time) {
707 Ok(t) => self.timestamp = Some(t),
708 Err(e) => self.error = Some(e),
714 /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
715 /// is not representable in BOLT 11 invoices).
716 pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
717 match PositiveTimestamp::from_duration_since_epoch(time) {
718 Ok(t) => self.timestamp = Some(t),
719 Err(e) => self.error = Some(e),
725 /// Sets the timestamp to the current system time.
726 #[cfg(feature = "std")]
727 pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
728 let now = PositiveTimestamp::from_system_time(SystemTime::now());
729 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
734 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S, M> {
735 /// Sets `min_final_cltv_expiry_delta`.
736 pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S, M> {
737 self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
742 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False, M> {
743 /// Sets the payment secret and relevant features.
744 pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True, M> {
745 let mut found_features = false;
746 for field in self.tagged_fields.iter_mut() {
747 if let TaggedField::Features(f) = field {
748 found_features = true;
749 f.set_variable_length_onion_required();
750 f.set_payment_secret_required();
753 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
755 let mut features = Bolt11InvoiceFeatures::empty();
756 features.set_variable_length_onion_required();
757 features.set_payment_secret_required();
758 self.tagged_fields.push(TaggedField::Features(features));
764 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::False> {
765 /// Sets the payment metadata.
767 /// By default features are set to *optionally* allow the sender to include the payment metadata.
768 /// If you wish to require that the sender include the metadata (and fail to parse the invoice if
769 /// they don't support payment metadata fields), you need to call
770 /// [`InvoiceBuilder::require_payment_metadata`] after this.
771 pub fn payment_metadata(mut self, payment_metadata: Vec<u8>) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
772 self.tagged_fields.push(TaggedField::PaymentMetadata(payment_metadata));
773 let mut found_features = false;
774 for field in self.tagged_fields.iter_mut() {
775 if let TaggedField::Features(f) = field {
776 found_features = true;
777 f.set_payment_metadata_optional();
781 let mut features = Bolt11InvoiceFeatures::empty();
782 features.set_payment_metadata_optional();
783 self.tagged_fields.push(TaggedField::Features(features));
789 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::True> {
790 /// Sets forwarding of payment metadata as required. A reader of the invoice which does not
791 /// support sending payment metadata will fail to read the invoice.
792 pub fn require_payment_metadata(mut self) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
793 for field in self.tagged_fields.iter_mut() {
794 if let TaggedField::Features(f) = field {
795 f.set_payment_metadata_required();
802 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True, M> {
803 /// Sets the `basic_mpp` feature as optional.
804 pub fn basic_mpp(mut self) -> Self {
805 for field in self.tagged_fields.iter_mut() {
806 if let TaggedField::Features(f) = field {
807 f.set_basic_mpp_optional();
814 impl<M: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True, M> {
815 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
816 /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
817 /// the included payee public key.
818 pub fn build_signed<F>(self, sign_function: F) -> Result<Bolt11Invoice, CreationError>
819 where F: FnOnce(&Message) -> RecoverableSignature
821 let invoice = self.try_build_signed::<_, ()>(|hash| {
822 Ok(sign_function(hash))
827 Err(SignOrCreationError::CreationError(e)) => Err(e),
828 Err(SignOrCreationError::SignError(())) => unreachable!(),
832 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
833 /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
834 /// if applicable also for the included payee public key.
835 pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Bolt11Invoice, SignOrCreationError<E>>
836 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
838 let raw = match self.build_raw() {
840 Err(e) => return Err(SignOrCreationError::CreationError(e)),
843 let signed = match raw.sign(sign_function) {
845 Err(e) => return Err(SignOrCreationError::SignError(e)),
848 let invoice = Bolt11Invoice {
849 signed_invoice: signed,
852 invoice.check_field_counts().expect("should be ensured by type signature of builder");
853 invoice.check_feature_bits().expect("should be ensured by type signature of builder");
854 invoice.check_amount().expect("should be ensured by type signature of builder");
861 impl SignedRawBolt11Invoice {
862 /// Disassembles the `SignedRawBolt11Invoice` into its three parts:
864 /// 2. hash of the raw invoice
866 pub fn into_parts(self) -> (RawBolt11Invoice, [u8; 32], Bolt11InvoiceSignature) {
867 (self.raw_invoice, self.hash, self.signature)
870 /// The [`RawBolt11Invoice`] which was signed.
871 pub fn raw_invoice(&self) -> &RawBolt11Invoice {
875 /// The hash of the [`RawBolt11Invoice`] that was signed.
876 pub fn signable_hash(&self) -> &[u8; 32] {
880 /// Signature for the invoice.
881 pub fn signature(&self) -> &Bolt11InvoiceSignature {
885 /// Recovers the public key used for signing the invoice from the recoverable signature.
886 pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
887 let hash = Message::from_slice(&self.hash[..])
888 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
890 Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
896 /// Checks if the signature is valid for the included payee public key or if none exists if it's
897 /// valid for the recovered signature (which should always be true?).
898 pub fn check_signature(&self) -> bool {
899 let included_pub_key = self.raw_invoice.payee_pub_key();
901 let mut recovered_pub_key = Option::None;
902 if recovered_pub_key.is_none() {
903 let recovered = match self.recover_payee_pub_key() {
905 Err(_) => return false,
907 recovered_pub_key = Some(recovered);
910 let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
911 .expect("One is always present");
913 let hash = Message::from_slice(&self.hash[..])
914 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
916 let secp_context = Secp256k1::new();
917 let verification_result = secp_context.verify_ecdsa(
919 &self.signature.to_standard(),
923 match verification_result {
930 /// Finds the first element of an enum stream of a given variant and extracts one member of the
931 /// variant. If no element was found `None` gets returned.
933 /// The following example would extract the first B.
941 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
943 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
945 macro_rules! find_extract {
946 ($iter:expr, $enm:pat, $enm_var:ident) => {
947 find_all_extract!($iter, $enm, $enm_var).next()
951 /// Finds the all elements of an enum stream of a given variant and extracts one member of the
952 /// variant through an iterator.
954 /// The following example would extract all A.
962 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
965 /// find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
966 /// vec![1u8, 2u8, 4u8]
969 macro_rules! find_all_extract {
970 ($iter:expr, $enm:pat, $enm_var:ident) => {
971 $iter.filter_map(|tf| match *tf {
972 $enm => Some($enm_var),
978 #[allow(missing_docs)]
979 impl RawBolt11Invoice {
980 /// Hash the HRP as bytes and signatureless data part.
981 fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
982 let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
983 let mut hash: [u8; 32] = Default::default();
984 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
988 /// Calculate the hash of the encoded `RawBolt11Invoice` which should be signed.
989 pub fn signable_hash(&self) -> [u8; 32] {
990 use bech32::ToBase32;
992 RawBolt11Invoice::hash_from_parts(
993 self.hrp.to_string().as_bytes(),
994 &self.data.to_base32()
998 /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
999 /// type `E`. Since the signature of a [`SignedRawBolt11Invoice`] is not required to be valid there
1000 /// are no constraints regarding the validity of the produced signature.
1002 /// This is not exported to bindings users as we don't currently support passing function pointers into methods
1004 pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawBolt11Invoice, E>
1005 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
1007 let raw_hash = self.signable_hash();
1008 let hash = Message::from_slice(&raw_hash[..])
1009 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
1010 let signature = sign_method(&hash)?;
1012 Ok(SignedRawBolt11Invoice {
1015 signature: Bolt11InvoiceSignature(signature),
1019 /// Returns an iterator over all tagged fields with known semantics.
1021 /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1022 pub fn known_tagged_fields(&self)
1023 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
1025 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
1026 // function's type signature.
1027 // TODO: refactor once impl Trait is available
1028 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
1030 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
1035 self.data.tagged_fields.iter().filter_map(match_raw )
1038 pub fn payment_hash(&self) -> Option<&Sha256> {
1039 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
1042 pub fn description(&self) -> Option<&Description> {
1043 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
1046 pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
1047 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
1050 pub fn description_hash(&self) -> Option<&Sha256> {
1051 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
1054 pub fn expiry_time(&self) -> Option<&ExpiryTime> {
1055 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
1058 pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
1059 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
1062 pub fn payment_secret(&self) -> Option<&PaymentSecret> {
1063 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
1066 pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1067 find_extract!(self.known_tagged_fields(), TaggedField::PaymentMetadata(ref x), x)
1070 pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1071 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
1074 /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1075 pub fn fallbacks(&self) -> Vec<&Fallback> {
1076 find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
1079 pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1080 find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
1083 pub fn amount_pico_btc(&self) -> Option<u64> {
1084 self.hrp.raw_amount.map(|v| {
1085 v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
1089 pub fn currency(&self) -> Currency {
1090 self.hrp.currency.clone()
1094 impl PositiveTimestamp {
1095 /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
1097 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1098 pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
1099 if unix_seconds <= MAX_TIMESTAMP {
1100 Ok(Self(Duration::from_secs(unix_seconds)))
1102 Err(CreationError::TimestampOutOfBounds)
1106 /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
1107 /// the range `0..=MAX_TIMESTAMP`.
1109 /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1111 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1112 #[cfg(feature = "std")]
1113 pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
1114 time.duration_since(SystemTime::UNIX_EPOCH)
1115 .map(Self::from_duration_since_epoch)
1116 .unwrap_or(Err(CreationError::TimestampOutOfBounds))
1119 /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
1120 /// `0..=MAX_TIMESTAMP`.
1122 /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1124 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1125 pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
1126 Self::from_unix_timestamp(duration.as_secs())
1129 /// Returns the Unix timestamp representing the stored time
1130 pub fn as_unix_timestamp(&self) -> u64 {
1134 /// Returns the duration of the stored time since the Unix epoch
1135 pub fn as_duration_since_epoch(&self) -> Duration {
1139 /// Returns the [`SystemTime`] representing the stored time
1140 #[cfg(feature = "std")]
1141 pub fn as_time(&self) -> SystemTime {
1142 SystemTime::UNIX_EPOCH + self.0
1146 impl From<PositiveTimestamp> for Duration {
1147 fn from(val: PositiveTimestamp) -> Self {
1152 #[cfg(feature = "std")]
1153 impl From<PositiveTimestamp> for SystemTime {
1154 fn from(val: PositiveTimestamp) -> Self {
1155 SystemTime::UNIX_EPOCH + val.0
1159 impl Bolt11Invoice {
1160 /// The hash of the [`RawBolt11Invoice`] that was signed.
1161 pub fn signable_hash(&self) -> [u8; 32] {
1162 self.signed_invoice.hash
1165 /// Transform the `Bolt11Invoice` into its unchecked version.
1166 pub fn into_signed_raw(self) -> SignedRawBolt11Invoice {
1170 /// Check that all mandatory fields are present
1171 fn check_field_counts(&self) -> Result<(), Bolt11SemanticError> {
1172 // "A writer MUST include exactly one p field […]."
1173 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1174 TaggedField::PaymentHash(_) => true,
1177 if payment_hash_cnt < 1 {
1178 return Err(Bolt11SemanticError::NoPaymentHash);
1179 } else if payment_hash_cnt > 1 {
1180 return Err(Bolt11SemanticError::MultiplePaymentHashes);
1183 // "A writer MUST include either exactly one d or exactly one h field."
1184 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1185 TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1188 if description_cnt < 1 {
1189 return Err(Bolt11SemanticError::NoDescription);
1190 } else if description_cnt > 1 {
1191 return Err(Bolt11SemanticError::MultipleDescriptions);
1194 self.check_payment_secret()?;
1199 /// Checks that there is exactly one payment secret field
1200 fn check_payment_secret(&self) -> Result<(), Bolt11SemanticError> {
1201 // "A writer MUST include exactly one `s` field."
1202 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1203 TaggedField::PaymentSecret(_) => true,
1206 if payment_secret_count < 1 {
1207 return Err(Bolt11SemanticError::NoPaymentSecret);
1208 } else if payment_secret_count > 1 {
1209 return Err(Bolt11SemanticError::MultiplePaymentSecrets);
1215 /// Check that amount is a whole number of millisatoshis
1216 fn check_amount(&self) -> Result<(), Bolt11SemanticError> {
1217 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1218 if amount_pico_btc % 10 != 0 {
1219 return Err(Bolt11SemanticError::ImpreciseAmount);
1225 /// Check that feature bits are set as required
1226 fn check_feature_bits(&self) -> Result<(), Bolt11SemanticError> {
1227 self.check_payment_secret()?;
1229 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1230 // (this requirement has been since removed, and we now require the payment secret
1231 // feature bit always).
1232 let features = self.tagged_fields().find(|&tf| match *tf {
1233 TaggedField::Features(_) => true,
1237 None => Err(Bolt11SemanticError::InvalidFeatures),
1238 Some(TaggedField::Features(features)) => {
1239 if features.requires_unknown_bits() {
1240 Err(Bolt11SemanticError::InvalidFeatures)
1241 } else if !features.supports_payment_secret() {
1242 Err(Bolt11SemanticError::InvalidFeatures)
1247 Some(_) => unreachable!(),
1251 /// Check that the invoice is signed correctly and that key recovery works
1252 pub fn check_signature(&self) -> Result<(), Bolt11SemanticError> {
1253 match self.signed_invoice.recover_payee_pub_key() {
1254 Err(secp256k1::Error::InvalidRecoveryId) =>
1255 return Err(Bolt11SemanticError::InvalidRecoveryId),
1256 Err(secp256k1::Error::InvalidSignature) =>
1257 return Err(Bolt11SemanticError::InvalidSignature),
1258 Err(e) => panic!("no other error may occur, got {:?}", e),
1262 if !self.signed_invoice.check_signature() {
1263 return Err(Bolt11SemanticError::InvalidSignature);
1269 /// Constructs a `Bolt11Invoice` from a [`SignedRawBolt11Invoice`] by checking all its invariants.
1271 /// use lightning_invoice::*;
1273 /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1274 /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1275 /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1276 /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1277 /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1278 /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1279 /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1280 /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1281 /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1282 /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1283 /// j5r6drg6k6zcqj0fcwg";
1285 /// let signed = invoice.parse::<SignedRawBolt11Invoice>().unwrap();
1287 /// assert!(Bolt11Invoice::from_signed(signed).is_ok());
1289 pub fn from_signed(signed_invoice: SignedRawBolt11Invoice) -> Result<Self, Bolt11SemanticError> {
1290 let invoice = Bolt11Invoice {
1293 invoice.check_field_counts()?;
1294 invoice.check_feature_bits()?;
1295 invoice.check_signature()?;
1296 invoice.check_amount()?;
1301 /// Returns the `Bolt11Invoice`'s timestamp (should equal its creation time)
1302 #[cfg(feature = "std")]
1303 pub fn timestamp(&self) -> SystemTime {
1304 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1307 /// Returns the `Bolt11Invoice`'s timestamp as a duration since the Unix epoch
1308 pub fn duration_since_epoch(&self) -> Duration {
1309 self.signed_invoice.raw_invoice().data.timestamp.0
1312 /// Returns an iterator over all tagged fields of this `Bolt11Invoice`.
1314 /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1315 pub fn tagged_fields(&self)
1316 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1317 self.signed_invoice.raw_invoice().known_tagged_fields()
1320 /// Returns the hash to which we will receive the preimage on completion of the payment
1321 pub fn payment_hash(&self) -> &sha256::Hash {
1322 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1325 /// Return the description or a hash of it for longer ones
1327 /// This is not exported to bindings users because we don't yet export Bolt11InvoiceDescription
1328 pub fn description(&self) -> Bolt11InvoiceDescription {
1329 if let Some(direct) = self.signed_invoice.description() {
1330 return Bolt11InvoiceDescription::Direct(direct);
1331 } else if let Some(hash) = self.signed_invoice.description_hash() {
1332 return Bolt11InvoiceDescription::Hash(hash);
1334 unreachable!("ensured by constructor");
1337 /// Get the payee's public key if one was included in the invoice
1338 pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1339 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1342 /// Get the payment secret if one was included in the invoice
1343 pub fn payment_secret(&self) -> &PaymentSecret {
1344 self.signed_invoice.payment_secret().expect("was checked by constructor")
1347 /// Get the payment metadata blob if one was included in the invoice
1348 pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1349 self.signed_invoice.payment_metadata()
1352 /// Get the invoice features if they were included in the invoice
1353 pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1354 self.signed_invoice.features()
1357 /// Recover the payee's public key (only to be used if none was included in the invoice)
1358 pub fn recover_payee_pub_key(&self) -> PublicKey {
1359 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1362 /// Returns the Duration since the Unix epoch at which the invoice expires.
1363 /// Returning None if overflow occurred.
1364 pub fn expires_at(&self) -> Option<Duration> {
1365 self.duration_since_epoch().checked_add(self.expiry_time())
1368 /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1369 pub fn expiry_time(&self) -> Duration {
1370 self.signed_invoice.expiry_time()
1372 .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1375 /// Returns whether the invoice has expired.
1376 #[cfg(feature = "std")]
1377 pub fn is_expired(&self) -> bool {
1378 Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
1381 /// Returns whether the expiry time from the given epoch has passed.
1382 #[cfg(feature = "std")]
1383 pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
1384 match epoch.elapsed() {
1385 Ok(elapsed) => elapsed > expiry_time,
1390 /// Returns the Duration remaining until the invoice expires.
1391 #[cfg(feature = "std")]
1392 pub fn duration_until_expiry(&self) -> Duration {
1393 SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
1394 .map(|now| self.expiration_remaining_from_epoch(now))
1395 .unwrap_or(Duration::from_nanos(0))
1398 /// Returns the Duration remaining until the invoice expires given the current time.
1399 /// `time` is the timestamp as a duration since the Unix epoch.
1400 pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
1401 self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
1404 /// Returns whether the expiry time would pass at the given point in time.
1405 /// `at_time` is the timestamp as a duration since the Unix epoch.
1406 pub fn would_expire(&self, at_time: Duration) -> bool {
1407 self.duration_since_epoch()
1408 .checked_add(self.expiry_time())
1409 .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
1412 /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
1413 /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
1414 pub fn min_final_cltv_expiry_delta(&self) -> u64 {
1415 self.signed_invoice.min_final_cltv_expiry_delta()
1417 .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
1420 /// Returns a list of all fallback addresses
1422 /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1423 pub fn fallbacks(&self) -> Vec<&Fallback> {
1424 self.signed_invoice.fallbacks()
1427 /// Returns a list of all fallback addresses as [`Address`]es
1428 pub fn fallback_addresses(&self) -> Vec<Address> {
1429 self.fallbacks().iter().filter_map(|fallback| {
1430 let payload = match fallback {
1431 Fallback::SegWitProgram { version, program } => {
1432 match WitnessProgram::new(*version, program.clone()) {
1433 Ok(witness_program) => Payload::WitnessProgram(witness_program),
1434 Err(_) => return None,
1437 Fallback::PubKeyHash(pkh) => {
1438 Payload::PubkeyHash(*pkh)
1440 Fallback::ScriptHash(sh) => {
1441 Payload::ScriptHash(*sh)
1445 Some(Address::new(self.network(), payload))
1449 /// Returns a list of all routes included in the invoice
1450 pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1451 self.signed_invoice.private_routes()
1454 /// Returns a list of all routes included in the invoice as the underlying hints
1455 pub fn route_hints(&self) -> Vec<RouteHint> {
1457 self.signed_invoice.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x
1458 ).map(|route| (**route).clone()).collect()
1461 /// Returns the currency for which the invoice was issued
1462 pub fn currency(&self) -> Currency {
1463 self.signed_invoice.currency()
1466 /// Returns the network for which the invoice was issued
1468 /// This is not exported to bindings users, see [`Self::currency`] instead.
1469 pub fn network(&self) -> Network {
1470 self.signed_invoice.currency().into()
1473 /// Returns the amount if specified in the invoice as millisatoshis.
1474 pub fn amount_milli_satoshis(&self) -> Option<u64> {
1475 self.signed_invoice.amount_pico_btc().map(|v| v / 10)
1478 /// Returns the amount if specified in the invoice as pico BTC.
1479 fn amount_pico_btc(&self) -> Option<u64> {
1480 self.signed_invoice.amount_pico_btc()
1484 impl From<TaggedField> for RawTaggedField {
1485 fn from(tf: TaggedField) -> Self {
1486 RawTaggedField::KnownSemantics(tf)
1491 /// Numeric representation of the field's tag
1492 pub fn tag(&self) -> u5 {
1493 let tag = match *self {
1494 TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
1495 TaggedField::Description(_) => constants::TAG_DESCRIPTION,
1496 TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
1497 TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
1498 TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
1499 TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
1500 TaggedField::Fallback(_) => constants::TAG_FALLBACK,
1501 TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
1502 TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
1503 TaggedField::PaymentMetadata(_) => constants::TAG_PAYMENT_METADATA,
1504 TaggedField::Features(_) => constants::TAG_FEATURES,
1507 u5::try_from_u8(tag).expect("all tags defined are <32")
1513 /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
1514 /// returns [`CreationError::DescriptionTooLong`] otherwise
1516 /// Please note that single characters may use more than one byte due to UTF8 encoding.
1517 pub fn new(description: String) -> Result<Description, CreationError> {
1518 if description.len() > 639 {
1519 Err(CreationError::DescriptionTooLong)
1521 Ok(Description(UntrustedString(description)))
1525 /// Returns the underlying description [`UntrustedString`]
1526 pub fn into_inner(self) -> UntrustedString {
1531 impl Display for Description {
1532 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1533 write!(f, "{}", self.0)
1537 impl From<PublicKey> for PayeePubKey {
1538 fn from(pk: PublicKey) -> Self {
1543 impl Deref for PayeePubKey {
1544 type Target = PublicKey;
1546 fn deref(&self) -> &PublicKey {
1552 /// Construct an `ExpiryTime` from seconds.
1553 pub fn from_seconds(seconds: u64) -> ExpiryTime {
1554 ExpiryTime(Duration::from_secs(seconds))
1557 /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
1558 pub fn from_duration(duration: Duration) -> ExpiryTime {
1559 Self::from_seconds(duration.as_secs())
1562 /// Returns the expiry time in seconds
1563 pub fn as_seconds(&self) -> u64 {
1567 /// Returns a reference to the underlying [`Duration`] (=expiry time)
1568 pub fn as_duration(&self) -> &Duration {
1574 /// Creates a new (partial) route from a list of hops
1575 pub fn new(hops: RouteHint) -> Result<PrivateRoute, CreationError> {
1576 if hops.0.len() <= 12 {
1577 Ok(PrivateRoute(hops))
1579 Err(CreationError::RouteTooLong)
1583 /// Returns the underlying list of hops
1584 pub fn into_inner(self) -> RouteHint {
1589 impl From<PrivateRoute> for RouteHint {
1590 fn from(val: PrivateRoute) -> Self {
1595 impl Deref for PrivateRoute {
1596 type Target = RouteHint;
1598 fn deref(&self) -> &RouteHint {
1603 impl Deref for Bolt11InvoiceSignature {
1604 type Target = RecoverableSignature;
1606 fn deref(&self) -> &RecoverableSignature {
1611 impl Deref for SignedRawBolt11Invoice {
1612 type Target = RawBolt11Invoice;
1614 fn deref(&self) -> &RawBolt11Invoice {
1619 /// Errors that may occur when constructing a new [`RawBolt11Invoice`] or [`Bolt11Invoice`]
1620 #[derive(Eq, PartialEq, Debug, Clone)]
1621 pub enum CreationError {
1622 /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
1625 /// The specified route has too many hops and can't be encoded
1628 /// The Unix timestamp of the supplied date is less than zero or greater than 35-bits
1629 TimestampOutOfBounds,
1631 /// The supplied millisatoshi amount was greater than the total bitcoin supply.
1634 /// Route hints were required for this invoice and were missing. Applies to
1635 /// [phantom invoices].
1637 /// [phantom invoices]: crate::utils::create_phantom_invoice
1640 /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
1642 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
1643 MinFinalCltvExpiryDeltaTooShort,
1646 impl Display for CreationError {
1647 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1649 CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
1650 CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
1651 CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
1652 CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
1653 CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
1654 CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
1655 "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
1660 #[cfg(feature = "std")]
1661 impl std::error::Error for CreationError { }
1663 /// Errors that may occur when converting a [`RawBolt11Invoice`] to a [`Bolt11Invoice`]. They relate to
1664 /// the requirements sections in BOLT #11
1665 #[derive(Eq, PartialEq, Debug, Clone)]
1666 pub enum Bolt11SemanticError {
1667 /// The invoice is missing the mandatory payment hash
1670 /// The invoice has multiple payment hashes which isn't allowed
1671 MultiplePaymentHashes,
1673 /// No description or description hash are part of the invoice
1676 /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
1677 MultipleDescriptions,
1679 /// The invoice is missing the mandatory payment secret, which all modern lightning nodes
1683 /// The invoice contains multiple payment secrets
1684 MultiplePaymentSecrets,
1686 /// The invoice's features are invalid
1689 /// The recovery id doesn't fit the signature/pub key
1692 /// The invoice's signature is invalid
1695 /// The invoice's amount was not a whole number of millisatoshis
1699 impl Display for Bolt11SemanticError {
1700 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1702 Bolt11SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
1703 Bolt11SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
1704 Bolt11SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
1705 Bolt11SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
1706 Bolt11SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
1707 Bolt11SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
1708 Bolt11SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
1709 Bolt11SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
1710 Bolt11SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
1711 Bolt11SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
1716 #[cfg(feature = "std")]
1717 impl std::error::Error for Bolt11SemanticError { }
1719 /// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
1721 #[derive(Eq, PartialEq, Debug, Clone)]
1722 pub enum SignOrCreationError<S = ()> {
1723 /// An error occurred during signing
1726 /// An error occurred while building the transaction
1727 CreationError(CreationError),
1730 impl<S> Display for SignOrCreationError<S> {
1731 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
1733 SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
1734 SignOrCreationError::CreationError(err) => err.fmt(f),
1739 #[cfg(feature = "serde")]
1740 impl Serialize for Bolt11Invoice {
1741 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer {
1742 serializer.serialize_str(self.to_string().as_str())
1745 #[cfg(feature = "serde")]
1746 impl<'de> Deserialize<'de> for Bolt11Invoice {
1747 fn deserialize<D>(deserializer: D) -> Result<Bolt11Invoice, D::Error> where D: Deserializer<'de> {
1748 let bolt11 = String::deserialize(deserializer)?
1749 .parse::<Bolt11Invoice>()
1750 .map_err(|e| D::Error::custom(format_args!("{:?}", e)))?;
1758 use bitcoin::ScriptBuf;
1759 use bitcoin_hashes::sha256;
1760 use std::str::FromStr;
1763 fn test_system_time_bounds_assumptions() {
1765 crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
1766 Err(crate::CreationError::TimestampOutOfBounds)
1771 fn test_calc_invoice_hash() {
1772 use crate::{RawBolt11Invoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
1773 use crate::TaggedField::*;
1775 let invoice = RawBolt11Invoice {
1777 currency: Currency::Bitcoin,
1782 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1783 tagged_fields: vec![
1784 PaymentHash(crate::Sha256(sha256::Hash::from_str(
1785 "0001020304050607080900010203040506070809000102030405060708090102"
1786 ).unwrap())).into(),
1787 Description(crate::Description::new(
1788 "Please consider supporting this project".to_owned()
1794 let expected_hash = [
1795 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
1796 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
1797 0xd5, 0x18, 0xe1, 0xc9
1800 assert_eq!(invoice.signable_hash(), expected_hash)
1804 fn test_check_signature() {
1805 use crate::TaggedField::*;
1806 use secp256k1::Secp256k1;
1807 use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
1808 use secp256k1::{SecretKey, PublicKey};
1809 use crate::{SignedRawBolt11Invoice, Bolt11InvoiceSignature, RawBolt11Invoice, RawHrp, RawDataPart, Currency, Sha256,
1812 let invoice = SignedRawBolt11Invoice {
1813 raw_invoice: RawBolt11Invoice {
1815 currency: Currency::Bitcoin,
1820 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1821 tagged_fields: vec ! [
1822 PaymentHash(Sha256(sha256::Hash::from_str(
1823 "0001020304050607080900010203040506070809000102030405060708090102"
1824 ).unwrap())).into(),
1826 crate::Description::new(
1827 "Please consider supporting this project".to_owned()
1834 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
1835 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
1836 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
1838 signature: Bolt11InvoiceSignature(RecoverableSignature::from_compact(
1840 0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
1841 0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
1842 0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
1843 0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
1844 0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
1845 0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
1847 RecoveryId::from_i32(0).unwrap()
1851 assert!(invoice.check_signature());
1853 let private_key = SecretKey::from_slice(
1855 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
1856 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
1857 0x3b, 0x2d, 0xb7, 0x34
1860 let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
1862 assert_eq!(invoice.recover_payee_pub_key(), Ok(crate::PayeePubKey(public_key)));
1864 let (raw_invoice, _, _) = invoice.into_parts();
1865 let new_signed = raw_invoice.sign::<_, ()>(|hash| {
1866 Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key))
1869 assert!(new_signed.check_signature());
1873 fn test_check_feature_bits() {
1874 use crate::TaggedField::*;
1875 use lightning::ln::features::Bolt11InvoiceFeatures;
1876 use secp256k1::Secp256k1;
1877 use secp256k1::SecretKey;
1878 use crate::{Bolt11Invoice, RawBolt11Invoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp,
1879 Bolt11SemanticError};
1881 let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
1882 let payment_secret = lightning::ln::PaymentSecret([21; 32]);
1883 let invoice_template = RawBolt11Invoice {
1885 currency: Currency::Bitcoin,
1890 timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
1891 tagged_fields: vec ! [
1892 PaymentHash(Sha256(sha256::Hash::from_str(
1893 "0001020304050607080900010203040506070809000102030405060708090102"
1894 ).unwrap())).into(),
1896 crate::Description::new(
1897 "Please consider supporting this project".to_owned()
1906 let mut invoice = invoice_template.clone();
1907 invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1908 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1910 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::InvalidFeatures));
1912 // Missing feature bits
1914 let mut invoice = invoice_template.clone();
1915 invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1916 invoice.data.tagged_fields.push(Features(Bolt11InvoiceFeatures::empty()).into());
1917 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1919 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::InvalidFeatures));
1921 let mut payment_secret_features = Bolt11InvoiceFeatures::empty();
1922 payment_secret_features.set_payment_secret_required();
1924 // Including payment secret and feature bits
1926 let mut invoice = invoice_template.clone();
1927 invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1928 invoice.data.tagged_fields.push(Features(payment_secret_features.clone()).into());
1929 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1931 assert!(Bolt11Invoice::from_signed(invoice).is_ok());
1933 // No payment secret or features
1935 let invoice = invoice_template.clone();
1936 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1938 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::NoPaymentSecret));
1940 // No payment secret or feature bits
1942 let mut invoice = invoice_template.clone();
1943 invoice.data.tagged_fields.push(Features(Bolt11InvoiceFeatures::empty()).into());
1944 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1946 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::NoPaymentSecret));
1948 // Missing payment secret
1950 let mut invoice = invoice_template.clone();
1951 invoice.data.tagged_fields.push(Features(payment_secret_features).into());
1952 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1954 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::NoPaymentSecret));
1956 // Multiple payment secrets
1958 let mut invoice = invoice_template;
1959 invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1960 invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
1961 invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
1963 assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::MultiplePaymentSecrets));
1967 fn test_builder_amount() {
1970 let builder = InvoiceBuilder::new(Currency::Bitcoin)
1971 .description("Test".into())
1972 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
1973 .duration_since_epoch(Duration::from_secs(1234567));
1975 let invoice = builder.clone()
1976 .amount_milli_satoshis(1500)
1980 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
1981 assert_eq!(invoice.hrp.raw_amount, Some(15));
1984 let invoice = builder
1985 .amount_milli_satoshis(150)
1989 assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
1990 assert_eq!(invoice.hrp.raw_amount, Some(1500));
1994 fn test_builder_fail() {
1996 use lightning::routing::router::RouteHintHop;
1997 use std::iter::FromIterator;
1998 use secp256k1::PublicKey;
2000 let builder = InvoiceBuilder::new(Currency::Bitcoin)
2001 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2002 .duration_since_epoch(Duration::from_secs(1234567))
2003 .min_final_cltv_expiry_delta(144);
2005 let too_long_string = String::from_iter(
2006 (0..1024).map(|_| '?')
2009 let long_desc_res = builder.clone()
2010 .description(too_long_string)
2012 assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
2014 let route_hop = RouteHintHop {
2015 src_node_id: PublicKey::from_slice(
2017 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
2018 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
2019 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
2022 short_channel_id: 0,
2025 proportional_millionths: 0,
2027 cltv_expiry_delta: 0,
2028 htlc_minimum_msat: None,
2029 htlc_maximum_msat: None,
2031 let too_long_route = RouteHint(vec![route_hop; 13]);
2032 let long_route_res = builder.clone()
2033 .description("Test".into())
2034 .private_route(too_long_route)
2036 assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
2038 let sign_error_res = builder
2039 .description("Test".into())
2040 .payment_secret(PaymentSecret([0; 32]))
2041 .try_build_signed(|_| {
2042 Err("ImaginaryError")
2044 assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
2048 fn test_builder_ok() {
2050 use lightning::routing::router::RouteHintHop;
2051 use secp256k1::Secp256k1;
2052 use secp256k1::{SecretKey, PublicKey};
2053 use std::time::{UNIX_EPOCH, Duration};
2055 let secp_ctx = Secp256k1::new();
2057 let private_key = SecretKey::from_slice(
2059 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
2060 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
2061 0x3b, 0x2d, 0xb7, 0x34
2064 let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
2066 let route_1 = RouteHint(vec![
2068 src_node_id: public_key,
2069 short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
2072 proportional_millionths: 1,
2074 cltv_expiry_delta: 145,
2075 htlc_minimum_msat: None,
2076 htlc_maximum_msat: None,
2079 src_node_id: public_key,
2080 short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
2083 proportional_millionths: 2,
2085 cltv_expiry_delta: 146,
2086 htlc_minimum_msat: None,
2087 htlc_maximum_msat: None,
2091 let route_2 = RouteHint(vec![
2093 src_node_id: public_key,
2094 short_channel_id: 0,
2097 proportional_millionths: 3,
2099 cltv_expiry_delta: 147,
2100 htlc_minimum_msat: None,
2101 htlc_maximum_msat: None,
2104 src_node_id: public_key,
2105 short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
2108 proportional_millionths: 4,
2110 cltv_expiry_delta: 148,
2111 htlc_minimum_msat: None,
2112 htlc_maximum_msat: None,
2116 let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
2117 .amount_milli_satoshis(123)
2118 .duration_since_epoch(Duration::from_secs(1234567))
2119 .payee_pub_key(public_key)
2120 .expiry_time(Duration::from_secs(54321))
2121 .min_final_cltv_expiry_delta(144)
2122 .fallback(Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap()))
2123 .private_route(route_1.clone())
2124 .private_route(route_2.clone())
2125 .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
2126 .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap())
2127 .payment_secret(PaymentSecret([42; 32]))
2130 let invoice = builder.clone().build_signed(|hash| {
2131 secp_ctx.sign_ecdsa_recoverable(hash, &private_key)
2134 assert!(invoice.check_signature().is_ok());
2135 assert_eq!(invoice.tagged_fields().count(), 10);
2137 assert_eq!(invoice.amount_milli_satoshis(), Some(123));
2138 assert_eq!(invoice.amount_pico_btc(), Some(1230));
2139 assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
2140 #[cfg(feature = "std")]
2142 invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
2145 assert_eq!(invoice.payee_pub_key(), Some(&public_key));
2146 assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
2147 assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
2148 assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap())]);
2149 let address = Address::from_script(&ScriptBuf::new_p2pkh(&PubkeyHash::from_slice(&[0;20]).unwrap()), Network::Testnet).unwrap();
2150 assert_eq!(invoice.fallback_addresses(), vec![address]);
2151 assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
2153 invoice.description(),
2154 Bolt11InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
2156 assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
2157 assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
2159 let mut expected_features = Bolt11InvoiceFeatures::empty();
2160 expected_features.set_variable_length_onion_required();
2161 expected_features.set_payment_secret_required();
2162 expected_features.set_basic_mpp_optional();
2163 assert_eq!(invoice.features(), Some(&expected_features));
2165 let raw_invoice = builder.build_raw().unwrap();
2166 assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
2170 fn test_default_values() {
2172 use secp256k1::Secp256k1;
2173 use secp256k1::SecretKey;
2175 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2176 .description("Test".into())
2177 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2178 .payment_secret(PaymentSecret([0; 32]))
2179 .duration_since_epoch(Duration::from_secs(1234567))
2182 .sign::<_, ()>(|hash| {
2183 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2184 let secp_ctx = Secp256k1::new();
2185 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2188 let invoice = Bolt11Invoice::from_signed(signed_invoice).unwrap();
2190 assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
2191 assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
2192 assert!(!invoice.would_expire(Duration::from_secs(1234568)));
2196 fn test_expiration() {
2198 use secp256k1::Secp256k1;
2199 use secp256k1::SecretKey;
2201 let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
2202 .description("Test".into())
2203 .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
2204 .payment_secret(PaymentSecret([0; 32]))
2205 .duration_since_epoch(Duration::from_secs(1234567))
2208 .sign::<_, ()>(|hash| {
2209 let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
2210 let secp_ctx = Secp256k1::new();
2211 Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
2214 let invoice = Bolt11Invoice::from_signed(signed_invoice).unwrap();
2216 assert!(invoice.would_expire(Duration::from_secs(1234567 + DEFAULT_EXPIRY_TIME + 1)));
2219 #[cfg(feature = "serde")]
2222 let invoice_str = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
2223 h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
2224 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
2225 h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
2226 j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
2227 ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
2228 guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
2229 ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
2230 p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
2231 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
2232 j5r6drg6k6zcqj0fcwg";
2233 let invoice = invoice_str.parse::<super::Bolt11Invoice>().unwrap();
2234 let serialized_invoice = serde_json::to_string(&invoice).unwrap();
2235 let deserialized_invoice: super::Bolt11Invoice = serde_json::from_str(serialized_invoice.as_str()).unwrap();
2236 assert_eq!(invoice, deserialized_invoice);
2237 assert_eq!(invoice_str, deserialized_invoice.to_string().as_str());
2238 assert_eq!(invoice_str, serialized_invoice.as_str().trim_matches('\"'));