+// Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
+#![deny(broken_intra_doc_links)]
+#![deny(private_intra_doc_links)]
+
#![deny(missing_docs)]
#![deny(non_upper_case_globals)]
#![deny(non_camel_case_types)]
#![deny(non_snake_case)]
#![deny(unused_mut)]
-#![deny(broken_intra_doc_links)]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
//! This crate provides data structures to represent
-//! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)
+//! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
//! invoices and functions to create, encode and decode these. If you just want to use the standard
//! en-/decoding functionality this should get you started:
//!
-//! * For parsing use `str::parse::<Invoice>(&self)` (see the docs of `impl FromStr for Invoice`)
-//! * For constructing invoices use the `InvoiceBuilder`
-//! * For serializing invoices use the `Display`/`ToString` traits
+//! * For parsing use `str::parse::<Invoice>(&self)` (see [`Invoice::from_str`])
+//! * For constructing invoices use the [`InvoiceBuilder`]
+//! * For serializing invoices use the [`Display`]/[`ToString`] traits
+//!
+//! [`Invoice::from_str`]: crate::Invoice#impl-FromStr
#[cfg(not(any(feature = "std", feature = "no-std")))]
compile_error!("at least one of the `std` or `no-std` features must be enabled");
pub mod payment;
pub mod utils;
+pub(crate) mod time_utils;
+
extern crate bech32;
extern crate bitcoin_hashes;
#[macro_use] extern crate lightning;
extern crate alloc;
#[cfg(any(test, feature = "std"))]
extern crate core;
+#[cfg(feature = "serde")]
+extern crate serde;
#[cfg(feature = "std")]
use std::time::SystemTime;
use bech32::u5;
-use bitcoin_hashes::Hash;
-use bitcoin_hashes::sha256;
+use bitcoin::{Address, Network, PubkeyHash, ScriptHash};
+use bitcoin::util::address::{Payload, WitnessVersion};
+use bitcoin_hashes::{Hash, sha256};
use lightning::ln::PaymentSecret;
use lightning::ln::features::InvoiceFeatures;
#[cfg(any(doc, test))]
-use lightning::routing::network_graph::RoutingFees;
+use lightning::routing::gossip::RoutingFees;
use lightning::routing::router::RouteHint;
use lightning::util::invoice::construct_invoice_preimage;
-use secp256k1::key::PublicKey;
+use secp256k1::PublicKey;
use secp256k1::{Message, Secp256k1};
-use secp256k1::recovery::RecoverableSignature;
+use secp256k1::ecdsa::RecoverableSignature;
use core::fmt::{Display, Formatter, self};
use core::iter::FilterMap;
+use core::num::ParseIntError;
use core::ops::Deref;
use core::slice::Iter;
use core::time::Duration;
+use core::str;
+
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
mod de;
mod ser;
pub use alloc::string::ToString;
}
-use prelude::*;
+use crate::prelude::*;
/// Sync compat for std/no_std
#[cfg(feature = "std")]
#[cfg(not(feature = "std"))]
mod sync;
-pub use de::{ParseError, ParseOrSemanticError};
+/// Errors that indicate what is wrong with the invoice. They have some granularity for debug
+/// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
+#[allow(missing_docs)]
+#[derive(PartialEq, Eq, Debug, Clone)]
+pub enum ParseError {
+ Bech32Error(bech32::Error),
+ ParseAmountError(ParseIntError),
+ MalformedSignature(secp256k1::Error),
+ BadPrefix,
+ UnknownCurrency,
+ UnknownSiPrefix,
+ MalformedHRP,
+ TooShortDataPart,
+ UnexpectedEndOfTaggedFields,
+ DescriptionDecodeError(str::Utf8Error),
+ PaddingError,
+ IntegerOverflowError,
+ InvalidSegWitProgramLength,
+ InvalidPubKeyHashLength,
+ InvalidScriptHashLength,
+ InvalidRecoveryId,
+ InvalidSliceLength(String),
+
+ /// Not an error, but used internally to signal that a part of the invoice should be ignored
+ /// according to BOLT11
+ Skip,
+}
+
+/// Indicates that something went wrong while parsing or validating the invoice. Parsing errors
+/// should be mostly seen as opaque and are only there for debugging reasons. Semantic errors
+/// like wrong signatures, missing fields etc. could mean that someone tampered with the invoice.
+#[derive(PartialEq, Eq, Debug, Clone)]
+pub enum ParseOrSemanticError {
+ /// The invoice couldn't be decoded
+ ParseError(ParseError),
+
+ /// The invoice could be decoded but violates the BOLT11 standard
+ SemanticError(crate::SemanticError),
+}
/// The number of bits used to represent timestamps as defined in BOLT 11.
const TIMESTAMP_BITS: usize = 35;
/// Default minimum final CLTV expiry as defined by [BOLT 11].
///
/// Note that this is *not* the same value as rust-lightning's minimum CLTV expiry, which is
-/// provided in [`MIN_FINAL_CLTV_EXPIRY`].
+/// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
///
/// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-/// [`MIN_FINAL_CLTV_EXPIRY`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY
-pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
+/// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
+pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
-/// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures
+/// Builder for [`Invoice`]s. It's the most convenient and advised way to use this library. It ensures
/// that only a semantically and syntactically correct Invoice can be built using it.
///
/// ```
/// use bitcoin_hashes::sha256;
///
/// use secp256k1::Secp256k1;
-/// use secp256k1::key::SecretKey;
+/// use secp256k1::SecretKey;
///
/// use lightning::ln::PaymentSecret;
///
/// .payment_hash(payment_hash)
/// .payment_secret(payment_secret)
/// .current_timestamp()
-/// .min_final_cltv_expiry(144)
+/// .min_final_cltv_expiry_delta(144)
/// .build_signed(|hash| {
-/// Secp256k1::new().sign_recoverable(hash, &private_key)
+/// Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
/// })
/// .unwrap();
///
/// # Type parameters
/// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
/// given field:
-/// * `D`: exactly one `Description` or `DescriptionHash`
-/// * `H`: exactly one `PaymentHash`
+/// * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
+/// * `H`: exactly one [`TaggedField::PaymentHash`]
/// * `T`: the timestamp is set
+/// * `C`: the CLTV expiry is set
+/// * `S`: the payment secret is set
+/// * `M`: payment metadata is set
///
-/// (C-not exported) as we likely need to manually select one set of boolean type parameters.
+/// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> {
+pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> {
currency: Currency,
amount: Option<u64>,
si_prefix: Option<SiPrefix>,
phantom_t: core::marker::PhantomData<T>,
phantom_c: core::marker::PhantomData<C>,
phantom_s: core::marker::PhantomData<S>,
+ phantom_m: core::marker::PhantomData<M>,
}
/// Represents a syntactically and semantically correct lightning BOLT11 invoice.
///
/// There are three ways to construct an `Invoice`:
-/// 1. using `InvoiceBuilder`
-/// 2. using `Invoice::from_signed(SignedRawInvoice)`
-/// 3. using `str::parse::<Invoice>(&str)`
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// 1. using [`InvoiceBuilder`]
+/// 2. using [`Invoice::from_signed`]
+/// 3. using `str::parse::<Invoice>(&str)` (see [`Invoice::from_str`])
+///
+/// [`Invoice::from_str`]: crate::Invoice#impl-FromStr
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct Invoice {
signed_invoice: SignedRawInvoice,
}
/// Represents the description of an invoice which has to be either a directly included string or
/// a hash of a description provided out of band.
///
-/// (C-not exported) As we don't have a good way to map the reference lifetimes making this
+/// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
/// practically impossible to use safely in languages like C.
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum InvoiceDescription<'f> {
Hash(&'f Sha256),
}
-/// Represents a signed `RawInvoice` with cached hash. The signature is not checked and may be
+/// Represents a signed [`RawInvoice`] with cached hash. The signature is not checked and may be
/// invalid.
///
/// # Invariants
-/// The hash has to be either from the deserialized invoice or from the serialized `raw_invoice`.
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// The hash has to be either from the deserialized invoice or from the serialized [`RawInvoice`].
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct SignedRawInvoice {
/// The rawInvoice that the signature belongs to
raw_invoice: RawInvoice,
- /// Hash of the `RawInvoice` that will be used to check the signature.
+ /// Hash of the [`RawInvoice`] that will be used to check the signature.
///
/// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form,
/// since it's not guaranteed that encoding it again will lead to the same result since integers
/// could have been encoded with leading zeroes etc.
/// * if the `SignedRawInvoice` was constructed manually the hash will be the calculated hash
- /// from the `RawInvoice`
+ /// from the [`RawInvoice`]
hash: [u8; 32],
/// signature of the payment request
signature: InvoiceSignature,
}
-/// Represents an syntactically correct Invoice for a payment on the lightning network,
+/// Represents an syntactically correct [`Invoice`] for a payment on the lightning network,
/// but without the signature information.
-/// De- and encoding should not lead to information loss but may lead to different hashes.
+/// Decoding and encoding should not lead to information loss but may lead to different hashes.
///
-/// For methods without docs see the corresponding methods in `Invoice`.
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// For methods without docs see the corresponding methods in [`Invoice`].
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawInvoice {
/// human readable part
pub hrp: RawHrp,
pub data: RawDataPart,
}
-/// Data of the `RawInvoice` that is encoded in the human readable part
+/// Data of the [`RawInvoice`] that is encoded in the human readable part.
///
-/// (C-not exported) As we don't yet support Option<Enum>
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// This is not exported to bindings users as we don't yet support `Option<Enum>`
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawHrp {
/// The currency deferred from the 3rd and 4th character of the bech32 transaction
pub currency: Currency,
pub si_prefix: Option<SiPrefix>,
}
-/// Data of the `RawInvoice` that is encoded in the data part
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// Data of the [`RawInvoice`] that is encoded in the data part
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawDataPart {
/// generation time of the invoice
pub timestamp: PositiveTimestamp,
///
/// The Unix timestamp representing the stored time has to be positive and no greater than
/// [`MAX_TIMESTAMP`].
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct PositiveTimestamp(Duration);
/// SI prefixes for the human readable part
-#[derive(Eq, PartialEq, Debug, Clone, Copy)]
+#[derive(Eq, PartialEq, Debug, Clone, Copy, Hash)]
pub enum SiPrefix {
/// 10^-3
Milli,
/// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
/// multiplier.
///
- /// (C-not exported) As we don't yet support a slice of enums, and also because this function
+ /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
/// isn't the most critical to expose.
pub fn values_desc() -> &'static [SiPrefix] {
- use SiPrefix::*;
+ use crate::SiPrefix::*;
static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
&VALUES
}
Signet,
}
+impl From<Network> for Currency {
+ fn from(network: Network) -> Self {
+ match network {
+ Network::Bitcoin => Currency::Bitcoin,
+ Network::Testnet => Currency::BitcoinTestnet,
+ Network::Regtest => Currency::Regtest,
+ Network::Signet => Currency::Signet,
+ }
+ }
+}
+
+impl From<Currency> for Network {
+ fn from(currency: Currency) -> Self {
+ match currency {
+ Currency::Bitcoin => Network::Bitcoin,
+ Currency::BitcoinTestnet => Network::Testnet,
+ Currency::Regtest => Network::Regtest,
+ Currency::Simnet => Network::Regtest,
+ Currency::Signet => Network::Signet,
+ }
+ }
+}
+
/// Tagged field which may have an unknown tag
///
-/// (C-not exported) as we don't currently support TaggedField
+/// This is not exported to bindings users as we don't currently support TaggedField
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum RawTaggedField {
/// Parsed tagged field with known tag
///
/// For descriptions of the enum values please refer to the enclosed type's docs.
///
-/// (C-not exported) As we don't yet support enum variants with the same name the struct contained
+/// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
/// in the variant.
#[allow(missing_docs)]
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
PayeePubKey(PayeePubKey),
DescriptionHash(Sha256),
ExpiryTime(ExpiryTime),
- MinFinalCltvExpiry(MinFinalCltvExpiry),
+ MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
Fallback(Fallback),
PrivateRoute(PrivateRoute),
PaymentSecret(PaymentSecret),
+ PaymentMetadata(Vec<u8>),
Features(InvoiceFeatures),
}
/// SHA-256 hash
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct Sha256(/// (C-not exported) as the native hash types are not currently mapped
+pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
pub sha256::Hash);
+impl Sha256 {
+ /// Constructs a new [`Sha256`] from the given bytes, which are assumed to be the output of a
+ /// single sha256 hash.
+ #[cfg(c_bindings)]
+ pub fn from_bytes(bytes: &[u8; 32]) -> Self {
+ Self(sha256::Hash::from_slice(bytes).expect("from_slice only fails if len is not 32"))
+ }
+}
+
/// Description string
///
/// # Invariants
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct ExpiryTime(Duration);
-/// `min_final_cltv_expiry` to use for the last HTLC in the route
+/// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct MinFinalCltvExpiry(pub u64);
+pub struct MinFinalCltvExpiryDelta(pub u64);
-// TODO: better types instead onf byte arrays
/// Fallback address in case no LN payment is possible
#[allow(missing_docs)]
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum Fallback {
SegWitProgram {
- version: u5,
+ version: WitnessVersion,
program: Vec<u8>,
},
- PubKeyHash([u8; 20]),
- ScriptHash([u8; 20]),
+ PubKeyHash(PubkeyHash),
+ ScriptHash(ScriptHash),
}
/// Recoverable signature
-#[derive(Clone, Debug, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct InvoiceSignature(pub RecoverableSignature);
/// Private routing information
pub const TAG_PAYEE_PUB_KEY: u8 = 19;
pub const TAG_DESCRIPTION_HASH: u8 = 23;
pub const TAG_EXPIRY_TIME: u8 = 6;
- pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
+ pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
pub const TAG_FALLBACK: u8 = 9;
pub const TAG_PRIVATE_ROUTE: u8 = 3;
pub const TAG_PAYMENT_SECRET: u8 = 16;
+ pub const TAG_PAYMENT_METADATA: u8 = 27;
pub const TAG_FEATURES: u8 = 5;
}
-impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False> {
+impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False, tb::False> {
/// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
/// `InvoiceBuilder::build(self)` becomes available.
- pub fn new(currrency: Currency) -> Self {
+ pub fn new(currency: Currency) -> Self {
InvoiceBuilder {
- currency: currrency,
+ currency,
amount: None,
si_prefix: None,
timestamp: None,
phantom_t: core::marker::PhantomData,
phantom_c: core::marker::PhantomData,
phantom_s: core::marker::PhantomData,
+ phantom_m: core::marker::PhantomData,
}
}
}
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S> {
+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> {
/// Helper function to set the completeness flags.
- fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN> {
- InvoiceBuilder::<DN, HN, TN, CN, SN> {
+ 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> {
+ InvoiceBuilder::<DN, HN, TN, CN, SN, MN> {
currency: self.currency,
amount: self.amount,
si_prefix: self.si_prefix,
phantom_t: core::marker::PhantomData,
phantom_c: core::marker::PhantomData,
phantom_s: core::marker::PhantomData,
+ phantom_m: core::marker::PhantomData,
}
}
self
}
- /// Sets the expiry time
+ /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
+ /// invoices).
pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
self
}
}
-impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S> {
- /// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields.
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S, M> {
+ /// Builds a [`RawInvoice`] if no [`CreationError`] occurred while construction any of the
+ /// fields.
pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
// If an error occurred at any time before, return it now
}).collect::<Vec<_>>();
let data = RawDataPart {
- timestamp: timestamp,
- tagged_fields: tagged_fields,
+ timestamp,
+ tagged_fields,
};
Ok(RawInvoice {
- hrp: hrp,
- data: data,
+ hrp,
+ data,
})
}
}
-impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S> {
+impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S, M> {
/// Set the description. This function is only available if no description (hash) was set.
- pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S> {
+ pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
match Description::new(description) {
Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
Err(e) => self.error = Some(e),
}
/// Set the description hash. This function is only available if no description (hash) was set.
- pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S> {
+ pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
self.set_flags()
}
+
+ /// Set the description or description hash. This function is only available if no description (hash) was set.
+ pub fn invoice_description(self, description: InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
+ match description {
+ InvoiceDescription::Direct(desc) => {
+ self.description(desc.clone().into_inner())
+ }
+ InvoiceDescription::Hash(hash) => {
+ self.description_hash(hash.0)
+ }
+ }
+ }
}
-impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
+impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S, M> {
/// Set the payment hash. This function is only available if no payment hash was set.
- pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S> {
+ pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S, M> {
self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
self.set_flags()
}
}
-impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S, M> {
/// Sets the timestamp to a specific [`SystemTime`].
#[cfg(feature = "std")]
- pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
+ pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
match PositiveTimestamp::from_system_time(time) {
Ok(t) => self.timestamp = Some(t),
Err(e) => self.error = Some(e),
self.set_flags()
}
- /// Sets the timestamp to a duration since the Unix epoch.
- pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S> {
+ /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
+ /// is not representable in BOLT 11 invoices).
+ pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
match PositiveTimestamp::from_duration_since_epoch(time) {
Ok(t) => self.timestamp = Some(t),
Err(e) => self.error = Some(e),
/// Sets the timestamp to the current system time.
#[cfg(feature = "std")]
- pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
+ pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
let now = PositiveTimestamp::from_system_time(SystemTime::now());
self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
self.set_flags()
}
}
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
- /// Sets `min_final_cltv_expiry`.
- pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
- self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S, M> {
+ /// Sets `min_final_cltv_expiry_delta`.
+ pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S, M> {
+ self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
self.set_flags()
}
}
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False, M> {
/// Sets the payment secret and relevant features.
- pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True> {
- let features = InvoiceFeatures::empty()
- .set_variable_length_onion_required()
- .set_payment_secret_required();
+ pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True, M> {
+ let mut found_features = false;
+ for field in self.tagged_fields.iter_mut() {
+ if let TaggedField::Features(f) = field {
+ found_features = true;
+ f.set_variable_length_onion_required();
+ f.set_payment_secret_required();
+ }
+ }
self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
- self.tagged_fields.push(TaggedField::Features(features));
+ if !found_features {
+ let mut features = InvoiceFeatures::empty();
+ features.set_variable_length_onion_required();
+ features.set_payment_secret_required();
+ self.tagged_fields.push(TaggedField::Features(features));
+ }
self.set_flags()
}
}
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::False> {
+ /// Sets the payment metadata.
+ ///
+ /// By default features are set to *optionally* allow the sender to include the payment metadata.
+ /// If you wish to require that the sender include the metadata (and fail to parse the invoice if
+ /// they don't support payment metadata fields), you need to call
+ /// [`InvoiceBuilder::require_payment_metadata`] after this.
+ pub fn payment_metadata(mut self, payment_metadata: Vec<u8>) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
+ self.tagged_fields.push(TaggedField::PaymentMetadata(payment_metadata));
+ let mut found_features = false;
+ for field in self.tagged_fields.iter_mut() {
+ if let TaggedField::Features(f) = field {
+ found_features = true;
+ f.set_payment_metadata_optional();
+ }
+ }
+ if !found_features {
+ let mut features = InvoiceFeatures::empty();
+ features.set_payment_metadata_optional();
+ self.tagged_fields.push(TaggedField::Features(features));
+ }
+ self.set_flags()
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::True> {
+ /// Sets forwarding of payment metadata as required. A reader of the invoice which does not
+ /// support sending payment metadata will fail to read the invoice.
+ pub fn require_payment_metadata(mut self) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
+ for field in self.tagged_fields.iter_mut() {
+ if let TaggedField::Features(f) = field {
+ f.set_payment_metadata_required();
+ }
+ }
+ self
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True, M> {
/// Sets the `basic_mpp` feature as optional.
pub fn basic_mpp(mut self) -> Self {
- self.tagged_fields = self.tagged_fields
- .drain(..)
- .map(|field| match field {
- TaggedField::Features(f) => TaggedField::Features(f.set_basic_mpp_optional()),
- _ => field,
- })
- .collect();
+ for field in self.tagged_fields.iter_mut() {
+ if let TaggedField::Features(f) = field {
+ f.set_basic_mpp_optional();
+ }
+ }
self
}
}
-impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
+impl<M: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True, M> {
/// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
/// and MUST produce a recoverable signature valid for the given hash and if applicable also for
/// the included payee public key.
(self.raw_invoice, self.hash, self.signature)
}
- /// The `RawInvoice` which was signed.
+ /// The [`RawInvoice`] which was signed.
pub fn raw_invoice(&self) -> &RawInvoice {
&self.raw_invoice
}
- /// The hash of the `RawInvoice` that was signed.
- pub fn hash(&self) -> &[u8; 32] {
+ /// The hash of the [`RawInvoice`] that was signed.
+ pub fn signable_hash(&self) -> &[u8; 32] {
&self.hash
}
- /// InvoiceSignature for the invoice.
+ /// Signature for the invoice.
pub fn signature(&self) -> &InvoiceSignature {
&self.signature
}
let hash = Message::from_slice(&self.hash[..])
.expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
- Ok(PayeePubKey(Secp256k1::new().recover(
+ Ok(PayeePubKey(Secp256k1::new().recover_ecdsa(
&hash,
&self.signature
)?))
recovered_pub_key = Some(recovered);
}
- let pub_key = included_pub_key.or_else(|| recovered_pub_key.as_ref())
+ let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
.expect("One is always present");
let hash = Message::from_slice(&self.hash[..])
.expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
let secp_context = Secp256k1::new();
- let verification_result = secp_context.verify(
+ let verification_result = secp_context.verify_ecdsa(
&hash,
&self.signature.to_standard(),
pub_key
/// variant. If no element was found `None` gets returned.
///
/// The following example would extract the first B.
-/// ```
-/// use Enum::*
///
+/// ```ignore
/// enum Enum {
/// A(u8),
/// B(u16)
/// }
///
-/// let elements = vec![A(1), A(2), B(3), A(4)]
+/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
///
-/// assert_eq!(find_extract!(elements.iter(), Enum::B(ref x), x), Some(3u16))
+/// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
/// ```
macro_rules! find_extract {
($iter:expr, $enm:pat, $enm_var:ident) => {
/// variant through an iterator.
///
/// The following example would extract all A.
-/// ```
-/// use Enum::*
///
+/// ```ignore
/// enum Enum {
/// A(u8),
/// B(u16)
/// }
///
-/// let elements = vec![A(1), A(2), B(3), A(4)]
+/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
///
/// assert_eq!(
-/// find_all_extract!(elements.iter(), Enum::A(ref x), x).collect::<Vec<u8>>(),
-/// vec![1u8, 2u8, 4u8])
+/// find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
+/// vec![1u8, 2u8, 4u8]
+/// );
/// ```
macro_rules! find_all_extract {
($iter:expr, $enm:pat, $enm_var:ident) => {
hash
}
- /// Calculate the hash of the encoded `RawInvoice`
- pub fn hash(&self) -> [u8; 32] {
+ /// Calculate the hash of the encoded `RawInvoice` which should be signed.
+ pub fn signable_hash(&self) -> [u8; 32] {
use bech32::ToBase32;
RawInvoice::hash_from_parts(
)
}
- /// Signs the invoice using the supplied `sign_function`. This function MAY fail with an error
- /// of type `E`. Since the signature of a `SignedRawInvoice` is not required to be valid there
+ /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
+ /// type `E`. Since the signature of a [`SignedRawInvoice`] is not required to be valid there
/// are no constraints regarding the validity of the produced signature.
///
- /// (C-not exported) As we don't currently support passing function pointers into methods
+ /// This is not exported to bindings users as we don't currently support passing function pointers into methods
/// explicitly.
pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
{
- let raw_hash = self.hash();
+ let raw_hash = self.signable_hash();
let hash = Message::from_slice(&raw_hash[..])
.expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
let signature = sign_method(&hash)?;
/// Returns an iterator over all tagged fields with known semantics.
///
- /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+ /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
pub fn known_tagged_fields(&self)
-> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
{
find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
}
- pub fn min_final_cltv_expiry(&self) -> Option<&MinFinalCltvExpiry> {
- find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
+ pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
+ find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
}
pub fn payment_secret(&self) -> Option<&PaymentSecret> {
find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
}
+ pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
+ find_extract!(self.known_tagged_fields(), TaggedField::PaymentMetadata(ref x), x)
+ }
+
pub fn features(&self) -> Option<&InvoiceFeatures> {
find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
}
- /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+ /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
pub fn fallbacks(&self) -> Vec<&Fallback> {
find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
}
///
/// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
- Self::from_duration_since_epoch(Duration::from_secs(unix_seconds))
+ if unix_seconds <= MAX_TIMESTAMP {
+ Ok(Self(Duration::from_secs(unix_seconds)))
+ } else {
+ Err(CreationError::TimestampOutOfBounds)
+ }
}
/// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
/// the range `0..=MAX_TIMESTAMP`.
///
+ /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
+ ///
/// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
#[cfg(feature = "std")]
pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
/// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
/// `0..=MAX_TIMESTAMP`.
///
+ /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
+ ///
/// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
- if duration.as_secs() <= MAX_TIMESTAMP {
- Ok(PositiveTimestamp(duration))
- } else {
- Err(CreationError::TimestampOutOfBounds)
- }
+ Self::from_unix_timestamp(duration.as_secs())
}
/// Returns the Unix timestamp representing the stored time
}
#[cfg(feature = "std")]
-impl Into<SystemTime> for PositiveTimestamp {
- fn into(self) -> SystemTime {
- SystemTime::UNIX_EPOCH + self.0
+impl From<PositiveTimestamp> for SystemTime {
+ fn from(val: PositiveTimestamp) -> Self {
+ SystemTime::UNIX_EPOCH + val.0
}
}
impl Invoice {
+ /// The hash of the [`RawInvoice`] that was signed.
+ pub fn signable_hash(&self) -> [u8; 32] {
+ self.signed_invoice.hash
+ }
+
/// Transform the `Invoice` into it's unchecked version
pub fn into_signed_raw(self) -> SignedRawInvoice {
self.signed_invoice
Ok(())
}
- /// Constructs an `Invoice` from a `SignedRawInvoice` by checking all its invariants.
+ /// Constructs an `Invoice` from a [`SignedRawInvoice`] by checking all its invariants.
/// ```
/// use lightning_invoice::*;
///
/// ```
pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
let invoice = Invoice {
- signed_invoice: signed_invoice,
+ signed_invoice,
};
invoice.check_field_counts()?;
invoice.check_feature_bits()?;
/// Returns an iterator over all tagged fields of this Invoice.
///
- /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+ /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
pub fn tagged_fields(&self)
-> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
self.signed_invoice.raw_invoice().known_tagged_fields()
/// Return the description or a hash of it for longer ones
///
- /// (C-not exported) because we don't yet export InvoiceDescription
+ /// This is not exported to bindings users because we don't yet export InvoiceDescription
pub fn description(&self) -> InvoiceDescription {
- if let Some(ref direct) = self.signed_invoice.description() {
+ if let Some(direct) = self.signed_invoice.description() {
return InvoiceDescription::Direct(direct);
- } else if let Some(ref hash) = self.signed_invoice.description_hash() {
+ } else if let Some(hash) = self.signed_invoice.description_hash() {
return InvoiceDescription::Hash(hash);
}
unreachable!("ensured by constructor");
self.signed_invoice.payment_secret().expect("was checked by constructor")
}
+ /// Get the payment metadata blob if one was included in the invoice
+ pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
+ self.signed_invoice.payment_metadata()
+ }
+
/// Get the invoice features if they were included in the invoice
pub fn features(&self) -> Option<&InvoiceFeatures> {
self.signed_invoice.features()
self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
}
+ /// Returns the Duration since the Unix epoch at which the invoice expires.
+ /// Returning None if overflow occurred.
+ pub fn expires_at(&self) -> Option<Duration> {
+ self.duration_since_epoch().checked_add(self.expiry_time())
+ }
+
/// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
pub fn expiry_time(&self) -> Duration {
self.signed_invoice.expiry_time()
}
}
+ /// Returns the Duration remaining until the invoice expires.
+ #[cfg(feature = "std")]
+ pub fn duration_until_expiry(&self) -> Duration {
+ SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
+ .map(|now| self.expiration_remaining_from_epoch(now))
+ .unwrap_or(Duration::from_nanos(0))
+ }
+
+ /// Returns the Duration remaining until the invoice expires given the current time.
+ /// `time` is the timestamp as a duration since the Unix epoch.
+ pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
+ self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
+ }
+
/// Returns whether the expiry time would pass at the given point in time.
/// `at_time` is the timestamp as a duration since the Unix epoch.
pub fn would_expire(&self, at_time: Duration) -> bool {
.unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
}
- /// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
- /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
- pub fn min_final_cltv_expiry(&self) -> u64 {
- self.signed_invoice.min_final_cltv_expiry()
+ /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
+ /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
+ pub fn min_final_cltv_expiry_delta(&self) -> u64 {
+ self.signed_invoice.min_final_cltv_expiry_delta()
.map(|x| x.0)
- .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
+ .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
}
/// Returns a list of all fallback addresses
///
- /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+ /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
pub fn fallbacks(&self) -> Vec<&Fallback> {
self.signed_invoice.fallbacks()
}
+ /// Returns a list of all fallback addresses as [`Address`]es
+ pub fn fallback_addresses(&self) -> Vec<Address> {
+ self.fallbacks().iter().map(|fallback| {
+ let payload = match fallback {
+ Fallback::SegWitProgram { version, program } => {
+ Payload::WitnessProgram { version: *version, program: program.to_vec() }
+ }
+ Fallback::PubKeyHash(pkh) => {
+ Payload::PubkeyHash(*pkh)
+ }
+ Fallback::ScriptHash(sh) => {
+ Payload::ScriptHash(*sh)
+ }
+ };
+
+ Address { payload, network: self.network() }
+ }).collect()
+ }
+
/// Returns a list of all routes included in the invoice
pub fn private_routes(&self) -> Vec<&PrivateRoute> {
self.signed_invoice.private_routes()
self.signed_invoice.currency()
}
+ /// Returns the network for which the invoice was issued
+ ///
+ /// This is not exported to bindings users, see [`Self::currency`] instead.
+ pub fn network(&self) -> Network {
+ self.signed_invoice.currency().into()
+ }
+
/// Returns the amount if specified in the invoice as millisatoshis.
pub fn amount_milli_satoshis(&self) -> Option<u64> {
self.signed_invoice.amount_pico_btc().map(|v| v / 10)
}
- /// Returns the amount if specified in the invoice as pico <currency>.
+ /// Returns the amount if specified in the invoice as pico BTC.
fn amount_pico_btc(&self) -> Option<u64> {
self.signed_invoice.amount_pico_btc()
}
TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
- TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY,
+ TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
TaggedField::Fallback(_) => constants::TAG_FALLBACK,
TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
+ TaggedField::PaymentMetadata(_) => constants::TAG_PAYMENT_METADATA,
TaggedField::Features(_) => constants::TAG_FEATURES,
};
impl Description {
/// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
- /// returns `CreationError::DescriptionTooLong` otherwise
+ /// returns [`CreationError::DescriptionTooLong`] otherwise
///
/// Please note that single characters may use more than one byte due to UTF8 encoding.
pub fn new(description: String) -> Result<Description, CreationError> {
}
}
- /// Returns the underlying description `String`
+ /// Returns the underlying description [`String`]
pub fn into_inner(self) -> String {
self.0
}
}
-impl Into<String> for Description {
- fn into(self) -> String {
- self.into_inner()
+impl From<Description> for String {
+ fn from(val: Description) -> Self {
+ val.into_inner()
}
}
ExpiryTime(Duration::from_secs(seconds))
}
- /// Construct an `ExpiryTime` from a `Duration`.
+ /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
pub fn from_duration(duration: Duration) -> ExpiryTime {
- ExpiryTime(duration)
+ Self::from_seconds(duration.as_secs())
}
/// Returns the expiry time in seconds
self.0.as_secs()
}
- /// Returns a reference to the underlying `Duration` (=expiry time)
+ /// Returns a reference to the underlying [`Duration`] (=expiry time)
pub fn as_duration(&self) -> &Duration {
&self.0
}
}
}
-impl Into<RouteHint> for PrivateRoute {
- fn into(self) -> RouteHint {
- self.into_inner()
+impl From<PrivateRoute> for RouteHint {
+ fn from(val: PrivateRoute) -> Self {
+ val.into_inner()
}
}
}
}
-/// Errors that may occur when constructing a new `RawInvoice` or `Invoice`
+/// Errors that may occur when constructing a new [`RawInvoice`] or [`Invoice`]
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum CreationError {
- /// The supplied description string was longer than 639 __bytes__ (see [`Description::new(…)`](./struct.Description.html#method.new))
+ /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
DescriptionTooLong,
/// The specified route has too many hops and can't be encoded
///
/// [phantom invoices]: crate::utils::create_phantom_invoice
MissingRouteHints,
+
+ /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
+ ///
+ /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
+ MinFinalCltvExpiryDeltaTooShort,
}
impl Display for CreationError {
CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
+ CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
+ "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
}
}
}
#[cfg(feature = "std")]
impl std::error::Error for CreationError { }
-/// Errors that may occur when converting a `RawInvoice` to an `Invoice`. They relate to the
+/// Errors that may occur when converting a [`RawInvoice`] to an [`Invoice`]. They relate to the
/// requirements sections in BOLT #11
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum SemanticError {
#[cfg(feature = "std")]
impl std::error::Error for SemanticError { }
-/// When signing using a fallible method either an user-supplied `SignError` or a `CreationError`
+/// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
/// may occur.
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum SignOrCreationError<S = ()> {
}
}
+#[cfg(feature = "serde")]
+impl Serialize for Invoice {
+ fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where S: Serializer {
+ serializer.serialize_str(self.to_string().as_str())
+ }
+}
+#[cfg(feature = "serde")]
+impl<'de> Deserialize<'de> for Invoice {
+ fn deserialize<D>(deserializer: D) -> Result<Invoice, D::Error> where D: Deserializer<'de> {
+ let bolt11 = String::deserialize(deserializer)?
+ .parse::<Invoice>()
+ .map_err(|e| D::Error::custom(format_args!("{:?}", e)))?;
+
+ Ok(bolt11)
+ }
+}
+
#[cfg(test)]
mod test {
+ use bitcoin::Script;
use bitcoin_hashes::hex::FromHex;
use bitcoin_hashes::sha256;
#[test]
fn test_system_time_bounds_assumptions() {
assert_eq!(
- ::PositiveTimestamp::from_unix_timestamp(::MAX_TIMESTAMP + 1),
- Err(::CreationError::TimestampOutOfBounds)
+ crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
+ Err(crate::CreationError::TimestampOutOfBounds)
);
}
#[test]
fn test_calc_invoice_hash() {
- use ::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
- use ::TaggedField::*;
+ use crate::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
+ use crate::TaggedField::*;
let invoice = RawInvoice {
hrp: RawHrp {
data: RawDataPart {
timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
tagged_fields: vec![
- PaymentHash(::Sha256(sha256::Hash::from_hex(
+ PaymentHash(crate::Sha256(sha256::Hash::from_hex(
"0001020304050607080900010203040506070809000102030405060708090102"
).unwrap())).into(),
- Description(::Description::new(
+ Description(crate::Description::new(
"Please consider supporting this project".to_owned()
).unwrap()).into(),
],
0xd5, 0x18, 0xe1, 0xc9
];
- assert_eq!(invoice.hash(), expected_hash)
+ assert_eq!(invoice.signable_hash(), expected_hash)
}
#[test]
fn test_check_signature() {
- use TaggedField::*;
+ use crate::TaggedField::*;
use secp256k1::Secp256k1;
- use secp256k1::recovery::{RecoveryId, RecoverableSignature};
- use secp256k1::key::{SecretKey, PublicKey};
- use {SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
+ use secp256k1::ecdsa::{RecoveryId, RecoverableSignature};
+ use secp256k1::{SecretKey, PublicKey};
+ use crate::{SignedRawInvoice, InvoiceSignature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
PositiveTimestamp};
let invoice = SignedRawInvoice {
"0001020304050607080900010203040506070809000102030405060708090102"
).unwrap())).into(),
Description(
- ::Description::new(
+ crate::Description::new(
"Please consider supporting this project".to_owned()
).unwrap()
).into(),
).unwrap();
let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
- assert_eq!(invoice.recover_payee_pub_key(), Ok(::PayeePubKey(public_key)));
+ assert_eq!(invoice.recover_payee_pub_key(), Ok(crate::PayeePubKey(public_key)));
let (raw_invoice, _, _) = invoice.into_parts();
let new_signed = raw_invoice.sign::<_, ()>(|hash| {
- Ok(Secp256k1::new().sign_recoverable(hash, &private_key))
+ Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key))
}).unwrap();
assert!(new_signed.check_signature());
#[test]
fn test_check_feature_bits() {
- use TaggedField::*;
+ use crate::TaggedField::*;
use lightning::ln::features::InvoiceFeatures;
use secp256k1::Secp256k1;
- use secp256k1::key::SecretKey;
- use {RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
+ use secp256k1::SecretKey;
+ use crate::{RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
SemanticError};
let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
"0001020304050607080900010203040506070809000102030405060708090102"
).unwrap())).into(),
Description(
- ::Description::new(
+ crate::Description::new(
"Please consider supporting this project".to_owned()
).unwrap()
).into(),
let invoice = {
let mut invoice = invoice_template.clone();
invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
let mut invoice = invoice_template.clone();
invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::InvalidFeatures));
+ let mut payment_secret_features = InvoiceFeatures::empty();
+ payment_secret_features.set_payment_secret_required();
+
// Including payment secret and feature bits
let invoice = {
let mut invoice = invoice_template.clone();
invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
- invoice.data.tagged_fields.push(Features(InvoiceFeatures::known()).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.data.tagged_fields.push(Features(payment_secret_features.clone()).into());
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert!(Invoice::from_signed(invoice).is_ok());
// No payment secret or features
let invoice = {
let invoice = invoice_template.clone();
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
let invoice = {
let mut invoice = invoice_template.clone();
invoice.data.tagged_fields.push(Features(InvoiceFeatures::empty()).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
// Missing payment secret
let invoice = {
let mut invoice = invoice_template.clone();
- invoice.data.tagged_fields.push(Features(InvoiceFeatures::known()).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.data.tagged_fields.push(Features(payment_secret_features).into());
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
// Multiple payment secrets
let invoice = {
- let mut invoice = invoice_template.clone();
+ let mut invoice = invoice_template;
invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
- invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+ invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
}.unwrap();
assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::MultiplePaymentSecrets));
}
#[test]
fn test_builder_amount() {
- use ::*;
+ use crate::*;
let builder = InvoiceBuilder::new(Currency::Bitcoin)
.description("Test".into())
assert_eq!(invoice.hrp.raw_amount, Some(15));
- let invoice = builder.clone()
+ let invoice = builder
.amount_milli_satoshis(150)
.build_raw()
.unwrap();
#[test]
fn test_builder_fail() {
- use ::*;
+ use crate::*;
use lightning::routing::router::RouteHintHop;
use std::iter::FromIterator;
- use secp256k1::key::PublicKey;
+ use secp256k1::PublicKey;
let builder = InvoiceBuilder::new(Currency::Bitcoin)
.payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
.duration_since_epoch(Duration::from_secs(1234567))
- .min_final_cltv_expiry(144);
+ .min_final_cltv_expiry_delta(144);
let too_long_string = String::from_iter(
(0..1024).map(|_| '?')
.build_raw();
assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
- let sign_error_res = builder.clone()
+ let sign_error_res = builder
.description("Test".into())
.payment_secret(PaymentSecret([0; 32]))
.try_build_signed(|_| {
#[test]
fn test_builder_ok() {
- use ::*;
+ use crate::*;
use lightning::routing::router::RouteHintHop;
use secp256k1::Secp256k1;
- use secp256k1::key::{SecretKey, PublicKey};
+ use secp256k1::{SecretKey, PublicKey};
use std::time::{UNIX_EPOCH, Duration};
let secp_ctx = Secp256k1::new();
let route_1 = RouteHint(vec![
RouteHintHop {
- src_node_id: public_key.clone(),
+ src_node_id: public_key,
short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
fees: RoutingFees {
base_msat: 2,
htlc_maximum_msat: None,
},
RouteHintHop {
- src_node_id: public_key.clone(),
+ src_node_id: public_key,
short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
fees: RoutingFees {
base_msat: 3,
let route_2 = RouteHint(vec![
RouteHintHop {
- src_node_id: public_key.clone(),
+ src_node_id: public_key,
short_channel_id: 0,
fees: RoutingFees {
base_msat: 4,
htlc_maximum_msat: None,
},
RouteHintHop {
- src_node_id: public_key.clone(),
+ src_node_id: public_key,
short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
fees: RoutingFees {
base_msat: 5,
let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
.amount_milli_satoshis(123)
.duration_since_epoch(Duration::from_secs(1234567))
- .payee_pub_key(public_key.clone())
+ .payee_pub_key(public_key)
.expiry_time(Duration::from_secs(54321))
- .min_final_cltv_expiry(144)
- .fallback(Fallback::PubKeyHash([0;20]))
+ .min_final_cltv_expiry_delta(144)
+ .fallback(Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap()))
.private_route(route_1.clone())
.private_route(route_2.clone())
.description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
.basic_mpp();
let invoice = builder.clone().build_signed(|hash| {
- secp_ctx.sign_recoverable(hash, &private_key)
+ secp_ctx.sign_ecdsa_recoverable(hash, &private_key)
}).unwrap();
assert!(invoice.check_signature().is_ok());
);
assert_eq!(invoice.payee_pub_key(), Some(&public_key));
assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
- assert_eq!(invoice.min_final_cltv_expiry(), 144);
- assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
+ assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
+ assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap())]);
+ let address = Address::from_script(&Script::new_p2pkh(&PubkeyHash::from_slice(&[0;20]).unwrap()), Network::Testnet).unwrap();
+ assert_eq!(invoice.fallback_addresses(), vec![address]);
assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
assert_eq!(
invoice.description(),
);
assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
- assert_eq!(invoice.features(), Some(&InvoiceFeatures::known()));
+
+ let mut expected_features = InvoiceFeatures::empty();
+ expected_features.set_variable_length_onion_required();
+ expected_features.set_payment_secret_required();
+ expected_features.set_basic_mpp_optional();
+ assert_eq!(invoice.features(), Some(&expected_features));
let raw_invoice = builder.build_raw().unwrap();
assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
#[test]
fn test_default_values() {
- use ::*;
+ use crate::*;
use secp256k1::Secp256k1;
- use secp256k1::key::SecretKey;
+ use secp256k1::SecretKey;
let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
.description("Test".into())
.sign::<_, ()>(|hash| {
let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
let secp_ctx = Secp256k1::new();
- Ok(secp_ctx.sign_recoverable(hash, &privkey))
+ Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
})
.unwrap();
let invoice = Invoice::from_signed(signed_invoice).unwrap();
- assert_eq!(invoice.min_final_cltv_expiry(), DEFAULT_MIN_FINAL_CLTV_EXPIRY);
+ assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
assert!(!invoice.would_expire(Duration::from_secs(1234568)));
}
#[test]
fn test_expiration() {
- use ::*;
+ use crate::*;
use secp256k1::Secp256k1;
- use secp256k1::key::SecretKey;
+ use secp256k1::SecretKey;
let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
.description("Test".into())
.sign::<_, ()>(|hash| {
let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
let secp_ctx = Secp256k1::new();
- Ok(secp_ctx.sign_recoverable(hash, &privkey))
+ Ok(secp_ctx.sign_ecdsa_recoverable(hash, &privkey))
})
.unwrap();
let invoice = Invoice::from_signed(signed_invoice).unwrap();
assert!(invoice.would_expire(Duration::from_secs(1234567 + DEFAULT_EXPIRY_TIME + 1)));
}
+
+ #[cfg(feature = "serde")]
+ #[test]
+ fn test_serde() {
+ let invoice_str = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
+ h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
+ 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
+ h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
+ j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
+ ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
+ guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
+ ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
+ p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
+ 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
+ j5r6drg6k6zcqj0fcwg";
+ let invoice = invoice_str.parse::<super::Invoice>().unwrap();
+ let serialized_invoice = serde_json::to_string(&invoice).unwrap();
+ let deserialized_invoice: super::Invoice = serde_json::from_str(serialized_invoice.as_str()).unwrap();
+ assert_eq!(invoice, deserialized_invoice);
+ assert_eq!(invoice_str, deserialized_invoice.to_string().as_str());
+ assert_eq!(invoice_str, serialized_invoice.as_str().trim_matches('\"'));
+ }
}
projects / rust-lightning / blobdiff