}
}
+/// Used by [`ChannelManager::list_recent_payments`] to express the status of recent payments.
+/// These include payments that have yet to find a successful path, or have unresolved HTLCs.
+#[derive(Debug, PartialEq)]
+pub enum RecentPaymentDetails {
+ /// When a payment is still being sent and awaiting successful delivery.
+ Pending {
+ /// Hash of the payment that is currently being sent but has yet to be fulfilled or
+ /// abandoned.
+ payment_hash: PaymentHash,
+ /// Total amount (in msat, excluding fees) across all paths for this payment,
+ /// not just the amount currently inflight.
+ total_msat: u64,
+ },
+ /// When a pending payment is fulfilled, we continue tracking it until all pending HTLCs have
+ /// been resolved. Upon receiving [`Event::PaymentSent`], we delay for a few minutes before the
+ /// payment is removed from tracking.
+ Fulfilled {
+ /// Hash of the payment that was claimed. `None` for serializations of [`ChannelManager`]
+ /// made before LDK version 0.0.104.
+ payment_hash: Option<PaymentHash>,
+ },
+ /// After a payment is explicitly abandoned by calling [`ChannelManager::abandon_payment`], it
+ /// is marked as abandoned until an [`Event::PaymentFailed`] is generated. A payment could also
+ /// be marked as abandoned if pathfinding fails repeatedly or retries have been exhausted.
+ Abandoned {
+ /// Hash of the payment that we have given up trying to send.
+ payment_hash: PaymentHash,
+ },
+}
+
/// Route hints used in constructing invoices for [phantom node payents].
///
/// [phantom node payments]: crate::chain::keysinterface::PhantomKeysManager
self.list_channels_with_filter(|&(_, ref channel)| channel.is_live())
}
+ /// Returns in an undefined order recent payments that -- if not fulfilled -- have yet to find a
+ /// successful path, or have unresolved HTLCs.
+ ///
+ /// This can be useful for payments that may have been prepared, but ultimately not sent, as a
+ /// result of a crash. If such a payment exists, is not listed here, and an
+ /// [`Event::PaymentSent`] has not been received, you may consider retrying the payment.
+ ///
+ /// [`Event::PaymentSent`]: events::Event::PaymentSent
+ pub fn list_recent_payments(&self) -> Vec<RecentPaymentDetails> {
+ self.pending_outbound_payments.pending_outbound_payments.lock().unwrap().iter()
+ .filter_map(|(_, pending_outbound_payment)| match pending_outbound_payment {
+ PendingOutboundPayment::Retryable { payment_hash, total_msat, .. } => {
+ Some(RecentPaymentDetails::Pending {
+ payment_hash: *payment_hash,
+ total_msat: *total_msat,
+ })
+ },
+ PendingOutboundPayment::Abandoned { payment_hash, .. } => {
+ Some(RecentPaymentDetails::Abandoned { payment_hash: *payment_hash })
+ },
+ PendingOutboundPayment::Fulfilled { payment_hash, .. } => {
+ Some(RecentPaymentDetails::Fulfilled { payment_hash: *payment_hash })
+ },
+ PendingOutboundPayment::Legacy { .. } => None
+ })
+ .collect()
+ }
+
/// Helper function that issues the channel close events
fn issue_channel_close_events(&self, channel: &Channel<<SP::Target as SignerProvider>::Signer>, closure_reason: ClosureReason) {
let mut pending_events_lock = self.pending_events.lock().unwrap();
/// Sends a payment along a given route.
///
- /// Value parameters are provided via the last hop in route, see documentation for RouteHop
+ /// Value parameters are provided via the last hop in route, see documentation for [`RouteHop`]
/// fields for more info.
///
+ /// May generate SendHTLCs message(s) event on success, which should be relayed (e.g. via
+ /// [`PeerManager::process_events`]).
+ ///
+ /// # Avoiding Duplicate Payments
+ ///
/// If a pending payment is currently in-flight with the same [`PaymentId`] provided, this
/// method will error with an [`APIError::InvalidRoute`]. Note, however, that once a payment
/// is no longer pending (either via [`ChannelManager::abandon_payment`], or handling of an
/// consider using the [`PaymentHash`] as the key for tracking payments. In that case, the
/// [`PaymentId`] should be a copy of the [`PaymentHash`] bytes.
///
- /// May generate SendHTLCs message(s) event on success, which should be relayed (e.g. via
- /// [`PeerManager::process_events`]).
+ /// Additionally, in the scenario where we begin the process of sending a payment, but crash
+ /// before `send_payment` returns (or prior to [`ChannelMonitorUpdate`] persistence if you're
+ /// using [`ChannelMonitorUpdateStatus::InProgress`]), the payment may be lost on restart. See
+ /// [`ChannelManager::list_recent_payments`] for more information.
+ ///
+ /// # Possible Error States on [`PaymentSendFailure`]
///
/// Each path may have a different return value, and PaymentSendValue may return a Vec with
/// each entry matching the corresponding-index entry in the route paths, see
- /// PaymentSendFailure for more info.
+ /// [`PaymentSendFailure`] for more info.
///
/// In general, a path may raise:
/// * [`APIError::InvalidRoute`] when an invalid route or forwarding parameter (cltv_delta, fee,
/// irrevocably committed to on our end. In such a case, do NOT retry the payment with a
/// different route unless you intend to pay twice!
///
- /// payment_secret is unrelated to payment_hash (or PaymentPreimage) and exists to authenticate
- /// the sender to the recipient and prevent payment-probing (deanonymization) attacks. For
- /// newer nodes, it will be provided to you in the invoice. If you do not have one, the Route
- /// must not contain multiple paths as multi-path payments require a recipient-provided
- /// payment_secret.
+ /// # A caution on `payment_secret`
+ ///
+ /// `payment_secret` is unrelated to `payment_hash` (or [`PaymentPreimage`]) and exists to
+ /// authenticate the sender to the recipient and prevent payment-probing (deanonymization)
+ /// attacks. For newer nodes, it will be provided to you in the invoice. If you do not have one,
+ /// the [`Route`] must not contain multiple paths as multi-path payments require a
+ /// recipient-provided `payment_secret`.
///
- /// If a payment_secret *is* provided, we assume that the invoice had the payment_secret feature
- /// bit set (either as required or as available). If multiple paths are present in the Route,
- /// we assume the invoice had the basic_mpp feature set.
+ /// If a `payment_secret` *is* provided, we assume that the invoice had the payment_secret
+ /// feature bit set (either as required or as available). If multiple paths are present in the
+ /// [`Route`], we assume the invoice had the basic_mpp feature set.
///
/// [`Event::PaymentSent`]: events::Event::PaymentSent
/// [`PeerManager::process_events`]: crate::ln::peer_handler::PeerManager::process_events
+ /// [`ChannelMonitorUpdateStatus::InProgress`]: crate::chain::ChannelMonitorUpdateStatus::InProgress
pub fn send_payment(&self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>, payment_id: PaymentId) -> Result<(), PaymentSendFailure> {
let best_block_height = self.best_block.read().unwrap().height();
self.pending_outbound_payments
/// Similar to [`ChannelManager::send_spontaneous_payment`], but will automatically find a route
/// based on `route_params` and retry failed payment paths based on `retry_strategy`.
+ ///
+ /// See [`PaymentParameters::for_keysend`] for help in constructing `route_params` for spontaneous
+ /// payments.
+ ///
+ /// [`PaymentParameters::for_keysend`]: crate::routing::router::PaymentParameters::for_keysend
pub fn send_spontaneous_payment_with_retry(&self, payment_preimage: Option<PaymentPreimage>, payment_id: PaymentId, route_params: RouteParameters, retry_strategy: Retry) -> Result<PaymentHash, PaymentSendFailure> {
let best_block_height = self.best_block.read().unwrap().height();
self.pending_outbound_payments.send_spontaneous_payment(payment_preimage, payment_id,
), chan),
// Note that announcement_signatures fails if the channel cannot be announced,
// so get_channel_update_for_broadcast will never fail by the time we get here.
- update_msg: self.get_channel_update_for_broadcast(chan.get()).unwrap(),
+ update_msg: Some(self.get_channel_update_for_broadcast(chan.get()).unwrap()),
});
},
hash_map::Entry::Vacant(_) => return Err(MsgHandleErrInternal::send_err_msg_no_close(format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", counterparty_node_id), msg.channel_id))
/// [`PaymentHash`] and [`PaymentPreimage`] for you.
///
/// The [`PaymentPreimage`] will ultimately be returned to you in the [`PaymentClaimable`], which
- /// will have the [`PaymentClaimable::payment_preimage`] field filled in. That should then be
+ /// will have the [`PaymentClaimable::purpose`] be [`PaymentPurpose::InvoicePayment`] with
+ /// its [`PaymentPurpose::InvoicePayment::payment_preimage`] field filled in. That should then be
/// passed directly to [`claim_funds`].
///
/// See [`create_inbound_payment_for_hash`] for detailed documentation on behavior and requirements.
///
/// [`claim_funds`]: Self::claim_funds
/// [`PaymentClaimable`]: events::Event::PaymentClaimable
- /// [`PaymentClaimable::payment_preimage`]: events::Event::PaymentClaimable::payment_preimage
+ /// [`PaymentClaimable::purpose`]: events::Event::PaymentClaimable::purpose
+ /// [`PaymentPurpose::InvoicePayment`]: events::PaymentPurpose::InvoicePayment
+ /// [`PaymentPurpose::InvoicePayment::payment_preimage`]: events::PaymentPurpose::InvoicePayment::payment_preimage
/// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
pub fn create_inbound_payment(&self, min_value_msat: Option<u64>, invoice_expiry_delta_secs: u32,
min_final_cltv_expiry_delta: Option<u16>) -> Result<(PaymentHash, PaymentSecret), ()> {
msg: announcement,
// Note that announcement_signatures fails if the channel cannot be announced,
// so get_channel_update_for_broadcast will never fail by the time we get here.
- update_msg: self.get_channel_update_for_broadcast(channel).unwrap(),
+ update_msg: Some(self.get_channel_update_for_broadcast(channel).unwrap()),
});
}
}
&events::MessageSendEvent::SendChannelAnnouncement { .. } => false,
&events::MessageSendEvent::BroadcastChannelAnnouncement { .. } => true,
&events::MessageSendEvent::BroadcastChannelUpdate { .. } => true,
+ &events::MessageSendEvent::BroadcastNodeAnnouncement { .. } => true,
&events::MessageSendEvent::SendChannelUpdate { .. } => false,
&events::MessageSendEvent::HandleError { .. } => false,
&events::MessageSendEvent::SendChannelRangeQuery { .. } => false,
let node_chanmgrs = create_node_chanmgrs(2, &node_cfgs, &[None, None]);
let nodes = create_network(2, &node_cfgs, &node_chanmgrs);
create_announced_chan_between_nodes(&nodes, 0, 1);
- let scorer = test_utils::TestScorer::with_penalty(0);
+ let scorer = test_utils::TestScorer::new();
let random_seed_bytes = chanmon_cfgs[1].keys_manager.get_secure_random_bytes();
// To start (1), send a regular payment but don't claim it.
};
let network_graph = nodes[0].network_graph.clone();
let first_hops = nodes[0].node.list_usable_channels();
- let scorer = test_utils::TestScorer::with_penalty(0);
+ let scorer = test_utils::TestScorer::new();
let random_seed_bytes = chanmon_cfgs[1].keys_manager.get_secure_random_bytes();
let route = find_route(
&payer_pubkey, &route_params, &network_graph, Some(&first_hops.iter().collect::<Vec<_>>()),
};
let network_graph = nodes[0].network_graph.clone();
let first_hops = nodes[0].node.list_usable_channels();
- let scorer = test_utils::TestScorer::with_penalty(0);
+ let scorer = test_utils::TestScorer::new();
let random_seed_bytes = chanmon_cfgs[1].keys_manager.get_secure_random_bytes();
let route = find_route(
&payer_pubkey, &route_params, &network_graph, Some(&first_hops.iter().collect::<Vec<_>>()),
let tx_broadcaster = test_utils::TestBroadcaster{txn_broadcasted: Mutex::new(Vec::new()), blocks: Arc::new(Mutex::new(Vec::new()))};
let fee_estimator = test_utils::TestFeeEstimator { sat_per_kw: Mutex::new(253) };
let logger_a = test_utils::TestLogger::with_id("node a".to_owned());
- let router = test_utils::TestRouter::new(Arc::new(NetworkGraph::new(genesis_hash, &logger_a)));
+ let scorer = Mutex::new(test_utils::TestScorer::new());
+ let router = test_utils::TestRouter::new(Arc::new(NetworkGraph::new(genesis_hash, &logger_a)), &scorer);
let mut config: UserConfig = Default::default();
config.channel_handshake_config.minimum_depth = 1;
let usable_channels = $node_a.list_usable_channels();
let payment_params = PaymentParameters::from_node_id($node_b.get_our_node_id(), TEST_FINAL_CLTV)
.with_features($node_b.invoice_features());
- let scorer = test_utils::TestScorer::with_penalty(0);
+ let scorer = test_utils::TestScorer::new();
let seed = [3u8; 32];
let keys_manager = KeysManager::new(&seed, 42, 42);
let random_seed_bytes = keys_manager.get_secure_random_bytes();
projects / rust-lightning / blobdiff