Clean up at least some lifetimes on `SimpleRefPeerManager`
[rust-lightning] / lightning-invoice / src / lib.rs
index 1dd7123a486d1077f1295b7655b1fac497cfb57f..9695d79036ecc6a776e9ab10e340f0a94a7463d1 100644 (file)
@@ -1,9 +1,12 @@
+// Prefix these with `rustdoc::` when we update our MSRV to be >= 1.52 to remove warnings.
+#![deny(broken_intra_doc_links)]
+#![deny(private_intra_doc_links)]
+
 #![deny(missing_docs)]
 #![deny(non_upper_case_globals)]
 #![deny(non_camel_case_types)]
 #![deny(non_snake_case)]
 #![deny(unused_mut)]
-#![deny(broken_intra_doc_links)]
 
 #![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 #![cfg_attr(all(not(feature = "std"), not(test)), no_std)]
 
 //! This crate provides data structures to represent
-//! [lightning BOLT11](https://github.com/lightningnetwork/lightning-rfc/blob/master/11-payment-encoding.md)
+//! [lightning BOLT11](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md)
 //! invoices and functions to create, encode and decode these. If you just want to use the standard
 //! en-/decoding functionality this should get you started:
 //!
-//!   * For parsing use `str::parse::<Invoice>(&self)` (see the docs of `impl FromStr for Invoice`)
-//!   * For constructing invoices use the `InvoiceBuilder`
-//!   * For serializing invoices use the `Display`/`ToString` traits
+//!   * For parsing use `str::parse::<Bolt11Invoice>(&self)` (see [`Bolt11Invoice::from_str`])
+//!   * For constructing invoices use the [`InvoiceBuilder`]
+//!   * For serializing invoices use the [`Display`]/[`ToString`] traits
+//!
+//! [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
 
 #[cfg(not(any(feature = "std", feature = "no-std")))]
 compile_error!("at least one of the `std` or `no-std` features must be enabled");
@@ -33,29 +38,41 @@ 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 bitcoin_hashes::sha256;
-use lightning::ln::PaymentSecret;
-use lightning::ln::features::InvoiceFeatures;
-#[cfg(any(doc, test))]
-use lightning::routing::network_graph::RoutingFees;
-use lightning::routing::router::RouteHint;
+use bitcoin::{Address, Network, PubkeyHash, ScriptHash};
+use bitcoin::util::address::{Payload, WitnessVersion};
+use bitcoin_hashes::{Hash, sha256};
+use lightning::ln::features::Bolt11InvoiceFeatures;
 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::cmp::Ordering;
 use core::fmt::{Display, Formatter, self};
 use core::iter::FilterMap;
+use core::num::ParseIntError;
 use core::ops::Deref;
 use core::slice::Iter;
 use core::time::Duration;
+use core::str;
+
+#[cfg(feature = "serde")]
+use serde::{Deserialize, Deserializer,Serialize, Serializer, de::Error};
+
+#[doc(no_inline)]
+pub use lightning::ln::PaymentSecret;
+#[doc(no_inline)]
+pub use lightning::routing::router::{RouteHint, RouteHintHop};
+#[doc(no_inline)]
+pub use lightning::routing::gossip::RoutingFees;
 
 mod de;
 mod ser;
@@ -74,7 +91,7 @@ mod prelude {
        pub use alloc::string::ToString;
 }
 
-use prelude::*;
+use crate::prelude::*;
 
 /// Sync compat for std/no_std
 #[cfg(feature = "std")]
@@ -86,7 +103,45 @@ mod sync {
 #[cfg(not(feature = "std"))]
 mod sync;
 
-pub use de::{ParseError, ParseOrSemanticError};
+/// Errors that indicate what is wrong with the invoice. They have some granularity for debug
+/// reasons, but should generally result in an "invalid BOLT11 invoice" message for the user.
+#[allow(missing_docs)]
+#[derive(PartialEq, Eq, Debug, Clone)]
+pub enum Bolt11ParseError {
+       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(Bolt11ParseError),
+
+       /// The invoice could be decoded but violates the BOLT11 standard
+       SemanticError(crate::Bolt11SemanticError),
+}
 
 /// The number of bits used to represent timestamps as defined in BOLT 11.
 const TIMESTAMP_BITS: usize = 35;
@@ -104,14 +159,14 @@ 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`].
+/// provided in [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
 ///
 /// [BOLT 11]: https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
-/// [`MIN_FINAL_CLTV_EXPIRY`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY
-pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
+/// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
+pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18;
 
-/// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures
-/// that only a semantically and syntactically correct Invoice can be built using it.
+/// Builder for [`Bolt11Invoice`]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;
@@ -123,7 +178,7 @@ pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
 /// use bitcoin_hashes::sha256;
 ///
 /// use secp256k1::Secp256k1;
-/// use secp256k1::key::SecretKey;
+/// use secp256k1::SecretKey;
 ///
 /// use lightning::ln::PaymentSecret;
 ///
@@ -149,9 +204,9 @@ pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
 ///    .payment_hash(payment_hash)
 ///    .payment_secret(payment_secret)
 ///    .current_timestamp()
-///    .min_final_cltv_expiry(144)
+///    .min_final_cltv_expiry_delta(144)
 ///    .build_signed(|hash| {
-///            Secp256k1::new().sign_recoverable(hash, &private_key)
+///            Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)
 ///    })
 ///    .unwrap();
 ///
@@ -162,13 +217,16 @@ pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY: u64 = 18;
 /// # Type parameters
 /// The two parameters `D` and `H` signal if the builder already contains the correct amount of the
 /// given field:
-///  * `D`: exactly one `Description` or `DescriptionHash`
-///  * `H`: exactly one `PaymentHash`
+///  * `D`: exactly one [`TaggedField::Description`] or [`TaggedField::DescriptionHash`]
+///  * `H`: exactly one [`TaggedField::PaymentHash`]
 ///  * `T`: the timestamp is set
+///  * `C`: the CLTV expiry is set
+///  * `S`: the payment secret is set
+///  * `M`: payment metadata is set
 ///
-/// (C-not exported) as we likely need to manually select one set of boolean type parameters.
+/// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
 #[derive(Eq, PartialEq, Debug, Clone)]
-pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> {
+pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> {
        currency: Currency,
        amount: Option<u64>,
        si_prefix: Option<SiPrefix>,
@@ -181,26 +239,29 @@ pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S:
        phantom_t: core::marker::PhantomData<T>,
        phantom_c: core::marker::PhantomData<C>,
        phantom_s: core::marker::PhantomData<S>,
+       phantom_m: core::marker::PhantomData<M>,
 }
 
 /// Represents a syntactically and semantically correct lightning BOLT11 invoice.
 ///
-/// There are three ways to construct an `Invoice`:
-///  1. using `InvoiceBuilder`
-///  2. using `Invoice::from_signed(SignedRawInvoice)`
-///  3. using `str::parse::<Invoice>(&str)`
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct Invoice {
-       signed_invoice: SignedRawInvoice,
+/// There are three ways to construct a `Bolt11Invoice`:
+///  1. using [`InvoiceBuilder`]
+///  2. using [`Bolt11Invoice::from_signed`]
+///  3. using `str::parse::<Bolt11Invoice>(&str)` (see [`Bolt11Invoice::from_str`])
+///
+/// [`Bolt11Invoice::from_str`]: crate::Bolt11Invoice#impl-FromStr
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
+pub struct Bolt11Invoice {
+       signed_invoice: SignedRawBolt11Invoice,
 }
 
 /// Represents the description of an invoice which has to be either a directly included string or
 /// a hash of a description provided out of band.
 ///
-/// (C-not exported) As we don't have a good way to map the reference lifetimes making this
+/// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
 /// practically impossible to use safely in languages like C.
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub enum InvoiceDescription<'f> {
+#[derive(Eq, PartialEq, Debug, Clone, Ord, PartialOrd)]
+pub enum Bolt11InvoiceDescription<'f> {
        /// Reference to the directly supplied description in the invoice
        Direct(&'f Description),
 
@@ -208,36 +269,36 @@ pub enum InvoiceDescription<'f> {
        Hash(&'f Sha256),
 }
 
-/// Represents a signed `RawInvoice` with cached hash. The signature is not checked and may be
+/// Represents a signed [`RawBolt11Invoice`] 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,
+/// The hash has to be either from the deserialized invoice or from the serialized [`RawBolt11Invoice`].
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
+pub struct SignedRawBolt11Invoice {
+       /// The raw invoice that the signature belongs to
+       raw_invoice: RawBolt11Invoice,
 
-       /// Hash of the `RawInvoice` that will be used to check the signature.
+       /// Hash of the [`RawBolt11Invoice`] that will be used to check the signature.
        ///
-       /// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form,
+       /// * if the `SignedRawBolt11Invoice` 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`
+       /// * if the `SignedRawBolt11Invoice` was constructed manually the hash will be the calculated hash
+       /// from the [`RawBolt11Invoice`]
        hash: [u8; 32],
 
        /// signature of the payment request
-       signature: InvoiceSignature,
+       signature: Bolt11InvoiceSignature,
 }
 
-/// Represents an syntactically correct Invoice for a payment on the lightning network,
+/// Represents an syntactically correct [`Bolt11Invoice`] for a payment on the lightning network,
 /// but without the signature information.
-/// De- and encoding should not lead to information loss but may lead to different hashes.
+/// Decoding and encoding should not lead to information loss but may lead to different hashes.
 ///
-/// For methods without docs see the corresponding methods in `Invoice`.
-#[derive(Eq, PartialEq, Debug, Clone)]
-pub struct RawInvoice {
+/// For methods without docs see the corresponding methods in [`Bolt11Invoice`].
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
+pub struct RawBolt11Invoice {
        /// human readable part
        pub hrp: RawHrp,
 
@@ -245,10 +306,10 @@ pub struct RawInvoice {
        pub data: RawDataPart,
 }
 
-/// Data of the `RawInvoice` that is encoded in the human readable part
+/// Data of the [`RawBolt11Invoice`] that is encoded in the human readable part.
 ///
-/// (C-not exported) As we don't yet support Option<Enum>
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// This is not exported to bindings users as we don't yet support `Option<Enum>`
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 pub struct RawHrp {
        /// The currency deferred from the 3rd and 4th character of the bech32 transaction
        pub currency: Currency,
@@ -260,8 +321,8 @@ pub struct RawHrp {
        pub si_prefix: Option<SiPrefix>,
 }
 
-/// Data of the `RawInvoice` that is encoded in the data part
-#[derive(Eq, PartialEq, Debug, Clone)]
+/// Data of the [`RawBolt11Invoice`] that is encoded in the data part
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 pub struct RawDataPart {
        /// generation time of the invoice
        pub timestamp: PositiveTimestamp,
@@ -276,11 +337,11 @@ pub struct RawDataPart {
 ///
 /// The Unix timestamp representing the stored time has to be positive and no greater than
 /// [`MAX_TIMESTAMP`].
-#[derive(Eq, PartialEq, Debug, Clone)]
+#[derive(Eq, PartialEq, Debug, Clone, Hash, Ord, PartialOrd)]
 pub struct PositiveTimestamp(Duration);
 
 /// SI prefixes for the human readable part
-#[derive(Eq, PartialEq, Debug, Clone, Copy)]
+#[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Ord, PartialOrd)]
 pub enum SiPrefix {
        /// 10^-3
        Milli,
@@ -307,17 +368,17 @@ impl SiPrefix {
        /// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
        /// multiplier.
        ///
-       /// (C-not exported) As we don't yet support a slice of enums, and also because this function
+       /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
        /// isn't the most critical to expose.
        pub fn values_desc() -> &'static [SiPrefix] {
-               use SiPrefix::*;
+               use crate::SiPrefix::*;
                static VALUES: [SiPrefix; 4] = [Milli, Micro, Nano, Pico];
                &VALUES
        }
 }
 
 /// Enum representing the crypto currencies (or networks) supported by this library
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum Currency {
        /// Bitcoin mainnet
        Bitcoin,
@@ -335,10 +396,33 @@ pub enum Currency {
        Signet,
 }
 
+impl From<Network> for Currency {
+       fn from(network: Network) -> Self {
+               match network {
+                       Network::Bitcoin => Currency::Bitcoin,
+                       Network::Testnet => Currency::BitcoinTestnet,
+                       Network::Regtest => Currency::Regtest,
+                       Network::Signet => Currency::Signet,
+               }
+       }
+}
+
+impl From<Currency> for Network {
+       fn from(currency: Currency) -> Self {
+               match currency {
+                       Currency::Bitcoin => Network::Bitcoin,
+                       Currency::BitcoinTestnet => Network::Testnet,
+                       Currency::Regtest => Network::Regtest,
+                       Currency::Simnet => Network::Regtest,
+                       Currency::Signet => Network::Signet,
+               }
+       }
+}
+
 /// Tagged field which may have an unknown tag
 ///
-/// (C-not exported) as we don't currently support TaggedField
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+/// This is not exported to bindings users as we don't currently support TaggedField
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum RawTaggedField {
        /// Parsed tagged field with known tag
        KnownSemantics(TaggedField),
@@ -350,71 +434,92 @@ pub enum RawTaggedField {
 ///
 /// For descriptions of the enum values please refer to the enclosed type's docs.
 ///
-/// (C-not exported) As we don't yet support enum variants with the same name the struct contained
+/// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
 /// in the variant.
 #[allow(missing_docs)]
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum TaggedField {
        PaymentHash(Sha256),
        Description(Description),
        PayeePubKey(PayeePubKey),
        DescriptionHash(Sha256),
        ExpiryTime(ExpiryTime),
-       MinFinalCltvExpiry(MinFinalCltvExpiry),
+       MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta),
        Fallback(Fallback),
        PrivateRoute(PrivateRoute),
        PaymentSecret(PaymentSecret),
-       Features(InvoiceFeatures),
+       PaymentMetadata(Vec<u8>),
+       Features(Bolt11InvoiceFeatures),
 }
 
 /// SHA-256 hash
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct Sha256(/// (C-not exported) as the native hash types are not currently mapped
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
+pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
        pub sha256::Hash);
 
+impl Sha256 {
+       /// Constructs a new [`Sha256`] from the given bytes, which are assumed to be the output of a
+       /// single sha256 hash.
+       #[cfg(c_bindings)]
+       pub fn from_bytes(bytes: &[u8; 32]) -> Self {
+               Self(sha256::Hash::from_slice(bytes).expect("from_slice only fails if len is not 32"))
+       }
+}
+
 /// Description string
 ///
 /// # Invariants
 /// The description can be at most 639 __bytes__ long
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub struct Description(String);
 
 /// Payee public key
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub struct PayeePubKey(pub PublicKey);
 
 /// Positive duration that defines when (relatively to the timestamp) in the future the invoice
 /// expires
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub struct ExpiryTime(Duration);
 
-/// `min_final_cltv_expiry` to use for the last HTLC in the route
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct MinFinalCltvExpiry(pub u64);
+/// `min_final_cltv_expiry_delta` to use for the last HTLC in the route
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
+pub struct MinFinalCltvExpiryDelta(pub u64);
 
-// TODO: better types instead onf byte arrays
 /// Fallback address in case no LN payment is possible
 #[allow(missing_docs)]
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub enum Fallback {
        SegWitProgram {
-               version: u5,
+               version: WitnessVersion,
                program: Vec<u8>,
        },
-       PubKeyHash([u8; 20]),
-       ScriptHash([u8; 20]),
+       PubKeyHash(PubkeyHash),
+       ScriptHash(ScriptHash),
 }
 
 /// Recoverable signature
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub struct InvoiceSignature(pub RecoverableSignature);
+#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+pub struct Bolt11InvoiceSignature(pub RecoverableSignature);
+
+impl PartialOrd for Bolt11InvoiceSignature {
+       fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
+               self.0.serialize_compact().1.partial_cmp(&other.0.serialize_compact().1)
+       }
+}
+
+impl Ord for Bolt11InvoiceSignature {
+       fn cmp(&self, other: &Self) -> Ordering {
+               self.0.serialize_compact().1.cmp(&other.0.serialize_compact().1)
+       }
+}
 
 /// Private routing information
 ///
 /// # Invariants
 /// The encoded route has to be <1024 5bit characters long (<=639 bytes or <=12 hops)
 ///
-#[derive(Clone, Debug, Hash, Eq, PartialEq)]
+#[derive(Clone, Debug, Hash, Eq, PartialEq, Ord, PartialOrd)]
 pub struct PrivateRoute(RouteHint);
 
 /// Tag constants as specified in BOLT11
@@ -425,19 +530,20 @@ pub mod constants {
        pub const TAG_PAYEE_PUB_KEY: u8 = 19;
        pub const TAG_DESCRIPTION_HASH: u8 = 23;
        pub const TAG_EXPIRY_TIME: u8 = 6;
-       pub const TAG_MIN_FINAL_CLTV_EXPIRY: u8 = 24;
+       pub const TAG_MIN_FINAL_CLTV_EXPIRY_DELTA: u8 = 24;
        pub const TAG_FALLBACK: u8 = 9;
        pub const TAG_PRIVATE_ROUTE: u8 = 3;
        pub const TAG_PAYMENT_SECRET: u8 = 16;
+       pub const TAG_PAYMENT_METADATA: u8 = 27;
        pub const TAG_FEATURES: u8 = 5;
 }
 
-impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False> {
+impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False, tb::False> {
        /// Construct new, empty `InvoiceBuilder`. All necessary fields have to be filled first before
        /// `InvoiceBuilder::build(self)` becomes available.
-       pub fn new(currrency: Currency) -> Self {
+       pub fn new(currency: Currency) -> Self {
                InvoiceBuilder {
-                       currency: currrency,
+                       currency,
                        amount: None,
                        si_prefix: None,
                        timestamp: None,
@@ -449,14 +555,15 @@ impl InvoiceBuilder<tb::False, tb::False, tb::False, tb::False, tb::False> {
                        phantom_t: core::marker::PhantomData,
                        phantom_c: core::marker::PhantomData,
                        phantom_s: core::marker::PhantomData,
+                       phantom_m: core::marker::PhantomData,
                }
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, S, M> {
        /// Helper function to set the completeness flags.
-       fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN> {
-               InvoiceBuilder::<DN, HN, TN, CN, SN> {
+       fn set_flags<DN: tb::Bool, HN: tb::Bool, TN: tb::Bool, CN: tb::Bool, SN: tb::Bool, MN: tb::Bool>(self) -> InvoiceBuilder<DN, HN, TN, CN, SN, MN> {
+               InvoiceBuilder::<DN, HN, TN, CN, SN, MN> {
                        currency: self.currency,
                        amount: self.amount,
                        si_prefix: self.si_prefix,
@@ -469,6 +576,7 @@ impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBui
                        phantom_t: core::marker::PhantomData,
                        phantom_c: core::marker::PhantomData,
                        phantom_s: core::marker::PhantomData,
+                       phantom_m: core::marker::PhantomData,
                }
        }
 
@@ -490,7 +598,8 @@ impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBui
                self
        }
 
-       /// Sets the expiry time
+       /// Sets the expiry time, dropping the subsecond part (which is not representable in BOLT 11
+       /// invoices).
        pub fn expiry_time(mut self, expiry_time: Duration) -> Self {
                self.tagged_fields.push(TaggedField::ExpiryTime(ExpiryTime::from_duration(expiry_time)));
                self
@@ -512,9 +621,10 @@ impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBui
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S> {
-       /// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields.
-       pub fn build_raw(self) -> Result<RawInvoice, CreationError> {
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::True, C, S, M> {
+       /// Builds a [`RawBolt11Invoice`] if no [`CreationError`] occurred while construction any of the
+       /// fields.
+       pub fn build_raw(self) -> Result<RawBolt11Invoice, CreationError> {
 
                // If an error occurred at any time before, return it now
                if let Some(e) = self.error {
@@ -534,20 +644,20 @@ impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb
                }).collect::<Vec<_>>();
 
                let data = RawDataPart {
-                       timestamp: timestamp,
-                       tagged_fields: tagged_fields,
+                       timestamp,
+                       tagged_fields,
                };
 
-               Ok(RawInvoice {
-                       hrp: hrp,
-                       data: data,
+               Ok(RawBolt11Invoice {
+                       hrp,
+                       data,
                })
        }
 }
 
-impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S> {
+impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<tb::False, H, T, C, S, M> {
        /// Set the description. This function is only available if no description (hash) was set.
-       pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S> {
+       pub fn description(mut self, description: String) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
                match Description::new(description) {
                        Ok(d) => self.tagged_fields.push(TaggedField::Description(d)),
                        Err(e) => self.error = Some(e),
@@ -556,24 +666,36 @@ impl<H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<tb::Fals
        }
 
        /// Set the description hash. This function is only available if no description (hash) was set.
-       pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S> {
+       pub fn description_hash(mut self, description_hash: sha256::Hash) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
                self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
                self.set_flags()
        }
+
+       /// Set the description or description hash. This function is only available if no description (hash) was set.
+       pub fn invoice_description(self, description: Bolt11InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S, M> {
+               match description {
+                       Bolt11InvoiceDescription::Direct(desc) => {
+                               self.description(desc.clone().into_inner())
+                       }
+                       Bolt11InvoiceDescription::Hash(hash) => {
+                               self.description_hash(hash.0)
+                       }
+               }
+       }
 }
 
-impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
+impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S, M> {
        /// Set the payment hash. This function is only available if no payment hash was set.
-       pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S> {
+       pub fn payment_hash(mut self, hash: sha256::Hash) -> InvoiceBuilder<D, tb::True, T, C, S, M> {
                self.tagged_fields.push(TaggedField::PaymentHash(Sha256(hash)));
                self.set_flags()
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S> {
+impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, tb::False, C, S, M> {
        /// Sets the timestamp to a specific [`SystemTime`].
        #[cfg(feature = "std")]
-       pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S> {
+       pub fn timestamp(mut self, time: SystemTime) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
                match PositiveTimestamp::from_system_time(time) {
                        Ok(t) => self.timestamp = Some(t),
                        Err(e) => self.error = Some(e),
@@ -582,8 +704,9 @@ impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb
                self.set_flags()
        }
 
-       /// Sets the timestamp to a duration since the Unix epoch.
-       pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S> {
+       /// Sets the timestamp to a duration since the Unix epoch, dropping the subsecond part (which
+       /// is not representable in BOLT 11 invoices).
+       pub fn duration_since_epoch(mut self, time: Duration) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
                match PositiveTimestamp::from_duration_since_epoch(time) {
                        Ok(t) => self.timestamp = Some(t),
                        Err(e) => self.error = Some(e),
@@ -594,34 +717,82 @@ impl<D: tb::Bool, H: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, tb
 
        /// Sets the timestamp to the current system time.
        #[cfg(feature = "std")]
-       pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S> {
+       pub fn current_timestamp(mut self) -> InvoiceBuilder<D, H, tb::True, C, S, M> {
                let now = PositiveTimestamp::from_system_time(SystemTime::now());
                self.timestamp = Some(now.expect("for the foreseeable future this shouldn't happen"));
                self.set_flags()
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S> {
-       /// Sets `min_final_cltv_expiry`.
-       pub fn min_final_cltv_expiry(mut self, min_final_cltv_expiry: u64) -> InvoiceBuilder<D, H, T, tb::True, S> {
-               self.tagged_fields.push(TaggedField::MinFinalCltvExpiry(MinFinalCltvExpiry(min_final_cltv_expiry)));
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, S: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, tb::False, S, M> {
+       /// Sets `min_final_cltv_expiry_delta`.
+       pub fn min_final_cltv_expiry_delta(mut self, min_final_cltv_expiry_delta: u64) -> InvoiceBuilder<D, H, T, tb::True, S, M> {
+               self.tagged_fields.push(TaggedField::MinFinalCltvExpiryDelta(MinFinalCltvExpiryDelta(min_final_cltv_expiry_delta)));
                self.set_flags()
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::False, M> {
        /// Sets the payment secret and relevant features.
-       pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True> {
-               let mut features = InvoiceFeatures::empty();
-               features.set_variable_length_onion_required();
-               features.set_payment_secret_required();
+       pub fn payment_secret(mut self, payment_secret: PaymentSecret) -> InvoiceBuilder<D, H, T, C, tb::True, M> {
+               let mut found_features = false;
+               for field in self.tagged_fields.iter_mut() {
+                       if let TaggedField::Features(f) = field {
+                               found_features = true;
+                               f.set_variable_length_onion_required();
+                               f.set_payment_secret_required();
+                       }
+               }
                self.tagged_fields.push(TaggedField::PaymentSecret(payment_secret));
-               self.tagged_fields.push(TaggedField::Features(features));
+               if !found_features {
+                       let mut features = Bolt11InvoiceFeatures::empty();
+                       features.set_variable_length_onion_required();
+                       features.set_payment_secret_required();
+                       self.tagged_fields.push(TaggedField::Features(features));
+               }
+               self.set_flags()
+       }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::False> {
+       /// Sets the payment metadata.
+       ///
+       /// By default features are set to *optionally* allow the sender to include the payment metadata.
+       /// If you wish to require that the sender include the metadata (and fail to parse the invoice if
+       /// they don't support payment metadata fields), you need to call
+       /// [`InvoiceBuilder::require_payment_metadata`] after this.
+       pub fn payment_metadata(mut self, payment_metadata: Vec<u8>) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
+               self.tagged_fields.push(TaggedField::PaymentMetadata(payment_metadata));
+               let mut found_features = false;
+               for field in self.tagged_fields.iter_mut() {
+                       if let TaggedField::Features(f) = field {
+                               found_features = true;
+                               f.set_payment_metadata_optional();
+                       }
+               }
+               if !found_features {
+                       let mut features = Bolt11InvoiceFeatures::empty();
+                       features.set_payment_metadata_optional();
+                       self.tagged_fields.push(TaggedField::Features(features));
+               }
                self.set_flags()
        }
 }
 
-impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True> {
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, H, T, C, S, tb::True> {
+       /// Sets forwarding of payment metadata as required. A reader of the invoice which does not
+       /// support sending payment metadata will fail to read the invoice.
+       pub fn require_payment_metadata(mut self) -> InvoiceBuilder<D, H, T, C, S, tb::True> {
+               for field in self.tagged_fields.iter_mut() {
+                       if let TaggedField::Features(f) = field {
+                               f.set_payment_metadata_required();
+                       }
+               }
+               self
+       }
+}
+
+impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, M: tb::Bool> InvoiceBuilder<D, H, T, C, tb::True, M> {
        /// Sets the `basic_mpp` feature as optional.
        pub fn basic_mpp(mut self) -> Self {
                for field in self.tagged_fields.iter_mut() {
@@ -633,11 +804,11 @@ impl<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool> InvoiceBuilder<D, H, T,
        }
 }
 
-impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
+impl<M: tb::Bool> InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True, M> {
        /// Builds and signs an invoice using the supplied `sign_function`. This function MAY NOT fail
        /// and MUST produce a recoverable signature valid for the given hash and if applicable also for
        /// the included payee public key.
-       pub fn build_signed<F>(self, sign_function: F) -> Result<Invoice, CreationError>
+       pub fn build_signed<F>(self, sign_function: F) -> Result<Bolt11Invoice, CreationError>
                where F: FnOnce(&Message) -> RecoverableSignature
        {
                let invoice = self.try_build_signed::<_, ()>(|hash| {
@@ -654,7 +825,7 @@ 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 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>>
+       pub fn try_build_signed<F, E>(self, sign_function: F) -> Result<Bolt11Invoice, SignOrCreationError<E>>
                where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
        {
                let raw = match self.build_raw() {
@@ -667,7 +838,7 @@ impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
                        Err(e) => return Err(SignOrCreationError::SignError(e)),
                };
 
-               let invoice = Invoice {
+               let invoice = Bolt11Invoice {
                        signed_invoice: signed,
                };
 
@@ -680,27 +851,27 @@ impl InvoiceBuilder<tb::True, tb::True, tb::True, tb::True, tb::True> {
 }
 
 
-impl SignedRawInvoice {
-       /// Disassembles the `SignedRawInvoice` into its three parts:
+impl SignedRawBolt11Invoice {
+       /// Disassembles the `SignedRawBolt11Invoice` into its three parts:
        ///  1. raw invoice
        ///  2. hash of the raw invoice
        ///  3. signature
-       pub fn into_parts(self) -> (RawInvoice, [u8; 32], InvoiceSignature) {
+       pub fn into_parts(self) -> (RawBolt11Invoice, [u8; 32], Bolt11InvoiceSignature) {
                (self.raw_invoice, self.hash, self.signature)
        }
 
-       /// The `RawInvoice` which was signed.
-       pub fn raw_invoice(&self) -> &RawInvoice {
+       /// The [`RawBolt11Invoice`] which was signed.
+       pub fn raw_invoice(&self) -> &RawBolt11Invoice {
                &self.raw_invoice
        }
 
-       /// The hash of the `RawInvoice` that was signed.
-       pub fn hash(&self) -> &[u8; 32] {
+       /// The hash of the [`RawBolt11Invoice`] that was signed.
+       pub fn signable_hash(&self) -> &[u8; 32] {
                &self.hash
        }
 
-       /// InvoiceSignature for the invoice.
-       pub fn signature(&self) -> &InvoiceSignature {
+       /// Signature for the invoice.
+       pub fn signature(&self) -> &Bolt11InvoiceSignature {
                &self.signature
        }
 
@@ -709,7 +880,7 @@ impl SignedRawInvoice {
                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
                )?))
@@ -729,14 +900,14 @@ impl SignedRawInvoice {
                        recovered_pub_key = Some(recovered);
                }
 
-               let pub_key = included_pub_key.or_else(|| recovered_pub_key.as_ref())
+               let pub_key = included_pub_key.or(recovered_pub_key.as_ref())
                        .expect("One is always present");
 
                let hash = Message::from_slice(&self.hash[..])
                        .expect("Hash is 32 bytes long, same as MESSAGE_SIZE");
 
                let secp_context = Secp256k1::new();
-               let verification_result = secp_context.verify(
+               let verification_result = secp_context.verify_ecdsa(
                        &hash,
                        &self.signature.to_standard(),
                        pub_key
@@ -753,17 +924,16 @@ impl SignedRawInvoice {
 /// variant. If no element was found `None` gets returned.
 ///
 /// The following example would extract the first B.
-/// ```
-/// use Enum::*
 ///
+/// ```ignore
 /// enum Enum {
 ///    A(u8),
 ///    B(u16)
 /// }
 ///
-/// let elements = vec![A(1), A(2), B(3), A(4)]
+/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 ///
-/// assert_eq!(find_extract!(elements.iter(), Enum::B(ref x), x), Some(3u16))
+/// assert_eq!(find_extract!(elements.iter(), Enum::B(x), x), Some(3u16));
 /// ```
 macro_rules! find_extract {
        ($iter:expr, $enm:pat, $enm_var:ident) => {
@@ -775,19 +945,19 @@ macro_rules! find_extract {
 /// variant through an iterator.
 ///
 /// The following example would extract all A.
-/// ```
-/// use Enum::*
 ///
+/// ```ignore
 /// enum Enum {
 ///    A(u8),
 ///    B(u16)
 /// }
 ///
-/// let elements = vec![A(1), A(2), B(3), A(4)]
+/// let elements = vec![Enum::A(1), Enum::A(2), Enum::B(3), Enum::A(4)];
 ///
 /// assert_eq!(
-///    find_all_extract!(elements.iter(), Enum::A(ref x), x).collect::<Vec<u8>>(),
-///    vec![1u8, 2u8, 4u8])
+///    find_all_extract!(elements.iter(), Enum::A(x), x).collect::<Vec<u8>>(),
+///    vec![1u8, 2u8, 4u8]
+/// );
 /// ```
 macro_rules! find_all_extract {
        ($iter:expr, $enm:pat, $enm_var:ident) => {
@@ -799,7 +969,7 @@ macro_rules! find_all_extract {
 }
 
 #[allow(missing_docs)]
-impl RawInvoice {
+impl RawBolt11Invoice {
        /// Hash the HRP as bytes and signatureless data part.
        fn hash_from_parts(hrp_bytes: &[u8], data_without_signature: &[u5]) -> [u8; 32] {
                let preimage = construct_invoice_preimage(hrp_bytes, data_without_signature);
@@ -808,40 +978,40 @@ impl RawInvoice {
                hash
        }
 
-       /// Calculate the hash of the encoded `RawInvoice`
-       pub fn hash(&self) -> [u8; 32] {
+       /// Calculate the hash of the encoded `RawBolt11Invoice` which should be signed.
+       pub fn signable_hash(&self) -> [u8; 32] {
                use bech32::ToBase32;
 
-               RawInvoice::hash_from_parts(
+               RawBolt11Invoice::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
+       /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of
+       /// type `E`. Since the signature of a [`SignedRawBolt11Invoice`] is not required to be valid there
        /// are no constraints regarding the validity of the produced signature.
        ///
-       /// (C-not exported) As we don't currently support passing function pointers into methods
+       /// This is not exported to bindings users as we don't currently support passing function pointers into methods
        /// explicitly.
-       pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
+       pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawBolt11Invoice, 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)?;
 
-               Ok(SignedRawInvoice {
+               Ok(SignedRawBolt11Invoice {
                        raw_invoice: self,
                        hash: raw_hash,
-                       signature: InvoiceSignature(signature),
+                       signature: Bolt11InvoiceSignature(signature),
                })
        }
 
        /// Returns an iterator over all tagged fields with known semantics.
        ///
-       /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+       /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
        pub fn known_tagged_fields(&self)
                -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
        {
@@ -878,19 +1048,23 @@ impl RawInvoice {
                find_extract!(self.known_tagged_fields(), TaggedField::ExpiryTime(ref x), x)
        }
 
-       pub fn min_final_cltv_expiry(&self) -> Option<&MinFinalCltvExpiry> {
-               find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiry(ref x), x)
+       pub fn min_final_cltv_expiry_delta(&self) -> Option<&MinFinalCltvExpiryDelta> {
+               find_extract!(self.known_tagged_fields(), TaggedField::MinFinalCltvExpiryDelta(ref x), x)
        }
 
        pub fn payment_secret(&self) -> Option<&PaymentSecret> {
                find_extract!(self.known_tagged_fields(), TaggedField::PaymentSecret(ref x), x)
        }
 
-       pub fn features(&self) -> Option<&InvoiceFeatures> {
+       pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
+               find_extract!(self.known_tagged_fields(), TaggedField::PaymentMetadata(ref x), x)
+       }
+
+       pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
                find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
        }
 
-       /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+       /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
        pub fn fallbacks(&self) -> Vec<&Fallback> {
                find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
        }
@@ -915,12 +1089,18 @@ impl PositiveTimestamp {
        ///
        /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
        pub fn from_unix_timestamp(unix_seconds: u64) -> Result<Self, CreationError> {
-               Self::from_duration_since_epoch(Duration::from_secs(unix_seconds))
+               if unix_seconds <= MAX_TIMESTAMP {
+                       Ok(Self(Duration::from_secs(unix_seconds)))
+               } else {
+                       Err(CreationError::TimestampOutOfBounds)
+               }
        }
 
        /// Creates a `PositiveTimestamp` from a [`SystemTime`] with a corresponding Unix timestamp in
        /// the range `0..=MAX_TIMESTAMP`.
        ///
+       /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
+       ///
        /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
        #[cfg(feature = "std")]
        pub fn from_system_time(time: SystemTime) -> Result<Self, CreationError> {
@@ -932,13 +1112,11 @@ impl PositiveTimestamp {
        /// Creates a `PositiveTimestamp` from a [`Duration`] since the Unix epoch in the range
        /// `0..=MAX_TIMESTAMP`.
        ///
+       /// Note that the subsecond part is dropped as it is not representable in BOLT 11 invoices.
+       ///
        /// Otherwise, returns a [`CreationError::TimestampOutOfBounds`].
        pub fn from_duration_since_epoch(duration: Duration) -> Result<Self, CreationError> {
-               if duration.as_secs() <= MAX_TIMESTAMP {
-                       Ok(PositiveTimestamp(duration))
-               } else {
-                       Err(CreationError::TimestampOutOfBounds)
-               }
+               Self::from_unix_timestamp(duration.as_secs())
        }
 
        /// Returns the Unix timestamp representing the stored time
@@ -959,29 +1137,34 @@ impl PositiveTimestamp {
 }
 
 #[cfg(feature = "std")]
-impl Into<SystemTime> for PositiveTimestamp {
-       fn into(self) -> SystemTime {
-               SystemTime::UNIX_EPOCH + self.0
+impl From<PositiveTimestamp> for SystemTime {
+       fn from(val: PositiveTimestamp) -> Self {
+               SystemTime::UNIX_EPOCH + val.0
        }
 }
 
-impl Invoice {
-       /// Transform the `Invoice` into it's unchecked version
-       pub fn into_signed_raw(self) -> SignedRawInvoice {
+impl Bolt11Invoice {
+       /// The hash of the [`RawBolt11Invoice`] that was signed.
+       pub fn signable_hash(&self) -> [u8; 32] {
+               self.signed_invoice.hash
+       }
+
+       /// Transform the `Bolt11Invoice` into its unchecked version.
+       pub fn into_signed_raw(self) -> SignedRawBolt11Invoice {
                self.signed_invoice
        }
 
        /// Check that all mandatory fields are present
-       fn check_field_counts(&self) -> Result<(), SemanticError> {
+       fn check_field_counts(&self) -> Result<(), Bolt11SemanticError> {
                // "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);
+                       return Err(Bolt11SemanticError::NoPaymentHash);
                } else if payment_hash_cnt > 1 {
-                       return Err(SemanticError::MultiplePaymentHashes);
+                       return Err(Bolt11SemanticError::MultiplePaymentHashes);
                }
 
                // "A writer MUST include either exactly one d or exactly one h field."
@@ -990,9 +1173,9 @@ impl Invoice {
                        _ => false,
                }).count();
                if  description_cnt < 1 {
-                       return Err(SemanticError::NoDescription);
+                       return Err(Bolt11SemanticError::NoDescription);
                } else if description_cnt > 1 {
-                       return  Err(SemanticError::MultipleDescriptions);
+                       return  Err(Bolt11SemanticError::MultipleDescriptions);
                }
 
                self.check_payment_secret()?;
@@ -1001,33 +1184,33 @@ impl Invoice {
        }
 
        /// Checks that there is exactly one payment secret field
-       fn check_payment_secret(&self) -> Result<(), SemanticError> {
+       fn check_payment_secret(&self) -> Result<(), Bolt11SemanticError> {
                // "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 {
-                       return Err(SemanticError::NoPaymentSecret);
+                       return Err(Bolt11SemanticError::NoPaymentSecret);
                } else if payment_secret_count > 1 {
-                       return Err(SemanticError::MultiplePaymentSecrets);
+                       return Err(Bolt11SemanticError::MultiplePaymentSecrets);
                }
 
                Ok(())
        }
 
        /// Check that amount is a whole number of millisatoshis
-       fn check_amount(&self) -> Result<(), SemanticError> {
+       fn check_amount(&self) -> Result<(), Bolt11SemanticError> {
                if let Some(amount_pico_btc) = self.amount_pico_btc() {
                        if amount_pico_btc % 10 != 0 {
-                               return Err(SemanticError::ImpreciseAmount);
+                               return Err(Bolt11SemanticError::ImpreciseAmount);
                        }
                }
                Ok(())
        }
 
        /// Check that feature bits are set as required
-       fn check_feature_bits(&self) -> Result<(), SemanticError> {
+       fn check_feature_bits(&self) -> Result<(), Bolt11SemanticError> {
                self.check_payment_secret()?;
 
                // "A writer MUST set an s field if and only if the payment_secret feature is set."
@@ -1038,12 +1221,12 @@ impl Invoice {
                        _ => false,
                });
                match features {
-                       None => Err(SemanticError::InvalidFeatures),
+                       None => Err(Bolt11SemanticError::InvalidFeatures),
                        Some(TaggedField::Features(features)) => {
                                if features.requires_unknown_bits() {
-                                       Err(SemanticError::InvalidFeatures)
+                                       Err(Bolt11SemanticError::InvalidFeatures)
                                } else if !features.supports_payment_secret() {
-                                       Err(SemanticError::InvalidFeatures)
+                                       Err(Bolt11SemanticError::InvalidFeatures)
                                } else {
                                        Ok(())
                                }
@@ -1053,24 +1236,24 @@ impl Invoice {
        }
 
        /// Check that the invoice is signed correctly and that key recovery works
-       pub fn check_signature(&self) -> Result<(), SemanticError> {
+       pub fn check_signature(&self) -> Result<(), Bolt11SemanticError> {
                match self.signed_invoice.recover_payee_pub_key() {
                        Err(secp256k1::Error::InvalidRecoveryId) =>
-                               return Err(SemanticError::InvalidRecoveryId),
+                               return Err(Bolt11SemanticError::InvalidRecoveryId),
                        Err(secp256k1::Error::InvalidSignature) =>
-                               return Err(SemanticError::InvalidSignature),
+                               return Err(Bolt11SemanticError::InvalidSignature),
                        Err(e) => panic!("no other error may occur, got {:?}", e),
                        Ok(_) => {},
                }
 
                if !self.signed_invoice.check_signature() {
-                       return Err(SemanticError::InvalidSignature);
+                       return Err(Bolt11SemanticError::InvalidSignature);
                }
 
                Ok(())
        }
 
-       /// Constructs an `Invoice` from a `SignedRawInvoice` by checking all its invariants.
+       /// Constructs a `Bolt11Invoice` from a [`SignedRawBolt11Invoice`] by checking all its invariants.
        /// ```
        /// use lightning_invoice::*;
        ///
@@ -1086,13 +1269,13 @@ impl Invoice {
        /// 8s0gyuxjjgux34w75dnc6xp2l35j7es3jd4ugt3lu0xzre26yg5m7ke54n2d5sym4xcmxtl8238xxvw5h5h5\
        /// j5r6drg6k6zcqj0fcwg";
        ///
-       /// let signed = invoice.parse::<SignedRawInvoice>().unwrap();
+       /// let signed = invoice.parse::<SignedRawBolt11Invoice>().unwrap();
        ///
-       /// assert!(Invoice::from_signed(signed).is_ok());
+       /// assert!(Bolt11Invoice::from_signed(signed).is_ok());
        /// ```
-       pub fn from_signed(signed_invoice: SignedRawInvoice) -> Result<Self, SemanticError> {
-               let invoice = Invoice {
-                       signed_invoice: signed_invoice,
+       pub fn from_signed(signed_invoice: SignedRawBolt11Invoice) -> Result<Self, Bolt11SemanticError> {
+               let invoice = Bolt11Invoice {
+                       signed_invoice,
                };
                invoice.check_field_counts()?;
                invoice.check_feature_bits()?;
@@ -1102,20 +1285,20 @@ impl Invoice {
                Ok(invoice)
        }
 
-       /// Returns the `Invoice`'s timestamp (should equal its creation time)
+       /// Returns the `Bolt11Invoice`'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
+       /// Returns the `Bolt11Invoice`'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.
+       /// Returns an iterator over all tagged fields of this `Bolt11Invoice`.
        ///
-       /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+       /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
        pub fn tagged_fields(&self)
                -> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
                self.signed_invoice.raw_invoice().known_tagged_fields()
@@ -1128,12 +1311,12 @@ impl Invoice {
 
        /// Return the description or a hash of it for longer ones
        ///
-       /// (C-not exported) because we don't yet export InvoiceDescription
-       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);
+       /// This is not exported to bindings users because we don't yet export Bolt11InvoiceDescription
+       pub fn description(&self) -> Bolt11InvoiceDescription {
+               if let Some(direct) = self.signed_invoice.description() {
+                       return Bolt11InvoiceDescription::Direct(direct);
+               } else if let Some(hash) = self.signed_invoice.description_hash() {
+                       return Bolt11InvoiceDescription::Hash(hash);
                }
                unreachable!("ensured by constructor");
        }
@@ -1148,8 +1331,13 @@ impl Invoice {
                self.signed_invoice.payment_secret().expect("was checked by constructor")
        }
 
+       /// Get the payment metadata blob if one was included in the invoice
+       pub fn payment_metadata(&self) -> Option<&Vec<u8>> {
+               self.signed_invoice.payment_metadata()
+       }
+
        /// Get the invoice features if they were included in the invoice
-       pub fn features(&self) -> Option<&InvoiceFeatures> {
+       pub fn features(&self) -> Option<&Bolt11InvoiceFeatures> {
                self.signed_invoice.features()
        }
 
@@ -1158,6 +1346,12 @@ impl Invoice {
                self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
        }
 
+       /// Returns the Duration since the Unix epoch at which the invoice expires.
+       /// Returning None if overflow occurred.
+       pub fn expires_at(&self) -> Option<Duration> {
+               self.duration_since_epoch().checked_add(self.expiry_time())
+       }
+
        /// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
        pub fn expiry_time(&self) -> Duration {
                self.signed_invoice.expiry_time()
@@ -1180,6 +1374,20 @@ impl Invoice {
                }
        }
 
+       /// Returns the Duration remaining until the invoice expires.
+       #[cfg(feature = "std")]
+       pub fn duration_until_expiry(&self) -> Duration {
+               SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
+                       .map(|now| self.expiration_remaining_from_epoch(now))
+                       .unwrap_or(Duration::from_nanos(0))
+       }
+
+       /// Returns the Duration remaining until the invoice expires given the current time.
+       /// `time` is the timestamp as a duration since the Unix epoch.
+       pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
+               self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
+       }
+
        /// Returns whether the expiry time would pass at the given point in time.
        /// `at_time` is the timestamp as a duration since the Unix epoch.
        pub fn would_expire(&self, at_time: Duration) -> bool {
@@ -1188,21 +1396,40 @@ impl Invoice {
                        .unwrap_or_else(|| Duration::new(u64::max_value(), 1_000_000_000 - 1)) < at_time
        }
 
-       /// Returns the invoice's `min_final_cltv_expiry` time, if present, otherwise
-       /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY`].
-       pub fn min_final_cltv_expiry(&self) -> u64 {
-               self.signed_invoice.min_final_cltv_expiry()
+       /// Returns the invoice's `min_final_cltv_expiry_delta` time, if present, otherwise
+       /// [`DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA`].
+       pub fn min_final_cltv_expiry_delta(&self) -> u64 {
+               self.signed_invoice.min_final_cltv_expiry_delta()
                        .map(|x| x.0)
-                       .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY)
+                       .unwrap_or(DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA)
        }
 
        /// Returns a list of all fallback addresses
        ///
-       /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+       /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
        pub fn fallbacks(&self) -> Vec<&Fallback> {
                self.signed_invoice.fallbacks()
        }
 
+       /// Returns a list of all fallback addresses as [`Address`]es
+       pub fn fallback_addresses(&self) -> Vec<Address> {
+               self.fallbacks().iter().map(|fallback| {
+                       let payload = match fallback {
+                               Fallback::SegWitProgram { version, program } => {
+                                       Payload::WitnessProgram { version: *version, program: program.to_vec() }
+                               }
+                               Fallback::PubKeyHash(pkh) => {
+                                       Payload::PubkeyHash(*pkh)
+                               }
+                               Fallback::ScriptHash(sh) => {
+                                       Payload::ScriptHash(*sh)
+                               }
+                       };
+
+                       Address { payload, network: self.network() }
+               }).collect()
+       }
+
        /// Returns a list of all routes included in the invoice
        pub fn private_routes(&self) -> Vec<&PrivateRoute> {
                self.signed_invoice.private_routes()
@@ -1220,12 +1447,19 @@ impl Invoice {
                self.signed_invoice.currency()
        }
 
+       /// Returns the network for which the invoice was issued
+       ///
+       /// This is not exported to bindings users, see [`Self::currency`] instead.
+       pub fn network(&self) -> Network {
+               self.signed_invoice.currency().into()
+       }
+
        /// Returns the amount if specified in the invoice as millisatoshis.
        pub fn amount_milli_satoshis(&self) -> Option<u64> {
                self.signed_invoice.amount_pico_btc().map(|v| v / 10)
        }
 
-       /// Returns the amount if specified in the invoice as pico <currency>.
+       /// Returns the amount if specified in the invoice as pico BTC.
        fn amount_pico_btc(&self) -> Option<u64> {
                self.signed_invoice.amount_pico_btc()
        }
@@ -1246,10 +1480,11 @@ impl TaggedField {
                        TaggedField::PayeePubKey(_) => constants::TAG_PAYEE_PUB_KEY,
                        TaggedField::DescriptionHash(_) => constants::TAG_DESCRIPTION_HASH,
                        TaggedField::ExpiryTime(_) => constants::TAG_EXPIRY_TIME,
-                       TaggedField::MinFinalCltvExpiry(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY,
+                       TaggedField::MinFinalCltvExpiryDelta(_) => constants::TAG_MIN_FINAL_CLTV_EXPIRY_DELTA,
                        TaggedField::Fallback(_) => constants::TAG_FALLBACK,
                        TaggedField::PrivateRoute(_) => constants::TAG_PRIVATE_ROUTE,
                        TaggedField::PaymentSecret(_) => constants::TAG_PAYMENT_SECRET,
+                       TaggedField::PaymentMetadata(_) => constants::TAG_PAYMENT_METADATA,
                        TaggedField::Features(_) => constants::TAG_FEATURES,
                };
 
@@ -1260,7 +1495,7 @@ impl TaggedField {
 impl Description {
 
        /// Creates a new `Description` if `description` is at most 1023 __bytes__ long,
-       /// returns `CreationError::DescriptionTooLong` otherwise
+       /// returns [`CreationError::DescriptionTooLong`] otherwise
        ///
        /// Please note that single characters may use more than one byte due to UTF8 encoding.
        pub fn new(description: String) -> Result<Description, CreationError> {
@@ -1271,15 +1506,15 @@ impl Description {
                }
        }
 
-       /// Returns the underlying description `String`
+       /// Returns the underlying description [`String`]
        pub fn into_inner(self) -> String {
                self.0
        }
 }
 
-impl Into<String> for Description {
-       fn into(self) -> String {
-               self.into_inner()
+impl From<Description> for String {
+       fn from(val: Description) -> Self {
+               val.into_inner()
        }
 }
 
@@ -1311,9 +1546,9 @@ impl ExpiryTime {
                ExpiryTime(Duration::from_secs(seconds))
        }
 
-       /// Construct an `ExpiryTime` from a `Duration`.
+       /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part.
        pub fn from_duration(duration: Duration) -> ExpiryTime {
-               ExpiryTime(duration)
+               Self::from_seconds(duration.as_secs())
        }
 
        /// Returns the expiry time in seconds
@@ -1321,7 +1556,7 @@ impl ExpiryTime {
                self.0.as_secs()
        }
 
-       /// Returns a reference to the underlying `Duration` (=expiry time)
+       /// Returns a reference to the underlying [`Duration`] (=expiry time)
        pub fn as_duration(&self) -> &Duration {
                &self.0
        }
@@ -1343,9 +1578,9 @@ impl PrivateRoute {
        }
 }
 
-impl Into<RouteHint> for PrivateRoute {
-       fn into(self) -> RouteHint {
-               self.into_inner()
+impl From<PrivateRoute> for RouteHint {
+       fn from(val: PrivateRoute) -> Self {
+               val.into_inner()
        }
 }
 
@@ -1357,7 +1592,7 @@ impl Deref for PrivateRoute {
        }
 }
 
-impl Deref for InvoiceSignature {
+impl Deref for Bolt11InvoiceSignature {
        type Target = RecoverableSignature;
 
        fn deref(&self) -> &RecoverableSignature {
@@ -1365,18 +1600,18 @@ impl Deref for InvoiceSignature {
        }
 }
 
-impl Deref for SignedRawInvoice {
-       type Target = RawInvoice;
+impl Deref for SignedRawBolt11Invoice {
+       type Target = RawBolt11Invoice;
 
-       fn deref(&self) -> &RawInvoice {
+       fn deref(&self) -> &RawBolt11Invoice {
                &self.raw_invoice
        }
 }
 
-/// Errors that may occur when constructing a new `RawInvoice` or `Invoice`
+/// Errors that may occur when constructing a new [`RawBolt11Invoice`] or [`Bolt11Invoice`]
 #[derive(Eq, PartialEq, Debug, Clone)]
 pub enum CreationError {
-       /// The supplied description string was longer than 639 __bytes__ (see [`Description::new(…)`](./struct.Description.html#method.new))
+       /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`])
        DescriptionTooLong,
 
        /// The specified route has too many hops and can't be encoded
@@ -1393,6 +1628,11 @@ pub enum CreationError {
        ///
        /// [phantom invoices]: crate::utils::create_phantom_invoice
        MissingRouteHints,
+
+       /// The provided `min_final_cltv_expiry_delta` was less than [`MIN_FINAL_CLTV_EXPIRY_DELTA`].
+       ///
+       /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA
+       MinFinalCltvExpiryDeltaTooShort,
 }
 
 impl Display for CreationError {
@@ -1403,6 +1643,8 @@ impl Display for CreationError {
                        CreationError::TimestampOutOfBounds => f.write_str("The Unix timestamp of the supplied date is less than zero or greater than 35-bits"),
                        CreationError::InvalidAmount => f.write_str("The supplied millisatoshi amount was greater than the total bitcoin supply"),
                        CreationError::MissingRouteHints => f.write_str("The invoice required route hints and they weren't provided"),
+                       CreationError::MinFinalCltvExpiryDeltaTooShort => f.write_str(
+                               "The supplied final CLTV expiry delta was less than LDK's `MIN_FINAL_CLTV_EXPIRY_DELTA`"),
                }
        }
 }
@@ -1410,10 +1652,10 @@ impl Display for CreationError {
 #[cfg(feature = "std")]
 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
+/// Errors that may occur when converting a [`RawBolt11Invoice`] to a [`Bolt11Invoice`]. They relate to
+/// the requirements sections in BOLT #11
 #[derive(Eq, PartialEq, Debug, Clone)]
-pub enum SemanticError {
+pub enum Bolt11SemanticError {
        /// The invoice is missing the mandatory payment hash
        NoPaymentHash,
 
@@ -1446,27 +1688,27 @@ pub enum SemanticError {
        ImpreciseAmount,
 }
 
-impl Display for SemanticError {
+impl Display for Bolt11SemanticError {
        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::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"),
+                       Bolt11SemanticError::NoPaymentHash => f.write_str("The invoice is missing the mandatory payment hash"),
+                       Bolt11SemanticError::MultiplePaymentHashes => f.write_str("The invoice has multiple payment hashes which isn't allowed"),
+                       Bolt11SemanticError::NoDescription => f.write_str("No description or description hash are part of the invoice"),
+                       Bolt11SemanticError::MultipleDescriptions => f.write_str("The invoice contains multiple descriptions and/or description hashes which isn't allowed"),
+                       Bolt11SemanticError::NoPaymentSecret => f.write_str("The invoice is missing the mandatory payment secret"),
+                       Bolt11SemanticError::MultiplePaymentSecrets => f.write_str("The invoice contains multiple payment secrets"),
+                       Bolt11SemanticError::InvalidFeatures => f.write_str("The invoice's features are invalid"),
+                       Bolt11SemanticError::InvalidRecoveryId => f.write_str("The recovery id doesn't fit the signature/pub key"),
+                       Bolt11SemanticError::InvalidSignature => f.write_str("The invoice's signature is invalid"),
+                       Bolt11SemanticError::ImpreciseAmount => f.write_str("The invoice's amount was not a whole number of millisatoshis"),
                }
        }
 }
 
 #[cfg(feature = "std")]
-impl std::error::Error for SemanticError { }
+impl std::error::Error for Bolt11SemanticError { }
 
-/// When signing using a fallible method either an user-supplied `SignError` or a `CreationError`
+/// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`]
 /// may occur.
 #[derive(Eq, PartialEq, Debug, Clone)]
 pub enum SignOrCreationError<S = ()> {
@@ -1486,25 +1728,43 @@ impl<S> Display for SignOrCreationError<S> {
        }
 }
 
+#[cfg(feature = "serde")]
+impl Serialize for Bolt11Invoice {
+       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 Bolt11Invoice {
+       fn deserialize<D>(deserializer: D) -> Result<Bolt11Invoice, D::Error> where D: Deserializer<'de> {
+               let bolt11 = String::deserialize(deserializer)?
+                       .parse::<Bolt11Invoice>()
+                       .map_err(|e| D::Error::custom(format_args!("{:?}", e)))?;
+
+               Ok(bolt11)
+       }
+}
+
 #[cfg(test)]
 mod test {
+       use bitcoin::Script;
        use bitcoin_hashes::hex::FromHex;
        use bitcoin_hashes::sha256;
 
        #[test]
        fn test_system_time_bounds_assumptions() {
                assert_eq!(
-                       ::PositiveTimestamp::from_unix_timestamp(::MAX_TIMESTAMP + 1),
-                       Err(::CreationError::TimestampOutOfBounds)
+                       crate::PositiveTimestamp::from_unix_timestamp(crate::MAX_TIMESTAMP + 1),
+                       Err(crate::CreationError::TimestampOutOfBounds)
                );
        }
 
        #[test]
        fn test_calc_invoice_hash() {
-               use ::{RawInvoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
-               use ::TaggedField::*;
+               use crate::{RawBolt11Invoice, RawHrp, RawDataPart, Currency, PositiveTimestamp};
+               use crate::TaggedField::*;
 
-               let invoice = RawInvoice {
+               let invoice = RawBolt11Invoice {
                        hrp: RawHrp {
                                currency: Currency::Bitcoin,
                                raw_amount: None,
@@ -1513,10 +1773,10 @@ mod test {
                        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(),
                                ],
@@ -1529,20 +1789,20 @@ mod test {
                        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::{SignedRawBolt11Invoice, Bolt11InvoiceSignature, RawBolt11Invoice, RawHrp, RawDataPart, Currency, Sha256,
                         PositiveTimestamp};
 
-               let invoice = SignedRawInvoice {
-                       raw_invoice: RawInvoice {
+               let invoice = SignedRawBolt11Invoice {
+                       raw_invoice: RawBolt11Invoice {
                                hrp: RawHrp {
                                        currency: Currency::Bitcoin,
                                        raw_amount: None,
@@ -1555,7 +1815,7 @@ mod test {
                                                        "0001020304050607080900010203040506070809000102030405060708090102"
                                                ).unwrap())).into(),
                                                Description(
-                                                       ::Description::new(
+                                                       crate::Description::new(
                                                                "Please consider supporting this project".to_owned()
                                                        ).unwrap()
                                                ).into(),
@@ -1567,7 +1827,7 @@ mod test {
                                0x7b, 0x1d, 0x85, 0x8d, 0xb1, 0xd1, 0xf7, 0xab, 0x71, 0x37, 0xdc, 0xb7,
                                0x83, 0x5d, 0xb2, 0xec, 0xd5, 0x18, 0xe1, 0xc9
                        ],
-                       signature: InvoiceSignature(RecoverableSignature::from_compact(
+                       signature: Bolt11InvoiceSignature(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,
@@ -1591,11 +1851,11 @@ mod test {
                ).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());
@@ -1603,16 +1863,16 @@ mod test {
 
        #[test]
        fn test_check_feature_bits() {
-               use TaggedField::*;
-               use lightning::ln::features::InvoiceFeatures;
+               use crate::TaggedField::*;
+               use lightning::ln::features::Bolt11InvoiceFeatures;
                use secp256k1::Secp256k1;
-               use secp256k1::key::SecretKey;
-               use {RawInvoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, Invoice,
-                        SemanticError};
+               use secp256k1::SecretKey;
+               use crate::{Bolt11Invoice, RawBolt11Invoice, RawHrp, RawDataPart, Currency, Sha256, PositiveTimestamp, 
+                        Bolt11SemanticError};
 
                let private_key = SecretKey::from_slice(&[42; 32]).unwrap();
                let payment_secret = lightning::ln::PaymentSecret([21; 32]);
-               let invoice_template = RawInvoice {
+               let invoice_template = RawBolt11Invoice {
                        hrp: RawHrp {
                                currency: Currency::Bitcoin,
                                raw_amount: None,
@@ -1625,7 +1885,7 @@ mod test {
                                                "0001020304050607080900010203040506070809000102030405060708090102"
                                        ).unwrap())).into(),
                                        Description(
-                                               ::Description::new(
+                                               crate::Description::new(
                                                        "Please consider supporting this project".to_owned()
                                                ).unwrap()
                                        ).into(),
@@ -1637,64 +1897,67 @@ mod test {
                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));
+               assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::InvalidFeatures));
 
                // Missing 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::empty()).into());
-                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+                       invoice.data.tagged_fields.push(Features(Bolt11InvoiceFeatures::empty()).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!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::InvalidFeatures));
+
+               let mut payment_secret_features = Bolt11InvoiceFeatures::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());
+               assert!(Bolt11Invoice::from_signed(invoice).is_ok());
 
                // No payment secret or features
                let invoice = {
                        let invoice = invoice_template.clone();
-                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
                }.unwrap();
-               assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
+               assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::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.data.tagged_fields.push(Features(Bolt11InvoiceFeatures::empty()).into());
+                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
                }.unwrap();
-               assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
+               assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::NoPaymentSecret));
 
                // Missing payment secret
                let invoice = {
                        let mut invoice = invoice_template.clone();
-                       invoice.data.tagged_fields.push(Features(InvoiceFeatures::known()).into());
-                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+                       invoice.data.tagged_fields.push(Features(payment_secret_features).into());
+                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
                }.unwrap();
-               assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::NoPaymentSecret));
+               assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::NoPaymentSecret));
 
                // Multiple payment secrets
                let invoice = {
-                       let mut invoice = invoice_template.clone();
+                       let mut invoice = invoice_template;
                        invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
                        invoice.data.tagged_fields.push(PaymentSecret(payment_secret).into());
-                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_recoverable(hash, &private_key)))
+                       invoice.sign::<_, ()>(|hash| Ok(Secp256k1::new().sign_ecdsa_recoverable(hash, &private_key)))
                }.unwrap();
-               assert_eq!(Invoice::from_signed(invoice), Err(SemanticError::MultiplePaymentSecrets));
+               assert_eq!(Bolt11Invoice::from_signed(invoice), Err(Bolt11SemanticError::MultiplePaymentSecrets));
        }
 
        #[test]
        fn test_builder_amount() {
-               use ::*;
+               use crate::*;
 
                let builder = InvoiceBuilder::new(Currency::Bitcoin)
                        .description("Test".into())
@@ -1710,7 +1973,7 @@ mod test {
                assert_eq!(invoice.hrp.raw_amount, Some(15));
 
 
-               let invoice = builder.clone()
+               let invoice = builder
                        .amount_milli_satoshis(150)
                        .build_raw()
                        .unwrap();
@@ -1721,15 +1984,15 @@ mod test {
 
        #[test]
        fn test_builder_fail() {
-               use ::*;
+               use crate::*;
                use lightning::routing::router::RouteHintHop;
                use std::iter::FromIterator;
-               use secp256k1::key::PublicKey;
+               use secp256k1::PublicKey;
 
                let builder = InvoiceBuilder::new(Currency::Bitcoin)
                        .payment_hash(sha256::Hash::from_slice(&[0;32][..]).unwrap())
                        .duration_since_epoch(Duration::from_secs(1234567))
-                       .min_final_cltv_expiry(144);
+                       .min_final_cltv_expiry_delta(144);
 
                let too_long_string = String::from_iter(
                        (0..1024).map(|_| '?')
@@ -1764,7 +2027,7 @@ mod test {
                        .build_raw();
                assert_eq!(long_route_res, Err(CreationError::RouteTooLong));
 
-               let sign_error_res = builder.clone()
+               let sign_error_res = builder
                        .description("Test".into())
                        .payment_secret(PaymentSecret([0; 32]))
                        .try_build_signed(|_| {
@@ -1775,10 +2038,10 @@ mod test {
 
        #[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();
@@ -1794,7 +2057,7 @@ mod test {
 
                let route_1 = RouteHint(vec![
                        RouteHintHop {
-                               src_node_id: public_key.clone(),
+                               src_node_id: public_key,
                                short_channel_id: de::parse_int_be(&[123; 8], 256).expect("short chan ID slice too big?"),
                                fees: RoutingFees {
                                        base_msat: 2,
@@ -1805,7 +2068,7 @@ mod test {
                                htlc_maximum_msat: None,
                        },
                        RouteHintHop {
-                               src_node_id: public_key.clone(),
+                               src_node_id: public_key,
                                short_channel_id: de::parse_int_be(&[42; 8], 256).expect("short chan ID slice too big?"),
                                fees: RoutingFees {
                                        base_msat: 3,
@@ -1819,7 +2082,7 @@ mod test {
 
                let route_2 = RouteHint(vec![
                        RouteHintHop {
-                               src_node_id: public_key.clone(),
+                               src_node_id: public_key,
                                short_channel_id: 0,
                                fees: RoutingFees {
                                        base_msat: 4,
@@ -1830,7 +2093,7 @@ mod test {
                                htlc_maximum_msat: None,
                        },
                        RouteHintHop {
-                               src_node_id: public_key.clone(),
+                               src_node_id: public_key,
                                short_channel_id: de::parse_int_be(&[1; 8], 256).expect("short chan ID slice too big?"),
                                fees: RoutingFees {
                                        base_msat: 5,
@@ -1845,10 +2108,10 @@ mod test {
                let builder = InvoiceBuilder::new(Currency::BitcoinTestnet)
                        .amount_milli_satoshis(123)
                        .duration_since_epoch(Duration::from_secs(1234567))
-                       .payee_pub_key(public_key.clone())
+                       .payee_pub_key(public_key)
                        .expiry_time(Duration::from_secs(54321))
-                       .min_final_cltv_expiry(144)
-                       .fallback(Fallback::PubKeyHash([0;20]))
+                       .min_final_cltv_expiry_delta(144)
+                       .fallback(Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap()))
                        .private_route(route_1.clone())
                        .private_route(route_2.clone())
                        .description_hash(sha256::Hash::from_slice(&[3;32][..]).unwrap())
@@ -1857,7 +2120,7 @@ mod test {
                        .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());
@@ -1873,16 +2136,23 @@ mod test {
                );
                assert_eq!(invoice.payee_pub_key(), Some(&public_key));
                assert_eq!(invoice.expiry_time(), Duration::from_secs(54321));
-               assert_eq!(invoice.min_final_cltv_expiry(), 144);
-               assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]);
+               assert_eq!(invoice.min_final_cltv_expiry_delta(), 144);
+               assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash(PubkeyHash::from_slice(&[0;20]).unwrap())]);
+               let address = Address::from_script(&Script::new_p2pkh(&PubkeyHash::from_slice(&[0;20]).unwrap()), Network::Testnet).unwrap();
+               assert_eq!(invoice.fallback_addresses(), vec![address]);
                assert_eq!(invoice.private_routes(), vec![&PrivateRoute(route_1), &PrivateRoute(route_2)]);
                assert_eq!(
                        invoice.description(),
-                       InvoiceDescription::Hash(&Sha256(sha256::Hash::from_slice(&[3;32][..]).unwrap()))
+                       Bolt11InvoiceDescription::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(), &PaymentSecret([42; 32]));
-               assert_eq!(invoice.features(), Some(&InvoiceFeatures::known()));
+
+               let mut expected_features = Bolt11InvoiceFeatures::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())
@@ -1890,9 +2160,9 @@ mod test {
 
        #[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())
@@ -1904,21 +2174,21 @@ mod test {
                        .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();
+               let invoice = Bolt11Invoice::from_signed(signed_invoice).unwrap();
 
-               assert_eq!(invoice.min_final_cltv_expiry(), DEFAULT_MIN_FINAL_CLTV_EXPIRY);
+               assert_eq!(invoice.min_final_cltv_expiry_delta(), DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA);
                assert_eq!(invoice.expiry_time(), Duration::from_secs(DEFAULT_EXPIRY_TIME));
                assert!(!invoice.would_expire(Duration::from_secs(1234568)));
        }
 
        #[test]
        fn test_expiration() {
-               use ::*;
+               use crate::*;
                use secp256k1::Secp256k1;
-               use secp256k1::key::SecretKey;
+               use secp256k1::SecretKey;
 
                let signed_invoice = InvoiceBuilder::new(Currency::Bitcoin)
                        .description("Test".into())
@@ -1930,11 +2200,33 @@ mod test {
                        .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();
+               let invoice = Bolt11Invoice::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::Bolt11Invoice>().unwrap();
+               let serialized_invoice = serde_json::to_string(&invoice).unwrap();
+               let deserialized_invoice: super::Bolt11Invoice = 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('\"'));
+       }
 }