+// 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(feature = "strict", deny(warnings))]
+#![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
+
+#[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;
-extern crate lightning;
+#[macro_use] extern crate lightning;
extern crate num_traits;
extern crate secp256k1;
+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 lightning::ln::PaymentSecret;
use lightning::ln::features::InvoiceFeatures;
#[cfg(any(doc, test))]
-use lightning::routing::network_graph::RoutingFees;
-use lightning::routing::router::RouteHintHop;
+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;
-use std::fmt::{Display, Formatter, self};
-use std::iter::FilterMap;
-use std::ops::Deref;
-use std::slice::Iter;
-use std::time::{SystemTime, Duration, UNIX_EPOCH};
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
mod de;
mod ser;
mod tb;
-pub use de::{ParseError, ParseOrSemanticError};
+mod prelude {
+ #[cfg(feature = "hashbrown")]
+ extern crate hashbrown;
-// TODO: fix before 2037 (see rust PR #55527)
-/// Defines the maximum UNIX timestamp that can be represented as `SystemTime`. This is checked by
-/// one of the unit tests, please run them.
-const SYSTEM_TIME_MAX_UNIX_TIMESTAMP: u64 = std::i32::MAX as u64;
+ pub use alloc::{vec, vec::Vec, string::String, collections::VecDeque, boxed::Box};
+ #[cfg(not(feature = "hashbrown"))]
+ pub use std::collections::{HashMap, HashSet, hash_map};
+ #[cfg(feature = "hashbrown")]
+ pub use self::hashbrown::{HashMap, HashSet, hash_map};
-/// Allow the expiry time to be up to one year. Since this reduces the range of possible timestamps
-/// it should be rather low as long as we still have to support 32bit time representations
-const MAX_EXPIRY_TIME: u64 = 60 * 60 * 24 * 356;
+ pub use alloc::string::ToString;
+}
-/// Default expiry time as defined by [BOLT 11].
-///
-/// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
-const DEFAULT_EXPIRY_TIME: u64 = 3600;
+use crate::prelude::*;
-/// Default minimum final CLTV expiry as defined by [BOLT 11].
-///
-/// [BOLT 11]: https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md
-const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
-
-/// This function is used as a static assert for the size of `SystemTime`. If the crate fails to
-/// compile due to it this indicates that your system uses unexpected bounds for `SystemTime`. You
-/// can remove this functions and run the test `test_system_time_bounds_assumptions`. In any case,
-/// please open an issue. If all tests pass you should be able to use this library safely by just
-/// removing this function till we patch it accordingly.
-fn __system_time_size_check() {
- // Use 2 * sizeof(u64) as expected size since the expected underlying implementation is storing
- // a `Duration` since `SystemTime::UNIX_EPOCH`.
- unsafe { std::mem::transmute_copy::<SystemTime, [u8; 16]>(&UNIX_EPOCH); }
+/// Sync compat for std/no_std
+#[cfg(feature = "std")]
+mod sync {
+ pub use ::std::sync::{Mutex, MutexGuard};
}
+/// Sync compat for std/no_std
+#[cfg(not(feature = "std"))]
+mod sync;
-/// **Call this function on startup to ensure that all assumptions about the platform are valid.**
-///
-/// Unfortunately we have to make assumptions about the upper bounds of the `SystemTime` type on
-/// your platform which we can't fully verify at compile time and which isn't part of it's contract.
-/// To our best knowledge our assumptions hold for all platforms officially supported by rust, but
-/// since this check is fast we recommend to do it anyway.
+/// 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;
+
+/// The maximum timestamp as [`Duration::as_secs`] since the Unix epoch allowed by [`BOLT 11`].
///
-/// If this function fails this is considered a bug. Please open an issue describing your
-/// platform and stating your current system time.
+/// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
+pub const MAX_TIMESTAMP: u64 = (1 << TIMESTAMP_BITS) - 1;
+
+/// Default expiry time as defined by [BOLT 11].
///
-/// # Panics
-/// If the check fails this function panics. By calling this function on startup you ensure that
-/// this wont happen at an arbitrary later point in time.
-pub fn check_platform() {
- // The upper and lower bounds of `SystemTime` are not part of its public contract and are
- // platform specific. That's why we have to test if our assumptions regarding these bounds
- // hold on the target platform.
- //
- // If this test fails on your platform, please don't use the library and open an issue
- // instead so we can resolve the situation. Currently this library is tested on:
- // * Linux (64bit)
- let fail_date = UNIX_EPOCH + Duration::from_secs(SYSTEM_TIME_MAX_UNIX_TIMESTAMP);
- let year = Duration::from_secs(60 * 60 * 24 * 365);
-
- // Make sure that the library will keep working for another year
- assert!(fail_date.duration_since(SystemTime::now()).unwrap() > year);
-
- let max_ts = PositiveTimestamp::from_unix_timestamp(
- SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME
- ).unwrap();
- let max_exp = ::ExpiryTime::from_seconds(MAX_EXPIRY_TIME).unwrap();
-
- assert_eq!(
- (*max_ts.as_time() + *max_exp.as_duration()).duration_since(UNIX_EPOCH).unwrap().as_secs(),
- SYSTEM_TIME_MAX_UNIX_TIMESTAMP
- );
-}
+/// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
+pub const DEFAULT_EXPIRY_TIME: u64 = 3600;
+/// 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`].
+///
+/// [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;
/// 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.
///
/// ```
/// extern crate secp256k1;
+/// extern crate lightning;
/// extern crate lightning_invoice;
/// extern crate bitcoin_hashes;
///
/// use bitcoin_hashes::sha256;
///
/// use secp256k1::Secp256k1;
-/// use secp256k1::key::SecretKey;
+/// use secp256k1::SecretKey;
+///
+/// use lightning::ln::PaymentSecret;
///
/// use lightning_invoice::{Currency, InvoiceBuilder};
///
+/// # #[cfg(not(feature = "std"))]
+/// # fn main() {}
+/// # #[cfg(feature = "std")]
/// # fn main() {
/// let private_key = SecretKey::from_slice(
/// &[
/// ).unwrap();
///
/// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
+/// let payment_secret = PaymentSecret([42u8; 32]);
///
/// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
/// .description("Coins pls!".into())
/// .payment_hash(payment_hash)
+/// .payment_secret(payment_secret)
/// .current_timestamp()
/// .min_final_cltv_expiry(144)
/// .build_signed(|hash| {
-/// Secp256k1::new().sign_recoverable(hash, &private_key)
+/// Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
/// })
/// .unwrap();
///
tagged_fields: Vec<TaggedField>,
error: Option<CreationError>,
- phantom_d: std::marker::PhantomData<D>,
- phantom_h: std::marker::PhantomData<H>,
- phantom_t: std::marker::PhantomData<T>,
- phantom_c: std::marker::PhantomData<C>,
- phantom_s: std::marker::PhantomData<S>,
+ phantom_d: core::marker::PhantomData<D>,
+ phantom_h: core::marker::PhantomData<H>,
+ phantom_t: core::marker::PhantomData<T>,
+ phantom_c: core::marker::PhantomData<C>,
+ phantom_s: core::marker::PhantomData<S>,
}
/// Represents a syntactically and semantically correct lightning BOLT11 invoice.
/// 1. using `InvoiceBuilder`
/// 2. using `Invoice::from_signed(SignedRawInvoice)`
/// 3. using `str::parse::<Invoice>(&str)`
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct Invoice {
signed_invoice: SignedRawInvoice,
}
///
/// # Invariants
/// The hash has to be either from the deserialized invoice or from the serialized `raw_invoice`.
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct SignedRawInvoice {
/// The rawInvoice that the signature belongs to
raw_invoice: RawInvoice,
/// De- 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)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawInvoice {
/// human readable part
pub hrp: RawHrp,
/// 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)]
+#[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,
}
/// Data of the `RawInvoice` that is encoded in the data part
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawDataPart {
/// generation time of the invoice
pub timestamp: PositiveTimestamp,
pub tagged_fields: Vec<RawTaggedField>,
}
-/// A timestamp that refers to a date after 1 January 1970 which means its representation as UNIX
-/// timestamp is positive.
+/// A timestamp that refers to a date after 1 January 1970.
///
/// # Invariants
-/// The UNIX timestamp representing the stored time has to be positive and small enough so that
-/// a `EpiryTime` can be added to it without an overflow.
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct PositiveTimestamp(SystemTime);
+///
+/// The Unix timestamp representing the stored time has to be positive and no greater than
+/// [`MAX_TIMESTAMP`].
+#[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,
/// (C-not exported) 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
}
}
/// Enum representing the crypto currencies (or networks) supported by this library
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum Currency {
/// Bitcoin mainnet
Bitcoin,
/// Bitcoin regtest
Regtest,
- /// Bitcoin simnet/signet
+ /// Bitcoin simnet
Simnet,
+
+ /// Bitcoin signet
+ Signet,
}
/// Tagged field which may have an unknown tag
-#[derive(Eq, PartialEq, Debug, Clone)]
+///
+/// (C-not exported) as we don't currently support TaggedField
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum RawTaggedField {
/// Parsed tagged field with known tag
KnownSemantics(TaggedField),
/// 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
+/// in the variant.
#[allow(missing_docs)]
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum TaggedField {
PaymentHash(Sha256),
Description(Description),
ExpiryTime(ExpiryTime),
MinFinalCltvExpiry(MinFinalCltvExpiry),
Fallback(Fallback),
- Route(RouteHint),
+ PrivateRoute(PrivateRoute),
PaymentSecret(PaymentSecret),
Features(InvoiceFeatures),
}
/// SHA-256 hash
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct Sha256(pub sha256::Hash);
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub struct Sha256(/// (C-not exported) as the native hash types are not currently mapped
+ pub sha256::Hash);
/// Description string
///
/// # Invariants
/// The description can be at most 639 __bytes__ long
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct Description(String);
/// Payee public key
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct PayeePubKey(pub PublicKey);
/// Positive duration that defines when (relatively to the timestamp) in the future the invoice
/// expires
-///
-/// # Invariants
-/// The number of seconds this expiry time represents has to be in the range
-/// `0...(SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)` to avoid overflows when adding it to a
-/// timestamp
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct ExpiryTime(Duration);
/// `min_final_cltv_expiry` to use for the last HTLC in the route
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct MinFinalCltvExpiry(pub u64);
// TODO: better types instead onf byte arrays
/// Fallback address in case no LN payment is possible
#[allow(missing_docs)]
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum Fallback {
SegWitProgram {
version: u5,
}
/// Recoverable signature
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub struct InvoiceSignature(pub RecoverableSignature);
/// Private routing information
/// # Invariants
/// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
///
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct RouteHint(Vec<RouteHintHop>);
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub struct PrivateRoute(RouteHint);
/// Tag constants as specified in BOLT11
#[allow(missing_docs)]
pub const TAG_EXPIRY_TIME: u8 = 6;
pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
pub const TAG_FALLBACK: u8 = 9;
- pub const TAG_ROUTE: u8 = 3;
+ pub const TAG_PRIVATE_ROUTE: u8 = 3;
pub const TAG_PAYMENT_SECRET: u8 = 16;
pub const TAG_FEATURES: u8 = 5;
}
tagged_fields: Vec::new(),
error: None,
- phantom_d: std::marker::PhantomData,
- phantom_h: std::marker::PhantomData,
- phantom_t: std::marker::PhantomData,
- phantom_c: std::marker::PhantomData,
- phantom_s: std::marker::PhantomData,
+ phantom_d: core::marker::PhantomData,
+ phantom_h: core::marker::PhantomData,
+ phantom_t: core::marker::PhantomData,
+ phantom_c: core::marker::PhantomData,
+ phantom_s: core::marker::PhantomData,
}
}
}
tagged_fields: self.tagged_fields,
error: self.error,
- phantom_d: std::marker::PhantomData,
- phantom_h: std::marker::PhantomData,
- phantom_t: std::marker::PhantomData,
- phantom_c: std::marker::PhantomData,
- phantom_s: std::marker::PhantomData,
+ phantom_d: core::marker::PhantomData,
+ phantom_h: core::marker::PhantomData,
+ phantom_t: core::marker::PhantomData,
+ phantom_c: core::marker::PhantomData,
+ phantom_s: core::marker::PhantomData,
}
}
- /// Sets the amount in pico BTC. The optimal SI prefix is choosen automatically.
- pub fn amount_pico_btc(mut self, amount: u64) -> Self {
+ /// Sets the amount in millisatoshis. The optimal SI prefix is chosen automatically.
+ pub fn amount_milli_satoshis(mut self, amount_msat: u64) -> Self {
+ let amount = amount_msat * 10; // Invoices are denominated in "pico BTC"
let biggest_possible_si_prefix = SiPrefix::values_desc()
.iter()
.find(|prefix| amount % prefix.multiplier() == 0)
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 {
- match ExpiryTime::from_duration(expiry_time) {
- Ok(t) => self.tagged_fields.push(TaggedField::ExpiryTime(t)),
- Err(e) => self.error = Some(e),
- };
+ self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
self
}
}
/// Adds a private route.
- pub fn route(mut self, route: Vec<RouteHintHop>) -> Self {
- match RouteHint::new(route) {
- Ok(r) => self.tagged_fields.push(TaggedField::Route(r)),
+ pub fn private_route(mut self, hint: RouteHint) -> Self {
+ match PrivateRoute::new(hint) {
+ Ok(r) => self.tagged_fields.push(TaggedField::PrivateRoute(r)),
Err(e) => self.error = Some(e),
}
self
}
impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
- /// Sets the timestamp.
+ /// Sets the timestamp to a specific [`SystemTime`].
+ #[cfg(feature = "std")]
pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
match PositiveTimestamp::from_system_time(time) {
Ok(t) => self.timestamp = Some(t),
self.set_flags()
}
- /// Sets the timestamp to the current UNIX timestamp.
+ /// 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> {
+ match PositiveTimestamp::from_duration_since_epoch(time) {
+ Ok(t) => self.timestamp = Some(t),
+ Err(e) => self.error = Some(e),
+ }
+
+ self.set_flags()
+ }
+
+ /// Sets the timestamp to the current system time.
+ #[cfg(feature = "std")]
pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
let now = PositiveTimestamp::from_system_time(SystemTime::now());
self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False> {
/// 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();
+ let mut features = InvoiceFeatures::empty();
+ features.set_variable_length_onion_required();
+ features.set_payment_secret_required();
self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
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> {
/// 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<S: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, S> {
+impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
/// 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.
invoice.check_field_counts().expect("should be ensured by type signature of builder");
invoice.check_feature_bits().expect("should be ensured by type signature of builder");
+ invoice.check_amount().expect("should be ensured by type signature of builder");
Ok(invoice)
}
}
/// The hash of the `RawInvoice` that was signed.
- pub fn hash(&self) -> &[u8; 32] {
+ pub fn signable_hash(&self) -> &[u8; 32] {
&self.hash
}
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
)?))
.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
/// Finds the first element of an enum stream of a given variant and extracts one member of the
/// variant. If no element was found `None` gets returned.
///
-/// The following example would extract the first
-/// ```
-/// use Enum::*
+/// The following example would extract the first B.
///
/// 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) => {
- $iter.filter_map(|tf| match *tf {
+ ($iter:expr, $enm:pat, $enm_var:ident) => {
+ find_all_extract!($iter, $enm, $enm_var).next()
+ };
+}
+
+/// Finds the all elements of an enum stream of a given variant and extracts one member of the
+/// variant through an iterator.
+///
+/// The following example would extract all A.
+///
+/// enum Enum {
+/// A(u8),
+/// B(u16)
+/// }
+///
+/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
+///
+/// assert_eq!(
+/// 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) => {
+ $iter.filter_map(|tf| match *tf {
$enm => Some($enm_var),
_ => None,
- }).next()
- };
+ })
+ };
}
#[allow(missing_docs)]
impl RawInvoice {
- /// Construct the invoice's HRP and signatureless data into a preimage to be hashed.
- pub(crate) fn construct_invoice_preimage(hrp_bytes: &[u8], data_without_signature: &[u5]) -> Vec<u8> {
- use bech32::FromBase32;
-
- let mut preimage = Vec::<u8>::from(hrp_bytes);
-
- let mut data_part = Vec::from(data_without_signature);
- let overhang = (data_part.len() * 5) % 8;
- if overhang > 0 {
- // add padding if data does not end at a byte boundary
- data_part.push(u5::try_from_u8(0).unwrap());
-
- // if overhang is in (1..3) we need to add u5(0) padding two times
- if overhang < 3 {
- data_part.push(u5::try_from_u8(0).unwrap());
- }
- }
-
- preimage.extend_from_slice(&Vec::<u8>::from_base32(&data_part)
- .expect("No padding error may occur due to appended zero above."));
- preimage
- }
-
/// Hash the HRP as bytes and signatureless data part.
fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
- let preimage = RawInvoice::construct_invoice_preimage(hrp_bytes, data_without_signature);
+ let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
let mut hash: [u8; 32] = Default::default();
hash.copy_from_slice(&sha256::Hash::hash(&preimage)[..]);
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(
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)?;
/// (C-not exported) as we don't support Vec<&NonOpaqueType>
pub fn fallbacks(&self) -> Vec<&Fallback> {
- self.known_tagged_fields().filter_map(|tf| match tf {
- &TaggedField::Fallback(ref f) => Some(f),
- _ => None,
- }).collect::<Vec<&Fallback>>()
+ find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
}
- pub fn routes(&self) -> Vec<&RouteHint> {
- self.known_tagged_fields().filter_map(|tf| match tf {
- &TaggedField::Route(ref r) => Some(r),
- _ => None,
- }).collect::<Vec<&RouteHint>>()
+ pub fn private_routes(&self) -> Vec<&PrivateRoute> {
+ find_all_extract!(self.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x).collect()
}
pub fn amount_pico_btc(&self) -> Option<u64> {
}
impl PositiveTimestamp {
- /// Create a new `PositiveTimestamp` from a unix timestamp in the Range
- /// `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
- /// `CreationError::TimestampOutOfBounds`.
+ /// Creates a `PositiveTimestamp` from a Unix timestamp in the range `0..=MAX_TIMESTAMP`.
+ ///
+ /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
- if unix_seconds > SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME {
- Err(CreationError::TimestampOutOfBounds)
+ if unix_seconds <= MAX_TIMESTAMP {
+ Ok(Self(Duration::from_secs(unix_seconds)))
} else {
- Ok(PositiveTimestamp(UNIX_EPOCH + Duration::from_secs(unix_seconds)))
+ Err(CreationError::TimestampOutOfBounds)
}
}
- /// Create a new `PositiveTimestamp` from a `SystemTime` with a corresponding unix timestamp in
- /// the Range `0...SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME`, otherwise return a
- /// `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> {
- if time
- .duration_since(UNIX_EPOCH)
- .map(|t| t.as_secs() <= SYSTEM_TIME_MAX_UNIX_TIMESTAMP - MAX_EXPIRY_TIME)
- .unwrap_or(true)
- {
- Ok(PositiveTimestamp(time))
- } else {
- Err(CreationError::TimestampOutOfBounds)
- }
+ time.duration_since(SystemTime::UNIX_EPOCH)
+ .map(Self::from_duration_since_epoch)
+ .unwrap_or(Err(CreationError::TimestampOutOfBounds))
}
- /// Returns the UNIX timestamp representing the stored time
- pub fn as_unix_timestamp(&self) -> u64 {
- self.0.duration_since(UNIX_EPOCH)
- .expect("ensured by type contract/constructors")
- .as_secs()
+ /// 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> {
+ Self::from_unix_timestamp(duration.as_secs())
}
- /// Returns a reference to the internal `SystemTime` time representation
- pub fn as_time(&self) -> &SystemTime {
- &self.0
+ /// Returns the Unix timestamp representing the stored time
+ pub fn as_unix_timestamp(&self) -> u64 {
+ self.0.as_secs()
}
-}
-impl Into<SystemTime> for PositiveTimestamp {
- fn into(self) -> SystemTime {
+ /// Returns the duration of the stored time since the Unix epoch
+ pub fn as_duration_since_epoch(&self) -> Duration {
self.0
}
-}
-impl Deref for PositiveTimestamp {
- type Target = SystemTime;
+ /// Returns the [`SystemTime`] representing the stored time
+ #[cfg(feature = "std")]
+ pub fn as_time(&self) -> SystemTime {
+ SystemTime::UNIX_EPOCH + self.0
+ }
+}
- fn deref(&self) -> &Self::Target {
- &self.0
+#[cfg(feature = "std")]
+impl Into<SystemTime> for PositiveTimestamp {
+ fn into(self) -> SystemTime {
+ SystemTime::UNIX_EPOCH + self.0
}
}
return Err(SemanticError::MultipleDescriptions);
}
+ self.check_payment_secret()?;
+
Ok(())
}
- /// Check that feature bits are set as required
- fn check_feature_bits(&self) -> Result<(), SemanticError> {
- // "If the payment_secret feature is set, MUST include exactly one s field."
+ /// Checks that there is exactly one payment secret field
+ fn check_payment_secret(&self) -> Result<(), SemanticError> {
+ // "A writer MUST include exactly one `s` field."
let payment_secret_count = self.tagged_fields().filter(|&tf| match *tf {
TaggedField::PaymentSecret(_) => true,
_ => false,
}).count();
- if payment_secret_count > 1 {
+ if payment_secret_count < 1 {
+ return Err(SemanticError::NoPaymentSecret);
+ } else if payment_secret_count > 1 {
return Err(SemanticError::MultiplePaymentSecrets);
}
+ Ok(())
+ }
+
+ /// Check that amount is a whole number of millisatoshis
+ fn check_amount(&self) -> Result<(), SemanticError> {
+ if let Some(amount_pico_btc) = self.amount_pico_btc() {
+ if amount_pico_btc % 10 != 0 {
+ return Err(SemanticError::ImpreciseAmount);
+ }
+ }
+ Ok(())
+ }
+
+ /// Check that feature bits are set as required
+ fn check_feature_bits(&self) -> Result<(), SemanticError> {
+ self.check_payment_secret()?;
+
// "A writer MUST set an s field if and only if the payment_secret feature is set."
- let has_payment_secret = payment_secret_count == 1;
+ // (this requirement has been since removed, and we now require the payment secret
+ // feature bit always).
let features = self.tagged_fields().find(|&tf| match *tf {
TaggedField::Features(_) => true,
_ => false,
});
match features {
- None if has_payment_secret => Err(SemanticError::InvalidFeatures),
- None => Ok(()),
+ None => Err(SemanticError::InvalidFeatures),
Some(TaggedField::Features(features)) => {
- if features.supports_payment_secret() && has_payment_secret {
- Ok(())
- } else if has_payment_secret {
+ if features.requires_unknown_bits() {
Err(SemanticError::InvalidFeatures)
- } else if features.supports_payment_secret() {
+ } else if !features.supports_payment_secret() {
Err(SemanticError::InvalidFeatures)
} else {
Ok(())
match self.signed_invoice.recover_payee_pub_key() {
Err(secp256k1::Error::InvalidRecoveryId) =>
return Err(SemanticError::InvalidRecoveryId),
- Err(_) => panic!("no other error may occur"),
+ Err(secp256k1::Error::InvalidSignature) =>
+ return Err(SemanticError::InvalidSignature),
+ Err(e) => panic!("no other error may occur, got {:?}", e),
Ok(_) => {},
}
Ok(())
}
- /// Constructs an `Invoice` from a `SignedInvoice` by checking all its invariants.
+ /// Constructs an `Invoice` from a `SignedRawInvoice` by checking all its invariants.
/// ```
/// use lightning_invoice::*;
///
- /// let invoice = "lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp\
- /// l2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d7\
- /// 3gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ec\
- /// ky03ylcqca784w";
+ /// let invoice = "lnbc100p1psj9jhxdqud3jxktt5w46x7unfv9kz6mn0v3jsnp4q0d3p2sfluzdx45tqcs\
+ /// h2pu5qc7lgq0xs578ngs6s0s68ua4h7cvspp5q6rmq35js88zp5dvwrv9m459tnk2zunwj5jalqtyxqulh0l\
+ /// 5gflssp5nf55ny5gcrfl30xuhzj3nphgj27rstekmr9fw3ny5989s300gyus9qyysgqcqpcrzjqw2sxwe993\
+ /// h5pcm4dxzpvttgza8zhkqxpgffcrf5v25nwpr3cmfg7z54kuqq8rgqqqqqqqq2qqqqq9qq9qrzjqd0ylaqcl\
+ /// j9424x9m8h2vcukcgnm6s56xfgu3j78zyqzhgs4hlpzvznlugqq9vsqqqqqqqlgqqqqqeqq9qrzjqwldmj9d\
+ /// ha74df76zhx6l9we0vjdquygcdt3kssupehe64g6yyp5yz5rhuqqwccqqyqqqqlgqqqqjcqq9qrzjqf9e58a\
+ /// guqr0rcun0ajlvmzq3ek63cw2w282gv3z5uupmuwvgjtq2z55qsqqg6qqqyqqqrtnqqqzq3cqygrzjqvphms\
+ /// ywntrrhqjcraumvc4y6r8v4z5v593trte429v4hredj7ms5z52usqq9ngqqqqqqqlgqqqqqqgq9qrzjq2v0v\
+ /// p62g49p7569ev48cmulecsxe59lvaw3wlxm7r982zxa9zzj7z5l0cqqxusqqyqqqqlgqqqqqzsqygarl9fh3\
+ /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
+ /// j5r6drg6k6zcqj0fcwg";
///
/// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
///
invoice.check_field_counts()?;
invoice.check_feature_bits()?;
invoice.check_signature()?;
+ invoice.check_amount()?;
Ok(invoice)
}
- /// Returns the `Invoice`'s timestamp (should equal it's creation time)
- pub fn timestamp(&self) -> &SystemTime {
+ /// Returns the `Invoice`'s timestamp (should equal its creation time)
+ #[cfg(feature = "std")]
+ pub fn timestamp(&self) -> SystemTime {
self.signed_invoice.raw_invoice().data.timestamp.as_time()
}
+ /// Returns the `Invoice`'s timestamp as a duration since the Unix epoch
+ pub fn duration_since_epoch(&self) -> Duration {
+ self.signed_invoice.raw_invoice().data.timestamp.0
+ }
+
/// Returns an iterator over all tagged fields of this Invoice.
///
/// (C-not exported) As there is not yet a manual mapping for a FilterMap
}
/// Get the payment secret if one was included in the invoice
- pub fn payment_secret(&self) -> Option<&PaymentSecret> {
- self.signed_invoice.payment_secret()
+ pub fn payment_secret(&self) -> &PaymentSecret {
+ self.signed_invoice.payment_secret().expect("was checked by constructor")
}
/// Get the invoice features if they were included in the invoice
.unwrap_or(Duration::from_secs(DEFAULT_EXPIRY_TIME))
}
+ /// Returns whether the invoice has expired.
+ #[cfg(feature = "std")]
+ pub fn is_expired(&self) -> bool {
+ Self::is_expired_from_epoch(&self.timestamp(), self.expiry_time())
+ }
+
+ /// Returns whether the expiry time from the given epoch has passed.
+ #[cfg(feature = "std")]
+ pub(crate) fn is_expired_from_epoch(epoch: &SystemTime, expiry_time: Duration) -> bool {
+ match epoch.elapsed() {
+ Ok(elapsed) => elapsed > expiry_time,
+ Err(_) => false,
+ }
+ }
+
+ /// 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 {
+ self.duration_since_epoch()
+ .checked_add(self.expiry_time())
+ .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 {
}
/// Returns a list of all routes included in the invoice
- pub fn routes(&self) -> Vec<&RouteHint> {
- self.signed_invoice.routes()
+ pub fn private_routes(&self) -> Vec<&PrivateRoute> {
+ self.signed_invoice.private_routes()
+ }
+
+ /// Returns a list of all routes included in the invoice as the underlying hints
+ pub fn route_hints(&self) -> Vec<RouteHint> {
+ find_all_extract!(
+ self.signed_invoice.known_tagged_fields(), TaggedField::PrivateRoute(ref x), x
+ ).map(|route| (**route).clone()).collect()
}
/// Returns the currency for which the invoice was issued
self.signed_invoice.currency()
}
+ /// 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>.
- pub fn amount_pico_btc(&self) -> Option<u64> {
+ fn amount_pico_btc(&self) -> Option<u64> {
self.signed_invoice.amount_pico_btc()
}
}
TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY,
TaggedField::Fallback(_) => constants::TAG_FALLBACK,
- TaggedField::Route(_) => constants::TAG_ROUTE,
+ TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
TaggedField::Features(_) => constants::TAG_FEATURES,
};
}
impl ExpiryTime {
- /// Construct an `ExpiryTime` from seconds. If there exists a `PositiveTimestamp` which would
- /// overflow on adding the `EpiryTime` to it then this function will return a
- /// `CreationError::ExpiryTimeOutOfBounds`.
- pub fn from_seconds(seconds: u64) -> Result<ExpiryTime, CreationError> {
- if seconds <= MAX_EXPIRY_TIME {
- Ok(ExpiryTime(Duration::from_secs(seconds)))
- } else {
- Err(CreationError::ExpiryTimeOutOfBounds)
- }
+ /// Construct an `ExpiryTime` from seconds.
+ pub fn from_seconds(seconds: u64) -> ExpiryTime {
+ ExpiryTime(Duration::from_secs(seconds))
}
- /// Construct an `ExpiryTime` from a `Duration`. If there exists a `PositiveTimestamp` which
- /// would overflow on adding the `EpiryTime` to it then this function will return a
- /// `CreationError::ExpiryTimeOutOfBounds`.
- pub fn from_duration(duration: Duration) -> Result<ExpiryTime, CreationError> {
- if duration.as_secs() <= MAX_EXPIRY_TIME {
- Ok(ExpiryTime(duration))
- } else {
- Err(CreationError::ExpiryTimeOutOfBounds)
- }
+ /// Construct an `ExpiryTime` from a `Duration`, dropping the sub-second part.
+ pub fn from_duration(duration: Duration) -> ExpiryTime {
+ Self::from_seconds(duration.as_secs())
}
/// Returns the expiry time in seconds
}
}
-impl RouteHint {
- /// Create a new (partial) route from a list of hops
- pub fn new(hops: Vec<RouteHintHop>) -> Result<RouteHint, CreationError> {
- if hops.len() <= 12 {
- Ok(RouteHint(hops))
+impl PrivateRoute {
+ /// Creates a new (partial) route from a list of hops
+ pub fn new(hops: RouteHint) -> Result<PrivateRoute, CreationError> {
+ if hops.0.len() <= 12 {
+ Ok(PrivateRoute(hops))
} else {
Err(CreationError::RouteTooLong)
}
}
- /// Returrn the underlying vector of hops
- pub fn into_inner(self) -> Vec<RouteHintHop> {
+ /// Returns the underlying list of hops
+ pub fn into_inner(self) -> RouteHint {
self.0
}
}
-impl Into<Vec<RouteHintHop>> for RouteHint {
- fn into(self) -> Vec<RouteHintHop> {
+impl Into<RouteHint> for PrivateRoute {
+ fn into(self) -> RouteHint {
self.into_inner()
}
}
-impl Deref for RouteHint {
- type Target = Vec<RouteHintHop>;
+impl Deref for PrivateRoute {
+ type Target = RouteHint;
- fn deref(&self) -> &Vec<RouteHintHop> {
+ fn deref(&self) -> &RouteHint {
&self.0
}
}
/// The specified route has too many hops and can't be encoded
RouteTooLong,
- /// The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`
+ /// The Unix timestamp of the supplied date is less than zero or greater than 35-bits
TimestampOutOfBounds,
- /// The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`
- ExpiryTimeOutOfBounds,
+ /// The supplied millisatoshi amount was greater than the total bitcoin supply.
+ InvalidAmount,
+
+ /// Route hints were required for this invoice and were missing. Applies to
+ /// [phantom invoices].
+ ///
+ /// [phantom invoices]: crate::utils::create_phantom_invoice
+ MissingRouteHints,
}
impl Display for CreationError {
match self {
CreationError::DescriptionTooLong => f.write_str("The supplied description string was longer than 639 bytes"),
CreationError::RouteTooLong => f.write_str("The specified route has too many hops and can't be encoded"),
- CreationError::TimestampOutOfBounds => f.write_str("The unix timestamp of the supplied date is <0 or can't be represented as `SystemTime`"),
- CreationError::ExpiryTimeOutOfBounds => f.write_str("The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`"),
+ 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"),
}
}
}
+#[cfg(feature = "std")]
impl std::error::Error for CreationError { }
/// Errors that may occur when converting a `RawInvoice` to an `Invoice`. They relate to the
/// The invoice contains multiple descriptions and/or description hashes which isn't allowed
MultipleDescriptions,
+ /// The invoice is missing the mandatory payment secret, which all modern lightning nodes
+ /// should provide.
+ NoPaymentSecret,
+
/// The invoice contains multiple payment secrets
MultiplePaymentSecrets,
/// The invoice's signature is invalid
InvalidSignature,
+
+ /// The invoice's amount was not a whole number of millisatoshis
+ ImpreciseAmount,
}
impl Display for SemanticError {
SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
+ SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
+ SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
}
}
}
+#[cfg(feature = "std")]
impl std::error::Error for SemanticError { }
/// When signing using a fallible method either an user-supplied `SignError` or a `CreationError`
/// may occur.
-///
-/// (C-not exported) As we don't support unbounded generics
#[derive(Eq, PartialEq, Debug, Clone)]
-pub enum SignOrCreationError<S> {
+pub enum SignOrCreationError<S = ()> {
/// An error occurred during signing
SignError(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!("{:?}", e)))?;
+
+ Ok(bolt11)
+ }
+}
+
#[cfg(test)]
mod test {
use bitcoin_hashes::hex::FromHex;
#[test]
fn test_system_time_bounds_assumptions() {
- ::check_platform();
-
- assert_eq!(
- ::PositiveTimestamp::from_unix_timestamp(::SYSTEM_TIME_MAX_UNIX_TIMESTAMP + 1),
- Err(::CreationError::TimestampOutOfBounds)
- );
-
- assert_eq!(
- ::ExpiryTime::from_seconds(::MAX_EXPIRY_TIME + 1),
- Err(::CreationError::ExpiryTimeOutOfBounds)
- );
+ assert_eq!(
+ 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!(Invoice::from_signed(invoice).is_ok());
+ assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
// No payment secret or feature bits
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!(Invoice::from_signed(invoice).is_ok());
+ 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::InvalidFeatures));
+ assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
// Multiple payment secrets
let invoice = {
let mut invoice = invoice_template.clone();
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())
.payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
- .current_timestamp();
+ .duration_since_epoch(Duration::from_secs(1234567));
let invoice = builder.clone()
- .amount_pico_btc(15000)
+ .amount_milli_satoshis(1500)
.build_raw()
.unwrap();
let invoice = builder.clone()
- .amount_pico_btc(1500)
+ .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())
- .current_timestamp()
+ .duration_since_epoch(Duration::from_secs(1234567))
.min_final_cltv_expiry(144);
let too_long_string = String::from_iter(
htlc_minimum_msat: None,
htlc_maximum_msat: None,
};
- let too_long_route = vec![route_hop; 13];
+ let too_long_route = RouteHint(vec![route_hop; 13]);
let long_route_res = builder.clone()
.description("Test".into())
- .route(too_long_route)
+ .private_route(too_long_route)
.build_raw();
assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
let sign_error_res = builder.clone()
.description("Test".into())
+ .payment_secret(PaymentSecret([0; 32]))
.try_build_signed(|_| {
Err("ImaginaryError")
});
#[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();
).unwrap();
let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
- let route_1 = vec![
+ let route_1 = RouteHint(vec![
RouteHintHop {
src_node_id: public_key.clone(),
short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
htlc_minimum_msat: None,
htlc_maximum_msat: None,
}
- ];
+ ]);
- let route_2 = vec![
+ let route_2 = RouteHint(vec![
RouteHintHop {
src_node_id: public_key.clone(),
short_channel_id: 0,
htlc_minimum_msat: None,
htlc_maximum_msat: None,
}
- ];
+ ]);
let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
- .amount_pico_btc(123)
- .timestamp(UNIX_EPOCH + Duration::from_secs(1234567))
+ .amount_milli_satoshis(123)
+ .duration_since_epoch(Duration::from_secs(1234567))
.payee_pub_key(public_key.clone())
.expiry_time(Duration::from_secs(54321))
.min_final_cltv_expiry(144)
.fallback(Fallback::PubKeyHash([0;20]))
- .route(route_1.clone())
- .route(route_2.clone())
+ .private_route(route_1.clone())
+ .private_route(route_2.clone())
.description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
.payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap())
.payment_secret(PaymentSecret([42; 32]))
.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.tagged_fields().count(), 10);
- assert_eq!(invoice.amount_pico_btc(), Some(123));
+ assert_eq!(invoice.amount_milli_satoshis(), Some(123));
+ assert_eq!(invoice.amount_pico_btc(), Some(1230));
assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
+ #[cfg(feature = "std")]
assert_eq!(
invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
1234567
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.routes(), vec![&RouteHint(route_1), &RouteHint(route_2)]);
+ assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
assert_eq!(
invoice.description(),
InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
);
assert_eq!(invoice.payment_hash(), &sha256::Hash::from_slice(&[21;32][..]).unwrap());
- assert_eq!(invoice.payment_secret(), Some(&PaymentSecret([42; 32])));
- assert_eq!(invoice.features(), Some(&InvoiceFeatures::known()));
+ assert_eq!(invoice.payment_secret(), &PaymentSecret([42; 32]));
+
+ 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())
.payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
- .current_timestamp()
+ .payment_secret(PaymentSecret([0; 32]))
+ .duration_since_epoch(Duration::from_secs(1234567))
.build_raw()
.unwrap()
.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.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
+ assert!(!invoice.would_expire(Duration::from_secs(1234568)));
+ }
+
+ #[test]
+ fn test_expiration() {
+ use crate::*;
+ use secp256k1::Secp256k1;
+ use secp256k1::SecretKey;
+
+ let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
+ .description("Test".into())
+ .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
+ .payment_secret(PaymentSecret([0; 32]))
+ .duration_since_epoch(Duration::from_secs(1234567))
+ .build_raw()
+ .unwrap()
+ .sign::<_, ()>(|hash| {
+ let privkey = SecretKey::from_slice(&[41; 32]).unwrap();
+ let secp_ctx = Secp256k1::new();
+ 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('\"'));
}
}