+#![deny(missing_docs)]
+#![deny(non_upper_case_globals)]
+#![deny(non_camel_case_types)]
+#![deny(non_snake_case)]
+#![deny(unused_mut)]
+
+#![cfg_attr(feature = "strict", deny(warnings))]
+
+//! This crate provides data structures to represent
+//! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/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
+
+extern crate bech32;
+extern crate bitcoin_hashes;
+extern crate num_traits;
+extern crate secp256k1;
+
+use bech32::u5;
+use bitcoin_hashes::Hash;
+use bitcoin_hashes::sha256;
+
+use secp256k1::key::PublicKey;
+use secp256k1::{Message, Secp256k1};
+use secp256k1::recovery::RecoverableSignature;
+use std::ops::Deref;
+
+use std::iter::FilterMap;
+use std::slice::Iter;
+use std::time::{SystemTime, Duration, UNIX_EPOCH};
+use std::fmt::{Display, Formatter, self};
+
+mod de;
+mod ser;
+mod tb;
+
+pub use de::{ParseError, ParseOrSemanticError};
+
+// 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;
+
+/// 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;
+
+/// 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::<SystemTime, [u8; 16]>(UNIX_EPOCH); }
+}
+
+
+/// **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.
+///
+/// If this function fails this is considered a bug. Please open an issue describing your
+/// platform and stating your current system time.
+///
+/// # 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
+ );
+}
+
+
+/// 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_invoice;
+/// extern crate bitcoin_hashes;
+///
+/// use bitcoin_hashes::Hash;
+/// use bitcoin_hashes::sha256;
+///
+/// use secp256k1::Secp256k1;
+/// use secp256k1::key::SecretKey;
+///
+/// use lightning_invoice::{Currency, InvoiceBuilder};
+///
+/// # fn main() {
+/// let private_key = SecretKey::from_slice(
+/// &[
+/// 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f,
+/// 0xe2, 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04,
+/// 0xa8, 0xca, 0x3b, 0x2d, 0xb7, 0x34
+/// ][..]
+/// ).unwrap();
+///
+/// let payment_hash = sha256::Hash::from_slice(&[0; 32][..]).unwrap();
+///
+/// let invoice = InvoiceBuilder::new(Currency::Bitcoin)
+/// .description("Coins pls!".into())
+/// .payment_hash(payment_hash)
+/// .current_timestamp()
+/// .build_signed(|hash| {
+/// Secp256k1::new().sign_recoverable(hash, &private_key)
+/// })
+/// .unwrap();
+///
+/// assert!(invoice.to_string().starts_with("lnbc1"));
+/// # }
+/// ```
+///
+/// # 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`
+/// * `T`: the timestamp is set
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool> {
+ currency: Currency,
+ amount: Option<u64>,
+ si_prefix: Option<SiPrefix>,
+ timestamp: Option<PositiveTimestamp>,
+ 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>,
+}
+
+/// 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)]
+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.
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub enum InvoiceDescription<'f> {
+ /// Reference to the directly supplied description in the invoice
+ Direct(&'f Description),
+
+ /// Reference to the description's hash included in the invoice
+ Hash(&'f Sha256),
+}
+
+/// 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)]
+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.
+ ///
+ /// * 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`
+ hash: [u8; 32],
+
+ /// signature of the payment request
+ signature: Signature,
+}
+
+/// 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.
+///
+/// For methods without docs see the corresponding methods in `Invoice`.
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct RawInvoice {
+ /// human readable part
+ pub hrp: RawHrp,
+
+ /// data part
+ pub data: RawDataPart,
+}
+
+/// Data of the `RawInvoice` that is encoded in the human readable part
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct RawHrp {
+ /// The currency deferred from the 3rd and 4th character of the bech32 transaction
+ pub currency: Currency,
+
+ /// The amount that, multiplied by the SI prefix, has to be payed
+ pub raw_amount: Option<u64>,
+
+ /// SI prefix that gets multiplied with the `raw_amount`
+ pub si_prefix: Option<SiPrefix>,
+}
+
+/// Data of the `RawInvoice` that is encoded in the data part
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct RawDataPart {
+ /// generation time of the invoice
+ pub timestamp: PositiveTimestamp,
+
+ /// tagged fields of the payment request
+ 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.
+///
+/// # 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);
+
+/// SI prefixes for the human readable part
+#[derive(Eq, PartialEq, Debug, Clone, Copy)]
+pub enum SiPrefix {
+ /// 10^-3
+ Milli,
+ /// 10^-6
+ Micro,
+ /// 10^-9
+ Nano,
+ /// 10^-12
+ Pico,
+}
+
+impl SiPrefix {
+ /// Returns the multiplier to go from a BTC value to picoBTC implied by this SiPrefix.
+ /// This is effectively 10^12 * the prefix multiplier
+ pub fn multiplier(&self) -> u64 {
+ match *self {
+ SiPrefix::Milli => 1_000_000_000,
+ SiPrefix::Micro => 1_000_000,
+ SiPrefix::Nano => 1_000,
+ SiPrefix::Pico => 1,
+ }
+ }
+
+ /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
+ /// multiplier.
+ pub fn values_desc() -> &'static [SiPrefix] {
+ use 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)]
+pub enum Currency {
+ /// Bitcoin mainnet
+ Bitcoin,
+
+ /// Bitcoin testnet
+ BitcoinTestnet,
+
+ /// Bitcoin regtest
+ Regtest,
+
+ /// Bitcoin simnet/signet
+ Simnet,
+}
+
+/// Tagged field which may have an unknown tag
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub enum RawTaggedField {
+ /// Parsed tagged field with known tag
+ KnownSemantics(TaggedField),
+ /// tagged field which was not parsed due to an unknown tag or undefined field semantics
+ UnknownSemantics(Vec<u5>),
+}
+
+/// Tagged field with known tag
+///
+/// For descriptions of the enum values please refer to the enclosed type's docs.
+#[allow(missing_docs)]
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub enum TaggedField {
+ PaymentHash(Sha256),
+ Description(Description),
+ PayeePubKey(PayeePubKey),
+ DescriptionHash(Sha256),
+ ExpiryTime(ExpiryTime),
+ MinFinalCltvExpiry(MinFinalCltvExpiry),
+ Fallback(Fallback),
+ Route(Route),
+ PaymentSecret(PaymentSecret),
+}
+
+/// SHA-256 hash
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct Sha256(pub sha256::Hash);
+
+/// Description string
+///
+/// # Invariants
+/// The description can be at most 639 __bytes__ long
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct Description(String);
+
+/// Payee public key
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct PayeePubKey(pub PublicKey);
+
+/// 256-bit payment secret
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct PaymentSecret(pub [u8; 32]);
+
+/// 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)]
+pub struct ExpiryTime(Duration);
+
+/// `min_final_cltv_expiry` to use for the last HTLC in the route
+#[derive(Eq, PartialEq, Debug, Clone)]
+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)]
+pub enum Fallback {
+ SegWitProgram {
+ version: u5,
+ program: Vec<u8>,
+ },
+ PubKeyHash([u8; 20]),
+ ScriptHash([u8; 20]),
+}
+
+/// Recoverable signature
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct Signature(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 Route(Vec<RouteHop>);
+
+/// Node on a private route
+#[derive(Eq, PartialEq, Debug, Clone)]
+pub struct RouteHop {
+ /// Node's public key
+ pub pubkey: PublicKey,
+
+ /// Which channel of this node we would be using
+ pub short_channel_id: [u8; 8],
+
+ /// Fee charged by this node per transaction
+ pub fee_base_msat: u32,
+
+ /// Fee charged by this node proportional to the amount routed
+ pub fee_proportional_millionths: u32,
+
+ /// Delta substracted by this node from incoming cltv_expiry value
+ pub cltv_expiry_delta: u16,
+}
+
+/// Tag constants as specified in BOLT11
+#[allow(missing_docs)]
+pub mod constants {
+ pub const TAG_PAYMENT_HASH: u8 = 1;
+ pub const TAG_DESCRIPTION: u8 = 13;
+ 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_FALLBACK: u8 = 9;
+ pub const TAG_ROUTE: u8 = 3;
+ pub const TAG_PAYMENT_SECRET: u8 = 16;
+}
+
+impl InvoiceBuilder<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 {
+ InvoiceBuilder {
+ currency: currrency,
+ amount: None,
+ si_prefix: None,
+ timestamp: None,
+ tagged_fields: Vec::new(),
+ error: None,
+
+ phantom_d: std::marker::PhantomData,
+ phantom_h: std::marker::PhantomData,
+ phantom_t: std::marker::PhantomData,
+ }
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool> InvoiceBuilder<D, H, T> {
+ /// Helper function to set the completeness flags.
+ fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN> {
+ InvoiceBuilder::<DN, HN, TN> {
+ currency: self.currency,
+ amount: self.amount,
+ si_prefix: self.si_prefix,
+ timestamp: self.timestamp,
+ tagged_fields: self.tagged_fields,
+ error: self.error,
+
+ phantom_d: std::marker::PhantomData,
+ phantom_h: std::marker::PhantomData,
+ phantom_t: std::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 {
+ let biggest_possible_si_prefix = SiPrefix::values_desc()
+ .iter()
+ .find(|prefix| amount % prefix.multiplier() == 0)
+ .expect("Pico should always match");
+ self.amount = Some(amount / biggest_possible_si_prefix.multiplier());
+ self.si_prefix = Some(*biggest_possible_si_prefix);
+ self
+ }
+
+ /// Sets the payee's public key.
+ pub fn payee_pub_key(mut self, pub_key: PublicKey) -> Self {
+ self.tagged_fields.push(TaggedField::PayeePubKey(PayeePubKey(pub_key)));
+ self
+ }
+
+ /// Sets the payment secret
+ pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> Self {
+ self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
+ self
+ }
+
+ /// Sets the expiry time
+ 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
+ }
+
+ /// Sets `min_final_cltv_expiry`.
+ pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> Self {
+ self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
+ self
+ }
+
+ /// Adds a fallback address.
+ pub fn fallback(mut self, fallback: Fallback) -> Self {
+ self.tagged_fields.push(TaggedField::Fallback(fallback));
+ self
+ }
+
+ /// Adds a private route.
+ pub fn route(mut self, route: Vec<RouteHop>) -> Self {
+ match Route::new(route) {
+ Ok(r) => self.tagged_fields.push(TaggedField::Route(r)),
+ Err(e) => self.error = Some(e),
+ }
+ self
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool> InvoiceBuilder<D, H, tb::True> {
+ /// 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
+ if let Some(e) = self.error {
+ return Err(e);
+ }
+
+ let hrp = RawHrp {
+ currency: self.currency,
+ raw_amount: self.amount,
+ si_prefix: self.si_prefix,
+ };
+
+ let timestamp = self.timestamp.expect("ensured to be Some(t) by type T");
+
+ let tagged_fields = self.tagged_fields.into_iter().map(|tf| {
+ RawTaggedField::KnownSemantics(tf)
+ }).collect::<Vec<_>>();
+
+ let data = RawDataPart {
+ timestamp: timestamp,
+ tagged_fields: tagged_fields,
+ };
+
+ Ok(RawInvoice {
+ hrp: hrp,
+ data: data,
+ })
+ }
+}
+
+impl<H: tb::Bool, T: tb::Bool> InvoiceBuilder<tb::False, H, T> {
+ /// 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> {
+ match Description::new(description) {
+ Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
+ Err(e) => self.error = Some(e),
+ }
+ self.set_flags()
+ }
+
+ /// 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> {
+ self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
+ self.set_flags()
+ }
+}
+
+impl<D: tb::Bool, T: tb::Bool> InvoiceBuilder<D, tb::False, T> {
+ /// 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> {
+ self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
+ self.set_flags()
+ }
+}
+
+impl<D: tb::Bool, H: tb::Bool> InvoiceBuilder<D, H, tb::False> {
+ /// Sets the timestamp.
+ pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True> {
+ 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 the current UNIX timestamp.
+ pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True> {
+ 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 InvoiceBuilder<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.
+ pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
+ where F: FnOnce(&Message) -> RecoverableSignature
+ {
+ let invoice = self.try_build_signed::<_, ()>(|hash| {
+ Ok(sign_function(hash))
+ });
+
+ match invoice {
+ Ok(i) => Ok(i),
+ Err(SignOrCreationError::CreationError(e)) => Err(e),
+ Err(SignOrCreationError::SignError(())) => unreachable!(),
+ }
+ }
+
+ /// Builds and signs an invoice using the supplied `sign_function`. This function MAY fail with
+ /// an error of type `E` and MUST produce a recoverable signature valid for the given hash and
+ /// if applicable also for the included payee public key.
+ pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Invoice, SignOrCreationError<E>>
+ where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
+ {
+ let raw = match self.build_raw() {
+ Ok(r) => r,
+ Err(e) => return Err(SignOrCreationError::CreationError(e)),
+ };
+
+ let signed = match raw.sign(sign_function) {
+ Ok(s) => s,
+ Err(e) => return Err(SignOrCreationError::SignError(e)),
+ };
+
+ let invoice = Invoice {
+ signed_invoice: signed,
+ };
+
+ invoice.check_field_counts().expect("should be ensured by type signature of builder");
+
+ Ok(invoice)
+ }
+}
+
+
+impl SignedRawInvoice {
+ /// Disassembles the `SignedRawInvoice` into its three parts:
+ /// 1. raw invoice
+ /// 2. hash of the raw invoice
+ /// 3. signature
+ pub fn into_parts(self) -> (RawInvoice, [u8; 32], Signature) {
+ (self.raw_invoice, self.hash, self.signature)
+ }
+
+ /// 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] {
+ &self.hash
+ }
+
+ /// Signature for the invoice.
+ pub fn signature(&self) -> &Signature {
+ &self.signature
+ }
+
+ /// Recovers the public key used for signing the invoice from the recoverable signature.
+ pub fn recover_payee_pub_key(&self) -> Result<PayeePubKey, secp256k1::Error> {
+ let hash = Message::from_slice(&self.hash[..])
+ .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
+
+ Ok(PayeePubKey(Secp256k1::new().recover(
+ &hash,
+ &self.signature
+ )?))
+ }
+
+ /// Checks if the signature is valid for the included payee public key or if none exists if it's
+ /// valid for the recovered signature (which should always be true?).
+ pub fn check_signature(&self) -> bool {
+ let included_pub_key = self.raw_invoice.payee_pub_key();
+
+ let mut recovered_pub_key = Option::None;
+ if recovered_pub_key.is_none() {
+ let recovered = match self.recover_payee_pub_key() {
+ Ok(pk) => pk,
+ Err(_) => return false,
+ };
+ recovered_pub_key = Some(recovered);
+ }
+
+ let pub_key = included_pub_key.or_else(|| 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(
+ &hash,
+ &self.signature.to_standard(),
+ pub_key
+ );
+
+ match verification_result {
+ Ok(()) => true,
+ Err(_) => false,
+ }
+ }
+}
+
+/// 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::*
+///
+/// enum Enum {
+/// A(u8),
+/// B(u16)
+/// }
+///
+/// let elements = vec![A(1), A(2), B(3), A(4)]
+///
+/// assert_eq!(find_extract!(elements.iter(), Enum::B(ref x), x), Some(3u16))
+/// ```
+macro_rules! find_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 {
+ /// Hash the HRP as bytes and signatureless data part.
+ fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
+ 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."));
+
+ 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] {
+ use bech32::ToBase32;
+
+ RawInvoice::hash_from_parts(
+ self.hrp.to_string().as_bytes(),
+ &self.data.to_base32()
+ )
+ }
+
+ /// 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
+ /// are no constraints regarding the validity of the produced signature.
+ 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 hash = Message::from_slice(&raw_hash[..])
+ .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
+ let signature = sign_method(&hash)?;
+
+ Ok(SignedRawInvoice {
+ raw_invoice: self,
+ hash: raw_hash,
+ signature: Signature(signature),
+ })
+ }
+
+ /// Returns an iterator over all tagged fields with known semantics.
+ pub fn known_tagged_fields(&self)
+ -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
+ {
+ // For 1.14.0 compatibility: closures' types can't be written an fn()->() in the
+ // function's type signature.
+ // TODO: refactor once impl Trait is available
+ fn match_raw(raw: &RawTaggedField) -> Option<&TaggedField> {
+ match *raw {
+ RawTaggedField::KnownSemantics(ref tf) => Some(tf),
+ _ => None,
+ }
+ }
+
+ self.data.tagged_fields.iter().filter_map(match_raw )
+ }
+
+ pub fn payment_hash(&self) -> Option<&Sha256> {
+ find_extract!(self.known_tagged_fields(), TaggedField::PaymentHash(ref x), x)
+ }
+
+ pub fn description(&self) -> Option<&Description> {
+ find_extract!(self.known_tagged_fields(), TaggedField::Description(ref x), x)
+ }
+
+ pub fn payee_pub_key(&self) -> Option<&PayeePubKey> {
+ find_extract!(self.known_tagged_fields(), TaggedField::PayeePubKey(ref x), x)
+ }
+
+ pub fn description_hash(&self) -> Option<&Sha256> {
+ find_extract!(self.known_tagged_fields(), TaggedField::DescriptionHash(ref x), x)
+ }
+
+ pub fn expiry_time(&self) -> Option<&ExpiryTime> {
+ 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 payment_secret(&self) -> Option<&PaymentSecret> {
+ find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
+ }
+
+ 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>>()
+ }
+
+ pub fn routes(&self) -> Vec<&Route> {
+ self.known_tagged_fields().filter_map(|tf| match tf {
+ &TaggedField::Route(ref r) => Some(r),
+ _ => None,
+ }).collect::<Vec<&Route>>()
+ }
+
+ pub fn amount_pico_btc(&self) -> Option<u64> {
+ self.hrp.raw_amount.map(|v| {
+ v * self.hrp.si_prefix.as_ref().map_or(1_000_000_000_000, |si| { si.multiplier() })
+ })
+ }
+
+ pub fn currency(&self) -> Currency {
+ self.hrp.currency.clone()
+ }
+}
+
+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`.
+ 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)
+ } else {
+ Ok(PositiveTimestamp(UNIX_EPOCH + Duration::from_secs(unix_seconds)))
+ }
+ }
+
+ /// 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`.
+ 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)
+ }
+ }
+
+ /// 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()
+ }
+
+ /// Returns a reference to the internal `SystemTime` time representation
+ pub fn as_time(&self) -> &SystemTime {
+ &self.0
+ }
+}
+
+impl Into<SystemTime> for PositiveTimestamp {
+ fn into(self) -> SystemTime {
+ self.0
+ }
+}
+
+impl Deref for PositiveTimestamp {
+ type Target = SystemTime;
+
+ fn deref(&self) -> &Self::Target {
+ &self.0
+ }
+}
+
+impl Invoice {
+ /// Transform the `Invoice` into it's unchecked version
+ pub fn into_signed_raw(self) -> SignedRawInvoice {
+ self.signed_invoice
+ }
+
+ /// Check that all mandatory fields are present
+ fn check_field_counts(&self) -> Result<(), SemanticError> {
+ // "A writer MUST include exactly one p field […]."
+ let payment_hash_cnt = self.tagged_fields().filter(|&tf| match *tf {
+ TaggedField::PaymentHash(_) => true,
+ _ => false,
+ }).count();
+ if payment_hash_cnt < 1 {
+ return Err(SemanticError::NoPaymentHash);
+ } else if payment_hash_cnt > 1 {
+ return Err(SemanticError::MultiplePaymentHashes);
+ }
+
+ // "A writer MUST include either exactly one d or exactly one h field."
+ let description_cnt = self.tagged_fields().filter(|&tf| match *tf {
+ TaggedField::Description(_) | TaggedField::DescriptionHash(_) => true,
+ _ => false,
+ }).count();
+ if description_cnt < 1 {
+ return Err(SemanticError::NoDescription);
+ } else if description_cnt > 1 {
+ return Err(SemanticError::MultipleDescriptions);
+ }
+
+ Ok(())
+ }
+
+ /// Check that the invoice is signed correctly and that key recovery works
+ pub fn check_signature(&self) -> Result<(), SemanticError> {
+ match self.signed_invoice.recover_payee_pub_key() {
+ Err(secp256k1::Error::InvalidRecoveryId) =>
+ return Err(SemanticError::InvalidRecoveryId),
+ Err(_) => panic!("no other error may occur"),
+ Ok(_) => {},
+ }
+
+ if !self.signed_invoice.check_signature() {
+ return Err(SemanticError::InvalidSignature);
+ }
+
+ Ok(())
+ }
+
+ /// Constructs an `Invoice` from a `SignedInvoice` by checking all its invariants.
+ /// ```
+ /// use lightning_invoice::*;
+ ///
+ /// let invoice = "lnbc1pvjluezpp5qqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqqqsyqcyq5rqwzqfqypqdp\
+ /// l2pkx2ctnv5sxxmmwwd5kgetjypeh2ursdae8g6twvus8g6rfwvs8qun0dfjkxaq8rkx3yf5tcsyz3d7\
+ /// 3gafnh3cax9rn449d9p5uxz9ezhhypd0elx87sjle52x86fux2ypatgddc6k63n7erqz25le42c4u4ec\
+ /// ky03ylcqca784w";
+ ///
+ /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
+ ///
+ /// assert!(Invoice::from_signed(signed).is_ok());
+ /// ```
+ pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
+ let invoice = Invoice {
+ signed_invoice: signed_invoice,
+ };
+ invoice.check_field_counts()?;
+ invoice.check_signature()?;
+
+ Ok(invoice)
+ }
+
+ /// Returns the `Invoice`'s timestamp (should equal it's creation time)
+ pub fn timestamp(&self) -> &SystemTime {
+ self.signed_invoice.raw_invoice().data.timestamp.as_time()
+ }
+
+ /// Returns an iterator over all tagged fields of this Invoice.
+ pub fn tagged_fields(&self)
+ -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
+ self.signed_invoice.raw_invoice().known_tagged_fields()
+ }
+
+ /// Returns the hash to which we will receive the preimage on completion of the payment
+ pub fn payment_hash(&self) -> &sha256::Hash {
+ &self.signed_invoice.payment_hash().expect("checked by constructor").0
+ }
+
+ /// Return the description or a hash of it for longer ones
+ pub fn description(&self) -> InvoiceDescription {
+ if let Some(ref direct) = self.signed_invoice.description() {
+ return InvoiceDescription::Direct(direct);
+ } else if let Some(ref hash) = self.signed_invoice.description_hash() {
+ return InvoiceDescription::Hash(hash);
+ }
+ unreachable!("ensured by constructor");
+ }
+
+ /// Get the payee's public key if one was included in the invoice
+ pub fn payee_pub_key(&self) -> Option<&PublicKey> {
+ self.signed_invoice.payee_pub_key().map(|x| &x.0)
+ }
+
+ /// Get the payment secret if one was included in the invoice
+ pub fn payment_secret(&self) -> Option<&PaymentSecret> {
+ self.signed_invoice.payment_secret()
+ }
+
+ /// Recover the payee's public key (only to be used if none was included in the invoice)
+ pub fn recover_payee_pub_key(&self) -> PublicKey {
+ self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
+ }
+
+ /// Returns the invoice's expiry time if present
+ pub fn expiry_time(&self) -> Duration {
+ self.signed_invoice.expiry_time()
+ .map(|x| x.0)
+ .unwrap_or(Duration::from_secs(3600))
+ }
+
+ /// Returns the invoice's `min_cltv_expiry` time if present
+ pub fn min_final_cltv_expiry(&self) -> Option<&u64> {
+ self.signed_invoice.min_final_cltv_expiry().map(|x| &x.0)
+ }
+
+ /// Returns a list of all fallback addresses
+ pub fn fallbacks(&self) -> Vec<&Fallback> {
+ self.signed_invoice.fallbacks()
+ }
+
+ /// Returns a list of all routes included in the invoice
+ pub fn routes(&self) -> Vec<&Route> {
+ self.signed_invoice.routes()
+ }
+
+ /// Returns the currency for which the invoice was issued
+ pub fn currency(&self) -> Currency {
+ self.signed_invoice.currency()
+ }
+
+ /// Returns the amount if specified in the invoice as pico <currency>.
+ pub fn amount_pico_btc(&self) -> Option<u64> {
+ self.signed_invoice.amount_pico_btc()
+ }
+}
+
+impl From<TaggedField> for RawTaggedField {
+ fn from(tf: TaggedField) -> Self {
+ RawTaggedField::KnownSemantics(tf)
+ }
+}
+
+impl TaggedField {
+ /// Numeric representation of the field's tag
+ pub fn tag(&self) -> u5 {
+ let tag = match *self {
+ TaggedField::PaymentHash(_) => constants::TAG_PAYMENT_HASH,
+ TaggedField::Description(_) => constants::TAG_DESCRIPTION,
+ 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::Fallback(_) => constants::TAG_FALLBACK,
+ TaggedField::Route(_) => constants::TAG_ROUTE,
+ TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
+ };
+
+ u5::try_from_u8(tag).expect("all tags defined are <32")
+ }
+}
+
+impl Description {
+
+ /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
+ /// 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> {
+ if description.len() > 639 {
+ Err(CreationError::DescriptionTooLong)
+ } else {
+ Ok(Description(description))
+ }
+ }
+
+ /// 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 Deref for Description {
+ type Target = str;
+
+ fn deref(&self) -> &str {
+ &self.0
+ }
+}
+
+impl From<PublicKey> for PayeePubKey {
+ fn from(pk: PublicKey) -> Self {
+ PayeePubKey(pk)
+ }
+}
+
+impl Deref for PayeePubKey {
+ type Target = PublicKey;
+
+ fn deref(&self) -> &PublicKey {
+ &self.0
+ }
+}
+
+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 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)
+ }
+ }
+
+ /// Returns the expiry time in seconds
+ pub fn as_seconds(&self) -> u64 {
+ self.0.as_secs()
+ }
+
+ /// Returns a reference to the underlying `Duration` (=expiry time)
+ pub fn as_duration(&self) -> &Duration {
+ &self.0
+ }
+}
+
+impl Route {
+ /// Create a new (partial) route from a list of hops
+ pub fn new(hops: Vec<RouteHop>) -> Result<Route, CreationError> {
+ if hops.len() <= 12 {
+ Ok(Route(hops))
+ } else {
+ Err(CreationError::RouteTooLong)
+ }
+ }
+
+ /// Returrn the underlying vector of hops
+ pub fn into_inner(self) -> Vec<RouteHop> {
+ self.0
+ }
+}
+
+impl Into<Vec<RouteHop>> for Route {
+ fn into(self) -> Vec<RouteHop> {
+ self.into_inner()
+ }
+}
+
+impl Deref for Route {
+ type Target = Vec<RouteHop>;
+
+ fn deref(&self) -> &Vec<RouteHop> {
+ &self.0
+ }
+}
+
+impl Deref for Signature {
+ type Target = RecoverableSignature;
+
+ fn deref(&self) -> &RecoverableSignature {
+ &self.0
+ }
+}
+
+impl Deref for SignedRawInvoice {
+ type Target = RawInvoice;
+
+ fn deref(&self) -> &RawInvoice {
+ &self.raw_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))
+ DescriptionTooLong,
+
+ /// 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`
+ TimestampOutOfBounds,
+
+ /// The supplied expiry time could cause an overflow if added to a `PositiveTimestamp`
+ ExpiryTimeOutOfBounds,
+}
+
+impl Display for CreationError {
+ fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+ 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`"),
+ }
+ }
+}
+
+impl std::error::Error for CreationError { }
+
+/// 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 {
+ /// The invoice is missing the mandatory payment hash
+ NoPaymentHash,
+
+ /// The invoice has multiple payment hashes which isn't allowed
+ MultiplePaymentHashes,
+
+ /// No description or description hash are part of the invoice
+ NoDescription,
+
+ /// The invoice contains multiple descriptions and/or description hashes which isn't allowed
+ MultipleDescriptions,
+
+ /// The recovery id doesn't fit the signature/pub key
+ InvalidRecoveryId,
+
+ /// The invoice's signature is invalid
+ InvalidSignature,
+}
+
+impl Display for SemanticError {
+ fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+ match self {
+ SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
+ 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::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"),
+ }
+ }
+}
+
+impl std::error::Error for SemanticError { }
+
+/// 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> {
+ /// An error occurred during signing
+ SignError(S),
+
+ /// An error occurred while building the transaction
+ CreationError(CreationError),
+}
+
+impl<S> Display for SignOrCreationError<S> {
+ fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+ match self {
+ SignOrCreationError::SignError(_) => f.write_str("An error occurred during signing"),
+ SignOrCreationError::CreationError(err) => err.fmt(f),
+ }
+ }
+}
+
+#[cfg(test)]
+mod test {
+ use bitcoin_hashes::hex::FromHex;
+ use bitcoin_hashes::sha256;
+
+ #[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)
+ );
+ }
+
+ #[test]
+ fn test_calc_invoice_hash() {
+ use ::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
+ use ::TaggedField::*;
+
+ let invoice = RawInvoice {
+ hrp: RawHrp {
+ currency: Currency::Bitcoin,
+ raw_amount: None,
+ si_prefix: None,
+ },
+ data: RawDataPart {
+ timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
+ tagged_fields: vec![
+ PaymentHash(::Sha256(sha256::Hash::from_hex(
+ "0001020304050607080900010203040506070809000102030405060708090102"
+ ).unwrap())).into(),
+ Description(::Description::new(
+ "Please consider supporting this project".to_owned()
+ ).unwrap()).into(),
+ ],
+ },
+ };
+
+ let expected_hash = [
+ 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27, 0x7b, 0x1d,
+ 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7, 0x83, 0x5d, 0xb2, 0xec,
+ 0xd5, 0x18, 0xe1, 0xc9
+ ];
+
+ assert_eq!(invoice.hash(), expected_hash)
+ }
+
+ #[test]
+ fn test_check_signature() {
+ use TaggedField::*;
+ use secp256k1::Secp256k1;
+ use secp256k1::recovery::{RecoveryId, RecoverableSignature};
+ use secp256k1::key::{SecretKey, PublicKey};
+ use {SignedRawInvoice, Signature, RawInvoice, RawHrp, RawDataPart, Currency, Sha256,
+ PositiveTimestamp};
+
+ let invoice = SignedRawInvoice {
+ raw_invoice: RawInvoice {
+ hrp: RawHrp {
+ currency: Currency::Bitcoin,
+ raw_amount: None,
+ si_prefix: None,
+ },
+ data: RawDataPart {
+ timestamp: PositiveTimestamp::from_unix_timestamp(1496314658).unwrap(),
+ tagged_fields: vec ! [
+ PaymentHash(Sha256(sha256::Hash::from_hex(
+ "0001020304050607080900010203040506070809000102030405060708090102"
+ ).unwrap())).into(),
+ Description(
+ ::Description::new(
+ "Please consider supporting this project".to_owned()
+ ).unwrap()
+ ).into(),
+ ],
+ },
+ },
+ hash: [
+ 0xc3, 0xd4, 0xe8, 0x3f, 0x64, 0x6f, 0xa7, 0x9a, 0x39, 0x3d, 0x75, 0x27,
+ 0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
+ 0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
+ ],
+ signature: Signature(RecoverableSignature::from_compact(
+ & [
+ 0x38u8, 0xec, 0x68, 0x91, 0x34, 0x5e, 0x20, 0x41, 0x45, 0xbe, 0x8a,
+ 0x3a, 0x99, 0xde, 0x38, 0xe9, 0x8a, 0x39, 0xd6, 0xa5, 0x69, 0x43,
+ 0x4e, 0x18, 0x45, 0xc8, 0xaf, 0x72, 0x05, 0xaf, 0xcf, 0xcc, 0x7f,
+ 0x42, 0x5f, 0xcd, 0x14, 0x63, 0xe9, 0x3c, 0x32, 0x88, 0x1e, 0xad,
+ 0x0d, 0x6e, 0x35, 0x6d, 0x46, 0x7e, 0xc8, 0xc0, 0x25, 0x53, 0xf9,
+ 0xaa, 0xb1, 0x5e, 0x57, 0x38, 0xb1, 0x1f, 0x12, 0x7f
+ ],
+ RecoveryId::from_i32(0).unwrap()
+ ).unwrap()),
+ };
+
+ assert!(invoice.check_signature());
+
+ let private_key = SecretKey::from_slice(
+ &[
+ 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
+ 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
+ 0x3b, 0x2d, 0xb7, 0x34
+ ][..]
+ ).unwrap();
+ let public_key = PublicKey::from_secret_key(&Secp256k1::new(), &private_key);
+
+ assert_eq!(invoice.recover_payee_pub_key(), Ok(::PayeePubKey(public_key)));
+
+ let (raw_invoice, _, _) = invoice.into_parts();
+ let new_signed = raw_invoice.sign::<_, ()>(|hash| {
+ Ok(Secp256k1::new().sign_recoverable(hash, &private_key))
+ }).unwrap();
+
+ assert!(new_signed.check_signature());
+ }
+
+ #[test]
+ fn test_builder_amount() {
+ use ::*;
+
+ let builder = InvoiceBuilder::new(Currency::Bitcoin)
+ .description("Test".into())
+ .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
+ .current_timestamp();
+
+ let invoice = builder.clone()
+ .amount_pico_btc(15000)
+ .build_raw()
+ .unwrap();
+
+ assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Nano));
+ assert_eq!(invoice.hrp.raw_amount, Some(15));
+
+
+ let invoice = builder.clone()
+ .amount_pico_btc(1500)
+ .build_raw()
+ .unwrap();
+
+ assert_eq!(invoice.hrp.si_prefix, Some(SiPrefix::Pico));
+ assert_eq!(invoice.hrp.raw_amount, Some(1500));
+ }
+
+ #[test]
+ fn test_builder_fail() {
+ use ::*;
+ use std::iter::FromIterator;
+ use secp256k1::key::PublicKey;
+
+ let builder = InvoiceBuilder::new(Currency::Bitcoin)
+ .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
+ .current_timestamp();
+
+ let too_long_string = String::from_iter(
+ (0..1024).map(|_| '?')
+ );
+
+ let long_desc_res = builder.clone()
+ .description(too_long_string)
+ .build_raw();
+ assert_eq!(long_desc_res, Err(CreationError::DescriptionTooLong));
+
+ let route_hop = RouteHop {
+ pubkey: PublicKey::from_slice(
+ &[
+ 0x03, 0x9e, 0x03, 0xa9, 0x01, 0xb8, 0x55, 0x34, 0xff, 0x1e, 0x92, 0xc4,
+ 0x3c, 0x74, 0x43, 0x1f, 0x7c, 0xe7, 0x20, 0x46, 0x06, 0x0f, 0xcf, 0x7a,
+ 0x95, 0xc3, 0x7e, 0x14, 0x8f, 0x78, 0xc7, 0x72, 0x55
+ ][..]
+ ).unwrap(),
+ short_channel_id: [0; 8],
+ fee_base_msat: 0,
+ fee_proportional_millionths: 0,
+ cltv_expiry_delta: 0,
+ };
+ let too_long_route = vec![route_hop; 13];
+ let long_route_res = builder.clone()
+ .description("Test".into())
+ .route(too_long_route)
+ .build_raw();
+ assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
+
+ let sign_error_res = builder.clone()
+ .description("Test".into())
+ .try_build_signed(|_| {
+ Err("ImaginaryError")
+ });
+ assert_eq!(sign_error_res, Err(SignOrCreationError::SignError("ImaginaryError")));
+ }
+
+ #[test]
+ fn test_builder_ok() {
+ use ::*;
+ use secp256k1::Secp256k1;
+ use secp256k1::key::{SecretKey, PublicKey};
+ use std::time::{UNIX_EPOCH, Duration};
+
+ let secp_ctx = Secp256k1::new();
+
+ let private_key = SecretKey::from_slice(
+ &[
+ 0xe1, 0x26, 0xf6, 0x8f, 0x7e, 0xaf, 0xcc, 0x8b, 0x74, 0xf5, 0x4d, 0x26, 0x9f, 0xe2,
+ 0x06, 0xbe, 0x71, 0x50, 0x00, 0xf9, 0x4d, 0xac, 0x06, 0x7d, 0x1c, 0x04, 0xa8, 0xca,
+ 0x3b, 0x2d, 0xb7, 0x34
+ ][..]
+ ).unwrap();
+ let public_key = PublicKey::from_secret_key(&secp_ctx, &private_key);
+
+ let route_1 = vec![
+ RouteHop {
+ pubkey: public_key.clone(),
+ short_channel_id: [123; 8],
+ fee_base_msat: 2,
+ fee_proportional_millionths: 1,
+ cltv_expiry_delta: 145,
+ },
+ RouteHop {
+ pubkey: public_key.clone(),
+ short_channel_id: [42; 8],
+ fee_base_msat: 3,
+ fee_proportional_millionths: 2,
+ cltv_expiry_delta: 146,
+ }
+ ];
+
+ let route_2 = vec![
+ RouteHop {
+ pubkey: public_key.clone(),
+ short_channel_id: [0; 8],
+ fee_base_msat: 4,
+ fee_proportional_millionths: 3,
+ cltv_expiry_delta: 147,
+ },
+ RouteHop {
+ pubkey: public_key.clone(),
+ short_channel_id: [1; 8],
+ fee_base_msat: 5,
+ fee_proportional_millionths: 4,
+ cltv_expiry_delta: 148,
+ }
+ ];
+
+ let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
+ .amount_pico_btc(123)
+ .timestamp(UNIX_EPOCH + Duration::from_secs(1234567))
+ .payee_pub_key(public_key.clone())
+ .expiry_time(Duration::from_secs(54321))
+ .min_final_cltv_expiry(144)
+ .min_final_cltv_expiry(143)
+ .fallback(Fallback::PubKeyHash([0;20]))
+ .route(route_1.clone())
+ .route(route_2.clone())
+ .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
+ .payment_hash(sha256::Hash::from_slice(&[21;32][..]).unwrap());
+
+ let invoice = builder.clone().build_signed(|hash| {
+ secp_ctx.sign_recoverable(hash, &private_key)
+ }).unwrap();
+
+ assert!(invoice.check_signature().is_ok());
+ assert_eq!(invoice.tagged_fields().count(), 9);
+
+ assert_eq!(invoice.amount_pico_btc(), Some(123));
+ assert_eq!(invoice.currency(), Currency::BitcoinTestnet);
+ assert_eq!(
+ invoice.timestamp().duration_since(UNIX_EPOCH).unwrap().as_secs(),
+ 1234567
+ );
+ 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(), Some(&144));
+ assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
+ assert_eq!(invoice.routes(), vec![&Route(route_1), &Route(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());
+
+ let raw_invoice = builder.build_raw().unwrap();
+ assert_eq!(raw_invoice, *invoice.into_signed_raw().raw_invoice())
+ }
+}