X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-invoice%2Fsrc%2Flib.rs;h=94a93fe62b7f1d160c5f1dc0c89ba66b56bf34c1;hb=68149a204f9da3462f15cc108b5efe7a054cd27b;hp=593701cab458c85079dff3e135dcebbf63845277;hpb=ba1349982ba28657c9e2d03a5b02c3ecc054b5cc;p=rust-lightning diff --git a/lightning-invoice/src/lib.rs b/lightning-invoice/src/lib.rs index 593701ca..94a93fe6 100644 --- a/lightning-invoice/src/lib.rs +++ b/lightning-invoice/src/lib.rs @@ -18,9 +18,11 @@ //! 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::(&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::(&self)` (see [`Invoice::from_str`]) +//! * For constructing invoices use the [`InvoiceBuilder`] +//! * For serializing invoices use the [`Display`]/[`ToString`] traits +//! +//! [`Invoice::from_str`]: crate::Invoice#impl-FromStr #[cfg(not(any(feature = "std", feature = "no-std")))] compile_error!("at least one of the `std` or `no-std` features must be enabled"); @@ -45,8 +47,9 @@ extern crate serde; use std::time::SystemTime; use bech32::u5; -use bitcoin_hashes::Hash; -use bitcoin_hashes::sha256; +use bitcoin::{Address, Network, PubkeyHash, ScriptHash}; +use bitcoin::util::address::{Payload, WitnessVersion}; +use bitcoin_hashes::{Hash, sha256}; use lightning::ln::PaymentSecret; use lightning::ln::features::InvoiceFeatures; #[cfg(any(doc, test))] @@ -160,7 +163,7 @@ pub const DEFAULT_EXPIRY_TIME: u64 = 3600; /// [`MIN_FINAL_CLTV_EXPIRY_DELTA`]: lightning::ln::channelmanager::MIN_FINAL_CLTV_EXPIRY_DELTA pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: u64 = 18; -/// Builder for `Invoice`s. It's the most convenient and advised way to use this library. It ensures +/// Builder for [`Invoice`]s. It's the most convenient and advised way to use this library. It ensures /// that only a semantically and syntactically correct Invoice can be built using it. /// /// ``` @@ -212,8 +215,8 @@ pub const DEFAULT_MIN_FINAL_CLTV_EXPIRY_DELTA: 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 /// /// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters. @@ -236,9 +239,11 @@ pub struct InvoiceBuilder(&str)` +/// 1. using [`InvoiceBuilder`] +/// 2. using [`Invoice::from_signed`] +/// 3. using `str::parse::(&str)` (see [`Invoice::from_str`]) +/// +/// [`Invoice::from_str`]: crate::Invoice#impl-FromStr #[derive(Eq, PartialEq, Debug, Clone, Hash)] pub struct Invoice { signed_invoice: SignedRawInvoice, @@ -258,34 +263,34 @@ pub enum InvoiceDescription<'f> { Hash(&'f Sha256), } -/// Represents a signed `RawInvoice` with cached hash. The signature is not checked and may be +/// Represents a signed [`RawInvoice`] with cached hash. The signature is not checked and may be /// invalid. /// /// # Invariants -/// The hash has to be either from the deserialized invoice or from the serialized `raw_invoice`. +/// The hash has to be either from the deserialized invoice or from the serialized [`RawInvoice`]. #[derive(Eq, PartialEq, Debug, Clone, Hash)] pub struct SignedRawInvoice { /// The rawInvoice that the signature belongs to raw_invoice: RawInvoice, - /// Hash of the `RawInvoice` that will be used to check the signature. + /// Hash of the [`RawInvoice`] that will be used to check the signature. /// /// * if the `SignedRawInvoice` was deserialized the hash is of from the original encoded form, /// since it's not guaranteed that encoding it again will lead to the same result since integers /// could have been encoded with leading zeroes etc. /// * if the `SignedRawInvoice` was constructed manually the hash will be the calculated hash - /// from the `RawInvoice` + /// from the [`RawInvoice`] hash: [u8; 32], /// signature of the payment request signature: InvoiceSignature, } -/// Represents an syntactically correct Invoice for a payment on the lightning network, +/// Represents an syntactically correct [`Invoice`] for a payment on the lightning network, /// but without the signature information. -/// De- and encoding should not lead to information loss but may lead to different hashes. +/// Decoding and encoding should not lead to information loss but may lead to different hashes. /// -/// For methods without docs see the corresponding methods in `Invoice`. +/// For methods without docs see the corresponding methods in [`Invoice`]. #[derive(Eq, PartialEq, Debug, Clone, Hash)] pub struct RawInvoice { /// human readable part @@ -295,7 +300,7 @@ pub struct RawInvoice { pub data: RawDataPart, } -/// Data of the `RawInvoice` that is encoded in the human readable part +/// Data of the [`RawInvoice`] that is encoded in the human readable part. /// /// This is not exported to bindings users as we don't yet support `Option` #[derive(Eq, PartialEq, Debug, Clone, Hash)] @@ -310,7 +315,7 @@ pub struct RawHrp { pub si_prefix: Option, } -/// Data of the `RawInvoice` that is encoded in the data part +/// Data of the [`RawInvoice`] that is encoded in the data part #[derive(Eq, PartialEq, Debug, Clone, Hash)] pub struct RawDataPart { /// generation time of the invoice @@ -385,6 +390,29 @@ pub enum Currency { Signet, } +impl From 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 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 /// /// This is not exported to bindings users as we don't currently support TaggedField @@ -442,17 +470,16 @@ pub struct ExpiryTime(Duration); #[derive(Clone, Debug, Hash, Eq, PartialEq)] pub struct MinFinalCltvExpiryDelta(pub u64); -// TODO: better types instead onf byte arrays /// Fallback address in case no LN payment is possible #[allow(missing_docs)] #[derive(Clone, Debug, Hash, Eq, PartialEq)] pub enum Fallback { SegWitProgram { - version: u5, + version: WitnessVersion, program: Vec, }, - PubKeyHash([u8; 20]), - ScriptHash([u8; 20]), + PubKeyHash(PubkeyHash), + ScriptHash(ScriptHash), } /// Recoverable signature @@ -564,7 +591,8 @@ impl InvoiceBui } impl InvoiceBuilder { - /// Builds a `RawInvoice` if no `CreationError` occurred while construction any of the fields. + /// Builds a [`RawInvoice`] if no [`CreationError`] occurred while construction any of the + /// fields. pub fn build_raw(self) -> Result { // If an error occurred at any time before, return it now @@ -753,17 +781,17 @@ impl SignedRawInvoice { (self.raw_invoice, self.hash, self.signature) } - /// The `RawInvoice` which was signed. + /// The [`RawInvoice`] which was signed. pub fn raw_invoice(&self) -> &RawInvoice { &self.raw_invoice } - /// The hash of the `RawInvoice` that was signed. + /// The hash of the [`RawInvoice`] that was signed. pub fn signable_hash(&self) -> &[u8; 32] { &self.hash } - /// InvoiceSignature for the invoice. + /// Signature for the invoice. pub fn signature(&self) -> &InvoiceSignature { &self.signature } @@ -881,8 +909,8 @@ impl RawInvoice { ) } - /// Signs the invoice using the supplied `sign_function`. This function MAY fail with an error - /// of type `E`. Since the signature of a `SignedRawInvoice` is not required to be valid there + /// Signs the invoice using the supplied `sign_method`. This function MAY fail with an error of + /// type `E`. Since the signature of a [`SignedRawInvoice`] is not required to be valid there /// are no constraints regarding the validity of the produced signature. /// /// This is not exported to bindings users as we don't currently support passing function pointers into methods @@ -1033,6 +1061,11 @@ impl From for SystemTime { } impl Invoice { + /// The hash of the [`RawInvoice`] that was signed. + pub fn signable_hash(&self) -> [u8; 32] { + self.signed_invoice.hash + } + /// Transform the `Invoice` into it's unchecked version pub fn into_signed_raw(self) -> SignedRawInvoice { self.signed_invoice @@ -1137,7 +1170,7 @@ impl Invoice { Ok(()) } - /// Constructs an `Invoice` from a `SignedRawInvoice` by checking all its invariants. + /// Constructs an `Invoice` from a [`SignedRawInvoice`] by checking all its invariants. /// ``` /// use lightning_invoice::*; /// @@ -1290,6 +1323,25 @@ impl Invoice { self.signed_invoice.fallbacks() } + /// Returns a list of all fallback addresses as [`Address`]es + pub fn fallback_addresses(&self) -> Vec
{ + 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() @@ -1307,6 +1359,13 @@ 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 { self.signed_invoice.amount_pico_btc().map(|v| v / 10) @@ -1347,7 +1406,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 { @@ -1358,7 +1417,7 @@ impl Description { } } - /// Returns the underlying description `String` + /// Returns the underlying description [`String`] pub fn into_inner(self) -> String { self.0 } @@ -1398,7 +1457,7 @@ impl ExpiryTime { ExpiryTime(Duration::from_secs(seconds)) } - /// Construct an `ExpiryTime` from a `Duration`, dropping the sub-second part. + /// Construct an `ExpiryTime` from a [`Duration`], dropping the sub-second part. pub fn from_duration(duration: Duration) -> ExpiryTime { Self::from_seconds(duration.as_secs()) } @@ -1408,7 +1467,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 } @@ -1460,10 +1519,10 @@ impl Deref for SignedRawInvoice { } } -/// Errors that may occur when constructing a new `RawInvoice` or `Invoice` +/// Errors that may occur when constructing a new [`RawInvoice`] or [`Invoice`] #[derive(Eq, PartialEq, Debug, Clone)] pub enum CreationError { - /// The supplied description string was longer than 639 __bytes__ (see [`Description::new(…)`](./struct.Description.html#method.new)) + /// The supplied description string was longer than 639 __bytes__ (see [`Description::new`]) DescriptionTooLong, /// The specified route has too many hops and can't be encoded @@ -1504,7 +1563,7 @@ 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 +/// Errors that may occur when converting a [`RawInvoice`] to an [`Invoice`]. They relate to the /// requirements sections in BOLT #11 #[derive(Eq, PartialEq, Debug, Clone)] pub enum SemanticError { @@ -1560,7 +1619,7 @@ impl Display for SemanticError { #[cfg(feature = "std")] impl std::error::Error for SemanticError { } -/// When signing using a fallible method either an user-supplied `SignError` or a `CreationError` +/// When signing using a fallible method either an user-supplied `SignError` or a [`CreationError`] /// may occur. #[derive(Eq, PartialEq, Debug, Clone)] pub enum SignOrCreationError { @@ -1591,7 +1650,7 @@ impl<'de> Deserialize<'de> for Invoice { fn deserialize(deserializer: D) -> Result where D: Deserializer<'de> { let bolt11 = String::deserialize(deserializer)? .parse::() - .map_err(|e| D::Error::custom(format!("{:?}", e)))?; + .map_err(|e| D::Error::custom(alloc::format!("{:?}", e)))?; Ok(bolt11) } @@ -1599,6 +1658,7 @@ impl<'de> Deserialize<'de> for Invoice { #[cfg(test)] mod test { + use bitcoin::Script; use bitcoin_hashes::hex::FromHex; use bitcoin_hashes::sha256; @@ -1962,7 +2022,7 @@ mod test { .payee_pub_key(public_key) .expiry_time(Duration::from_secs(54321)) .min_final_cltv_expiry_delta(144) - .fallback(Fallback::PubKeyHash([0;20])) + .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()) @@ -1988,7 +2048,9 @@ 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_delta(), 144); - assert_eq!(invoice.fallbacks(), vec![&Fallback::PubKeyHash([0;20])]); + 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(),