1 // Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
2 #![deny(broken_intra_doc_links)]
3 #![deny(private_intra_doc_links)]
6 #![deny(non_upper_case_globals)]
7 #![deny(non_camel_case_types)]
8 #![deny(non_snake_case)]
11 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
13 #![cfg_attr(feature = "strict", deny(warnings))]
14 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
16 //! This crate provides data structures to represent
17 //! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
18 //! invoices and functions to create, encode and decode these. If you just want to use the standard
19 //! en-/decoding functionality this should get you started:
21 //! * For parsing use `str::parse::<Bolt11Invoice>(&self)` (see [`Bolt11Invoice::from_str`])
22 //! * For constructing invoices use the [`InvoiceBuilder`]
23 //! * For serializing invoices use the [`Display`]/[`ToString`] traits
25 //! [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
27 #[cfg(not(any(feature = "std", feature = "no-std")))]
28 compile_error!("at least one of the `std` or `no-std` features must be enabled");
34 extern crate bitcoin_hashes;
35 #[macro_use] extern crate lightning;
36 extern crate num_traits;
37 extern crate secp256k1;
39 #[cfg(any(test, feature = "std"))]
41 #[cfg(feature = "serde")]
44 #[cfg(feature = "std")]
45 use std::time::SystemTime;
48 use bitcoin::{Address, Network, PubkeyHash, ScriptHash};
49 use bitcoin::util::address::{Payload, WitnessVersion};
50 use bitcoin_hashes::{Hash, sha256};
51 use lightning::ln::features::Bolt11InvoiceFeatures;
52 use lightning::util::invoice::construct_invoice_preimage;
54 use secp256k1::PublicKey;
55 use secp256k1::{Message, Secp256k1};
56 use secp256k1::ecdsa::RecoverableSignature;
58 use core::cmp::Ordering;
59 use core::fmt::{Display, Formatter, self};
60 use core::iter::FilterMap;
61 use core::num::ParseIntError;
63 use core::slice::Iter;
64 use core::time::Duration;
67 #[cfg(feature = "serde")]
68 use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
71 pub use lightning::ln::PaymentSecret;
73 pub use lightning::routing::router::{RouteHint, RouteHintHop};
75 pub use lightning::routing::gossip::RoutingFees;
76 use lightning::util::string::UntrustedString;
83 #[cfg(feature = "hashbrown")]
84 extern crate hashbrown;
86 pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
87 #[cfg(not(feature = "hashbrown"))]
88 pub use std::collections::{HashMap, HashSet, hash_map};
89 #[cfg(feature = "hashbrown")]
90 pub use self::hashbrown::{HashMap, HashSet, hash_map};
92 pub use alloc::string::ToString;
95 use crate::prelude::*;
97 /// Sync compat for std/no_std
98 #[cfg(feature = "std")]
100 pub use ::std::sync::{Mutex, MutexGuard};
103 /// Sync compat for std/no_std
104 #[cfg(not(feature = "std"))]
107 /// Errors that indicate what is wrong with the invoice. They have some granularity for debug
108 /// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
109 #[allow(missing_docs)]
110 #[derive(PartialEq, Eq, Debug, Clone)]
111 pub enum Bolt11ParseError {
112 Bech32Error(bech32::Error),
113 ParseAmountError(ParseIntError),
114 MalformedSignature(secp256k1::Error),
120 UnexpectedEndOfTaggedFields,
121 DescriptionDecodeError(str::Utf8Error),
123 IntegerOverflowError,
124 InvalidSegWitProgramLength,
125 InvalidPubKeyHashLength,
126 InvalidScriptHashLength,
128 InvalidSliceLength(String),
130 /// Not an error, but used internally to signal that a part of the invoice should be ignored
131 /// according to BOLT11
135 /// Indicates that something went wrong while parsing or validating the invoice. Parsing errors
136 /// should be mostly seen as opaque and are only there for debugging reasons. Semantic errors
137 /// like wrong signatures, missing fields etc. could mean that someone tampered with the invoice.
138 #[derive(PartialEq, Eq, Debug, Clone)]
139 pub enum ParseOrSemanticError {
140 /// The invoice couldn't be decoded
141 ParseError(Bolt11ParseError),
143 /// The invoice could be decoded but violates the BOLT11 standard
144 SemanticError(crate::Bolt11SemanticError),
147 /// The number of bits used to represent timestamps as defined in BOLT 11.
148 const TIMESTAMP_BITS: usize = 35;
150 /// The maximum timestamp as [`Duration::as_secs`] since the Unix epoch allowed by [`BOLT 11`].
152 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
153 pub const MAX_TIMESTAMP: u64 = (1 << TIMESTAMP_BITS) - 1;
155 /// Default expiry time as defined by [BOLT 11].
157 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
158 pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
160 /// Default minimum final CLTV expiry as defined by [BOLT 11].
162 /// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
163 /// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
165 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
166 /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
167 pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
169 /// Builder for [`Bolt11Invoice`]s. It's the most convenient and advised way to use this library. It
170 /// ensures that only a semantically and syntactically correct invoice can be built using it.
173 /// extern crate secp256k1;
174 /// extern crate lightning;
175 /// extern crate lightning_invoice;
176 /// extern crate bitcoin_hashes;
178 /// use bitcoin_hashes::Hash;
179 /// use bitcoin_hashes::sha256;
181 /// use secp256k1::Secp256k1;
182 /// use secp256k1::SecretKey;
184 /// use lightning::ln::PaymentSecret;
186 /// use lightning_invoice::{Currency, InvoiceBuilder};
188 /// # #[cfg(not(feature = "std"))]
190 /// # #[cfg(feature = "std")]
192 /// let private_key = SecretKey::from_slice(
194 /// 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
195 /// 0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
196 /// 0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
200 /// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
201 /// let payment_secret = PaymentSecret([42u8; 32]);
203 /// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
204 /// .description("Coins pls!".into())
205 /// .payment_hash(payment_hash)
206 /// .payment_secret(payment_secret)
207 /// .current_timestamp()
208 /// .min_final_cltv_expiry_delta(144)
209 /// .build_signed(|hash| {
210 /// Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
214 /// assert!(invoice.to_string().starts_with("lnbc1"));
218 /// # Type parameters
219 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
221 /// * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
222 /// * `H`: exactly one [`TaggedField::PaymentHash`]
223 /// * `T`: the timestamp is set
224 /// * `C`: the CLTV expiry is set
225 /// * `S`: the payment secret is set
226 /// * `M`: payment metadata is set
228 /// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
229 #[derive(Eq, PartialEq, Debug, Clone)]
230 pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> {
233 si_prefix: Option<SiPrefix>,
234 timestamp: Option<PositiveTimestamp>,
235 tagged_fields: Vec<TaggedField>,
236 error: Option<CreationError>,
238 phantom_d: core::marker::PhantomData<D>,
239 phantom_h: core::marker::PhantomData<H>,
240 phantom_t: core::marker::PhantomData<T>,
241 phantom_c: core::marker::PhantomData<C>,
242 phantom_s: core::marker::PhantomData<S>,
243 phantom_m: core::marker::PhantomData<M>,
246 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
248 /// There are three ways to construct a `Bolt11Invoice`:
249 /// 1. using [`InvoiceBuilder`]
250 /// 2. using [`Bolt11Invoice::from_signed`]
251 /// 3. using `str::parse::<Bolt11Invoice>(&str)` (see [`Bolt11Invoice::from_str`])
253 /// [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
254 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
255 pub struct Bolt11Invoice {
256 signed_invoice: SignedRawBolt11Invoice,
259 /// Represents the description of an invoice which has to be either a directly included string or
260 /// a hash of a description provided out of band.
262 /// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
263 /// practically impossible to use safely in languages like C.
264 #[derive(Eq, PartialEq, Debug, Clone, Ord, PartialOrd)]
265 pub enum Bolt11InvoiceDescription<'f> {
266 /// Reference to the directly supplied description in the invoice
267 Direct(&'f Description),
269 /// Reference to the description's hash included in the invoice
273 impl<'f> Display for Bolt11InvoiceDescription<'f> {
274 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
276 Bolt11InvoiceDescription::Direct(desc) => write!(f, "{}", desc.0),
277 Bolt11InvoiceDescription::Hash(hash) => write!(f, "{}", hash.0),
282 /// Represents a signed [`RawBolt11Invoice`] with cached hash. The signature is not checked and may be
286 /// The hash has to be either from the deserialized invoice or from the serialized [`RawBolt11Invoice`].
287 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
288 pub struct SignedRawBolt11Invoice {
289 /// The raw invoice that the signature belongs to
290 raw_invoice: RawBolt11Invoice,
292 /// Hash of the [`RawBolt11Invoice`] that will be used to check the signature.
294 /// * if the `SignedRawBolt11Invoice` was deserialized the hash is of from the original encoded form,
295 /// since it's not guaranteed that encoding it again will lead to the same result since integers
296 /// could have been encoded with leading zeroes etc.
297 /// * if the `SignedRawBolt11Invoice` was constructed manually the hash will be the calculated hash
298 /// from the [`RawBolt11Invoice`]
301 /// signature of the payment request
302 signature: Bolt11InvoiceSignature,
305 /// Represents an syntactically correct [`Bolt11Invoice`] for a payment on the lightning network,
306 /// but without the signature information.
307 /// Decoding and encoding should not lead to information loss but may lead to different hashes.
309 /// For methods without docs see the corresponding methods in [`Bolt11Invoice`].
310 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
311 pub struct RawBolt11Invoice {
312 /// human readable part
316 pub data: RawDataPart,
319 /// Data of the [`RawBolt11Invoice`] that is encoded in the human readable part.
321 /// This is not exported to bindings users as we don't yet support `Option<Enum>`
322 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
324 /// The currency deferred from the 3rd and 4th character of the bech32 transaction
325 pub currency: Currency,
327 /// The amount that, multiplied by the SI prefix, has to be payed
328 pub raw_amount: Option<u64>,
330 /// SI prefix that gets multiplied with the `raw_amount`
331 pub si_prefix: Option<SiPrefix>,
334 /// Data of the [`RawBolt11Invoice`] that is encoded in the data part
335 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
336 pub struct RawDataPart {
337 /// generation time of the invoice
338 pub timestamp: PositiveTimestamp,
340 /// tagged fields of the payment request
341 pub tagged_fields: Vec<RawTaggedField>,
344 /// A timestamp that refers to a date after 1 January 1970.
348 /// The Unix timestamp representing the stored time has to be positive and no greater than
349 /// [`MAX_TIMESTAMP`].
350 #[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
351 pub struct PositiveTimestamp(Duration);
353 /// SI prefixes for the human readable part
354 #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Ord, PartialOrd)]
367 /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
368 /// This is effectively 10^12 * the prefix multiplier
369 pub fn multiplier(&self) -> u64 {
371 SiPrefix::Milli => 1_000_000_000,
372 SiPrefix::Micro => 1_000_000,
373 SiPrefix::Nano => 1_000,
378 /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
381 /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
382 /// isn't the most critical to expose.
383 pub fn values_desc() -> &'static [SiPrefix] {
384 use crate::SiPrefix::*;
385 static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
390 /// Enum representing the crypto currencies (or networks) supported by this library
391 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
409 impl From<Network> for Currency {
410 fn from(network: Network) -> Self {
412 Network::Bitcoin => Currency::Bitcoin,
413 Network::Testnet => Currency::BitcoinTestnet,
414 Network::Regtest => Currency::Regtest,
415 Network::Signet => Currency::Signet,
420 impl From<Currency> for Network {
421 fn from(currency: Currency) -> Self {
423 Currency::Bitcoin => Network::Bitcoin,
424 Currency::BitcoinTestnet => Network::Testnet,
425 Currency::Regtest => Network::Regtest,
426 Currency::Simnet => Network::Regtest,
427 Currency::Signet => Network::Signet,
432 /// Tagged field which may have an unknown tag
434 /// This is not exported to bindings users as we don't currently support TaggedField
435 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
436 pub enum RawTaggedField {
437 /// Parsed tagged field with known tag
438 KnownSemantics(TaggedField),
439 /// tagged field which was not parsed due to an unknown tag or undefined field semantics
440 UnknownSemantics(Vec<u5>),
443 /// Tagged field with known tag
445 /// For descriptions of the enum values please refer to the enclosed type's docs.
447 /// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
449 #[allow(missing_docs)]
450 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
451 pub enum TaggedField {
453 Description(Description),
454 PayeePubKey(PayeePubKey),
455 DescriptionHash(Sha256),
456 ExpiryTime(ExpiryTime),
457 MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
459 PrivateRoute(PrivateRoute),
460 PaymentSecret(PaymentSecret),
461 PaymentMetadata(Vec<u8>),
462 Features(Bolt11InvoiceFeatures),
466 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
467 pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
471 /// Constructs a new [`Sha256`] from the given bytes, which are assumed to be the output of a
472 /// single sha256 hash.
474 pub fn from_bytes(bytes: &[u8; 32]) -> Self {
475 Self(sha256::Hash::from_slice(bytes).expect("from_slice only fails if len is not 32"))
479 /// Description string
482 /// The description can be at most 639 __bytes__ long
483 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd, Default)]
484 pub struct Description(UntrustedString);
487 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
488 pub struct PayeePubKey(pub PublicKey);
490 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
492 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
493 pub struct ExpiryTime(Duration);
495 /// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
496 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
497 pub struct MinFinalCltvExpiryDelta(pub u64);
499 /// Fallback address in case no LN payment is possible
500 #[allow(missing_docs)]
501 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
504 version: WitnessVersion,
507 PubKeyHash(PubkeyHash),
508 ScriptHash(ScriptHash),
511 /// Recoverable signature
512 #[derive(Clone, Debug, Hash, Eq, PartialEq)]
513 pub struct Bolt11InvoiceSignature(pub RecoverableSignature);
515 impl PartialOrd for Bolt11InvoiceSignature {
516 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
517 Some(self.cmp(other))
521 impl Ord for Bolt11InvoiceSignature {
522 fn cmp(&self, other: &Self) -> Ordering {
523 self.0.serialize_compact().1.cmp(&other.0.serialize_compact().1)
527 /// Private routing information
530 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
532 #[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
533 pub struct PrivateRoute(pub RouteHint);
535 /// Tag constants as specified in BOLT11
536 #[allow(missing_docs)]
538 pub const TAG_PAYMENT_HASH: u8 = 1;
539 pub const TAG_DESCRIPTION: u8 = 13;
540 pub const TAG_PAYEE_PUB_KEY: u8 = 19;
541 pub const TAG_DESCRIPTION_HASH: u8 = 23;
542 pub const TAG_EXPIRY_TIME: u8 = 6;
543 pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
544 pub const TAG_FALLBACK: u8 = 9;
545 pub const TAG_PRIVATE_ROUTE: u8 = 3;
546 pub const TAG_PAYMENT_SECRET: u8 = 16;
547 pub const TAG_PAYMENT_METADATA: u8 = 27;
548 pub const TAG_FEATURES: u8 = 5;
551 impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False, tb::False> {
552 /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
553 /// `InvoiceBuilder::build(self)` becomes available.
554 pub fn new(currency: Currency) -> Self {
560 tagged_fields: Vec::new(),
563 phantom_d: core::marker::PhantomData,
564 phantom_h: core::marker::PhantomData,
565 phantom_t: core::marker::PhantomData,
566 phantom_c: core::marker::PhantomData,
567 phantom_s: core::marker::PhantomData,
568 phantom_m: core::marker::PhantomData,
573 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> {
574 /// Helper function to set the completeness flags.
575 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> {
576 InvoiceBuilder::<DN, HN, TN, CN, SN, MN> {
577 currency: self.currency,
579 si_prefix: self.si_prefix,
580 timestamp: self.timestamp,
581 tagged_fields: self.tagged_fields,
584 phantom_d: core::marker::PhantomData,
585 phantom_h: core::marker::PhantomData,
586 phantom_t: core::marker::PhantomData,
587 phantom_c: core::marker::PhantomData,
588 phantom_s: core::marker::PhantomData,
589 phantom_m: core::marker::PhantomData,
593 /// Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.
594 pub fn amount_milli_satoshis(mut self, amount_msat: u64) -> Self {
595 let amount = amount_msat * 10; // Invoices are denominated in "pico BTC"
596 let biggest_possible_si_prefix = SiPrefix::values_desc()
598 .find(|prefix| amount % prefix.multiplier() == 0)
599 .expect("Pico should always match");
600 self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
601 self.si_prefix = Some(*biggest_possible_si_prefix);
605 /// Sets the payee's public key.
606 pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
607 self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
611 /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
613 pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
614 self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
618 /// Adds a fallback address.
619 pub fn fallback(mut self, fallback: Fallback) -> Self {
620 self.tagged_fields.push(TaggedField::Fallback(fallback));
624 /// Adds a private route.
625 pub fn private_route(mut self, hint: RouteHint) -> Self {
626 match PrivateRoute::new(hint) {
627 Ok(r) => self.tagged_fields.push(TaggedField::PrivateRoute(r)),
628 Err(e) => self.error = Some(e),
634 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S, M> {
635 /// Builds a [`RawBolt11Invoice`] if no [`CreationError`] occurred while construction any of the
637 pub fn build_raw(self) -> Result<RawBolt11Invoice, CreationError> {
639 // If an error occurred at any time before, return it now
640 if let Some(e) = self.error {
645 currency: self.currency,
646 raw_amount: self.amount,
647 si_prefix: self.si_prefix,
650 let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
652 let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
653 RawTaggedField::KnownSemantics(tf)
654 }).collect::<Vec<_>>();
656 let data = RawDataPart {
661 Ok(RawBolt11Invoice {
668 impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S, M> {
669 /// Set the description. This function is only available if no description (hash) was set.
670 pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
671 match Description::new(description) {
672 Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
673 Err(e) => self.error = Some(e),
678 /// Set the description hash. This function is only available if no description (hash) was set.
679 pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
680 self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
684 /// Set the description or description hash. This function is only available if no description (hash) was set.
685 pub fn invoice_description(self, description: Bolt11InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
687 Bolt11InvoiceDescription::Direct(desc) => {
688 self.description(desc.clone().into_inner().0)
690 Bolt11InvoiceDescription::Hash(hash) => {
691 self.description_hash(hash.0)
697 impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S, M> {
698 /// Set the payment hash. This function is only available if no payment hash was set.
699 pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S, M> {
700 self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
705 impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S, M> {
706 /// Sets the timestamp to a specific [`SystemTime`].
707 #[cfg(feature = "std")]
708 pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
709 match PositiveTimestamp::from_system_time(time) {
710 Ok(t) => self.timestamp = Some(t),
711 Err(e) => self.error = Some(e),
717 /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
718 /// is not representable in BOLT 11 invoices).
719 pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
720 match PositiveTimestamp::from_duration_since_epoch(time) {
721 Ok(t) => self.timestamp = Some(t),
722 Err(e) => self.error = Some(e),
728 /// Sets the timestamp to the current system time.
729 #[cfg(feature = "std")]
730 pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
731 let now = PositiveTimestamp::from_system_time(SystemTime::now());
732 self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
737 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S, M> {
738 /// Sets `min_final_cltv_expiry_delta`.
739 pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S, M> {
740 self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
745 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False, M> {
746 /// Sets the payment secret and relevant features.
747 pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True, M> {
748 let mut found_features = false;
749 for field in self.tagged_fields.iter_mut() {
750 if let TaggedField::Features(f) = field {
751 found_features = true;
752 f.set_variable_length_onion_required();
753 f.set_payment_secret_required();
756 self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
758 let mut features = Bolt11InvoiceFeatures::empty();
759 features.set_variable_length_onion_required();
760 features.set_payment_secret_required();
761 self.tagged_fields.push(TaggedField::Features(features));
767 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::False> {
768 /// Sets the payment metadata.
770 /// By default features are set to *optionally* allow the sender to include the payment metadata.
771 /// If you wish to require that the sender include the metadata (and fail to parse the invoice if
772 /// they don't support payment metadata fields), you need to call
773 /// [`InvoiceBuilder::require_payment_metadata`] after this.
774 pub fn payment_metadata(mut self, payment_metadata: Vec<u8>) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
775 self.tagged_fields.push(TaggedField::PaymentMetadata(payment_metadata));
776 let mut found_features = false;
777 for field in self.tagged_fields.iter_mut() {
778 if let TaggedField::Features(f) = field {
779 found_features = true;
780 f.set_payment_metadata_optional();
784 let mut features = Bolt11InvoiceFeatures::empty();
785 features.set_payment_metadata_optional();
786 self.tagged_fields.push(TaggedField::Features(features));
792 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::True> {
793 /// Sets forwarding of payment metadata as required. A reader of the invoice which does not
794 /// support sending payment metadata will fail to read the invoice.
795 pub fn require_payment_metadata(mut self) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
796 for field in self.tagged_fields.iter_mut() {
797 if let TaggedField::Features(f) = field {
798 f.set_payment_metadata_required();
805 impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True, M> {
806 /// Sets the `basic_mpp` feature as optional.
807 pub fn basic_mpp(mut self) -> Self {
808 for field in self.tagged_fields.iter_mut() {
809 if let TaggedField::Features(f) = field {
810 f.set_basic_mpp_optional();
817 impl<M: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True, M> {
818 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
819 /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
820 /// the included payee public key.
821 pub fn build_signed<F>(self, sign_function: F) -> Result<Bolt11Invoice, CreationError>
822 where F: FnOnce(&Message) -> RecoverableSignature
824 let invoice = self.try_build_signed::<_, ()>(|hash| {
825 Ok(sign_function(hash))
830 Err(SignOrCreationError::CreationError(e)) => Err(e),
831 Err(SignOrCreationError::SignError(())) => unreachable!(),
835 /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
836 /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
837 /// if applicable also for the included payee public key.
838 pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Bolt11Invoice, SignOrCreationError<E>>
839 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
841 let raw = match self.build_raw() {
843 Err(e) => return Err(SignOrCreationError::CreationError(e)),
846 let signed = match raw.sign(sign_function) {
848 Err(e) => return Err(SignOrCreationError::SignError(e)),
851 let invoice = Bolt11Invoice {
852 signed_invoice: signed,
855 invoice.check_field_counts().expect("should be ensured by type signature of builder");
856 invoice.check_feature_bits().expect("should be ensured by type signature of builder");
857 invoice.check_amount().expect("should be ensured by type signature of builder");
864 impl SignedRawBolt11Invoice {
865 /// Disassembles the `SignedRawBolt11Invoice` into its three parts:
867 /// 2. hash of the raw invoice
869 pub fn into_parts(self) -> (RawBolt11Invoice, [u8; 32], Bolt11InvoiceSignature) {
870 (self.raw_invoice, self.hash, self.signature)
873 /// The [`RawBolt11Invoice`] which was signed.
874 pub fn raw_invoice(&self) -> &RawBolt11Invoice {
878 /// The hash of the [`RawBolt11Invoice`] that was signed.
879 pub fn signable_hash(&self) -> &[u8; 32] {
883 /// Signature for the invoice.
884 pub fn signature(&self) -> &Bolt11InvoiceSignature {
888 /// Recovers the public key used for signing the invoice from the recoverable signature.
889 pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
890 let hash = Message::from_slice(&self.hash[..])
891 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
893 Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
899 /// Checks if the signature is valid for the included payee public key or if none exists if it's
900 /// valid for the recovered signature (which should always be true?).
901 pub fn check_signature(&self) -> bool {
902 let included_pub_key = self.raw_invoice.payee_pub_key();
904 let mut recovered_pub_key = Option::None;
905 if recovered_pub_key.is_none() {
906 let recovered = match self.recover_payee_pub_key() {
908 Err(_) => return false,
910 recovered_pub_key = Some(recovered);
913 let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
914 .expect("One is always present");
916 let hash = Message::from_slice(&self.hash[..])
917 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
919 let secp_context = Secp256k1::new();
920 let verification_result = secp_context.verify_ecdsa(
922 &self.signature.to_standard(),
926 match verification_result {
933 /// Finds the first element of an enum stream of a given variant and extracts one member of the
934 /// variant. If no element was found `None` gets returned.
936 /// The following example would extract the first B.
944 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
946 /// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
948 macro_rules! find_extract {
949 ($iter:expr, $enm:pat, $enm_var:ident) => {
950 find_all_extract!($iter, $enm, $enm_var).next()
954 /// Finds the all elements of an enum stream of a given variant and extracts one member of the
955 /// variant through an iterator.
957 /// The following example would extract all A.
965 /// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
968 /// find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
969 /// vec![1u8, 2u8, 4u8]
972 macro_rules! find_all_extract {
973 ($iter:expr, $enm:pat, $enm_var:ident) => {
974 $iter.filter_map(|tf| match *tf {
975 $enm => Some($enm_var),
981 #[allow(missing_docs)]
982 impl RawBolt11Invoice {
983 /// Hash the HRP as bytes and signatureless data part.
984 fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
985 let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
986 let mut hash: [u8; 32] = Default::default();
987 hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
991 /// Calculate the hash of the encoded `RawBolt11Invoice` which should be signed.
992 pub fn signable_hash(&self) -> [u8; 32] {
993 use bech32::ToBase32;
995 RawBolt11Invoice::hash_from_parts(
996 self.hrp.to_string().as_bytes(),
997 &self.data.to_base32()
1001 /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
1002 /// type `E`. Since the signature of a [`SignedRawBolt11Invoice`] is not required to be valid there
1003 /// are no constraints regarding the validity of the produced signature.
1005 /// This is not exported to bindings users as we don't currently support passing function pointers into methods
1007 pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawBolt11Invoice, E>
1008 where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
1010 let raw_hash = self.signable_hash();
1011 let hash = Message::from_slice(&raw_hash[..])
1012 .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
1013 let signature = sign_method(&hash)?;
1015 Ok(SignedRawBolt11Invoice {
1018 signature: Bolt11InvoiceSignature(signature),
1022 /// Returns an iterator over all tagged fields with known semantics.
1024 /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1025 pub fn known_tagged_fields(&self)
1026 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
1028 // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
1029 // function's type signature.
1030 // TODO: refactor once impl Trait is available
1031 fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
1033 RawTaggedField::KnownSemantics(ref tf) => Some(tf),
1038 self.data.tagged_fields.iter().filter_map(match_raw )
1041 pub fn payment_hash(&self) -> Option<&Sha256> {
1042 find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
1045 pub fn description(&self) -> Option<&Description> {
1046 find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
1049 pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
1050 find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
1053 pub fn description_hash(&self) -> Option<&Sha256> {
1054 find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
1057 pub fn expiry_time(&self) -> Option<&ExpiryTime> {
1058 find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
1061 pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
1062 find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
1065 pub fn payment_secret(&self) -> Option<&PaymentSecret> {
1066 find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
1069 pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1070 find_extract!(self.known_tagged_fields(), TaggedField::PaymentMetadata(ref x), x)
1073 pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1074 find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
1077 /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1078 pub fn fallbacks(&self) -> Vec<&Fallback> {
1079 find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
1082 pub fn private_routes(&self) -> Vec<&PrivateRoute> {
1083 find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
1086 pub fn amount_pico_btc(&self) -> Option<u64> {
1087 self.hrp.raw_amount.map(|v| {
1088 v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
1092 pub fn currency(&self) -> Currency {
1093 self.hrp.currency.clone()
1097 impl PositiveTimestamp {
1098 /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
1100 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1101 pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
1102 if unix_seconds <= MAX_TIMESTAMP {
1103 Ok(Self(Duration::from_secs(unix_seconds)))
1105 Err(CreationError::TimestampOutOfBounds)
1109 /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
1110 /// the range `0..=MAX_TIMESTAMP`.
1112 /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1114 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1115 #[cfg(feature = "std")]
1116 pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
1117 time.duration_since(SystemTime::UNIX_EPOCH)
1118 .map(Self::from_duration_since_epoch)
1119 .unwrap_or(Err(CreationError::TimestampOutOfBounds))
1122 /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
1123 /// `0..=MAX_TIMESTAMP`.
1125 /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
1127 /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
1128 pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
1129 Self::from_unix_timestamp(duration.as_secs())
1132 /// Returns the Unix timestamp representing the stored time
1133 pub fn as_unix_timestamp(&self) -> u64 {
1137 /// Returns the duration of the stored time since the Unix epoch
1138 pub fn as_duration_since_epoch(&self) -> Duration {
1142 /// Returns the [`SystemTime`] representing the stored time
1143 #[cfg(feature = "std")]
1144 pub fn as_time(&self) -> SystemTime {
1145 SystemTime::UNIX_EPOCH + self.0
1149 impl From<PositiveTimestamp> for Duration {
1150 fn from(val: PositiveTimestamp) -> Self {
1155 #[cfg(feature = "std")]
1156 impl From<PositiveTimestamp> for SystemTime {
1157 fn from(val: PositiveTimestamp) -> Self {
1158 SystemTime::UNIX_EPOCH + val.0
1162 impl Bolt11Invoice {
1163 /// The hash of the [`RawBolt11Invoice`] that was signed.
1164 pub fn signable_hash(&self) -> [u8; 32] {
1165 self.signed_invoice.hash
1168 /// Transform the `Bolt11Invoice` into its unchecked version.
1169 pub fn into_signed_raw(self) -> SignedRawBolt11Invoice {
1173 /// Check that all mandatory fields are present
1174 fn check_field_counts(&self) -> Result<(), Bolt11SemanticError> {
1175 // "A writer MUST include exactly one p field […]."
1176 let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
1177 TaggedField::PaymentHash(_) => true,
1180 if payment_hash_cnt < 1 {
1181 return Err(Bolt11SemanticError::NoPaymentHash);
1182 } else if payment_hash_cnt > 1 {
1183 return Err(Bolt11SemanticError::MultiplePaymentHashes);
1186 // "A writer MUST include either exactly one d or exactly one h field."
1187 let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
1188 TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
1191 if description_cnt < 1 {
1192 return Err(Bolt11SemanticError::NoDescription);
1193 } else if description_cnt > 1 {
1194 return Err(Bolt11SemanticError::MultipleDescriptions);
1197 self.check_payment_secret()?;
1202 /// Checks that there is exactly one payment secret field
1203 fn check_payment_secret(&self) -> Result<(), Bolt11SemanticError> {
1204 // "A writer MUST include exactly one `s` field."
1205 let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
1206 TaggedField::PaymentSecret(_) => true,
1209 if payment_secret_count < 1 {
1210 return Err(Bolt11SemanticError::NoPaymentSecret);
1211 } else if payment_secret_count > 1 {
1212 return Err(Bolt11SemanticError::MultiplePaymentSecrets);
1218 /// Check that amount is a whole number of millisatoshis
1219 fn check_amount(&self) -> Result<(), Bolt11SemanticError> {
1220 if let Some(amount_pico_btc) = self.amount_pico_btc() {
1221 if amount_pico_btc % 10 != 0 {
1222 return Err(Bolt11SemanticError::ImpreciseAmount);
1228 /// Check that feature bits are set as required
1229 fn check_feature_bits(&self) -> Result<(), Bolt11SemanticError> {
1230 self.check_payment_secret()?;
1232 // "A writer MUST set an s field if and only if the payment_secret feature is set."
1233 // (this requirement has been since removed, and we now require the payment secret
1234 // feature bit always).
1235 let features = self.tagged_fields().find(|&tf| match *tf {
1236 TaggedField::Features(_) => true,
1240 None => Err(Bolt11SemanticError::InvalidFeatures),
1241 Some(TaggedField::Features(features)) => {
1242 if features.requires_unknown_bits() {
1243 Err(Bolt11SemanticError::InvalidFeatures)
1244 } else if !features.supports_payment_secret() {
1245 Err(Bolt11SemanticError::InvalidFeatures)
1250 Some(_) => unreachable!(),
1254 /// Check that the invoice is signed correctly and that key recovery works
1255 pub fn check_signature(&self) -> Result<(), Bolt11SemanticError> {
1256 match self.signed_invoice.recover_payee_pub_key() {
1257 Err(secp256k1::Error::InvalidRecoveryId) =>
1258 return Err(Bolt11SemanticError::InvalidRecoveryId),
1259 Err(secp256k1::Error::InvalidSignature) =>
1260 return Err(Bolt11SemanticError::InvalidSignature),
1261 Err(e) => panic!("no other error may occur, got {:?}", e),
1265 if !self.signed_invoice.check_signature() {
1266 return Err(Bolt11SemanticError::InvalidSignature);
1272 /// Constructs a `Bolt11Invoice` from a [`SignedRawBolt11Invoice`] by checking all its invariants.
1274 /// use lightning_invoice::*;
1276 /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
1277 /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
1278 /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
1279 /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
1280 /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
1281 /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
1282 /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
1283 /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
1284 /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
1285 /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
1286 /// j5r6drg6k6zcqj0fcwg";
1288 /// let signed = invoice.parse::<SignedRawBolt11Invoice>().unwrap();
1290 /// assert!(Bolt11Invoice::from_signed(signed).is_ok());
1292 pub fn from_signed(signed_invoice: SignedRawBolt11Invoice) -> Result<Self, Bolt11SemanticError> {
1293 let invoice = Bolt11Invoice {
1296 invoice.check_field_counts()?;
1297 invoice.check_feature_bits()?;
1298 invoice.check_signature()?;
1299 invoice.check_amount()?;
1304 /// Returns the `Bolt11Invoice`'s timestamp (should equal its creation time)
1305 #[cfg(feature = "std")]
1306 pub fn timestamp(&self) -> SystemTime {
1307 self.signed_invoice.raw_invoice().data.timestamp.as_time()
1310 /// Returns the `Bolt11Invoice`'s timestamp as a duration since the Unix epoch
1311 pub fn duration_since_epoch(&self) -> Duration {
1312 self.signed_invoice.raw_invoice().data.timestamp.0
1315 /// Returns an iterator over all tagged fields of this `Bolt11Invoice`.
1317 /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
1318 pub fn tagged_fields(&self)
1319 -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
1320 self.signed_invoice.raw_invoice().known_tagged_fields()
1323 /// Returns the hash to which we will receive the preimage on completion of the payment
1324 pub fn payment_hash(&self) -> &sha256::Hash {
1325 &self.signed_invoice.payment_hash().expect("checked by constructor").0
1328 /// Return the description or a hash of it for longer ones
1330 /// This is not exported to bindings users because we don't yet export Bolt11InvoiceDescription
1331 pub fn description(&self) -> Bolt11InvoiceDescription {
1332 if let Some(direct) = self.signed_invoice.description() {
1333 return Bolt11InvoiceDescription::Direct(direct);
1334 } else if let Some(hash) = self.signed_invoice.description_hash() {
1335 return Bolt11InvoiceDescription::Hash(hash);
1337 unreachable!("ensured by constructor");
1340 /// Get the payee's public key if one was included in the invoice
1341 pub fn payee_pub_key(&self) -> Option<&PublicKey> {
1342 self.signed_invoice.payee_pub_key().map(|x| &x.0)
1345 /// Get the payment secret if one was included in the invoice
1346 pub fn payment_secret(&self) -> &PaymentSecret {
1347 self.signed_invoice.payment_secret().expect("was checked by constructor")
1350 /// Get the payment metadata blob if one was included in the invoice
1351 pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
1352 self.signed_invoice.payment_metadata()
1355 /// Get the invoice features if they were included in the invoice
1356 pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
1357 self.signed_invoice.features()
1360 /// Recover the payee's public key (only to be used if none was included in the invoice)
1361 pub fn recover_payee_pub_key(&self) -> PublicKey {
1362 self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
1365 /// Returns the Duration since the Unix epoch at which the invoice expires.
1366 /// Returning None if overflow occurred.
1367 pub fn expires_at(&self) -> Option<Duration> {
1368 self.duration_since_epoch().checked_add(self.expiry_time())
1371 /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
1372 pub fn expiry_time(&self) -> Duration {
1373 self.signed_invoice.expiry_time()
1375 .unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
1378 /// Returns whether the invoice has expired.
1379 #[cfg(feature = "std")]
1380 pub fn is_expired(&self) -> bool {
1381 Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
1384 /// Returns whether the expiry time from the given epoch has passed.
1385 #[cfg(feature = "std")]
1386 pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
1387 match epoch.elapsed() {
1388 Ok(elapsed) => elapsed > expiry_time,
1393 /// Returns the Duration remaining until the invoice expires.
1394 #[cfg(feature = "std")]
1395 pub fn duration_until_expiry(&self) -> Duration {
1396 SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
1397 .map(|now| self.expiration_remaining_from_epoch(now))
1398 .unwrap_or(Duration::from_nanos(0))
1401 /// Returns the Duration remaining until the invoice expires given the current time.
1402 /// `time` is the timestamp as a duration since the Unix epoch.
1403 pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
1404 self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
1407 /// Returns whether the expiry time would pass at the given point in time.
1408 /// `at_time` is the timestamp as a duration since the Unix epoch.
1409 pub fn would_expire(&self, at_time: Duration) -> bool {
1410 self.duration_since_epoch()
1411 .checked_add(self.expiry_time())
1412 .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
1415 /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
1416 /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
1417 pub fn min_final_cltv_expiry_delta(&self) -> u64 {
1418 self.signed_invoice.min_final_cltv_expiry_delta()
1420 .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
1423 /// Returns a list of all fallback addresses
1425 /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
1426 pub fn fallbacks(&self) -> Vec<&Fallback> {
1427 self.signed_invoice.fallbacks()
1430 /// Returns a list of all fallback addresses as [`Address`]es
1431 pub fn fallback_addresses(&self) -> Vec<Address> {
1432 self.fallbacks().iter().map(|fallback| {
1433 let payload = match fallback {
1434 Fallback::SegWitProgram { version, program } => {
1435 Payload::WitnessProgram { version: *version, program: program.to_vec() }
1437 Fallback::PubKeyHash(pkh) => {
1438 Payload::PubkeyHash(*pkh)
1440 Fallback::ScriptHash(sh) => {
1441 Payload::ScriptHash(*sh)
1445 Address { payload, network: self.network() }
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::Script;
1759 use bitcoin_hashes::hex::FromHex;
1760 use bitcoin_hashes::sha256;
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_hex(
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_hex(
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_hex(
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(&Script::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('\"'));