use {CreationError, Currency, DEFAULT_EXPIRY_TIME, Invoice, InvoiceBuilder, SignOrCreationError};
use payment::{Payer, Router};
+use crate::{prelude::*, Description, InvoiceDescription, Sha256};
use bech32::ToBase32;
use bitcoin_hashes::{Hash, sha256};
-use crate::prelude::*;
use lightning::chain;
use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
use lightning::chain::keysinterface::{Recipient, KeysInterface, Sign};
use lightning::ln::channelmanager::{ChannelDetails, ChannelManager, PaymentId, PaymentSendFailure, MIN_FINAL_CLTV_EXPIRY};
#[cfg(feature = "std")]
use lightning::ln::channelmanager::{PhantomRouteHints, MIN_CLTV_EXPIRY_DELTA};
+use lightning::ln::inbound_payment::{create, create_from_hash, ExpandedKey};
use lightning::ln::msgs::LightningError;
use lightning::routing::scoring::Score;
use lightning::routing::network_graph::{NetworkGraph, RoutingFees};
/// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
/// down
///
-/// `payment_hash` and `payment_secret` come from [`ChannelManager::create_inbound_payment`] or
-/// [`ChannelManager::create_inbound_payment_for_hash`]. These values can be retrieved from any
-/// participating node.
+/// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
+/// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
+/// If `None` is provided for `payment_hash`, then one will be created.
+///
+/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
+/// in excess of the current time.
///
/// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom
/// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
///
/// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager
/// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
+/// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
+/// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
/// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
pub fn create_phantom_invoice<Signer: Sign, K: Deref>(
- amt_msat: Option<u64>, description: String, payment_hash: PaymentHash, payment_secret:
- PaymentSecret, phantom_route_hints: Vec<PhantomRouteHints>, keys_manager: K, network: Currency
+ amt_msat: Option<u64>, payment_hash: Option<PaymentHash>, description: String, invoice_expiry_delta_secs: u32,
+ phantom_route_hints: Vec<PhantomRouteHints>, keys_manager: K, network: Currency,
) -> Result<Invoice, SignOrCreationError<()>> where K::Target: KeysInterface {
+ let description = Description::new(description).map_err(SignOrCreationError::CreationError)?;
+ let description = InvoiceDescription::Direct(&description,);
+ _create_phantom_invoice::<Signer, K>(
+ amt_msat, payment_hash, description, invoice_expiry_delta_secs, phantom_route_hints, keys_manager, network,
+ )
+}
+
+#[cfg(feature = "std")]
+/// Utility to create an invoice that can be paid to one of multiple nodes, or a "phantom invoice."
+/// See [`PhantomKeysManager`] for more information on phantom node payments.
+///
+/// `phantom_route_hints` parameter:
+/// * Contains channel info for all nodes participating in the phantom invoice
+/// * Entries are retrieved from a call to [`ChannelManager::get_phantom_route_hints`] on each
+/// participating node
+/// * It is fine to cache `phantom_route_hints` and reuse it across invoices, as long as the data is
+/// updated when a channel becomes disabled or closes
+/// * Note that if too many channels are included in [`PhantomRouteHints::channels`], the invoice
+/// may be too long for QR code scanning. To fix this, `PhantomRouteHints::channels` may be pared
+/// down
+///
+/// `description_hash` is a SHA-256 hash of the description text
+///
+/// `payment_hash` can be specified if you have a specific need for a custom payment hash (see the difference
+/// between [`ChannelManager::create_inbound_payment`] and [`ChannelManager::create_inbound_payment_for_hash`]).
+/// If `None` is provided for `payment_hash`, then one will be created.
+///
+/// `invoice_expiry_delta_secs` describes the number of seconds that the invoice is valid for
+/// in excess of the current time.
+///
+/// Note that the provided `keys_manager`'s `KeysInterface` implementation must support phantom
+/// invoices in its `sign_invoice` implementation ([`PhantomKeysManager`] satisfies this
+/// requirement).
+///
+/// [`PhantomKeysManager`]: lightning::chain::keysinterface::PhantomKeysManager
+/// [`ChannelManager::get_phantom_route_hints`]: lightning::ln::channelmanager::ChannelManager::get_phantom_route_hints
+/// [`ChannelManager::create_inbound_payment`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment
+/// [`ChannelManager::create_inbound_payment_for_hash`]: lightning::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
+/// [`PhantomRouteHints::channels`]: lightning::ln::channelmanager::PhantomRouteHints::channels
+pub fn create_phantom_invoice_with_description_hash<Signer: Sign, K: Deref>(
+ amt_msat: Option<u64>, payment_hash: Option<PaymentHash>, invoice_expiry_delta_secs: u32,
+ description_hash: Sha256, phantom_route_hints: Vec<PhantomRouteHints>, keys_manager: K, network: Currency,
+) -> Result<Invoice, SignOrCreationError<()>> where K::Target: KeysInterface
+{
+ _create_phantom_invoice::<Signer, K>(
+ amt_msat, payment_hash, InvoiceDescription::Hash(&description_hash),
+ invoice_expiry_delta_secs, phantom_route_hints, keys_manager, network,
+ )
+}
+
+#[cfg(feature = "std")]
+fn _create_phantom_invoice<Signer: Sign, K: Deref>(
+ amt_msat: Option<u64>, payment_hash: Option<PaymentHash>, description: InvoiceDescription,
+ invoice_expiry_delta_secs: u32, phantom_route_hints: Vec<PhantomRouteHints>, keys_manager: K, network: Currency,
+) -> Result<Invoice, SignOrCreationError<()>> where K::Target: KeysInterface
+{
+ use std::time::{SystemTime, UNIX_EPOCH};
+
if phantom_route_hints.len() == 0 {
- return Err(SignOrCreationError::CreationError(CreationError::MissingRouteHints))
+ return Err(SignOrCreationError::CreationError(
+ CreationError::MissingRouteHints,
+ ));
}
- let mut invoice = InvoiceBuilder::new(network)
- .description(description)
+ let invoice = match description {
+ InvoiceDescription::Direct(description) => {
+ InvoiceBuilder::new(network).description(description.0.clone())
+ }
+ InvoiceDescription::Hash(hash) => InvoiceBuilder::new(network).description_hash(hash.0),
+ };
+
+ // If we ever see performance here being too slow then we should probably take this ExpandedKey as a parameter instead.
+ let keys = ExpandedKey::new(&keys_manager.get_inbound_payment_key_material());
+ let (payment_hash, payment_secret) = if let Some(payment_hash) = payment_hash {
+ let payment_secret = create_from_hash(
+ &keys,
+ amt_msat,
+ payment_hash,
+ invoice_expiry_delta_secs,
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .expect("Time must be > 1970")
+ .as_secs(),
+ )
+ .map_err(|_| SignOrCreationError::CreationError(CreationError::InvalidAmount))?;
+ (payment_hash, payment_secret)
+ } else {
+ create(
+ &keys,
+ amt_msat,
+ invoice_expiry_delta_secs,
+ &keys_manager,
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .expect("Time must be > 1970")
+ .as_secs(),
+ )
+ .map_err(|_| SignOrCreationError::CreationError(CreationError::InvalidAmount))?
+ };
+
+ let mut invoice = invoice
.current_timestamp()
.payment_hash(Hash::from_slice(&payment_hash.0).unwrap())
.payment_secret(payment_secret)
let duration = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
.expect("for the foreseeable future this shouldn't happen");
create_invoice_from_channelmanager_and_duration_since_epoch(
- channelmanager,
- keys_manager,
- network,
- amt_msat,
- description,
- duration
+ channelmanager, keys_manager, network, amt_msat, description, duration
+ )
+}
+
+#[cfg(feature = "std")]
+/// Utility to construct an invoice. Generally, unless you want to do something like a custom
+/// cltv_expiry, this is what you should be using to create an invoice. The reason being, this
+/// method stores the invoice's payment secret and preimage in `ChannelManager`, so (a) the user
+/// doesn't have to store preimage/payment secret information and (b) `ChannelManager` can verify
+/// that the payment secret is valid when the invoice is paid.
+/// Use this variant if you want to pass the `description_hash` to the invoice.
+pub fn create_invoice_from_channelmanager_with_description_hash<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
+ channelmanager: &ChannelManager<Signer, M, T, K, F, L>, keys_manager: K, network: Currency,
+ amt_msat: Option<u64>, description_hash: Sha256,
+) -> Result<Invoice, SignOrCreationError<()>>
+where
+ M::Target: chain::Watch<Signer>,
+ T::Target: BroadcasterInterface,
+ K::Target: KeysInterface<Signer = Signer>,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+{
+ use std::time::SystemTime;
+
+ let duration = SystemTime::now()
+ .duration_since(SystemTime::UNIX_EPOCH)
+ .expect("for the foreseeable future this shouldn't happen");
+
+ create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(
+ channelmanager, keys_manager, network, amt_msat, description_hash, duration,
+ )
+}
+
+/// See [`create_invoice_from_channelmanager_with_description_hash`]
+/// This version can be used in a `no_std` environment, where [`std::time::SystemTime`] is not
+/// available and the current time is supplied by the caller.
+pub fn create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
+ channelmanager: &ChannelManager<Signer, M, T, K, F, L>, keys_manager: K, network: Currency,
+ amt_msat: Option<u64>, description_hash: Sha256, duration_since_epoch: Duration,
+) -> Result<Invoice, SignOrCreationError<()>>
+where
+ M::Target: chain::Watch<Signer>,
+ T::Target: BroadcasterInterface,
+ K::Target: KeysInterface<Signer = Signer>,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+{
+ _create_invoice_from_channelmanager_and_duration_since_epoch(
+ channelmanager, keys_manager, network, amt_msat,
+ InvoiceDescription::Hash(&description_hash),
+ duration_since_epoch,
)
}
channelmanager: &ChannelManager<Signer, M, T, K, F, L>, keys_manager: K, network: Currency,
amt_msat: Option<u64>, description: String, duration_since_epoch: Duration,
) -> Result<Invoice, SignOrCreationError<()>>
+where
+ M::Target: chain::Watch<Signer>,
+ T::Target: BroadcasterInterface,
+ K::Target: KeysInterface<Signer = Signer>,
+ F::Target: FeeEstimator,
+ L::Target: Logger,
+{
+ _create_invoice_from_channelmanager_and_duration_since_epoch(
+ channelmanager, keys_manager, network, amt_msat,
+ InvoiceDescription::Direct(
+ &Description::new(description).map_err(SignOrCreationError::CreationError)?,
+ ),
+ duration_since_epoch,
+ )
+}
+
+fn _create_invoice_from_channelmanager_and_duration_since_epoch<Signer: Sign, M: Deref, T: Deref, K: Deref, F: Deref, L: Deref>(
+ channelmanager: &ChannelManager<Signer, M, T, K, F, L>, keys_manager: K, network: Currency,
+ amt_msat: Option<u64>, description: InvoiceDescription, duration_since_epoch: Duration,
+) -> Result<Invoice, SignOrCreationError<()>>
where
M::Target: chain::Watch<Signer>,
T::Target: BroadcasterInterface,
// `create_inbound_payment` only returns an error if the amount is greater than the total bitcoin
// supply.
- let (payment_hash, payment_secret) = channelmanager.create_inbound_payment(
- amt_msat, DEFAULT_EXPIRY_TIME.try_into().unwrap())
+ let (payment_hash, payment_secret) = channelmanager
+ .create_inbound_payment(amt_msat, DEFAULT_EXPIRY_TIME.try_into().unwrap())
.map_err(|()| SignOrCreationError::CreationError(CreationError::InvalidAmount))?;
let our_node_pubkey = channelmanager.get_our_node_id();
- let mut invoice = InvoiceBuilder::new(network)
- .description(description)
+
+ let invoice = match description {
+ InvoiceDescription::Direct(description) => {
+ InvoiceBuilder::new(network).description(description.0.clone())
+ }
+ InvoiceDescription::Hash(hash) => InvoiceBuilder::new(network).description_hash(hash.0),
+ };
+
+ let mut invoice = invoice
.duration_since_epoch(duration_since_epoch)
.payee_pub_key(our_node_pubkey)
.payment_hash(Hash::from_slice(&payment_hash.0).unwrap())
proportional_millionths: forwarding_info.fee_proportional_millionths,
},
cltv_expiry_delta: forwarding_info.cltv_expiry_delta,
- htlc_minimum_msat: None,
- htlc_maximum_msat: None,}])
+ htlc_minimum_msat: channel.inbound_htlc_minimum_msat,
+ htlc_maximum_msat: channel.inbound_htlc_maximum_msat,}])
};
// If all channels are private, return the route hint for the highest inbound capacity channel
// per counterparty node. If channels with an higher inbound capacity than the
// Invoice SCIDs should always use inbound SCID aliases over the real channel ID, if one is
// available.
+ let chan = &nodes[1].node.list_usable_channels()[0];
assert_eq!(invoice.route_hints().len(), 1);
assert_eq!(invoice.route_hints()[0].0.len(), 1);
- assert_eq!(invoice.route_hints()[0].0[0].short_channel_id,
- nodes[1].node.list_usable_channels()[0].inbound_scid_alias.unwrap());
+ assert_eq!(invoice.route_hints()[0].0[0].short_channel_id, chan.inbound_scid_alias.unwrap());
+
+ assert_eq!(invoice.route_hints()[0].0[0].htlc_minimum_msat, chan.inbound_htlc_minimum_msat);
+ assert_eq!(invoice.route_hints()[0].0[0].htlc_maximum_msat, chan.inbound_htlc_maximum_msat);
let payment_params = PaymentParameters::from_node_id(invoice.recover_payee_pub_key())
.with_features(invoice.features().unwrap().clone())
assert_eq!(events.len(), 2);
}
+ #[test]
+ fn test_create_invoice_with_description_hash() {
+ let chanmon_cfgs = create_chanmon_cfgs(2);
+ let node_cfgs = create_node_cfgs(2, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
+ let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
+ let description_hash = crate::Sha256(Hash::hash("Testing description_hash".as_bytes()));
+ let invoice = ::utils::create_invoice_from_channelmanager_with_description_hash_and_duration_since_epoch(
+ &nodes[1].node, nodes[1].keys_manager, Currency::BitcoinTestnet, Some(10_000),
+ description_hash, Duration::from_secs(1234567),
+ ).unwrap();
+ assert_eq!(invoice.amount_pico_btc(), Some(100_000));
+ assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+ assert_eq!(invoice.description(), InvoiceDescription::Hash(&crate::Sha256(Sha256::hash("Testing description_hash".as_bytes()))));
+ }
+
#[test]
fn test_hints_includes_single_channels_to_nodes() {
let chanmon_cfgs = create_chanmon_cfgs(3);
nodes[2].node.handle_channel_update(&nodes[0].node.get_our_node_id(), &chan_0_2.0);
let payment_amt = 10_000;
- let (payment_preimage, payment_hash, payment_secret) = {
- if user_generated_pmt_hash {
- let payment_preimage = PaymentPreimage([1; 32]);
- let payment_hash = PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner());
- let payment_secret = nodes[1].node.create_inbound_payment_for_hash(payment_hash, Some(payment_amt), 3600).unwrap();
- (payment_preimage, payment_hash, payment_secret)
- } else {
- let (payment_hash, payment_secret) = nodes[1].node.create_inbound_payment(Some(payment_amt), 3600).unwrap();
- let payment_preimage = nodes[1].node.get_payment_preimage(payment_hash, payment_secret).unwrap();
- (payment_preimage, payment_hash, payment_secret)
- }
- };
let route_hints = vec![
nodes[1].node.get_phantom_route_hints(),
nodes[2].node.get_phantom_route_hints(),
];
- let invoice = ::utils::create_phantom_invoice::<EnforcingSigner, &test_utils::TestKeysInterface>(Some(payment_amt), "test".to_string(), payment_hash, payment_secret, route_hints, &nodes[1].keys_manager, Currency::BitcoinTestnet).unwrap();
+
+ let user_payment_preimage = PaymentPreimage([1; 32]);
+ let payment_hash = if user_generated_pmt_hash {
+ Some(PaymentHash(Sha256::hash(&user_payment_preimage.0[..]).into_inner()))
+ } else {
+ None
+ };
+
+ let invoice = ::utils::create_phantom_invoice::<EnforcingSigner, &test_utils::TestKeysInterface>(Some(payment_amt), payment_hash, "test".to_string(), 3600, route_hints, &nodes[1].keys_manager, Currency::BitcoinTestnet).unwrap();
+ let (payment_hash, payment_secret) = (PaymentHash(invoice.payment_hash().into_inner()), *invoice.payment_secret());
+ let payment_preimage = if user_generated_pmt_hash {
+ user_payment_preimage
+ } else {
+ nodes[1].node.get_payment_preimage(payment_hash, payment_secret).unwrap()
+ };
assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
assert_eq!(invoice.description(), InvoiceDescription::Direct(&Description("test".to_string())));
}
}
+ #[test]
+ #[cfg(feature = "std")]
+ fn test_multi_node_hints_has_htlc_min_max_values() {
+ let mut chanmon_cfgs = create_chanmon_cfgs(3);
+ let seed_1 = [42 as u8; 32];
+ let seed_2 = [43 as u8; 32];
+ let cross_node_seed = [44 as u8; 32];
+ chanmon_cfgs[1].keys_manager.backing = PhantomKeysManager::new(&seed_1, 43, 44, &cross_node_seed);
+ chanmon_cfgs[2].keys_manager.backing = PhantomKeysManager::new(&seed_2, 43, 44, &cross_node_seed);
+ let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]);
+ let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+
+ create_unannounced_chan_between_nodes_with_value(&nodes, 0, 1, 100000, 10001, InitFeatures::known(), InitFeatures::known());
+ create_unannounced_chan_between_nodes_with_value(&nodes, 0, 2, 100000, 10001, InitFeatures::known(), InitFeatures::known());
+
+ let payment_amt = 20_000;
+ let (payment_hash, _payment_secret) = nodes[1].node.create_inbound_payment(Some(payment_amt), 3600).unwrap();
+ let route_hints = vec![
+ nodes[1].node.get_phantom_route_hints(),
+ nodes[2].node.get_phantom_route_hints(),
+ ];
+
+ let invoice = ::utils::create_phantom_invoice::<EnforcingSigner, &test_utils::TestKeysInterface>(Some(payment_amt), Some(payment_hash), "test".to_string(), 3600, route_hints, &nodes[1].keys_manager, Currency::BitcoinTestnet).unwrap();
+
+ let chan_0_1 = &nodes[1].node.list_usable_channels()[0];
+ assert_eq!(invoice.route_hints()[0].0[0].htlc_minimum_msat, chan_0_1.inbound_htlc_minimum_msat);
+ assert_eq!(invoice.route_hints()[0].0[0].htlc_maximum_msat, chan_0_1.inbound_htlc_maximum_msat);
+
+ let chan_0_2 = &nodes[2].node.list_usable_channels()[0];
+ assert_eq!(invoice.route_hints()[1].0[0].htlc_minimum_msat, chan_0_2.inbound_htlc_minimum_msat);
+ assert_eq!(invoice.route_hints()[1].0[0].htlc_maximum_msat, chan_0_2.inbound_htlc_maximum_msat);
+ }
+
+ #[test]
+ #[cfg(feature = "std")]
+ fn create_phantom_invoice_with_description_hash() {
+ let chanmon_cfgs = create_chanmon_cfgs(3);
+ let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None, None, None]);
+ let nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+
+ let payment_amt = 20_000;
+ let route_hints = vec![
+ nodes[1].node.get_phantom_route_hints(),
+ nodes[2].node.get_phantom_route_hints(),
+ ];
+
+ let description_hash = crate::Sha256(Hash::hash("Description hash phantom invoice".as_bytes()));
+ let invoice = ::utils::create_phantom_invoice_with_description_hash::<EnforcingSigner,&test_utils::TestKeysInterface>(Some(payment_amt), None, 3600, description_hash, route_hints, &nodes[1].keys_manager, Currency::BitcoinTestnet).unwrap();
+
+ assert_eq!(invoice.amount_pico_btc(), Some(200_000));
+ assert_eq!(invoice.min_final_cltv_expiry(), MIN_FINAL_CLTV_EXPIRY as u64);
+ assert_eq!(invoice.description(), InvoiceDescription::Hash(&crate::Sha256(Sha256::hash("Description hash phantom invoice".as_bytes()))));
+ }
+
#[test]
#[cfg(feature = "std")]
fn test_multi_node_hints_includes_single_channels_to_participating_nodes() {
mut chan_ids_to_match: HashSet<u64>,
nodes_contains_public_channels: bool
){
- let (payment_hash, payment_secret) = invoice_node.node.create_inbound_payment(invoice_amt, 3600).unwrap();
let phantom_route_hints = network_multi_nodes.iter()
.map(|node| node.node.get_phantom_route_hints())
.collect::<Vec<PhantomRouteHints>>();
.map(|route_hint| route_hint.phantom_scid)
.collect::<HashSet<u64>>();
- let invoice = ::utils::create_phantom_invoice::<EnforcingSigner, &test_utils::TestKeysInterface>(invoice_amt, "test".to_string(), payment_hash, payment_secret, phantom_route_hints, &invoice_node.keys_manager, Currency::BitcoinTestnet).unwrap();
+ let invoice = ::utils::create_phantom_invoice::<EnforcingSigner, &test_utils::TestKeysInterface>(invoice_amt, None, "test".to_string(), 3600, phantom_route_hints, &invoice_node.keys_manager, Currency::BitcoinTestnet).unwrap();
let invoice_hints = invoice.private_routes();
projects / rust-lightning / blobdiff