X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning%2Fsrc%2Fevents%2Fmod.rs;h=ff51bf7d3baa08d80afe4063829d1f568feb2750;hb=478911d42a8b47020511bdcb793756723f3801be;hp=43a2ae02c059546a9332c9805689ff20072d891b;hpb=ca9ca75f082dec8dfc70f3e263a7c3789e17a054;p=rust-lightning diff --git a/lightning/src/events/mod.rs b/lightning/src/events/mod.rs index 43a2ae02..d34db885 100644 --- a/lightning/src/events/mod.rs +++ b/lightning/src/events/mod.rs @@ -14,46 +14,48 @@ //! future, as well as generate and broadcast funding transactions handle payment preimages and a //! few other things. -use crate::chain::keysinterface::SpendableOutputDescriptor; -#[cfg(anchors)] -use crate::ln::chan_utils::{self, ChannelTransactionParameters, HTLCOutputInCommitment}; -use crate::ln::channelmanager::{InterceptId, PaymentId}; +pub mod bump_transaction; + +pub use bump_transaction::BumpTransactionEvent; + +use crate::blinded_path::payment::{Bolt12OfferContext, Bolt12RefundContext, PaymentContext, PaymentContextRef}; +use crate::sign::SpendableOutputDescriptor; +use crate::ln::channelmanager::{InterceptId, PaymentId, RecipientOnionFields}; use crate::ln::channel::FUNDING_CONF_DEADLINE_BLOCKS; use crate::ln::features::ChannelTypeFeatures; use crate::ln::msgs; -use crate::ln::{PaymentPreimage, PaymentHash, PaymentSecret}; +use crate::ln::{ChannelId, PaymentPreimage, PaymentHash, PaymentSecret}; +use crate::chain::transaction; use crate::routing::gossip::NetworkUpdate; use crate::util::errors::APIError; use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength}; use crate::util::string::UntrustedString; -use crate::routing::router::{RouteHop, RouteParameters}; +use crate::routing::router::{BlindedTail, Path, RouteHop, RouteParameters}; -use bitcoin::{PackedLockTime, Transaction}; -#[cfg(anchors)] -use bitcoin::{OutPoint, Txid, TxIn, TxOut, Witness}; -use bitcoin::blockdata::script::Script; +use bitcoin::{Transaction, OutPoint}; +use bitcoin::blockdata::locktime::absolute::LockTime; +use bitcoin::blockdata::script::ScriptBuf; use bitcoin::hashes::Hash; use bitcoin::hashes::sha256::Hash as Sha256; use bitcoin::secp256k1::PublicKey; -#[cfg(anchors)] -use bitcoin::secp256k1::{self, Secp256k1}; -#[cfg(anchors)] -use bitcoin::secp256k1::ecdsa::Signature; use crate::io; -use crate::prelude::*; use core::time::Duration; use core::ops::Deref; use crate::sync::Arc; +#[allow(unused_imports)] +use crate::prelude::*; + /// Some information provided on receipt of payment depends on whether the payment received is a /// spontaneous payment or a "conventional" lightning payment that's paying an invoice. #[derive(Clone, Debug, PartialEq, Eq)] pub enum PaymentPurpose { - /// Information for receiving a payment that we generated an invoice for. - InvoicePayment { + /// A payment for a BOLT 11 invoice. + Bolt11InvoicePayment { /// The preimage to the payment_hash, if the payment hash (and secret) were fetched via - /// [`ChannelManager::create_inbound_payment`]. If provided, this can be handed directly to - /// [`ChannelManager::claim_funds`]. + /// [`ChannelManager::create_inbound_payment`]. When handling [`Event::PaymentClaimable`], + /// this can be passed directly to [`ChannelManager::claim_funds`] to claim the payment. No + /// action is needed when seen in [`Event::PaymentClaimed`]. /// /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds @@ -70,19 +72,158 @@ pub enum PaymentPurpose { /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash payment_secret: PaymentSecret, }, + /// A payment for a BOLT 12 [`Offer`]. + /// + /// [`Offer`]: crate::offers::offer::Offer + Bolt12OfferPayment { + /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be + /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed + /// when seen in [`Event::PaymentClaimed`]. + /// + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + payment_preimage: Option, + /// The secret used to authenticate the sender to the recipient, preventing a number of + /// de-anonymization attacks while routing a payment. + /// + /// See [`PaymentPurpose::Bolt11InvoicePayment::payment_secret`] for further details. + payment_secret: PaymentSecret, + /// The context of the payment such as information about the corresponding [`Offer`] and + /// [`InvoiceRequest`]. + /// + /// [`Offer`]: crate::offers::offer::Offer + /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest + payment_context: Bolt12OfferContext, + }, + /// A payment for a BOLT 12 [`Refund`]. + /// + /// [`Refund`]: crate::offers::refund::Refund + Bolt12RefundPayment { + /// The preimage to the payment hash. When handling [`Event::PaymentClaimable`], this can be + /// passed directly to [`ChannelManager::claim_funds`], if provided. No action is needed + /// when seen in [`Event::PaymentClaimed`]. + /// + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + payment_preimage: Option, + /// The secret used to authenticate the sender to the recipient, preventing a number of + /// de-anonymization attacks while routing a payment. + /// + /// See [`PaymentPurpose::Bolt11InvoicePayment::payment_secret`] for further details. + payment_secret: PaymentSecret, + /// The context of the payment such as information about the corresponding [`Refund`]. + /// + /// [`Refund`]: crate::offers::refund::Refund + payment_context: Bolt12RefundContext, + }, /// Because this is a spontaneous payment, the payer generated their own preimage rather than us /// (the payee) providing a preimage. SpontaneousPayment(PaymentPreimage), } +impl PaymentPurpose { + /// Returns the preimage for this payment, if it is known. + pub fn preimage(&self) -> Option { + match self { + PaymentPurpose::Bolt11InvoicePayment { payment_preimage, .. } => *payment_preimage, + PaymentPurpose::Bolt12OfferPayment { payment_preimage, .. } => *payment_preimage, + PaymentPurpose::Bolt12RefundPayment { payment_preimage, .. } => *payment_preimage, + PaymentPurpose::SpontaneousPayment(preimage) => Some(*preimage), + } + } + + pub(crate) fn is_keysend(&self) -> bool { + match self { + PaymentPurpose::Bolt11InvoicePayment { .. } => false, + PaymentPurpose::Bolt12OfferPayment { .. } => false, + PaymentPurpose::Bolt12RefundPayment { .. } => false, + PaymentPurpose::SpontaneousPayment(..) => true, + } + } + + pub(crate) fn from_parts( + payment_preimage: Option, payment_secret: PaymentSecret, + payment_context: Option, + ) -> Self { + match payment_context { + Some(PaymentContext::Unknown(_)) | None => { + PaymentPurpose::Bolt11InvoicePayment { + payment_preimage, + payment_secret, + } + }, + Some(PaymentContext::Bolt12Offer(context)) => { + PaymentPurpose::Bolt12OfferPayment { + payment_preimage, + payment_secret, + payment_context: context, + } + }, + Some(PaymentContext::Bolt12Refund(context)) => { + PaymentPurpose::Bolt12RefundPayment { + payment_preimage, + payment_secret, + payment_context: context, + } + }, + } + } +} + impl_writeable_tlv_based_enum!(PaymentPurpose, - (0, InvoicePayment) => { + (0, Bolt11InvoicePayment) => { (0, payment_preimage, option), (2, payment_secret, required), - }; + }, + (4, Bolt12OfferPayment) => { + (0, payment_preimage, option), + (2, payment_secret, required), + (4, payment_context, required), + }, + (6, Bolt12RefundPayment) => { + (0, payment_preimage, option), + (2, payment_secret, required), + (4, payment_context, required), + }, + ; (2, SpontaneousPayment) ); +/// Information about an HTLC that is part of a payment that can be claimed. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct ClaimedHTLC { + /// The `channel_id` of the channel over which the HTLC was received. + pub channel_id: ChannelId, + /// The `user_channel_id` of the channel over which the HTLC was received. This is the value + /// passed in to [`ChannelManager::create_channel`] for outbound channels, or to + /// [`ChannelManager::accept_inbound_channel`] for inbound channels if + /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise + /// `user_channel_id` will be randomized for an inbound channel. + /// + /// This field will be zero for a payment that was serialized prior to LDK version 0.0.117. (This + /// should only happen in the case that a payment was claimable prior to LDK version 0.0.117, but + /// was not actually claimed until after upgrading.) + /// + /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels + pub user_channel_id: u128, + /// The block height at which this HTLC expires. + pub cltv_expiry: u32, + /// The amount (in msats) of this part of an MPP. + pub value_msat: u64, + /// The extra fee our counterparty skimmed off the top of this HTLC, if any. + /// + /// This value will always be 0 for [`ClaimedHTLC`]s serialized with LDK versions prior to + /// 0.0.119. + pub counterparty_skimmed_fee_msat: u64, +} +impl_writeable_tlv_based!(ClaimedHTLC, { + (0, channel_id, required), + (1, counterparty_skimmed_fee_msat, (default_value, 0u64)), + (2, user_channel_id, required), + (4, cltv_expiry, required), + (6, value_msat, required), +}); + /// When the payment path failure took place and extra details about it. [`PathFailure::OnPath`] may /// contain a [`NetworkUpdate`] that needs to be applied to the [`NetworkGraph`]. /// @@ -117,7 +258,7 @@ impl_writeable_tlv_based_enum_upgradable!(PathFailure, ); #[derive(Clone, Debug, PartialEq, Eq)] -/// The reason the channel was closed. See individual variants more details. +/// The reason the channel was closed. See individual variants for more details. pub enum ClosureReason { /// Closure generated from receiving a peer error message. /// @@ -129,7 +270,7 @@ pub enum ClosureReason { /// Be careful about printing the peer_msg, a well-crafted message could exploit /// a security vulnerability in the terminal emulator or the logging subsystem. /// To be safe, use `Display` on `UntrustedString` - /// + /// /// [`UntrustedString`]: crate::util::string::UntrustedString peer_msg: UntrustedString, }, @@ -139,8 +280,20 @@ pub enum ClosureReason { HolderForceClosed, /// The channel was closed after negotiating a cooperative close and we've now broadcasted /// the cooperative close transaction. Note the shutdown may have been initiated by us. - //TODO: split between CounterpartyInitiated/LocallyInitiated - CooperativeClosure, + /// + /// This was only set in versions of LDK prior to 0.0.122. + // Can be removed once we disallow downgrading to 0.0.121 + LegacyCooperativeClosure, + /// The channel was closed after negotiating a cooperative close and we've now broadcasted + /// the cooperative close transaction. This indicates that the shutdown was initiated by our + /// counterparty. + /// + /// In rare cases where we initiated closure immediately prior to shutting down without + /// persisting, this value may be provided for channels we initiated closure for. + CounterpartyInitiatedCooperativeClosure, + /// The channel was closed after negotiating a cooperative close and we've now broadcasted + /// the cooperative close transaction. This indicates that the shutdown was initiated by us. + LocallyInitiatedCooperativeClosure, /// A commitment transaction was confirmed on chain, closing the channel. Most likely this /// commitment transaction came from our counterparty, but it may also have come from /// a copy of our own `ChannelMonitor`. @@ -168,7 +321,15 @@ pub enum ClosureReason { /// /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager - OutdatedChannelManager + OutdatedChannelManager, + /// The counterparty requested a cooperative close of a channel that had not been funded yet. + /// The channel has been immediately closed. + CounterpartyCoopClosedUnfundedChannel, + /// Another channel in the same funding batch closed before the funding transaction + /// was ready to be broadcast. + FundingBatchClosure, + /// One of our HTLCs timed out in a channel, causing us to force close the channel. + HTLCsTimedOut, } impl core::fmt::Display for ClosureReason { @@ -178,8 +339,10 @@ impl core::fmt::Display for ClosureReason { ClosureReason::CounterpartyForceClosed { peer_msg } => { f.write_fmt(format_args!("counterparty force-closed with message: {}", peer_msg)) }, - ClosureReason::HolderForceClosed => f.write_str("user manually force-closed the channel"), - ClosureReason::CooperativeClosure => f.write_str("the channel was cooperatively closed"), + ClosureReason::HolderForceClosed => f.write_str("user force-closed the channel"), + ClosureReason::LegacyCooperativeClosure => f.write_str("the channel was cooperatively closed"), + ClosureReason::CounterpartyInitiatedCooperativeClosure => f.write_str("the channel was cooperatively closed by our peer"), + ClosureReason::LocallyInitiatedCooperativeClosure => f.write_str("the channel was cooperatively closed by us"), ClosureReason::CommitmentTxConfirmed => f.write_str("commitment or closing transaction was confirmed on chain."), ClosureReason::FundingTimedOut => write!(f, "funding transaction failed to confirm within {} blocks", FUNDING_CONF_DEADLINE_BLOCKS), ClosureReason::ProcessingError { err } => { @@ -188,6 +351,9 @@ impl core::fmt::Display for ClosureReason { }, ClosureReason::DisconnectedPeer => f.write_str("the peer disconnected prior to the channel being funded"), ClosureReason::OutdatedChannelManager => f.write_str("the ChannelManager read from disk was stale compared to ChannelMonitor(s)"), + ClosureReason::CounterpartyCoopClosedUnfundedChannel => f.write_str("the peer requested the unfunded channel be closed"), + ClosureReason::FundingBatchClosure => f.write_str("another channel in the same funding batch closed"), + ClosureReason::HTLCsTimedOut => f.write_str("htlcs on the channel timed out"), } } } @@ -197,10 +363,15 @@ impl_writeable_tlv_based_enum_upgradable!(ClosureReason, (1, FundingTimedOut) => {}, (2, HolderForceClosed) => {}, (6, CommitmentTxConfirmed) => {}, - (4, CooperativeClosure) => {}, + (4, LegacyCooperativeClosure) => {}, (8, ProcessingError) => { (1, err, required) }, (10, DisconnectedPeer) => {}, (12, OutdatedChannelManager) => {}, + (13, CounterpartyCoopClosedUnfundedChannel) => {}, + (15, FundingBatchClosure) => {}, + (17, CounterpartyInitiatedCooperativeClosure) => {}, + (19, LocallyInitiatedCooperativeClosure) => {}, + (21, HTLCsTimedOut) => {}, ); /// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`]. @@ -214,7 +385,7 @@ pub enum HTLCDestination { /// counterparty node information. node_id: Option, /// The outgoing `channel_id` between us and the next node. - channel_id: [u8; 32], + channel_id: ChannelId, }, /// Scenario where we are unsure of the next node to forward the HTLC to. UnknownNextHop { @@ -227,13 +398,18 @@ pub enum HTLCDestination { /// Short channel id we are requesting to forward an HTLC to. requested_forward_scid: u64 }, + /// We couldn't decode the incoming onion to obtain the forwarding details. + InvalidOnion, /// Failure scenario where an HTLC may have been forwarded to be intended for us, /// but is invalid for some reason, so we reject it. /// /// Some of the reasons may include: /// * HTLC Timeouts - /// * Expected MPP amount to claim does not equal HTLC total - /// * Claimable amount does not match expected amount + /// * Excess HTLCs for a payment that we have already fully received, over-paying for the + /// payment, + /// * The counterparty node modified the HTLC in transit, + /// * A probing attack where an intermediary node is trying to detect if we are the ultimate + /// recipient for a payment. FailedPayment { /// The payment hash of the payment we attempted to process. payment_hash: PaymentHash @@ -251,227 +427,12 @@ impl_writeable_tlv_based_enum_upgradable!(HTLCDestination, (2, UnknownNextHop) => { (0, requested_forward_scid, required), }, + (3, InvalidOnion) => {}, (4, FailedPayment) => { (0, payment_hash, required), }, ); -#[cfg(anchors)] -/// A descriptor used to sign for a commitment transaction's anchor output. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct AnchorDescriptor { - /// A unique identifier used along with `channel_value_satoshis` to re-derive the - /// [`InMemorySigner`] required to sign `input`. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - pub channel_keys_id: [u8; 32], - /// The value in satoshis of the channel we're attempting to spend the anchor output of. This is - /// used along with `channel_keys_id` to re-derive the [`InMemorySigner`] required to sign - /// `input`. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - pub channel_value_satoshis: u64, - /// The transaction input's outpoint corresponding to the commitment transaction's anchor - /// output. - pub outpoint: OutPoint, -} - -#[cfg(anchors)] -/// A descriptor used to sign for a commitment transaction's HTLC output. -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct HTLCDescriptor { - /// A unique identifier used along with `channel_value_satoshis` to re-derive the - /// [`InMemorySigner`] required to sign `input`. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - pub channel_keys_id: [u8; 32], - /// The value in satoshis of the channel we're attempting to spend the anchor output of. This is - /// used along with `channel_keys_id` to re-derive the [`InMemorySigner`] required to sign - /// `input`. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - pub channel_value_satoshis: u64, - /// The necessary channel parameters that need to be provided to the re-derived - /// [`InMemorySigner`] through [`ChannelSigner::provide_channel_parameters`]. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - /// [`ChannelSigner::provide_channel_parameters`]: crate::chain::keysinterface::ChannelSigner::provide_channel_parameters - pub channel_parameters: ChannelTransactionParameters, - /// The txid of the commitment transaction in which the HTLC output lives. - pub commitment_txid: Txid, - /// The number of the commitment transaction in which the HTLC output lives. - pub per_commitment_number: u64, - /// The details of the HTLC as it appears in the commitment transaction. - pub htlc: HTLCOutputInCommitment, - /// The preimage, if `Some`, to claim the HTLC output with. If `None`, the timeout path must be - /// taken. - pub preimage: Option, - /// The counterparty's signature required to spend the HTLC output. - pub counterparty_sig: Signature -} - -#[cfg(anchors)] -impl HTLCDescriptor { - /// Returns the unsigned transaction input spending the HTLC output in the commitment - /// transaction. - pub fn unsigned_tx_input(&self) -> TxIn { - chan_utils::build_htlc_input(&self.commitment_txid, &self.htlc, true /* opt_anchors */) - } - - /// Returns the delayed output created as a result of spending the HTLC output in the commitment - /// transaction. - pub fn tx_output( - &self, per_commitment_point: &PublicKey, secp: &Secp256k1 - ) -> TxOut { - let channel_params = self.channel_parameters.as_holder_broadcastable(); - let broadcaster_keys = channel_params.broadcaster_pubkeys(); - let counterparty_keys = channel_params.countersignatory_pubkeys(); - let broadcaster_delayed_key = chan_utils::derive_public_key( - secp, per_commitment_point, &broadcaster_keys.delayed_payment_basepoint - ); - let counterparty_revocation_key = chan_utils::derive_public_revocation_key( - secp, per_commitment_point, &counterparty_keys.revocation_basepoint - ); - chan_utils::build_htlc_output( - 0 /* feerate_per_kw */, channel_params.contest_delay(), &self.htlc, true /* opt_anchors */, - false /* use_non_zero_fee_anchors */, &broadcaster_delayed_key, &counterparty_revocation_key - ) - } - - /// Returns the witness script of the HTLC output in the commitment transaction. - pub fn witness_script( - &self, per_commitment_point: &PublicKey, secp: &Secp256k1 - ) -> Script { - let channel_params = self.channel_parameters.as_holder_broadcastable(); - let broadcaster_keys = channel_params.broadcaster_pubkeys(); - let counterparty_keys = channel_params.countersignatory_pubkeys(); - let broadcaster_htlc_key = chan_utils::derive_public_key( - secp, per_commitment_point, &broadcaster_keys.htlc_basepoint - ); - let counterparty_htlc_key = chan_utils::derive_public_key( - secp, per_commitment_point, &counterparty_keys.htlc_basepoint - ); - let counterparty_revocation_key = chan_utils::derive_public_revocation_key( - secp, per_commitment_point, &counterparty_keys.revocation_basepoint - ); - chan_utils::get_htlc_redeemscript_with_explicit_keys( - &self.htlc, true /* opt_anchors */, &broadcaster_htlc_key, &counterparty_htlc_key, - &counterparty_revocation_key, - ) - } - - /// Returns the fully signed witness required to spend the HTLC output in the commitment - /// transaction. - pub fn tx_input_witness(&self, signature: &Signature, witness_script: &Script) -> Witness { - chan_utils::build_htlc_input_witness( - signature, &self.counterparty_sig, &self.preimage, witness_script, true /* opt_anchors */ - ) - } -} - -#[cfg(anchors)] -/// Represents the different types of transactions, originating from LDK, to be bumped. -#[derive(Clone, Debug, PartialEq, Eq)] -pub enum BumpTransactionEvent { - /// Indicates that a channel featuring anchor outputs is to be closed by broadcasting the local - /// commitment transaction. Since commitment transactions have a static feerate pre-agreed upon, - /// they may need additional fees to be attached through a child transaction using the popular - /// [Child-Pays-For-Parent](https://bitcoinops.org/en/topics/cpfp) fee bumping technique. This - /// child transaction must include the anchor input described within `anchor_descriptor` along - /// with additional inputs to meet the target feerate. Failure to meet the target feerate - /// decreases the confirmation odds of the transaction package (which includes the commitment - /// and child anchor transactions), possibly resulting in a loss of funds. Once the transaction - /// is constructed, it must be fully signed for and broadcast by the consumer of the event - /// along with the `commitment_tx` enclosed. Note that the `commitment_tx` must always be - /// broadcast first, as the child anchor transaction depends on it. - /// - /// The consumer should be able to sign for any of the additional inputs included within the - /// child anchor transaction. To sign its anchor input, an [`InMemorySigner`] should be - /// re-derived through [`KeysManager::derive_channel_keys`] with the help of - /// [`AnchorDescriptor::channel_keys_id`] and [`AnchorDescriptor::channel_value_satoshis`]. The - /// anchor input signature can be computed with [`EcdsaChannelSigner::sign_holder_anchor_input`], - /// which can then be provided to [`build_anchor_input_witness`] along with the `funding_pubkey` - /// to obtain the full witness required to spend. - /// - /// It is possible to receive more than one instance of this event if a valid child anchor - /// transaction is never broadcast or is but not with a sufficient fee to be mined. Care should - /// be taken by the consumer of the event to ensure any future iterations of the child anchor - /// transaction adhere to the [Replace-By-Fee - /// rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md) - /// for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of - /// these events is not user-controlled, users may ignore/drop the event if they are no longer - /// able to commit external confirmed funds to the child anchor transaction. - /// - /// The set of `pending_htlcs` on the commitment transaction to be broadcast can be inspected to - /// determine whether a significant portion of the channel's funds are allocated to HTLCs, - /// enabling users to make their own decisions regarding the importance of the commitment - /// transaction's confirmation. Note that this is not required, but simply exists as an option - /// for users to override LDK's behavior. On commitments with no HTLCs (indicated by those with - /// an empty `pending_htlcs`), confirmation of the commitment transaction can be considered to - /// be not urgent. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - /// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys - /// [`EcdsaChannelSigner::sign_holder_anchor_input`]: crate::chain::keysinterface::EcdsaChannelSigner::sign_holder_anchor_input - /// [`build_anchor_input_witness`]: crate::ln::chan_utils::build_anchor_input_witness - ChannelClose { - /// The target feerate that the transaction package, which consists of the commitment - /// transaction and the to-be-crafted child anchor transaction, must meet. - package_target_feerate_sat_per_1000_weight: u32, - /// The channel's commitment transaction to bump the fee of. This transaction should be - /// broadcast along with the anchor transaction constructed as a result of consuming this - /// event. - commitment_tx: Transaction, - /// The absolute fee in satoshis of the commitment transaction. This can be used along the - /// with weight of the commitment transaction to determine its feerate. - commitment_tx_fee_satoshis: u64, - /// The descriptor to sign the anchor input of the anchor transaction constructed as a - /// result of consuming this event. - anchor_descriptor: AnchorDescriptor, - /// The set of pending HTLCs on the commitment transaction that need to be resolved once the - /// commitment transaction confirms. - pending_htlcs: Vec, - }, - /// Indicates that a channel featuring anchor outputs has unilaterally closed on-chain by a - /// holder commitment transaction and its HTLC(s) need to be resolved on-chain. With the - /// zero-HTLC-transaction-fee variant of anchor outputs, the pre-signed HTLC - /// transactions have a zero fee, thus requiring additional inputs and/or outputs to be attached - /// for a timely confirmation within the chain. These additional inputs and/or outputs must be - /// appended to the resulting HTLC transaction to meet the target feerate. Failure to meet the - /// target feerate decreases the confirmation odds of the transaction, possibly resulting in a - /// loss of funds. Once the transaction meets the target feerate, it must be signed for and - /// broadcast by the consumer of the event. - /// - /// The consumer should be able to sign for any of the non-HTLC inputs added to the resulting - /// HTLC transaction. To sign HTLC inputs, an [`InMemorySigner`] should be re-derived through - /// [`KeysManager::derive_channel_keys`] with the help of `channel_keys_id` and - /// `channel_value_satoshis`. Each HTLC input's signature can be computed with - /// [`EcdsaChannelSigner::sign_holder_htlc_transaction`], which can then be provided to - /// [`HTLCDescriptor::tx_input_witness`] to obtain the fully signed witness required to spend. - /// - /// It is possible to receive more than one instance of this event if a valid HTLC transaction - /// is never broadcast or is but not with a sufficient fee to be mined. Care should be taken by - /// the consumer of the event to ensure any future iterations of the HTLC transaction adhere to - /// the [Replace-By-Fee - /// rules](https://github.com/bitcoin/bitcoin/blob/master/doc/policy/mempool-replacements.md) - /// for fee bumps to be accepted into the mempool, and eventually the chain. As the frequency of - /// these events is not user-controlled, users may ignore/drop the event if either they are no - /// longer able to commit external confirmed funds to the HTLC transaction or the fee committed - /// to the HTLC transaction is greater in value than the HTLCs being claimed. - /// - /// [`InMemorySigner`]: crate::chain::keysinterface::InMemorySigner - /// [`KeysManager::derive_channel_keys`]: crate::chain::keysinterface::KeysManager::derive_channel_keys - /// [`EcdsaChannelSigner::sign_holder_htlc_transaction`]: crate::chain::keysinterface::EcdsaChannelSigner::sign_holder_htlc_transaction - /// [`HTLCDescriptor::tx_input_witness`]: HTLCDescriptor::tx_input_witness - HTLCResolution { - /// The target feerate that the resulting HTLC transaction must meet. - target_feerate_sat_per_1000_weight: u32, - /// The set of pending HTLCs on the confirmed commitment that need to be claimed, preferably - /// by the same transaction. - htlc_descriptors: Vec, - }, -} - /// Will be used in [`Event::HTLCIntercepted`] to identify the next hop in the HTLC's path. /// Currently only used in serialization for the sake of maintaining compatibility. More variants /// will be added for general-purpose HTLC forward intercepts as well as trampoline forward @@ -488,6 +449,47 @@ impl_writeable_tlv_based_enum!(InterceptNextHop, }; ); +/// The reason the payment failed. Used in [`Event::PaymentFailed`]. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PaymentFailureReason { + /// The intended recipient rejected our payment. + RecipientRejected, + /// The user chose to abandon this payment by calling [`ChannelManager::abandon_payment`]. + /// + /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment + UserAbandoned, + /// We exhausted all of our retry attempts while trying to send the payment, or we + /// exhausted the [`Retry::Timeout`] if the user set one. If at any point a retry + /// attempt failed while being forwarded along the path, an [`Event::PaymentPathFailed`] will + /// have come before this. + /// + /// [`Retry::Timeout`]: crate::ln::channelmanager::Retry::Timeout + RetriesExhausted, + /// The payment expired while retrying, based on the provided + /// [`PaymentParameters::expiry_time`]. + /// + /// [`PaymentParameters::expiry_time`]: crate::routing::router::PaymentParameters::expiry_time + PaymentExpired, + /// We failed to find a route while retrying the payment. + /// + /// Note that this generally indicates that we've exhausted the available set of possible + /// routes - we tried the payment over a few routes but were not able to find any further + /// candidate routes beyond those. + RouteNotFound, + /// This error should generally never happen. This likely means that there is a problem with + /// your router. + UnexpectedError, +} + +impl_writeable_tlv_based_enum!(PaymentFailureReason, + (0, RecipientRejected) => {}, + (2, UserAbandoned) => {}, + (4, RetriesExhausted) => {}, + (6, PaymentExpired) => {}, + (8, RouteNotFound) => {}, + (10, UnexpectedError) => {}, ; +); + /// An Event which you should probably take some action in response to. /// /// Note that while Writeable and Readable are implemented for Event, you probably shouldn't use @@ -508,7 +510,7 @@ pub enum Event { /// [`ChannelManager::funding_transaction_generated`]. /// /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated - temporary_channel_id: [u8; 32], + temporary_channel_id: ChannelId, /// The counterparty's node_id, which you'll need to pass back into /// [`ChannelManager::funding_transaction_generated`]. /// @@ -517,12 +519,16 @@ pub enum Event { /// The value, in satoshis, that the output should have. channel_value_satoshis: u64, /// The script which should be used in the transaction output. - output_script: Script, - /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`], or a - /// random value for an inbound channel. This may be zero for objects serialized with LDK - /// versions prior to 0.0.113. + output_script: ScriptBuf, + /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound + /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if + /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise + /// `user_channel_id` will be randomized for an inbound channel. This may be zero for objects + /// serialized with LDK versions prior to 0.0.113. /// /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels user_channel_id: u128, }, /// Indicates that we've been offered a payment and it needs to be claimed via calling @@ -531,18 +537,32 @@ pub enum Event { /// Note that if the preimage is not known, you should call /// [`ChannelManager::fail_htlc_backwards`] or [`ChannelManager::fail_htlc_backwards_with_reason`] /// to free up resources for this HTLC and avoid network congestion. - /// If you fail to call either [`ChannelManager::claim_funds`], [`ChannelManager::fail_htlc_backwards`], - /// or [`ChannelManager::fail_htlc_backwards_with_reason`] within the HTLC's timeout, the HTLC will be - /// automatically failed. + /// + /// If [`Event::PaymentClaimable::onion_fields`] is `Some`, and includes custom TLVs with even type + /// numbers, you should use [`ChannelManager::fail_htlc_backwards_with_reason`] with + /// [`FailureCode::InvalidOnionPayload`] if you fail to understand and handle the contents, or + /// [`ChannelManager::claim_funds_with_known_custom_tlvs`] upon successful handling. + /// If you don't intend to check for custom TLVs, you can simply use + /// [`ChannelManager::claim_funds`], which will automatically fail back even custom TLVs. + /// + /// If you fail to call [`ChannelManager::claim_funds`], + /// [`ChannelManager::claim_funds_with_known_custom_tlvs`], + /// [`ChannelManager::fail_htlc_backwards`], or + /// [`ChannelManager::fail_htlc_backwards_with_reason`] within the HTLC's timeout, the HTLC will + /// be automatically failed. /// /// # Note /// LDK will not stop an inbound payment from being paid multiple times, so multiple - /// `PaymentClaimable` events may be generated for the same payment. + /// `PaymentClaimable` events may be generated for the same payment. In such a case it is + /// polite (and required in the lightning specification) to fail the payment the second time + /// and give the sender their money back rather than accepting double payment. /// /// # Note /// This event used to be called `PaymentReceived` in LDK versions 0.0.112 and earlier. /// /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + /// [`ChannelManager::claim_funds_with_known_custom_tlvs`]: crate::ln::channelmanager::ChannelManager::claim_funds_with_known_custom_tlvs + /// [`FailureCode::InvalidOnionPayload`]: crate::ln::channelmanager::FailureCode::InvalidOnionPayload /// [`ChannelManager::fail_htlc_backwards`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards /// [`ChannelManager::fail_htlc_backwards_with_reason`]: crate::ln::channelmanager::ChannelManager::fail_htlc_backwards_with_reason PaymentClaimable { @@ -551,20 +571,50 @@ pub enum Event { /// This field will always be filled in when the event was generated by LDK versions /// 0.0.113 and above. /// - /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager + /// [phantom nodes]: crate::sign::PhantomKeysManager receiver_node_id: Option, /// The hash for which the preimage should be handed to the ChannelManager. Note that LDK will /// not stop you from registering duplicate payment hashes for inbound payments. payment_hash: PaymentHash, - /// The value, in thousandths of a satoshi, that this payment is for. + /// The fields in the onion which were received with each HTLC. Only fields which were + /// identical in each HTLC involved in the payment will be included here. + /// + /// Payments received on LDK versions prior to 0.0.115 will have this field unset. + onion_fields: Option, + /// The value, in thousandths of a satoshi, that this payment is claimable for. May be greater + /// than the invoice amount. + /// + /// May be less than the invoice amount if [`ChannelConfig::accept_underpaying_htlcs`] is set + /// and the previous hop took an extra fee. + /// + /// # Note + /// If [`ChannelConfig::accept_underpaying_htlcs`] is set and you claim without verifying this + /// field, you may lose money! + /// + /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs amount_msat: u64, + /// The value, in thousands of a satoshi, that was skimmed off of this payment as an extra fee + /// taken by our channel counterparty. + /// + /// Will always be 0 unless [`ChannelConfig::accept_underpaying_htlcs`] is set. + /// + /// [`ChannelConfig::accept_underpaying_htlcs`]: crate::util::config::ChannelConfig::accept_underpaying_htlcs + counterparty_skimmed_fee_msat: u64, /// Information for claiming this received payment, based on whether the purpose of the /// payment is to pay an invoice or to send a spontaneous payment. purpose: PaymentPurpose, /// The `channel_id` indicating over which channel we received the payment. - via_channel_id: Option<[u8; 32]>, + via_channel_id: Option, /// The `user_channel_id` indicating over which channel we received the payment. via_user_channel_id: Option, + /// The block height at which this payment will be failed back and will no longer be + /// eligible for claiming. + /// + /// Prior to this height, a call to [`ChannelManager::claim_funds`] is guaranteed to + /// succeed, however you should wait for [`Event::PaymentClaimed`] to be sure. + /// + /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds + claim_deadline: Option, }, /// Indicates a payment has been claimed and we've received money! /// @@ -586,16 +636,54 @@ pub enum Event { /// This field will always be filled in when the event was generated by LDK versions /// 0.0.113 and above. /// - /// [phantom nodes]: crate::chain::keysinterface::PhantomKeysManager + /// [phantom nodes]: crate::sign::PhantomKeysManager receiver_node_id: Option, /// The payment hash of the claimed payment. Note that LDK will not stop you from /// registering duplicate payment hashes for inbound payments. payment_hash: PaymentHash, - /// The value, in thousandths of a satoshi, that this payment is for. + /// The value, in thousandths of a satoshi, that this payment is for. May be greater than the + /// invoice amount. amount_msat: u64, /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a /// spontaneous payment. purpose: PaymentPurpose, + /// The HTLCs that comprise the claimed payment. This will be empty for events serialized prior + /// to LDK version 0.0.117. + htlcs: Vec, + /// The sender-intended sum total of all the MPP parts. This will be `None` for events + /// serialized prior to LDK version 0.0.117. + sender_intended_total_msat: Option, + }, + /// Indicates that a peer connection with a node is needed in order to send an [`OnionMessage`]. + /// + /// Typically, this happens when a [`MessageRouter`] is unable to find a complete path to a + /// [`Destination`]. Once a connection is established, any messages buffered by an + /// [`OnionMessageHandler`] may be sent. + /// + /// This event will not be generated for onion message forwards; only for sends including + /// replies. Handlers should connect to the node otherwise any buffered messages may be lost. + /// + /// [`OnionMessage`]: msgs::OnionMessage + /// [`MessageRouter`]: crate::onion_message::messenger::MessageRouter + /// [`Destination`]: crate::onion_message::messenger::Destination + /// [`OnionMessageHandler`]: crate::ln::msgs::OnionMessageHandler + ConnectionNeeded { + /// The node id for the node needing a connection. + node_id: PublicKey, + /// Sockets for connecting to the node. + addresses: Vec, + }, + /// Indicates a request for an invoice failed to yield a response in a reasonable amount of time + /// or was explicitly abandoned by [`ChannelManager::abandon_payment`]. This may be for an + /// [`InvoiceRequest`] sent for an [`Offer`] or for a [`Refund`] that hasn't been redeemed. + /// + /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment + /// [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest + /// [`Offer`]: crate::offers::offer::Offer + /// [`Refund`]: crate::offers::refund::Refund + InvoiceRequestFailed { + /// The `payment_id` to have been associated with payment for the requested invoice. + payment_id: PaymentId, }, /// Indicates an outbound payment we made succeeded (i.e. it made it all the way to its target /// and we got back the payment preimage for it). @@ -603,7 +691,7 @@ pub enum Event { /// Note for MPP payments: in rare cases, this event may be preceded by a `PaymentPathFailed` /// event. In this situation, you SHOULD treat this payment as having succeeded. PaymentSent { - /// The id returned by [`ChannelManager::send_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_id: Option, @@ -633,37 +721,45 @@ pub enum Event { /// payment is no longer retryable, due either to the [`Retry`] provided or /// [`ChannelManager::abandon_payment`] having been called for the corresponding payment. /// + /// In exceedingly rare cases, it is possible that an [`Event::PaymentFailed`] is generated for + /// a payment after an [`Event::PaymentSent`] event for this same payment has already been + /// received and processed. In this case, the [`Event::PaymentFailed`] event MUST be ignored, + /// and the payment MUST be treated as having succeeded. + /// /// [`Retry`]: crate::ln::channelmanager::Retry /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentFailed { - /// The id returned by [`ChannelManager::send_payment`] and used with - /// [`ChannelManager::abandon_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment - /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment payment_id: PaymentId, /// The hash that was given to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_hash: PaymentHash, + /// The reason the payment failed. This is only `None` for events generated or serialized + /// by versions prior to 0.0.115. + reason: Option, }, /// Indicates that a path for an outbound payment was successful. /// /// Always generated after [`Event::PaymentSent`] and thus useful for scoring channels. See /// [`Event::PaymentSent`] for obtaining the payment preimage. PaymentPathSuccessful { - /// The id returned by [`ChannelManager::send_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_id: PaymentId, /// The hash that was given to [`ChannelManager::send_payment`]. /// + /// This will be `Some` for all payments which completed on LDK 0.0.104 or later. + /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment payment_hash: Option, /// The payment path that was successful. /// /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain. - path: Vec, + path: Path, }, /// Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to /// handle the HTLC. @@ -676,8 +772,9 @@ pub enum Event { /// /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment PaymentPathFailed { - /// The id returned by [`ChannelManager::send_payment`] and used with - /// [`ChannelManager::abandon_payment`]. + /// The `payment_id` passed to [`ChannelManager::send_payment`]. + /// + /// This will be `Some` for all payment paths which failed on LDK 0.0.103 or later. /// /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment @@ -696,7 +793,7 @@ pub enum Event { /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph failure: PathFailure, /// The payment path that failed. - path: Vec, + path: Path, /// The channel responsible for the failed payment path. /// /// Note that for route hints or for the first hop in a path this may be an SCID alias and @@ -722,7 +819,7 @@ pub enum Event { /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe payment_hash: PaymentHash, /// The payment path that was successful. - path: Vec, + path: Path, }, /// Indicates that a probe payment we sent failed at an intermediary node on the path. ProbeFailed { @@ -735,7 +832,7 @@ pub enum Event { /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe payment_hash: PaymentHash, /// The payment path that failed. - path: Vec, + path: Path, /// The channel responsible for the failed probe. /// /// Note that for route hints or for the first hop in a path this may be an SCID alias and @@ -780,6 +877,7 @@ pub enum Event { inbound_amount_msat: u64, /// How many msats the payer intended to route to the next node. Depending on the reason you are /// intercepting this payment, you might take a fee by forwarding less than this amount. + /// Forwarding less than this amount may break compatibility with LDK versions prior to 0.0.116. /// /// Note that LDK will NOT check that expected fees were factored into this value. You MUST /// check that whatever fee you want has been included here or subtract it as required. Further, @@ -794,17 +892,33 @@ pub enum Event { SpendableOutputs { /// The outputs which you should store as spendable by you. outputs: Vec, + /// The `channel_id` indicating which channel the spendable outputs belong to. + /// + /// This will always be `Some` for events generated by LDK versions 0.0.117 and above. + channel_id: Option, }, /// This event is generated when a payment has been successfully forwarded through us and a /// forwarding fee earned. PaymentForwarded { - /// The incoming channel between the previous node and us. This is only `None` for events - /// generated or serialized by versions prior to 0.0.107. - prev_channel_id: Option<[u8; 32]>, - /// The outgoing channel between the next node and us. This is only `None` for events - /// generated or serialized by versions prior to 0.0.107. - next_channel_id: Option<[u8; 32]>, - /// The fee, in milli-satoshis, which was earned as a result of the payment. + /// The channel id of the incoming channel between the previous node and us. + /// + /// This is only `None` for events generated or serialized by versions prior to 0.0.107. + prev_channel_id: Option, + /// The channel id of the outgoing channel between the next node and us. + /// + /// This is only `None` for events generated or serialized by versions prior to 0.0.107. + next_channel_id: Option, + /// The `user_channel_id` of the incoming channel between the previous node and us. + /// + /// This is only `None` for events generated or serialized by versions prior to 0.0.122. + prev_user_channel_id: Option, + /// The `user_channel_id` of the outgoing channel between the next node and us. + /// + /// This will be `None` if the payment was settled via an on-chain transaction. See the + /// caveat described for the `total_fee_earned_msat` field. Moreover it will be `None` for + /// events generated or serialized by versions prior to 0.0.122. + next_user_channel_id: Option, + /// The total fee, in milli-satoshis, which was earned as a result of the payment. /// /// Note that if we force-closed the channel over which we forwarded an HTLC while the HTLC /// was pending, the amount the next hop claimed will have been rounded down to the nearest @@ -815,20 +929,69 @@ pub enum Event { /// If the channel which sent us the payment has been force-closed, we will claim the funds /// via an on-chain transaction. In that case we do not yet know the on-chain transaction /// fees which we will spend and will instead set this to `None`. It is possible duplicate - /// `PaymentForwarded` events are generated for the same payment iff `fee_earned_msat` is + /// `PaymentForwarded` events are generated for the same payment iff `total_fee_earned_msat` is /// `None`. - fee_earned_msat: Option, + total_fee_earned_msat: Option, + /// The share of the total fee, in milli-satoshis, which was withheld in addition to the + /// forwarding fee. + /// + /// This will only be `Some` if we forwarded an intercepted HTLC with less than the + /// expected amount. This means our counterparty accepted to receive less than the invoice + /// amount, e.g., by claiming the payment featuring a corresponding + /// [`PaymentClaimable::counterparty_skimmed_fee_msat`]. + /// + /// Will also always be `None` for events serialized with LDK prior to version 0.0.122. + /// + /// The caveat described above the `total_fee_earned_msat` field applies here as well. + /// + /// [`PaymentClaimable::counterparty_skimmed_fee_msat`]: Self::PaymentClaimable::counterparty_skimmed_fee_msat + skimmed_fee_msat: Option, /// If this is `true`, the forwarded HTLC was claimed by our counterparty via an on-chain /// transaction. claim_from_onchain_tx: bool, + /// The final amount forwarded, in milli-satoshis, after the fee is deducted. + /// + /// The caveat described above the `total_fee_earned_msat` field applies here as well. + outbound_amount_forwarded_msat: Option, + }, + /// Used to indicate that a channel with the given `channel_id` is being opened and pending + /// confirmation on-chain. + /// + /// This event is emitted when the funding transaction has been signed and is broadcast to the + /// network. For 0conf channels it will be immediately followed by the corresponding + /// [`Event::ChannelReady`] event. + ChannelPending { + /// The `channel_id` of the channel that is pending confirmation. + channel_id: ChannelId, + /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound + /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if + /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise + /// `user_channel_id` will be randomized for an inbound channel. + /// + /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels + user_channel_id: u128, + /// The `temporary_channel_id` this channel used to be known by during channel establishment. + /// + /// Will be `None` for channels created prior to LDK version 0.0.115. + former_temporary_channel_id: Option, + /// The `node_id` of the channel counterparty. + counterparty_node_id: PublicKey, + /// The outpoint of the channel's funding transaction. + funding_txo: OutPoint, + /// The features that this channel will operate with. + /// + /// Will be `None` for channels created prior to LDK version 0.0.122. + channel_type: Option, }, /// Used to indicate that a channel with the given `channel_id` is ready to /// be used. This event is emitted either when the funding transaction has been confirmed /// on-chain, or, in case of a 0conf channel, when both parties have confirmed the channel /// establishment. ChannelReady { - /// The channel_id of the channel that is ready. - channel_id: [u8; 32], + /// The `channel_id` of the channel that is ready. + channel_id: ChannelId, /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise @@ -838,17 +1001,24 @@ pub enum Event { /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels user_channel_id: u128, - /// The node_id of the channel counterparty. + /// The `node_id` of the channel counterparty. counterparty_node_id: PublicKey, /// The features that this channel will operate with. channel_type: ChannelTypeFeatures, }, /// Used to indicate that a previously opened channel with the given `channel_id` is in the /// process of closure. - ChannelClosed { - /// The channel_id of the channel which has been closed. Note that on-chain transactions + /// + /// Note that this event is only triggered for accepted channels: if the + /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true and the channel is + /// rejected, no `ChannelClosed` event will be sent. + /// + /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel + /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels + ChannelClosed { + /// The `channel_id` of the channel which has been closed. Note that on-chain transactions /// resolving the channel are likely still awaiting confirmation. - channel_id: [u8; 32], + channel_id: ChannelId, /// The `user_channel_id` value passed in to [`ChannelManager::create_channel`] for outbound /// channels, or to [`ChannelManager::accept_inbound_channel`] for inbound channels if /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. Otherwise @@ -861,20 +1031,35 @@ pub enum Event { /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels user_channel_id: u128, /// The reason the channel was closed. - reason: ClosureReason + reason: ClosureReason, + /// Counterparty in the closed channel. + /// + /// This field will be `None` for objects serialized prior to LDK 0.0.117. + counterparty_node_id: Option, + /// Channel capacity of the closing channel (sats). + /// + /// This field will be `None` for objects serialized prior to LDK 0.0.117. + channel_capacity_sats: Option, + /// The original channel funding TXO; this helps checking for the existence and confirmation + /// status of the closing tx. + /// Note that for instances serialized in v0.0.119 or prior this will be missing (None). + channel_funding_txo: Option, }, /// Used to indicate to the user that they can abandon the funding transaction and recycle the /// inputs for another purpose. + /// + /// This event is not guaranteed to be generated for channels that are closed due to a restart. DiscardFunding { /// The channel_id of the channel which has been closed. - channel_id: [u8; 32], + channel_id: ChannelId, /// The full transaction received from the user transaction: Transaction }, /// Indicates a request to open a new channel by a peer. /// - /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the - /// request, call [`ChannelManager::force_close_without_broadcasting_txn`]. + /// To accept the request, call [`ChannelManager::accept_inbound_channel`]. To reject the request, + /// call [`ChannelManager::force_close_without_broadcasting_txn`]. Note that a ['ChannelClosed`] + /// event will _not_ be triggered if the channel is rejected. /// /// The event is only triggered when a new open channel request is received and the /// [`UserConfig::manually_accept_inbound_channels`] config flag is set to true. @@ -891,7 +1076,7 @@ pub enum Event { /// /// [`ChannelManager::accept_inbound_channel`]: crate::ln::channelmanager::ChannelManager::accept_inbound_channel /// [`ChannelManager::force_close_without_broadcasting_txn`]: crate::ln::channelmanager::ChannelManager::force_close_without_broadcasting_txn - temporary_channel_id: [u8; 32], + temporary_channel_id: ChannelId, /// The node_id of the counterparty requesting to open the channel. /// /// When responding to the request, the `counterparty_node_id` should be passed @@ -930,23 +1115,25 @@ pub enum Event { /// * Insufficient capacity in the outbound channel /// * While waiting to forward the HTLC, the channel it is meant to be forwarded through closes /// * When an unknown SCID is requested for forwarding a payment. - /// * Claiming an amount for an MPP payment that exceeds the HTLC total + /// * Expected MPP amount has already been reached /// * The HTLC has timed out /// /// This event, however, does not get generated if an HTLC fails to meet the forwarding /// requirements (i.e. insufficient fees paid, or a CLTV that is too soon). HTLCHandlingFailed { /// The channel over which the HTLC was received. - prev_channel_id: [u8; 32], + prev_channel_id: ChannelId, /// Destination of the HTLC that failed to be processed. failed_next_destination: HTLCDestination, }, - #[cfg(anchors)] /// Indicates that a transaction originating from LDK needs to have its fee bumped. This event /// requires confirmed external funds to be readily available to spend. /// - /// LDK does not currently generate this event. It is limited to the scope of channels with - /// anchor outputs, which will be introduced in a future release. + /// LDK does not currently generate this event unless the + /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`] config flag is set to true. + /// It is limited to the scope of channels with anchor outputs. + /// + /// [`ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx`]: crate::util::config::ChannelHandshakeConfig::negotiate_anchors_zero_fee_htlc_tx BumpTransaction(BumpTransactionEvent), } @@ -958,19 +1145,41 @@ impl Writeable for Event { // We never write out FundingGenerationReady events as, upon disconnection, peers // drop any channels which have not yet exchanged funding_signed. }, - &Event::PaymentClaimable { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id } => { + &Event::PaymentClaimable { ref payment_hash, ref amount_msat, counterparty_skimmed_fee_msat, + ref purpose, ref receiver_node_id, ref via_channel_id, ref via_user_channel_id, + ref claim_deadline, ref onion_fields + } => { 1u8.write(writer)?; let mut payment_secret = None; let payment_preimage; + let mut payment_context = None; match &purpose { - PaymentPurpose::InvoicePayment { payment_preimage: preimage, payment_secret: secret } => { + PaymentPurpose::Bolt11InvoicePayment { + payment_preimage: preimage, payment_secret: secret + } => { payment_secret = Some(secret); payment_preimage = *preimage; }, + PaymentPurpose::Bolt12OfferPayment { + payment_preimage: preimage, payment_secret: secret, payment_context: context + } => { + payment_secret = Some(secret); + payment_preimage = *preimage; + payment_context = Some(PaymentContextRef::Bolt12Offer(context)); + }, + PaymentPurpose::Bolt12RefundPayment { + payment_preimage: preimage, payment_secret: secret, payment_context: context + } => { + payment_secret = Some(secret); + payment_preimage = *preimage; + payment_context = Some(PaymentContextRef::Bolt12Refund(context)); + }, PaymentPurpose::SpontaneousPayment(preimage) => { payment_preimage = Some(*preimage); } } + let skimmed_fee_opt = if counterparty_skimmed_fee_msat == 0 { None } + else { Some(counterparty_skimmed_fee_msat) }; write_tlv_fields!(writer, { (0, payment_hash, required), (1, receiver_node_id, option), @@ -978,8 +1187,12 @@ impl Writeable for Event { (3, via_channel_id, option), (4, amount_msat, required), (5, via_user_channel_id, option), - (6, 0u64, required), // user_payment_id required for compatibility with 0.0.103 and earlier + // Type 6 was `user_payment_id` on 0.0.103 and earlier + (7, claim_deadline, option), (8, payment_preimage, option), + (9, onion_fields, option), + (10, skimmed_fee_opt, option), + (11, payment_context, option), }); }, &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => { @@ -1009,7 +1222,8 @@ impl Writeable for Event { (1, None::, option), // network_update in LDK versions prior to 0.0.114 (2, payment_failed_permanently, required), (3, false, required), // all_paths_failed in LDK versions prior to 0.0.114 - (5, *path, vec_type), + (4, path.blinded_tail, option), + (5, path.hops, required_vec), (7, short_channel_id, option), (9, None::, option), // retry in LDK versions prior to 0.0.115 (11, payment_id, option), @@ -1021,10 +1235,11 @@ impl Writeable for Event { // Note that we now ignore these on the read end as we'll re-generate them in // ChannelManager, we write them here only for backwards compatibility. }, - &Event::SpendableOutputs { ref outputs } => { + &Event::SpendableOutputs { ref outputs, channel_id } => { 5u8.write(writer)?; write_tlv_fields!(writer, { (0, WithoutLength(outputs), required), + (1, channel_id, option), }); }, &Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat, expected_outbound_amount_msat, intercept_id } => { @@ -1038,16 +1253,26 @@ impl Writeable for Event { (8, expected_outbound_amount_msat, required), }); } - &Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id } => { + &Event::PaymentForwarded { + prev_channel_id, next_channel_id, prev_user_channel_id, next_user_channel_id, + total_fee_earned_msat, skimmed_fee_msat, claim_from_onchain_tx, + outbound_amount_forwarded_msat, + } => { 7u8.write(writer)?; write_tlv_fields!(writer, { - (0, fee_earned_msat, option), + (0, total_fee_earned_msat, option), (1, prev_channel_id, option), (2, claim_from_onchain_tx, required), (3, next_channel_id, option), + (5, outbound_amount_forwarded_msat, option), + (7, skimmed_fee_msat, option), + (9, prev_user_channel_id, option), + (11, next_user_channel_id, option), }); }, - &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => { + &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason, + ref counterparty_node_id, ref channel_capacity_sats, ref channel_funding_txo + } => { 9u8.write(writer)?; // `user_channel_id` used to be a single u64 value. In order to remain backwards // compatible with versions prior to 0.0.113, the u128 is serialized as two @@ -1059,6 +1284,9 @@ impl Writeable for Event { (1, user_channel_id_low, required), (2, reason, required), (3, user_channel_id_high, required), + (5, counterparty_node_id, option), + (7, channel_capacity_sats, option), + (9, channel_funding_txo, option), }); }, &Event::DiscardFunding { ref channel_id, ref transaction } => { @@ -1073,13 +1301,15 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, option), - (4, *path, vec_type) + (4, path.hops, required_vec), + (6, path.blinded_tail, option), }) }, - &Event::PaymentFailed { ref payment_id, ref payment_hash } => { + &Event::PaymentFailed { ref payment_id, ref payment_hash, ref reason } => { 15u8.write(writer)?; write_tlv_fields!(writer, { (0, payment_id, required), + (1, reason, option), (2, payment_hash, required), }) }, @@ -1088,13 +1318,15 @@ impl Writeable for Event { // We never write the OpenChannelRequest events as, upon disconnection, peers // drop any channels which have not yet exchanged funding_signed. }, - &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id } => { + &Event::PaymentClaimed { ref payment_hash, ref amount_msat, ref purpose, ref receiver_node_id, ref htlcs, ref sender_intended_total_msat } => { 19u8.write(writer)?; write_tlv_fields!(writer, { (0, payment_hash, required), (1, receiver_node_id, option), (2, purpose, required), (4, amount_msat, required), + (5, *htlcs, optional_vec), + (7, sender_intended_total_msat, option), }); }, &Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => { @@ -1102,7 +1334,8 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, required), - (4, *path, vec_type) + (4, path.hops, required_vec), + (6, path.blinded_tail, option), }) }, &Event::ProbeFailed { ref payment_id, ref payment_hash, ref path, ref short_channel_id } => { @@ -1110,8 +1343,9 @@ impl Writeable for Event { write_tlv_fields!(writer, { (0, payment_id, required), (2, payment_hash, required), - (4, *path, vec_type), + (4, path.hops, required_vec), (6, short_channel_id, option), + (8, path.blinded_tail, option), }) }, &Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => { @@ -1121,7 +1355,6 @@ impl Writeable for Event { (2, failed_next_destination, required), }) }, - #[cfg(anchors)] &Event::BumpTransaction(ref event)=> { 27u8.write(writer)?; match event { @@ -1141,6 +1374,30 @@ impl Writeable for Event { (6, channel_type, required), }); }, + &Event::ChannelPending { ref channel_id, ref user_channel_id, + ref former_temporary_channel_id, ref counterparty_node_id, ref funding_txo, + ref channel_type + } => { + 31u8.write(writer)?; + write_tlv_fields!(writer, { + (0, channel_id, required), + (1, channel_type, option), + (2, user_channel_id, required), + (4, former_temporary_channel_id, required), + (6, counterparty_node_id, required), + (8, funding_txo, required), + }); + }, + &Event::InvoiceRequestFailed { ref payment_id } => { + 33u8.write(writer)?; + write_tlv_fields!(writer, { + (0, payment_id, required), + }) + }, + &Event::ConnectionNeeded { .. } => { + 35u8.write(writer)?; + // Never write ConnectionNeeded events as buffered onion messages aren't serialized. + }, // Note that, going forward, all new events must only write data inside of // `write_tlv_fields`. Versions 0.0.101+ will ignore odd-numbered events that write // data via `write_tlv_fields`. @@ -1151,19 +1408,22 @@ impl Writeable for Event { impl MaybeReadable for Event { fn read(reader: &mut R) -> Result, msgs::DecodeError> { match Readable::read(reader)? { - // Note that we do not write a length-prefixed TLV for FundingGenerationReady events, - // unlike all other events, thus we return immediately here. + // Note that we do not write a length-prefixed TLV for FundingGenerationReady events. 0u8 => Ok(None), 1u8 => { - let f = || { + let mut f = || { let mut payment_hash = PaymentHash([0; 32]); let mut payment_preimage = None; let mut payment_secret = None; let mut amount_msat = 0; + let mut counterparty_skimmed_fee_msat_opt = None; let mut receiver_node_id = None; - let mut _user_payment_id = None::; // For compatibility with 0.0.103 and earlier + let mut _user_payment_id = None::; // Used in 0.0.103 and earlier, no longer written in 0.0.116+. let mut via_channel_id = None; + let mut claim_deadline = None; let mut via_user_channel_id = None; + let mut onion_fields = None; + let mut payment_context = None; read_tlv_fields!(reader, { (0, payment_hash, required), (1, receiver_node_id, option), @@ -1172,13 +1432,14 @@ impl MaybeReadable for Event { (4, amount_msat, required), (5, via_user_channel_id, option), (6, _user_payment_id, option), + (7, claim_deadline, option), (8, payment_preimage, option), + (9, onion_fields, option), + (10, counterparty_skimmed_fee_msat_opt, option), + (11, payment_context, option), }); let purpose = match payment_secret { - Some(secret) => PaymentPurpose::InvoicePayment { - payment_preimage, - payment_secret: secret - }, + Some(secret) => PaymentPurpose::from_parts(payment_preimage, secret, payment_context), None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()), None => return Err(msgs::DecodeError::InvalidValue), }; @@ -1186,15 +1447,18 @@ impl MaybeReadable for Event { receiver_node_id, payment_hash, amount_msat, + counterparty_skimmed_fee_msat: counterparty_skimmed_fee_msat_opt.unwrap_or(0), purpose, via_channel_id, via_user_channel_id, + claim_deadline, + onion_fields, })) }; f() }, 2u8 => { - let f = || { + let mut f = || { let mut payment_preimage = PaymentPreimage([0; 32]); let mut payment_hash = None; let mut payment_id = None; @@ -1206,7 +1470,7 @@ impl MaybeReadable for Event { (5, fee_paid_msat, option), }); if payment_hash.is_none() { - payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner())); + payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).to_byte_array())); } Ok(Some(Event::PaymentSent { payment_id, @@ -1218,7 +1482,7 @@ impl MaybeReadable for Event { f() }, 3u8 => { - let f = || { + let mut f = || { #[cfg(test)] let error_code = Readable::read(reader)?; #[cfg(test)] @@ -1226,6 +1490,7 @@ impl MaybeReadable for Event { let mut payment_hash = PaymentHash([0; 32]); let mut payment_failed_permanently = false; let mut network_update = None; + let mut blinded_tail: Option = None; let mut path: Option> = Some(vec![]); let mut short_channel_id = None; let mut payment_id = None; @@ -1234,7 +1499,10 @@ impl MaybeReadable for Event { (0, payment_hash, required), (1, network_update, upgradable_option), (2, payment_failed_permanently, required), - (5, path, vec_type), + (4, blinded_tail, option), + // Added as a part of LDK 0.0.101 and always filled in since. + // Defaults to an empty Vec, though likely should have been `Option`al. + (5, path, optional_vec), (7, short_channel_id, option), (11, payment_id, option), (13, failure_opt, upgradable_option), @@ -1245,7 +1513,7 @@ impl MaybeReadable for Event { payment_hash, payment_failed_permanently, failure, - path: path.unwrap(), + path: Path { hops: path.unwrap(), blinded_tail }, short_channel_id, #[cfg(test)] error_code, @@ -1257,12 +1525,14 @@ impl MaybeReadable for Event { }, 4u8 => Ok(None), 5u8 => { - let f = || { + let mut f = || { let mut outputs = WithoutLength(Vec::new()); + let mut channel_id: Option = None; read_tlv_fields!(reader, { (0, outputs, required), + (1, channel_id, option), }); - Ok(Some(Event::SpendableOutputs { outputs: outputs.0 })) + Ok(Some(Event::SpendableOutputs { outputs: outputs.0, channel_id })) }; f() }, @@ -1291,32 +1561,50 @@ impl MaybeReadable for Event { })) }, 7u8 => { - let f = || { - let mut fee_earned_msat = None; + let mut f = || { let mut prev_channel_id = None; - let mut claim_from_onchain_tx = false; let mut next_channel_id = None; + let mut prev_user_channel_id = None; + let mut next_user_channel_id = None; + let mut total_fee_earned_msat = None; + let mut skimmed_fee_msat = None; + let mut claim_from_onchain_tx = false; + let mut outbound_amount_forwarded_msat = None; read_tlv_fields!(reader, { - (0, fee_earned_msat, option), + (0, total_fee_earned_msat, option), (1, prev_channel_id, option), (2, claim_from_onchain_tx, required), (3, next_channel_id, option), + (5, outbound_amount_forwarded_msat, option), + (7, skimmed_fee_msat, option), + (9, prev_user_channel_id, option), + (11, next_user_channel_id, option), }); - Ok(Some(Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id })) + Ok(Some(Event::PaymentForwarded { + prev_channel_id, next_channel_id, prev_user_channel_id, + next_user_channel_id, total_fee_earned_msat, skimmed_fee_msat, + claim_from_onchain_tx, outbound_amount_forwarded_msat, + })) }; f() }, 9u8 => { - let f = || { - let mut channel_id = [0; 32]; + let mut f = || { + let mut channel_id = ChannelId::new_zero(); let mut reason = UpgradableRequired(None); let mut user_channel_id_low_opt: Option = None; let mut user_channel_id_high_opt: Option = None; + let mut counterparty_node_id = None; + let mut channel_capacity_sats = None; + let mut channel_funding_txo = None; read_tlv_fields!(reader, { (0, channel_id, required), (1, user_channel_id_low_opt, option), (2, reason, upgradable_required), (3, user_channel_id_high_opt, option), + (5, counterparty_node_id, option), + (7, channel_capacity_sats, option), + (9, channel_funding_txo, option), }); // `user_channel_id` used to be a single u64 value. In order to remain @@ -1325,14 +1613,15 @@ impl MaybeReadable for Event { let user_channel_id = (user_channel_id_low_opt.unwrap_or(0) as u128) + ((user_channel_id_high_opt.unwrap_or(0) as u128) << 64); - Ok(Some(Event::ChannelClosed { channel_id, user_channel_id, reason: _init_tlv_based_struct_field!(reason, upgradable_required) })) + Ok(Some(Event::ChannelClosed { channel_id, user_channel_id, reason: _init_tlv_based_struct_field!(reason, upgradable_required), + counterparty_node_id, channel_capacity_sats, channel_funding_txo })) }; f() }, 11u8 => { - let f = || { - let mut channel_id = [0; 32]; - let mut transaction = Transaction{ version: 2, lock_time: PackedLockTime::ZERO, input: Vec::new(), output: Vec::new() }; + let mut f = || { + let mut channel_id = ChannelId::new_zero(); + let mut transaction = Transaction{ version: 2, lock_time: LockTime::ZERO, input: Vec::new(), output: Vec::new() }; read_tlv_fields!(reader, { (0, channel_id, required), (2, transaction, required), @@ -1342,34 +1631,35 @@ impl MaybeReadable for Event { f() }, 13u8 => { - let f = || { - let mut payment_id = PaymentId([0; 32]); - let mut payment_hash = None; - let mut path: Option> = Some(vec![]); - read_tlv_fields!(reader, { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, option), - (4, path, vec_type), + (4, path, required_vec), + (6, blinded_tail, option), }); Ok(Some(Event::PaymentPathSuccessful { - payment_id, + payment_id: payment_id.0.unwrap(), payment_hash, - path: path.unwrap(), + path: Path { hops: path, blinded_tail }, })) }; f() }, 15u8 => { - let f = || { + let mut f = || { let mut payment_hash = PaymentHash([0; 32]); let mut payment_id = PaymentId([0; 32]); + let mut reason = None; read_tlv_fields!(reader, { (0, payment_id, required), + (1, reason, upgradable_option), (2, payment_hash, required), }); Ok(Some(Event::PaymentFailed { payment_id, payment_hash, + reason, })) }; f() @@ -1379,68 +1669,69 @@ impl MaybeReadable for Event { Ok(None) }, 19u8 => { - let f = || { + let mut f = || { let mut payment_hash = PaymentHash([0; 32]); let mut purpose = UpgradableRequired(None); let mut amount_msat = 0; let mut receiver_node_id = None; + let mut htlcs: Option> = Some(vec![]); + let mut sender_intended_total_msat: Option = None; read_tlv_fields!(reader, { (0, payment_hash, required), (1, receiver_node_id, option), (2, purpose, upgradable_required), (4, amount_msat, required), + (5, htlcs, optional_vec), + (7, sender_intended_total_msat, option), }); Ok(Some(Event::PaymentClaimed { receiver_node_id, payment_hash, purpose: _init_tlv_based_struct_field!(purpose, upgradable_required), amount_msat, + htlcs: htlcs.unwrap_or(vec![]), + sender_intended_total_msat, })) }; f() }, 21u8 => { - let f = || { - let mut payment_id = PaymentId([0; 32]); - let mut payment_hash = PaymentHash([0; 32]); - let mut path: Option> = Some(vec![]); - read_tlv_fields!(reader, { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, required), - (4, path, vec_type), + (4, path, required_vec), + (6, blinded_tail, option), }); Ok(Some(Event::ProbeSuccessful { - payment_id, - payment_hash, - path: path.unwrap(), + payment_id: payment_id.0.unwrap(), + payment_hash: payment_hash.0.unwrap(), + path: Path { hops: path, blinded_tail }, })) }; f() }, 23u8 => { - let f = || { - let mut payment_id = PaymentId([0; 32]); - let mut payment_hash = PaymentHash([0; 32]); - let mut path: Option> = Some(vec![]); - let mut short_channel_id = None; - read_tlv_fields!(reader, { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { (0, payment_id, required), (2, payment_hash, required), - (4, path, vec_type), + (4, path, required_vec), (6, short_channel_id, option), + (8, blinded_tail, option), }); Ok(Some(Event::ProbeFailed { - payment_id, - payment_hash, - path: path.unwrap(), + payment_id: payment_id.0.unwrap(), + payment_hash: payment_hash.0.unwrap(), + path: Path { hops: path, blinded_tail }, short_channel_id, })) }; f() }, 25u8 => { - let f = || { - let mut prev_channel_id = [0; 32]; + let mut f = || { + let mut prev_channel_id = ChannelId::new_zero(); let mut failed_next_destination_opt = UpgradableRequired(None); read_tlv_fields!(reader, { (0, prev_channel_id, required), @@ -1455,8 +1746,8 @@ impl MaybeReadable for Event { }, 27u8 => Ok(None), 29u8 => { - let f = || { - let mut channel_id = [0; 32]; + let mut f = || { + let mut channel_id = ChannelId::new_zero(); let mut user_channel_id: u128 = 0; let mut counterparty_node_id = RequiredWrapper(None); let mut channel_type = RequiredWrapper(None); @@ -1476,6 +1767,47 @@ impl MaybeReadable for Event { }; f() }, + 31u8 => { + let mut f = || { + let mut channel_id = ChannelId::new_zero(); + let mut user_channel_id: u128 = 0; + let mut former_temporary_channel_id = None; + let mut counterparty_node_id = RequiredWrapper(None); + let mut funding_txo = RequiredWrapper(None); + let mut channel_type = None; + read_tlv_fields!(reader, { + (0, channel_id, required), + (1, channel_type, option), + (2, user_channel_id, required), + (4, former_temporary_channel_id, required), + (6, counterparty_node_id, required), + (8, funding_txo, required), + }); + + Ok(Some(Event::ChannelPending { + channel_id, + user_channel_id, + former_temporary_channel_id, + counterparty_node_id: counterparty_node_id.0.unwrap(), + funding_txo: funding_txo.0.unwrap(), + channel_type, + })) + }; + f() + }, + 33u8 => { + let mut f = || { + _init_and_read_len_prefixed_tlv_fields!(reader, { + (0, payment_id, required), + }); + Ok(Some(Event::InvoiceRequestFailed { + payment_id: payment_id.0.unwrap(), + })) + }; + f() + }, + // Note that we do not write a length-prefixed TLV for ConnectionNeeded events. + 35u8 => Ok(None), // Versions prior to 0.0.100 did not ignore odd types, instead returning InvalidValue. // Version 0.0.100 failed to properly ignore odd types, possibly resulting in corrupt // reads. @@ -1499,6 +1831,7 @@ impl MaybeReadable for Event { /// broadcast to most peers). /// These events are handled by PeerManager::process_events if you are using a PeerManager. #[derive(Clone, Debug)] +#[cfg_attr(test, derive(PartialEq))] pub enum MessageSendEvent { /// Used to indicate that we've accepted a channel open and should send the accept_channel /// message provided to the given peer. @@ -1508,6 +1841,14 @@ pub enum MessageSendEvent { /// The message which should be sent. msg: msgs::AcceptChannel, }, + /// Used to indicate that we've accepted a V2 channel open and should send the accept_channel2 + /// message provided to the given peer. + SendAcceptChannelV2 { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::AcceptChannelV2, + }, /// Used to indicate that we've initiated a channel open and should send the open_channel /// message provided to the given peer. SendOpenChannel { @@ -1516,6 +1857,14 @@ pub enum MessageSendEvent { /// The message which should be sent. msg: msgs::OpenChannel, }, + /// Used to indicate that we've initiated a V2 channel open and should send the open_channel2 + /// message provided to the given peer. + SendOpenChannelV2 { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::OpenChannelV2, + }, /// Used to indicate that a funding_created message should be sent to the peer with the given node_id. SendFundingCreated { /// The node_id of the node which should receive this message @@ -1530,6 +1879,97 @@ pub enum MessageSendEvent { /// The message which should be sent. msg: msgs::FundingSigned, }, + /// Used to indicate that a stfu message should be sent to the peer with the given node id. + SendStfu { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::Stfu, + }, + /// Used to indicate that a splice message should be sent to the peer with the given node id. + SendSplice { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::Splice, + }, + /// Used to indicate that a splice_ack message should be sent to the peer with the given node id. + SendSpliceAck { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::SpliceAck, + }, + /// Used to indicate that a splice_locked message should be sent to the peer with the given node id. + SendSpliceLocked { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::SpliceLocked, + }, + /// Used to indicate that a tx_add_input message should be sent to the peer with the given node_id. + SendTxAddInput { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxAddInput, + }, + /// Used to indicate that a tx_add_output message should be sent to the peer with the given node_id. + SendTxAddOutput { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxAddOutput, + }, + /// Used to indicate that a tx_remove_input message should be sent to the peer with the given node_id. + SendTxRemoveInput { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxRemoveInput, + }, + /// Used to indicate that a tx_remove_output message should be sent to the peer with the given node_id. + SendTxRemoveOutput { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxRemoveOutput, + }, + /// Used to indicate that a tx_complete message should be sent to the peer with the given node_id. + SendTxComplete { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxComplete, + }, + /// Used to indicate that a tx_signatures message should be sent to the peer with the given node_id. + SendTxSignatures { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxSignatures, + }, + /// Used to indicate that a tx_init_rbf message should be sent to the peer with the given node_id. + SendTxInitRbf { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxInitRbf, + }, + /// Used to indicate that a tx_ack_rbf message should be sent to the peer with the given node_id. + SendTxAckRbf { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxAckRbf, + }, + /// Used to indicate that a tx_abort message should be sent to the peer with the given node_id. + SendTxAbort { + /// The node_id of the node which should receive this message + node_id: PublicKey, + /// The message which should be sent. + msg: msgs::TxAbort, + }, /// Used to indicate that a channel_ready message should be sent to the peer with the given node_id. SendChannelReady { /// The node_id of the node which should receive these message(s) @@ -1672,12 +2112,6 @@ pub trait MessageSendEventsProvider { fn get_and_clear_pending_msg_events(&self) -> Vec; } -/// A trait indicating an object may generate onion messages to send -pub trait OnionMessageProvider { - /// Gets the next pending onion message for the peer with the given node id. - fn next_onion_message_for_peer(&self, peer_node_id: PublicKey) -> Option; -} - /// A trait indicating an object may generate events. /// /// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].