RUSTC_MINOR_VERSION=$(rustc --version | awk '{ split($2,a,"."); print a[2] }')
HOST_PLATFORM="$(rustc --version --verbose | grep "host:" | awk '{ print $2 }')"
-# Tokio MSRV on versions newer than 1.14 is rustc 1.49
+# Tokio MSRV on versions 1.17 through 1.26 is rustc 1.49. Above 1.26 MSRV is 1.56.
[ "$RUSTC_MINOR_VERSION" -lt 49 ] && cargo update -p tokio --precise "1.14.0" --verbose
+[[ "$RUSTC_MINOR_VERSION" -gt 48 && "$RUSTC_MINOR_VERSION" -lt 56 ]] && cargo update -p tokio --precise "1.26.0" --verbose
[ "$LDK_COVERAGE_BUILD" != "" ] && export RUSTFLAGS="-C link-dead-code"
export RUST_BACKTRACE=1
use lightning::chain::transaction::OutPoint;
use lightning::chain::chaininterface::{BroadcasterInterface, ConfirmationTarget, FeeEstimator};
use lightning::chain::keysinterface::{KeyMaterial, InMemorySigner, Recipient, EntropySource, NodeSigner, SignerProvider};
+use lightning::events;
+use lightning::events::MessageSendEventsProvider;
use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentSendFailure, ChannelManagerReadArgs, PaymentId};
use lightning::ln::channel::FEE_SPIKE_BUFFER_FEE_INCREASE_MULTIPLE;
use lightning::ln::script::ShutdownScript;
use lightning::util::enforcing_trait_impls::{EnforcingSigner, EnforcementState};
use lightning::util::errors::APIError;
-use lightning::util::events;
use lightning::util::logger::Logger;
use lightning::util::config::UserConfig;
-use lightning::util::events::MessageSendEventsProvider;
use lightning::util::ser::{Readable, ReadableArgs, Writeable, Writer};
use lightning::routing::router::{InFlightHtlcs, Route, RouteHop, RouteParameters, Router};
use lightning::chain::chainmonitor;
use lightning::chain::transaction::OutPoint;
use lightning::chain::keysinterface::{InMemorySigner, Recipient, KeyMaterial, EntropySource, NodeSigner, SignerProvider};
+use lightning::events::Event;
use lightning::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
use lightning::ln::channelmanager::{ChainParameters, ChannelDetails, ChannelManager, PaymentId};
use lightning::ln::peer_handler::{MessageHandler,PeerManager,SocketDescriptor,IgnoringMessageHandler};
use lightning::routing::scoring::FixedPenaltyScorer;
use lightning::util::config::UserConfig;
use lightning::util::errors::APIError;
-use lightning::util::events::Event;
use lightning::util::enforcing_trait_impls::{EnforcingSigner, EnforcementState};
use lightning::util::logger::Logger;
use lightning::util::ser::{Readable, Writeable};
use lightning::chain::chaininterface::{BroadcasterInterface, FeeEstimator};
use lightning::chain::chainmonitor::{ChainMonitor, Persist};
use lightning::chain::keysinterface::{EntropySource, NodeSigner, SignerProvider};
+use lightning::events::{Event, PathFailure};
+#[cfg(feature = "std")]
+use lightning::events::{EventHandler, EventsProvider};
use lightning::ln::channelmanager::ChannelManager;
use lightning::ln::msgs::{ChannelMessageHandler, OnionMessageHandler, RoutingMessageHandler};
use lightning::ln::peer_handler::{CustomMessageHandler, PeerManager, SocketDescriptor};
use lightning::routing::utxo::UtxoLookup;
use lightning::routing::router::Router;
use lightning::routing::scoring::{Score, WriteableScore};
-use lightning::util::events::{Event, PathFailure};
-#[cfg(feature = "std")]
-use lightning::util::events::{EventHandler, EventsProvider};
use lightning::util::logger::Logger;
use lightning::util::persist::Persister;
use lightning_rapid_gossip_sync::RapidGossipSync;
/// unilateral chain closure fees are at risk.
///
/// [`ChannelMonitor`]: lightning::chain::channelmonitor::ChannelMonitor
-/// [`Event`]: lightning::util::events::Event
+/// [`Event`]: lightning::events::Event
#[cfg(feature = "std")]
#[must_use = "BackgroundProcessor will immediately stop on drop. It should be stored until shutdown."]
pub struct BackgroundProcessor {
}
}
-/// (C-not exported) as the bindings concretize everything and have constructors for us
+/// This is not exported to bindings users as the bindings concretize everything and have constructors for us
impl<P: Deref<Target = P2PGossipSync<G, U, L>>, G: Deref<Target = NetworkGraph<L>>, U: Deref, L: Deref>
GossipSync<P, &RapidGossipSync<G, L>, G, U, L>
where
}
}
-/// (C-not exported) as the bindings concretize everything and have constructors for us
+/// This is not exported to bindings users as the bindings concretize everything and have constructors for us
impl<'a, R: Deref<Target = RapidGossipSync<G, L>>, G: Deref<Target = NetworkGraph<L>>, L: Deref>
GossipSync<
&P2PGossipSync<G, &'a (dyn UtxoLookup + Send + Sync), L>,
}
}
-/// (C-not exported) as the bindings concretize everything and have constructors for us
+/// This is not exported to bindings users as the bindings concretize everything and have constructors for us
impl<'a, L: Deref>
GossipSync<
&P2PGossipSync<&'a NetworkGraph<L>, &'a (dyn UtxoLookup + Send + Sync), L>,
use lightning::chain::channelmonitor::ANTI_REORG_DELAY;
use lightning::chain::keysinterface::{InMemorySigner, KeysManager};
use lightning::chain::transaction::OutPoint;
+ use lightning::events::{Event, PathFailure, MessageSendEventsProvider, MessageSendEvent};
use lightning::get_event_msg;
use lightning::ln::PaymentHash;
use lightning::ln::channelmanager;
use lightning::routing::router::{DefaultRouter, RouteHop};
use lightning::routing::scoring::{ChannelUsage, Score};
use lightning::util::config::UserConfig;
- use lightning::util::events::{Event, PathFailure, MessageSendEventsProvider, MessageSendEvent};
use lightning::util::ser::Writeable;
use lightning::util::test_utils;
use lightning::util::persist::KVStorePersister;
/// * `H`: exactly one `PaymentHash`
/// * `T`: the timestamp is set
///
-/// (C-not exported) as we likely need to manually select one set of boolean type parameters.
+/// This is not exported to bindings users as we likely need to manually select one set of boolean type parameters.
#[derive(Eq, PartialEq, Debug, Clone)]
pub struct InvoiceBuilder<D: tb::Bool, H: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> {
currency: Currency,
/// Represents the description of an invoice which has to be either a directly included string or
/// a hash of a description provided out of band.
///
-/// (C-not exported) As we don't have a good way to map the reference lifetimes making this
+/// This is not exported to bindings users as we don't have a good way to map the reference lifetimes making this
/// practically impossible to use safely in languages like C.
#[derive(Eq, PartialEq, Debug, Clone)]
pub enum InvoiceDescription<'f> {
/// Data of the `RawInvoice` that is encoded in the human readable part
///
-/// (C-not exported) As we don't yet support `Option<Enum>`
+/// This is not exported to bindings users as we don't yet support `Option<Enum>`
#[derive(Eq, PartialEq, Debug, Clone, Hash)]
pub struct RawHrp {
/// The currency deferred from the 3rd and 4th character of the bech32 transaction
/// Returns all enum variants of `SiPrefix` sorted in descending order of their associated
/// multiplier.
///
- /// (C-not exported) As we don't yet support a slice of enums, and also because this function
+ /// This is not exported to bindings users as we don't yet support a slice of enums, and also because this function
/// isn't the most critical to expose.
pub fn values_desc() -> &'static [SiPrefix] {
use crate::SiPrefix::*;
/// Tagged field which may have an unknown tag
///
-/// (C-not exported) as we don't currently support TaggedField
+/// This is not exported to bindings users as we don't currently support TaggedField
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
pub enum RawTaggedField {
/// Parsed tagged field with known tag
///
/// For descriptions of the enum values please refer to the enclosed type's docs.
///
-/// (C-not exported) As we don't yet support enum variants with the same name the struct contained
+/// This is not exported to bindings users as we don't yet support enum variants with the same name the struct contained
/// in the variant.
#[allow(missing_docs)]
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
/// SHA-256 hash
#[derive(Clone, Debug, Hash, Eq, PartialEq)]
-pub struct Sha256(/// (C-not exported) as the native hash types are not currently mapped
+pub struct Sha256(/// This is not exported to bindings users as the native hash types are not currently mapped
pub sha256::Hash);
/// Description string
self.tagged_fields.push(TaggedField::DescriptionHash(Sha256(description_hash)));
self.set_flags()
}
+
+ /// Set the description or description hash. This function is only available if no description (hash) was set.
+ pub fn invoice_description(self, description: InvoiceDescription) -> InvoiceBuilder<tb::True, H, T, C, S> {
+ match description {
+ InvoiceDescription::Direct(desc) => {
+ self.description(desc.clone().into_inner())
+ }
+ InvoiceDescription::Hash(hash) => {
+ self.description_hash(hash.0)
+ }
+ }
+ }
}
impl<D: tb::Bool, T: tb::Bool, C: tb::Bool, S: tb::Bool> InvoiceBuilder<D, tb::False, T, C, S> {
/// of type `E`. Since the signature of a `SignedRawInvoice` is not required to be valid there
/// are no constraints regarding the validity of the produced signature.
///
- /// (C-not exported) As we don't currently support passing function pointers into methods
+ /// This is not exported to bindings users as we don't currently support passing function pointers into methods
/// explicitly.
pub fn sign<F, E>(self, sign_method: F) -> Result<SignedRawInvoice, E>
where F: FnOnce(&Message) -> Result<RecoverableSignature, E>
/// Returns an iterator over all tagged fields with known semantics.
///
- /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+ /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
pub fn known_tagged_fields(&self)
-> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>>
{
find_extract!(self.known_tagged_fields(), TaggedField::Features(ref x), x)
}
- /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+ /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
pub fn fallbacks(&self) -> Vec<&Fallback> {
find_all_extract!(self.known_tagged_fields(), TaggedField::Fallback(ref x), x).collect()
}
/// Returns an iterator over all tagged fields of this Invoice.
///
- /// (C-not exported) As there is not yet a manual mapping for a FilterMap
+ /// This is not exported to bindings users as there is not yet a manual mapping for a FilterMap
pub fn tagged_fields(&self)
-> FilterMap<Iter<RawTaggedField>, fn(&RawTaggedField) -> Option<&TaggedField>> {
self.signed_invoice.raw_invoice().known_tagged_fields()
/// Return the description or a hash of it for longer ones
///
- /// (C-not exported) because we don't yet export InvoiceDescription
+ /// This is not exported to bindings users because we don't yet export InvoiceDescription
pub fn description(&self) -> InvoiceDescription {
if let Some(direct) = self.signed_invoice.description() {
return InvoiceDescription::Direct(direct);
self.signed_invoice.recover_payee_pub_key().expect("was checked by constructor").0
}
+ /// Returns the Duration since the Unix epoch at which the invoice expires.
+ /// Returning None if overflow occurred.
+ pub fn expires_at(&self) -> Option<Duration> {
+ self.duration_since_epoch().checked_add(self.expiry_time())
+ }
+
/// Returns the invoice's expiry time, if present, otherwise [`DEFAULT_EXPIRY_TIME`].
pub fn expiry_time(&self) -> Duration {
self.signed_invoice.expiry_time()
}
}
+ /// Returns the Duration remaining until the invoice expires.
+ #[cfg(feature = "std")]
+ pub fn duration_until_expiry(&self) -> Duration {
+ SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)
+ .map(|now| self.expiration_remaining_from_epoch(now))
+ .unwrap_or(Duration::from_nanos(0))
+ }
+
+ /// Returns the Duration remaining until the invoice expires given the current time.
+ /// `time` is the timestamp as a duration since the Unix epoch.
+ pub fn expiration_remaining_from_epoch(&self, time: Duration) -> Duration {
+ self.expires_at().map(|x| x.checked_sub(time)).flatten().unwrap_or(Duration::from_nanos(0))
+ }
+
/// Returns whether the expiry time would pass at the given point in time.
/// `at_time` is the timestamp as a duration since the Unix epoch.
pub fn would_expire(&self, at_time: Duration) -> bool {
/// Returns a list of all fallback addresses
///
- /// (C-not exported) as we don't support Vec<&NonOpaqueType>
+ /// This is not exported to bindings users as we don't support Vec<&NonOpaqueType>
pub fn fallbacks(&self) -> Vec<&Fallback> {
self.signed_invoice.fallbacks()
}
}
}
-/// (C-not exported)
+/// This is not exported to bindings users
impl Display for RawHrp {
fn fmt(&self, f: &mut Formatter) -> Result<(), fmt::Error> {
let amount = match self.raw_amount {
use bitcoin_hashes::{Hash, sha256};
use bitcoin_hashes::sha256::Hash as Sha256;
use lightning::chain::keysinterface::{EntropySource, PhantomKeysManager};
+ use lightning::events::{MessageSendEvent, MessageSendEventsProvider, Event};
use lightning::ln::{PaymentPreimage, PaymentHash};
use lightning::ln::channelmanager::{PhantomRouteHints, MIN_FINAL_CLTV_EXPIRY_DELTA, PaymentId};
use lightning::ln::functional_test_utils::*;
use lightning::ln::msgs::ChannelMessageHandler;
use lightning::routing::router::{PaymentParameters, RouteParameters, find_route};
- use lightning::util::events::{MessageSendEvent, MessageSendEventsProvider, Event};
use lightning::util::test_utils;
use lightning::util::config::UserConfig;
use crate::utils::create_invoice_from_channelmanager_and_duration_since_epoch;
//! ```
//! use std::net::TcpStream;
//! use bitcoin::secp256k1::PublicKey;
-//! use lightning::util::events::{Event, EventHandler, EventsProvider};
+//! use lightning::events::{Event, EventHandler, EventsProvider};
//! use std::net::SocketAddr;
//! use std::sync::Arc;
//!
use lightning::ln::peer_handler::{MessageHandler, PeerManager};
use lightning::ln::features::NodeFeatures;
use lightning::routing::gossip::NodeId;
- use lightning::util::events::*;
+ use lightning::events::*;
use lightning::util::test_utils::TestNodeSigner;
use bitcoin::secp256k1::{Secp256k1, SecretKey, PublicKey};
use lightning::chain::channelmonitor::CLOSED_CHANNEL_UPDATE_ID;
use lightning::chain::transaction::OutPoint;
use lightning::{check_closed_broadcast, check_closed_event, check_added_monitors};
+ use lightning::events::{ClosureReason, MessageSendEventsProvider};
use lightning::ln::functional_test_utils::*;
- use lightning::util::events::{ClosureReason, MessageSendEventsProvider};
use lightning::util::test_utils;
use std::fs;
use bitcoin::hashes::Hash;
/// Gets a reference to the underlying [`NetworkGraph`] which was provided in
/// [`RapidGossipSync::new`].
///
- /// (C-not exported) as bindings don't support a reference-to-a-reference yet
+ /// This is not exported to bindings users as bindings don't support a reference-to-a-reference yet
pub fn network_graph(&self) -> &NG {
&self.network_graph
}
bitcoin = { version = "0.29.0", default-features = false }
bdk-macros = "0.6"
futures = { version = "0.3", optional = true }
-esplora-client = { version = "0.3.0", default-features = false, optional = true }
+esplora-client = { version = "0.3", default-features = false, optional = true }
reqwest = { version = "0.11", optional = true, default-features = false, features = ["json"] }
[dev-dependencies]
lightning = { version = "0.0.114", path = "../lightning", features = ["std"] }
electrsd = { version = "0.22.0", features = ["legacy", "esplora_a33e97e1", "bitcoind_23_0"] }
electrum-client = "0.12.0"
-once_cell = "1.16.0"
tokio = { version = "1.14.0", features = ["full"] }
use bitcoind::bitcoincore_rpc::RpcApi;
use electrum_client::ElectrumApi;
-use once_cell::sync::OnceCell;
-
use std::env;
use std::sync::Mutex;
use std::time::Duration;
use std::collections::{HashMap, HashSet};
-static BITCOIND: OnceCell<BitcoinD> = OnceCell::new();
-static ELECTRSD: OnceCell<ElectrsD> = OnceCell::new();
-static PREMINE: OnceCell<()> = OnceCell::new();
-static MINER_LOCK: OnceCell<Mutex<()>> = OnceCell::new();
-
-fn get_bitcoind() -> &'static BitcoinD {
- BITCOIND.get_or_init(|| {
- let bitcoind_exe =
- env::var("BITCOIND_EXE").ok().or_else(|| bitcoind::downloaded_exe_path().ok()).expect(
- "you need to provide an env var BITCOIND_EXE or specify a bitcoind version feature",
- );
- let mut conf = bitcoind::Conf::default();
- conf.network = "regtest";
- let bitcoind = BitcoinD::with_conf(bitcoind_exe, &conf).unwrap();
- std::thread::sleep(Duration::from_secs(1));
- bitcoind
- })
-}
-
-fn get_electrsd() -> &'static ElectrsD {
- ELECTRSD.get_or_init(|| {
- let bitcoind = get_bitcoind();
- let electrs_exe =
- env::var("ELECTRS_EXE").ok().or_else(electrsd::downloaded_exe_path).expect(
- "you need to provide env var ELECTRS_EXE or specify an electrsd version feature",
- );
- let mut conf = electrsd::Conf::default();
- conf.http_enabled = true;
- conf.network = "regtest";
- let electrsd = ElectrsD::with_conf(electrs_exe, &bitcoind, &conf).unwrap();
- std::thread::sleep(Duration::from_secs(1));
- electrsd
- })
+pub fn setup_bitcoind_and_electrsd() -> (BitcoinD, ElectrsD) {
+ let bitcoind_exe =
+ env::var("BITCOIND_EXE").ok().or_else(|| bitcoind::downloaded_exe_path().ok()).expect(
+ "you need to provide an env var BITCOIND_EXE or specify a bitcoind version feature",
+ );
+ let mut bitcoind_conf = bitcoind::Conf::default();
+ bitcoind_conf.network = "regtest";
+ let bitcoind = BitcoinD::with_conf(bitcoind_exe, &bitcoind_conf).unwrap();
+
+ let electrs_exe = env::var("ELECTRS_EXE")
+ .ok()
+ .or_else(electrsd::downloaded_exe_path)
+ .expect("you need to provide env var ELECTRS_EXE or specify an electrsd version feature");
+ let mut electrsd_conf = electrsd::Conf::default();
+ electrsd_conf.http_enabled = true;
+ electrsd_conf.network = "regtest";
+ let electrsd = ElectrsD::with_conf(electrs_exe, &bitcoind, &electrsd_conf).unwrap();
+ (bitcoind, electrsd)
}
-fn generate_blocks_and_wait(num: usize) {
- let miner_lock = MINER_LOCK.get_or_init(|| Mutex::new(()));
- let _miner = miner_lock.lock().unwrap();
- let cur_height = get_bitcoind().client.get_block_count().expect("failed to get current block height");
- let address = get_bitcoind().client.get_new_address(Some("test"), Some(AddressType::Legacy)).expect("failed to get new address");
+pub fn generate_blocks_and_wait(bitcoind: &BitcoinD, electrsd: &ElectrsD, num: usize) {
+ let cur_height = bitcoind.client.get_block_count().expect("failed to get current block height");
+ let address = bitcoind
+ .client
+ .get_new_address(Some("test"), Some(AddressType::Legacy))
+ .expect("failed to get new address");
// TODO: expect this Result once the WouldBlock issue is resolved upstream.
- let _block_hashes_res = get_bitcoind().client.generate_to_address(num as u64, &address);
- wait_for_block(cur_height as usize + num);
+ let _block_hashes_res = bitcoind.client.generate_to_address(num as u64, &address);
+ wait_for_block(electrsd, cur_height as usize + num);
}
-fn wait_for_block(min_height: usize) {
- let mut header = match get_electrsd().client.block_headers_subscribe() {
+pub fn wait_for_block(electrsd: &ElectrsD, min_height: usize) {
+ let mut header = match electrsd.client.block_headers_subscribe() {
Ok(header) => header,
Err(_) => {
// While subscribing should succeed the first time around, we ran into some cases where
// it didn't. Since we can't proceed without subscribing, we try again after a delay
// and panic if it still fails.
std::thread::sleep(Duration::from_secs(1));
- get_electrsd().client.block_headers_subscribe().expect("failed to subscribe to block headers")
+ electrsd.client.block_headers_subscribe().expect("failed to subscribe to block headers")
}
};
-
loop {
if header.height >= min_height {
break;
}
header = exponential_backoff_poll(|| {
- get_electrsd().trigger().expect("failed to trigger electrsd");
- get_electrsd().client.ping().expect("failed to ping electrsd");
- get_electrsd().client.block_headers_pop().expect("failed to pop block header")
+ electrsd.trigger().expect("failed to trigger electrsd");
+ electrsd.client.ping().expect("failed to ping electrsd");
+ electrsd.client.block_headers_pop().expect("failed to pop block header")
});
}
}
}
}
-fn premine() {
- PREMINE.get_or_init(|| {
- generate_blocks_and_wait(101);
- });
-}
-
#[derive(Debug)]
enum TestConfirmableEvent {
Confirmed(Txid, BlockHash, u32),
#[test]
#[cfg(feature = "esplora-blocking")]
fn test_esplora_syncs() {
- premine();
+ let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+ generate_blocks_and_wait(&bitcoind, &electrsd, 101);
let mut logger = TestLogger {};
- let esplora_url = format!("http://{}", get_electrsd().esplora_url.as_ref().unwrap());
+ let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
let tx_sync = EsploraSyncClient::new(esplora_url, &mut logger);
let confirmable = TestConfirmable::new();
// Check we pick up on new best blocks
- let expected_height = 0u32;
- assert_eq!(confirmable.best_block.lock().unwrap().1, expected_height);
+ assert_eq!(confirmable.best_block.lock().unwrap().1, 0);
tx_sync.sync(vec![&confirmable]).unwrap();
-
- let expected_height = get_bitcoind().client.get_block_count().unwrap() as u32;
- assert_eq!(confirmable.best_block.lock().unwrap().1, expected_height);
+ assert_eq!(confirmable.best_block.lock().unwrap().1, 102);
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert_eq!(events.len(), 1);
// Check registered confirmed transactions are marked confirmed
- let new_address = get_bitcoind().client.get_new_address(Some("test"), Some(AddressType::Legacy)).unwrap();
- let txid = get_bitcoind().client.send_to_address(&new_address, Amount::from_sat(5000), None, None, None, None, None, None).unwrap();
+ let new_address = bitcoind.client.get_new_address(Some("test"), Some(AddressType::Legacy)).unwrap();
+ let txid = bitcoind.client.send_to_address(&new_address, Amount::from_sat(5000), None, None, None, None, None, None).unwrap();
tx_sync.register_tx(&txid, &new_address.script_pubkey());
tx_sync.sync(vec![&confirmable]).unwrap();
assert!(confirmable.confirmed_txs.lock().unwrap().is_empty());
assert!(confirmable.unconfirmed_txs.lock().unwrap().is_empty());
- generate_blocks_and_wait(1);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
tx_sync.sync(vec![&confirmable]).unwrap();
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert!(confirmable.unconfirmed_txs.lock().unwrap().is_empty());
// Check previously confirmed transactions are marked unconfirmed when they are reorged.
- let best_block_hash = get_bitcoind().client.get_best_block_hash().unwrap();
- get_bitcoind().client.invalidate_block(&best_block_hash).unwrap();
+ let best_block_hash = bitcoind.client.get_best_block_hash().unwrap();
+ bitcoind.client.invalidate_block(&best_block_hash).unwrap();
// We're getting back to the previous height with a new tip, but best block shouldn't change.
- generate_blocks_and_wait(1);
- assert_ne!(get_bitcoind().client.get_best_block_hash().unwrap(), best_block_hash);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
+ assert_ne!(bitcoind.client.get_best_block_hash().unwrap(), best_block_hash);
tx_sync.sync(vec![&confirmable]).unwrap();
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert_eq!(events.len(), 0);
// Now we're surpassing previous height, getting new tip.
- generate_blocks_and_wait(1);
- assert_ne!(get_bitcoind().client.get_best_block_hash().unwrap(), best_block_hash);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
+ assert_ne!(bitcoind.client.get_best_block_hash().unwrap(), best_block_hash);
tx_sync.sync(vec![&confirmable]).unwrap();
// Transaction still confirmed but under new tip.
#[tokio::test]
#[cfg(feature = "esplora-async")]
async fn test_esplora_syncs() {
- premine();
+ let (bitcoind, electrsd) = setup_bitcoind_and_electrsd();
+ generate_blocks_and_wait(&bitcoind, &electrsd, 101);
let mut logger = TestLogger {};
- let esplora_url = format!("http://{}", get_electrsd().esplora_url.as_ref().unwrap());
+ let esplora_url = format!("http://{}", electrsd.esplora_url.as_ref().unwrap());
let tx_sync = EsploraSyncClient::new(esplora_url, &mut logger);
let confirmable = TestConfirmable::new();
// Check we pick up on new best blocks
- let expected_height = 0u32;
- assert_eq!(confirmable.best_block.lock().unwrap().1, expected_height);
+ assert_eq!(confirmable.best_block.lock().unwrap().1, 0);
tx_sync.sync(vec![&confirmable]).await.unwrap();
-
- let expected_height = get_bitcoind().client.get_block_count().unwrap() as u32;
- assert_eq!(confirmable.best_block.lock().unwrap().1, expected_height);
+ assert_eq!(confirmable.best_block.lock().unwrap().1, 102);
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert_eq!(events.len(), 1);
// Check registered confirmed transactions are marked confirmed
- let new_address = get_bitcoind().client.get_new_address(Some("test"), Some(AddressType::Legacy)).unwrap();
- let txid = get_bitcoind().client.send_to_address(&new_address, Amount::from_sat(5000), None, None, None, None, None, None).unwrap();
+ let new_address = bitcoind.client.get_new_address(Some("test"), Some(AddressType::Legacy)).unwrap();
+ let txid = bitcoind.client.send_to_address(&new_address, Amount::from_sat(5000), None, None, None, None, None, None).unwrap();
tx_sync.register_tx(&txid, &new_address.script_pubkey());
tx_sync.sync(vec![&confirmable]).await.unwrap();
assert!(confirmable.confirmed_txs.lock().unwrap().is_empty());
assert!(confirmable.unconfirmed_txs.lock().unwrap().is_empty());
- generate_blocks_and_wait(1);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
tx_sync.sync(vec![&confirmable]).await.unwrap();
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert!(confirmable.unconfirmed_txs.lock().unwrap().is_empty());
// Check previously confirmed transactions are marked unconfirmed when they are reorged.
- let best_block_hash = get_bitcoind().client.get_best_block_hash().unwrap();
- get_bitcoind().client.invalidate_block(&best_block_hash).unwrap();
+ let best_block_hash = bitcoind.client.get_best_block_hash().unwrap();
+ bitcoind.client.invalidate_block(&best_block_hash).unwrap();
// We're getting back to the previous height with a new tip, but best block shouldn't change.
- generate_blocks_and_wait(1);
- assert_ne!(get_bitcoind().client.get_best_block_hash().unwrap(), best_block_hash);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
+ assert_ne!(bitcoind.client.get_best_block_hash().unwrap(), best_block_hash);
tx_sync.sync(vec![&confirmable]).await.unwrap();
let events = std::mem::take(&mut *confirmable.events.lock().unwrap());
assert_eq!(events.len(), 0);
// Now we're surpassing previous height, getting new tip.
- generate_blocks_and_wait(1);
- assert_ne!(get_bitcoind().client.get_best_block_hash().unwrap(), best_block_hash);
+ generate_blocks_and_wait(&bitcoind, &electrsd, 1);
+ assert_ne!(bitcoind.client.get_best_block_hash().unwrap(), best_block_hash);
tx_sync.sync(vec![&confirmable]).await.unwrap();
// Transaction still confirmed but under new tip.
use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, Balance, MonitorEvent, TransactionOutputs, LATENCY_GRACE_PERIOD_BLOCKS};
use crate::chain::transaction::{OutPoint, TransactionData};
use crate::chain::keysinterface::WriteableEcdsaChannelSigner;
+use crate::events;
+use crate::events::{Event, EventHandler};
use crate::util::atomic_counter::AtomicCounter;
use crate::util::logger::Logger;
use crate::util::errors::APIError;
-use crate::util::events;
-use crate::util::events::{Event, EventHandler};
use crate::ln::channelmanager::ChannelDetails;
use crate::prelude::*;
#[cfg(any(test, fuzzing, feature = "_test_utils"))]
pub fn get_and_clear_pending_events(&self) -> Vec<events::Event> {
- use crate::util::events::EventsProvider;
+ use crate::events::EventsProvider;
let events = core::cell::RefCell::new(Vec::new());
let event_handler = |event: events::Event| events.borrow_mut().push(event);
self.process_pending_events(&event_handler);
///
/// See the trait-level documentation of [`EventsProvider`] for requirements.
///
- /// [`EventsProvider`]: crate::util::events::EventsProvider
+ /// [`EventsProvider`]: crate::events::EventsProvider
pub async fn process_pending_events_async<Future: core::future::Future, H: Fn(Event) -> Future>(
&self, handler: H
) {
use crate::{get_htlc_update_msgs, get_local_commitment_txn, get_revoke_commit_msgs, get_route_and_payment_hash, unwrap_send_err};
use crate::chain::{ChannelMonitorUpdateStatus, Confirm, Watch};
use crate::chain::channelmonitor::LATENCY_GRACE_PERIOD_BLOCKS;
+ use crate::events::{Event, ClosureReason, MessageSendEvent, MessageSendEventsProvider};
use crate::ln::channelmanager::{PaymentSendFailure, PaymentId};
use crate::ln::functional_test_utils::*;
use crate::ln::msgs::ChannelMessageHandler;
use crate::util::errors::APIError;
- use crate::util::events::{Event, ClosureReason, MessageSendEvent, MessageSendEventsProvider};
#[test]
fn test_async_ooo_offchain_updates() {
use crate::util::logger::Logger;
use crate::util::ser::{Readable, ReadableArgs, RequiredWrapper, MaybeReadable, UpgradableRequired, Writer, Writeable, U48};
use crate::util::byte_utils;
-use crate::util::events::Event;
+use crate::events::Event;
#[cfg(anchors)]
-use crate::util::events::{AnchorDescriptor, HTLCDescriptor, BumpTransactionEvent};
+use crate::events::bump_transaction::{AnchorDescriptor, HTLCDescriptor, BumpTransactionEvent};
use crate::prelude::*;
use core::{cmp, mem};
/// This is called by the [`EventsProvider::process_pending_events`] implementation for
/// [`ChainMonitor`].
///
- /// [`EventsProvider::process_pending_events`]: crate::util::events::EventsProvider::process_pending_events
+ /// [`EventsProvider::process_pending_events`]: crate::events::EventsProvider::process_pending_events
/// [`ChainMonitor`]: crate::chain::chainmonitor::ChainMonitor
pub fn get_and_clear_pending_events(&self) -> Vec<Event> {
self.inner.lock().unwrap().get_and_clear_pending_events()
}));
},
ClaimEvent::BumpHTLC {
- target_feerate_sat_per_1000_weight, htlcs,
+ target_feerate_sat_per_1000_weight, htlcs, tx_lock_time,
} => {
let mut htlc_descriptors = Vec::with_capacity(htlcs.len());
for htlc in htlcs {
ret.push(Event::BumpTransaction(BumpTransactionEvent::HTLCResolution {
target_feerate_sat_per_1000_weight,
htlc_descriptors,
+ tx_lock_time,
}));
}
}
use crate::chain::package::{weight_offered_htlc, weight_received_htlc, weight_revoked_offered_htlc, weight_revoked_received_htlc, WEIGHT_REVOKED_OUTPUT};
use crate::chain::transaction::OutPoint;
use crate::chain::keysinterface::InMemorySigner;
+ use crate::events::ClosureReason;
use crate::ln::{PaymentPreimage, PaymentHash};
use crate::ln::chan_utils;
use crate::ln::chan_utils::{HTLCOutputInCommitment, ChannelPublicKeys, ChannelTransactionParameters, HolderCommitmentTransaction, CounterpartyChannelTransactionParameters};
use crate::ln::functional_test_utils::*;
use crate::ln::script::ShutdownScript;
use crate::util::errors::APIError;
- use crate::util::events::ClosureReason;
use crate::util::test_utils::{TestLogger, TestBroadcaster, TestFeeEstimator};
use crate::util::ser::{ReadableArgs, Writeable};
use crate::sync::{Arc, Mutex};
use crate::util::transaction_utils;
use crate::util::crypto::{hkdf_extract_expand_twice, sign};
use crate::util::ser::{Writeable, Writer, Readable};
-#[cfg(anchors)]
-use crate::util::events::HTLCDescriptor;
use crate::chain::transaction::OutPoint;
+#[cfg(anchors)]
+use crate::events::bump_transaction::HTLCDescriptor;
use crate::ln::channel::ANCHOR_OUTPUT_VALUE_SATOSHI;
use crate::ln::{chan_utils, PaymentPreimage};
use crate::ln::chan_utils::{HTLCOutputInCommitment, make_funding_redeemscript, ChannelPublicKeys, HolderCommitmentTransaction, ChannelTransactionParameters, CommitmentTransaction, ClosingTransaction};
/// Used as initial key material, to be expanded into multiple secret keys (but not to be used
/// directly). This is used within LDK to encrypt/decrypt inbound payment data.
///
-/// (C-not exported) as we just use `[u8; 32]` directly
+/// This is not exported to bindings users as we just use `[u8; 32]` directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct KeyMaterial(pub [u8; 32]);
/// outpoint describing which `txid` and output `index` is available, the full output which exists
/// at that `txid`/`index`, and any keys or other information required to sign.
///
-/// [`SpendableOutputs`]: crate::util::events::Event::SpendableOutputs
+/// [`SpendableOutputs`]: crate::events::Event::SpendableOutputs
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SpendableOutputDescriptor {
/// An output to a script which was provided via [`SignerProvider`] directly, either from
//! OnchainTxHandler objects are fully-part of ChannelMonitor and encapsulates all
//! building, tracking, bumping and notifications functions.
+#[cfg(anchors)]
+use bitcoin::PackedLockTime;
use bitcoin::blockdata::transaction::Transaction;
use bitcoin::blockdata::transaction::OutPoint as BitcoinOutPoint;
use bitcoin::blockdata::script::Script;
BumpHTLC {
target_feerate_sat_per_1000_weight: u32,
htlcs: Vec<ExternalHTLCClaim>,
+ tx_lock_time: PackedLockTime,
},
}
OnchainClaim::Event(ClaimEvent::BumpHTLC {
target_feerate_sat_per_1000_weight,
htlcs,
+ tx_lock_time: PackedLockTime(cached_request.package_locktime(cur_height)),
}),
));
} else {
) {
assert!(new_feerate != 0);
- let transaction = cached_request.finalize_malleable_package(self, output_value, self.destination_script.clone(), logger).unwrap();
+ let transaction = cached_request.finalize_malleable_package(
+ cur_height, self, output_value, self.destination_script.clone(), logger
+ ).unwrap();
log_trace!(logger, "...with timer {} and feerate {}", new_timer.unwrap(), new_feerate);
assert!(predicted_weight >= transaction.weight());
return Some((new_timer, new_feerate, OnchainClaim::Tx(transaction)));
.find(|locked_package| locked_package.outpoints() == req.outpoints());
if let Some(package) = timelocked_equivalent_package {
log_info!(logger, "Ignoring second claim for outpoint {}:{}, we already have one which we're waiting on a timelock at {} for.",
- req.outpoints()[0].txid, req.outpoints()[0].vout, package.package_timelock());
+ req.outpoints()[0].txid, req.outpoints()[0].vout, package.package_locktime(cur_height));
continue;
}
- if req.package_timelock() > cur_height + 1 {
- log_info!(logger, "Delaying claim of package until its timelock at {} (current height {}), the following outpoints are spent:", req.package_timelock(), cur_height);
+ let package_locktime = req.package_locktime(cur_height);
+ if package_locktime > cur_height + 1 {
+ log_info!(logger, "Delaying claim of package until its timelock at {} (current height {}), the following outpoints are spent:", package_locktime, cur_height);
for outpoint in req.outpoints() {
log_info!(logger, " Outpoint {}", outpoint);
}
- self.locktimed_packages.entry(req.package_timelock()).or_insert(Vec::new()).push(req);
+ self.locktimed_packages.entry(package_locktime).or_insert(Vec::new()).push(req);
continue;
}
let chan_keys = TxCreationKeys::derive_new(&onchain_handler.secp_ctx, &outp.per_commitment_point, &outp.counterparty_delayed_payment_base_key, &outp.counterparty_htlc_base_key, &onchain_handler.signer.pubkeys().revocation_basepoint, &onchain_handler.signer.pubkeys().htlc_basepoint);
let witness_script = chan_utils::get_htlc_redeemscript_with_explicit_keys(&outp.htlc, onchain_handler.opt_anchors(), &chan_keys.broadcaster_htlc_key, &chan_keys.countersignatory_htlc_key, &chan_keys.revocation_key);
- bumped_tx.lock_time = PackedLockTime(outp.htlc.cltv_expiry); // Right now we don't aggregate time-locked transaction, if we do we should set lock_time before to avoid breaking hash computation
if let Ok(sig) = onchain_handler.signer.sign_counterparty_htlc_transaction(&bumped_tx, i, &outp.htlc.amount_msat / 1000, &outp.per_commitment_point, &outp.htlc, &onchain_handler.secp_ctx) {
let mut ser_sig = sig.serialize_der().to_vec();
ser_sig.push(EcdsaSighashType::All as u8);
_ => { panic!("API Error!"); }
}
}
- fn absolute_tx_timelock(&self, output_conf_height: u32) -> u32 {
- // Get the absolute timelock at which this output can be spent given the height at which
- // this output was confirmed. We use `output_conf_height + 1` as a safe default as we can
- // be confirmed in the next block and transactions with time lock `current_height + 1`
- // always propagate.
+ fn absolute_tx_timelock(&self, current_height: u32) -> u32 {
+ // We use `current_height + 1` as our default locktime to discourage fee sniping and because
+ // transactions with it always propagate.
let absolute_timelock = match self {
- PackageSolvingData::RevokedOutput(_) => output_conf_height + 1,
- PackageSolvingData::RevokedHTLCOutput(_) => output_conf_height + 1,
- PackageSolvingData::CounterpartyOfferedHTLCOutput(_) => output_conf_height + 1,
- PackageSolvingData::CounterpartyReceivedHTLCOutput(ref outp) => cmp::max(outp.htlc.cltv_expiry, output_conf_height + 1),
- PackageSolvingData::HolderHTLCOutput(ref outp) => cmp::max(outp.cltv_expiry, output_conf_height + 1),
- PackageSolvingData::HolderFundingOutput(_) => output_conf_height + 1,
+ PackageSolvingData::RevokedOutput(_) => current_height + 1,
+ PackageSolvingData::RevokedHTLCOutput(_) => current_height + 1,
+ PackageSolvingData::CounterpartyOfferedHTLCOutput(_) => current_height + 1,
+ PackageSolvingData::CounterpartyReceivedHTLCOutput(ref outp) => cmp::max(outp.htlc.cltv_expiry, current_height + 1),
+ // HTLC timeout/success transactions rely on a fixed timelock due to the counterparty's
+ // signature.
+ PackageSolvingData::HolderHTLCOutput(ref outp) => {
+ if outp.preimage.is_some() {
+ debug_assert_eq!(outp.cltv_expiry, 0);
+ }
+ outp.cltv_expiry
+ },
+ PackageSolvingData::HolderFundingOutput(_) => current_height + 1,
};
absolute_timelock
}
}
amounts
}
- pub(crate) fn package_timelock(&self) -> u32 {
- self.inputs.iter().map(|(_, outp)| outp.absolute_tx_timelock(self.height_original))
- .max().expect("There must always be at least one output to spend in a PackageTemplate")
+ pub(crate) fn package_locktime(&self, current_height: u32) -> u32 {
+ let locktime = self.inputs.iter().map(|(_, outp)| outp.absolute_tx_timelock(current_height))
+ .max().expect("There must always be at least one output to spend in a PackageTemplate");
+
+ // If we ever try to aggregate a `HolderHTLCOutput`s with another output type, we'll likely
+ // end up with an incorrect transaction locktime since the counterparty has included it in
+ // its HTLC signature. This should never happen unless we decide to aggregate outputs across
+ // different channel commitments.
+ #[cfg(debug_assertions)] {
+ if self.inputs.iter().any(|(_, outp)|
+ if let PackageSolvingData::HolderHTLCOutput(outp) = outp {
+ outp.preimage.is_some()
+ } else {
+ false
+ }
+ ) {
+ debug_assert_eq!(locktime, 0);
+ };
+ for timeout_htlc_expiry in self.inputs.iter().filter_map(|(_, outp)|
+ if let PackageSolvingData::HolderHTLCOutput(outp) = outp {
+ if outp.preimage.is_none() {
+ Some(outp.cltv_expiry)
+ } else { None }
+ } else { None }
+ ) {
+ debug_assert_eq!(locktime, timeout_htlc_expiry);
+ }
+ }
+
+ locktime
}
pub(crate) fn package_weight(&self, destination_script: &Script) -> usize {
let mut inputs_weight = 0;
htlcs
}
pub(crate) fn finalize_malleable_package<L: Deref, Signer: WriteableEcdsaChannelSigner>(
- &self, onchain_handler: &mut OnchainTxHandler<Signer>, value: u64, destination_script: Script, logger: &L
+ &self, current_height: u32, onchain_handler: &mut OnchainTxHandler<Signer>, value: u64,
+ destination_script: Script, logger: &L
) -> Option<Transaction> where L::Target: Logger {
debug_assert!(self.is_malleable());
let mut bumped_tx = Transaction {
version: 2,
- lock_time: PackedLockTime::ZERO,
+ lock_time: PackedLockTime(self.package_locktime(current_height)),
input: vec![],
output: vec![TxOut {
script_pubkey: destination_script,
}
/// Converts this OutPoint into the OutPoint field as used by rust-bitcoin
- /// (C-not exported) as the same type is used universally in the C bindings for all outpoints
+ ///
+ /// This is not exported to bindings users as the same type is used universally in the C bindings
+ /// for all outpoints
pub fn into_bitcoin_outpoint(self) -> BitcoinOutPoint {
BitcoinOutPoint {
txid: self.txid,
--- /dev/null
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Utitilies for bumping transactions originating from [`super::Event`]s.
+
+use crate::ln::PaymentPreimage;
+use crate::ln::chan_utils;
+use crate::ln::chan_utils::{ChannelTransactionParameters, HTLCOutputInCommitment};
+
+use bitcoin::{OutPoint, PackedLockTime, Script, Transaction, Txid, TxIn, TxOut, Witness};
+use bitcoin::secp256k1;
+use bitcoin::secp256k1::{PublicKey, Secp256k1};
+use bitcoin::secp256k1::ecdsa::Signature;
+
+/// 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,
+}
+
+/// 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<PaymentPreimage>,
+ /// The counterparty's signature required to spend the HTLC output.
+ pub counterparty_sig: Signature
+}
+
+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<C: secp256k1::Signing + secp256k1::Verification>(
+ &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
+ ) -> 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<C: secp256k1::Signing + secp256k1::Verification>(
+ &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
+ ) -> 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 */
+ )
+ }
+}
+
+/// 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<HTLCOutputInCommitment>,
+ },
+ /// 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<HTLCDescriptor>,
+ /// The locktime required for the resulting HTLC transaction.
+ tx_lock_time: PackedLockTime,
+ },
+}
--- /dev/null
+// This file is Copyright its original authors, visible in version control
+// history.
+//
+// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
+// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
+// You may not use this file except in accordance with one or both of these
+// licenses.
+
+//! Events are returned from various bits in the library which indicate some action must be taken
+//! by the client.
+//!
+//! Because we don't have a built-in runtime, it's up to the client to call events at a time in the
+//! future, as well as generate and broadcast funding transactions handle payment preimages and a
+//! few other things.
+
+#[cfg(anchors)]
+pub mod bump_transaction;
+
+#[cfg(anchors)]
+pub use bump_transaction::BumpTransactionEvent;
+
+use crate::chain::keysinterface::SpendableOutputDescriptor;
+use crate::ln::channelmanager::{InterceptId, PaymentId};
+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::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 bitcoin::{PackedLockTime, Transaction};
+use bitcoin::blockdata::script::Script;
+use bitcoin::hashes::Hash;
+use bitcoin::hashes::sha256::Hash as Sha256;
+use bitcoin::secp256k1::PublicKey;
+use crate::io;
+use crate::prelude::*;
+use core::time::Duration;
+use core::ops::Deref;
+use crate::sync::Arc;
+
+/// 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 {
+ /// 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`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
+ /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
+ payment_preimage: Option<PaymentPreimage>,
+ /// The "payment secret". This authenticates the sender to the recipient, preventing a
+ /// number of deanonymization attacks during the routing process.
+ /// It is provided here for your reference, however its accuracy is enforced directly by
+ /// [`ChannelManager`] using the values you previously provided to
+ /// [`ChannelManager::create_inbound_payment`] or
+ /// [`ChannelManager::create_inbound_payment_for_hash`].
+ ///
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+ /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
+ /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
+ payment_secret: PaymentSecret,
+ },
+ /// Because this is a spontaneous payment, the payer generated their own preimage rather than us
+ /// (the payee) providing a preimage.
+ SpontaneousPayment(PaymentPreimage),
+}
+
+impl_writeable_tlv_based_enum!(PaymentPurpose,
+ (0, InvoicePayment) => {
+ (0, payment_preimage, option),
+ (2, payment_secret, required),
+ };
+ (2, SpontaneousPayment)
+);
+
+/// 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`].
+///
+/// [`NetworkUpdate`]: crate::routing::gossip::NetworkUpdate
+/// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum PathFailure {
+ /// We failed to initially send the payment and no HTLC was committed to. Contains the relevant
+ /// error.
+ InitialSend {
+ /// The error surfaced from initial send.
+ err: APIError,
+ },
+ /// A hop on the path failed to forward our payment.
+ OnPath {
+ /// If present, this [`NetworkUpdate`] should be applied to the [`NetworkGraph`] so that routing
+ /// decisions can take into account the update.
+ ///
+ /// [`NetworkUpdate`]: crate::routing::gossip::NetworkUpdate
+ /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
+ network_update: Option<NetworkUpdate>,
+ },
+}
+
+impl_writeable_tlv_based_enum_upgradable!(PathFailure,
+ (0, OnPath) => {
+ (0, network_update, upgradable_option),
+ },
+ (2, InitialSend) => {
+ (0, err, upgradable_required),
+ },
+);
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+/// The reason the channel was closed. See individual variants more details.
+pub enum ClosureReason {
+ /// Closure generated from receiving a peer error message.
+ ///
+ /// Our counterparty may have broadcasted their latest commitment state, and we have
+ /// as well.
+ CounterpartyForceClosed {
+ /// The error which the peer sent us.
+ ///
+ /// 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,
+ },
+ /// Closure generated from [`ChannelManager::force_close_channel`], called by the user.
+ ///
+ /// [`ChannelManager::force_close_channel`]: crate::ln::channelmanager::ChannelManager::force_close_channel.
+ 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,
+ /// 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`.
+ CommitmentTxConfirmed,
+ /// The funding transaction failed to confirm in a timely manner on an inbound channel.
+ FundingTimedOut,
+ /// Closure generated from processing an event, likely a HTLC forward/relay/reception.
+ ProcessingError {
+ /// A developer-readable error message which we generated.
+ err: String,
+ },
+ /// The peer disconnected prior to funding completing. In this case the spec mandates that we
+ /// forget the channel entirely - we can attempt again if the peer reconnects.
+ ///
+ /// This includes cases where we restarted prior to funding completion, including prior to the
+ /// initial [`ChannelMonitor`] persistence completing.
+ ///
+ /// In LDK versions prior to 0.0.107 this could also occur if we were unable to connect to the
+ /// peer because of mutual incompatibility between us and our channel counterparty.
+ ///
+ /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
+ DisconnectedPeer,
+ /// Closure generated from `ChannelManager::read` if the [`ChannelMonitor`] is newer than
+ /// the [`ChannelManager`] deserialized.
+ ///
+ /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+ OutdatedChannelManager
+}
+
+impl core::fmt::Display for ClosureReason {
+ fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
+ f.write_str("Channel closed because ")?;
+ match self {
+ 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::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 } => {
+ f.write_str("of an exception: ")?;
+ f.write_str(&err)
+ },
+ 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)"),
+ }
+ }
+}
+
+impl_writeable_tlv_based_enum_upgradable!(ClosureReason,
+ (0, CounterpartyForceClosed) => { (1, peer_msg, required) },
+ (1, FundingTimedOut) => {},
+ (2, HolderForceClosed) => {},
+ (6, CommitmentTxConfirmed) => {},
+ (4, CooperativeClosure) => {},
+ (8, ProcessingError) => { (1, err, required) },
+ (10, DisconnectedPeer) => {},
+ (12, OutdatedChannelManager) => {},
+);
+
+/// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`].
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HTLCDestination {
+ /// We tried forwarding to a channel but failed to do so. An example of such an instance is when
+ /// there is insufficient capacity in our outbound channel.
+ NextHopChannel {
+ /// The `node_id` of the next node. For backwards compatibility, this field is
+ /// marked as optional, versions prior to 0.0.110 may not always be able to provide
+ /// counterparty node information.
+ node_id: Option<PublicKey>,
+ /// The outgoing `channel_id` between us and the next node.
+ channel_id: [u8; 32],
+ },
+ /// Scenario where we are unsure of the next node to forward the HTLC to.
+ UnknownNextHop {
+ /// Short channel id we are requesting to forward an HTLC to.
+ requested_forward_scid: u64,
+ },
+ /// We couldn't forward to the outgoing scid. An example would be attempting to send a duplicate
+ /// intercept HTLC.
+ InvalidForward {
+ /// Short channel id we are requesting to forward an HTLC to.
+ requested_forward_scid: u64
+ },
+ /// 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 has already been reached
+ /// * Claimable amount does not match expected amount
+ FailedPayment {
+ /// The payment hash of the payment we attempted to process.
+ payment_hash: PaymentHash
+ },
+}
+
+impl_writeable_tlv_based_enum_upgradable!(HTLCDestination,
+ (0, NextHopChannel) => {
+ (0, node_id, required),
+ (2, channel_id, required),
+ },
+ (1, InvalidForward) => {
+ (0, requested_forward_scid, required),
+ },
+ (2, UnknownNextHop) => {
+ (0, requested_forward_scid, required),
+ },
+ (4, FailedPayment) => {
+ (0, payment_hash, required),
+ },
+);
+
+/// 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
+/// intercepts in upcoming work.
+enum InterceptNextHop {
+ FakeScid {
+ requested_next_hop_scid: u64,
+ },
+}
+
+impl_writeable_tlv_based_enum!(InterceptNextHop,
+ (0, FakeScid) => {
+ (0, requested_next_hop_scid, required),
+ };
+);
+
+/// 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
+/// them directly as they don't round-trip exactly (for example FundingGenerationReady is never
+/// written as it makes no sense to respond to it after reconnecting to peers).
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Event {
+ /// Used to indicate that the client should generate a funding transaction with the given
+ /// parameters and then call [`ChannelManager::funding_transaction_generated`].
+ /// Generated in [`ChannelManager`] message handling.
+ /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your
+ /// counterparty can steal your funds!
+ ///
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+ /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
+ FundingGenerationReady {
+ /// The random channel_id we picked which you'll need to pass into
+ /// [`ChannelManager::funding_transaction_generated`].
+ ///
+ /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
+ temporary_channel_id: [u8; 32],
+ /// The counterparty's node_id, which you'll need to pass back into
+ /// [`ChannelManager::funding_transaction_generated`].
+ ///
+ /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
+ counterparty_node_id: PublicKey,
+ /// 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.
+ ///
+ /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
+ user_channel_id: u128,
+ },
+ /// Indicates that we've been offered a payment and it needs to be claimed via calling
+ /// [`ChannelManager::claim_funds`] with the preimage given in [`PaymentPurpose`].
+ ///
+ /// 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.
+ ///
+ /// # Note
+ /// LDK will not stop an inbound payment from being paid multiple times, so multiple
+ /// `PaymentClaimable` events may be generated for the same 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::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 {
+ /// The node that will receive the payment after it has been claimed.
+ /// This is useful to identify payments received via [phantom nodes].
+ /// 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
+ receiver_node_id: Option<PublicKey>,
+ /// 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.
+ amount_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]>,
+ /// The `user_channel_id` indicating over which channel we received the payment.
+ via_user_channel_id: Option<u128>,
+ },
+ /// Indicates a payment has been claimed and we've received money!
+ ///
+ /// This most likely occurs when [`ChannelManager::claim_funds`] has been called in response
+ /// to an [`Event::PaymentClaimable`]. However, if we previously crashed during a
+ /// [`ChannelManager::claim_funds`] call you may see this event without a corresponding
+ /// [`Event::PaymentClaimable`] event.
+ ///
+ /// # Note
+ /// LDK will not stop an inbound payment from being paid multiple times, so multiple
+ /// `PaymentClaimable` events may be generated for the same payment. If you then call
+ /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentClaimable`] you may get
+ /// multiple `PaymentClaimed` events.
+ ///
+ /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
+ PaymentClaimed {
+ /// The node that received the payment.
+ /// This is useful to identify payments which were received via [phantom nodes].
+ /// 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
+ receiver_node_id: Option<PublicKey>,
+ /// 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.
+ amount_msat: u64,
+ /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
+ /// spontaneous payment.
+ purpose: PaymentPurpose,
+ },
+ /// 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).
+ ///
+ /// 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`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ payment_id: Option<PaymentId>,
+ /// The preimage to the hash given to ChannelManager::send_payment.
+ /// Note that this serves as a payment receipt, if you wish to have such a thing, you must
+ /// store it somehow!
+ payment_preimage: PaymentPreimage,
+ /// The hash that was given to [`ChannelManager::send_payment`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ payment_hash: PaymentHash,
+ /// The total fee which was spent at intermediate hops in this payment, across all paths.
+ ///
+ /// Note that, like [`Route::get_total_fees`] this does *not* include any potential
+ /// overpayment to the recipient node.
+ ///
+ /// If the recipient or an intermediate node misbehaves and gives us free money, this may
+ /// overstate the amount paid, though this is unlikely.
+ ///
+ /// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees
+ fee_paid_msat: Option<u64>,
+ },
+ /// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
+ /// provide failure information for each path attempt in the payment, including retries.
+ ///
+ /// This event is provided once there are no further pending HTLCs for the payment and the
+ /// payment is no longer retryable, due either to the [`Retry`] provided or
+ /// [`ChannelManager::abandon_payment`] having been called for the corresponding payment.
+ ///
+ /// [`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`].
+ ///
+ /// [`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,
+ },
+ /// 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`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ payment_id: PaymentId,
+ /// The hash that was given to [`ChannelManager::send_payment`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ payment_hash: Option<PaymentHash>,
+ /// The payment path that was successful.
+ ///
+ /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
+ path: Vec<RouteHop>,
+ },
+ /// Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to
+ /// handle the HTLC.
+ ///
+ /// Note that this does *not* indicate that all paths for an MPP payment have failed, see
+ /// [`Event::PaymentFailed`].
+ ///
+ /// See [`ChannelManager::abandon_payment`] for giving up on this payment before its retries have
+ /// been exhausted.
+ ///
+ /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+ PaymentPathFailed {
+ /// The id returned by [`ChannelManager::send_payment`] and used with
+ /// [`ChannelManager::abandon_payment`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
+ payment_id: Option<PaymentId>,
+ /// The hash that was given to [`ChannelManager::send_payment`].
+ ///
+ /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
+ payment_hash: PaymentHash,
+ /// Indicates the payment was rejected for some reason by the recipient. This implies that
+ /// the payment has failed, not just the route in question. If this is not set, the payment may
+ /// be retried via a different route.
+ payment_failed_permanently: bool,
+ /// Extra error details based on the failure type. May contain an update that needs to be
+ /// applied to the [`NetworkGraph`].
+ ///
+ /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
+ failure: PathFailure,
+ /// The payment path that failed.
+ path: Vec<RouteHop>,
+ /// 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
+ /// may not refer to a channel in the public network graph. These aliases may also collide
+ /// with channels in the public network graph.
+ ///
+ /// If this is `Some`, then the corresponding channel should be avoided when the payment is
+ /// retried. May be `None` for older [`Event`] serializations.
+ short_channel_id: Option<u64>,
+#[cfg(test)]
+ error_code: Option<u16>,
+#[cfg(test)]
+ error_data: Option<Vec<u8>>,
+ },
+ /// Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.
+ ProbeSuccessful {
+ /// The id returned by [`ChannelManager::send_probe`].
+ ///
+ /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
+ payment_id: PaymentId,
+ /// The hash generated by [`ChannelManager::send_probe`].
+ ///
+ /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
+ payment_hash: PaymentHash,
+ /// The payment path that was successful.
+ path: Vec<RouteHop>,
+ },
+ /// Indicates that a probe payment we sent failed at an intermediary node on the path.
+ ProbeFailed {
+ /// The id returned by [`ChannelManager::send_probe`].
+ ///
+ /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
+ payment_id: PaymentId,
+ /// The hash generated by [`ChannelManager::send_probe`].
+ ///
+ /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
+ payment_hash: PaymentHash,
+ /// The payment path that failed.
+ path: Vec<RouteHop>,
+ /// 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
+ /// may not refer to a channel in the public network graph. These aliases may also collide
+ /// with channels in the public network graph.
+ short_channel_id: Option<u64>,
+ },
+ /// Used to indicate that [`ChannelManager::process_pending_htlc_forwards`] should be called at
+ /// a time in the future.
+ ///
+ /// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards
+ PendingHTLCsForwardable {
+ /// The minimum amount of time that should be waited prior to calling
+ /// process_pending_htlc_forwards. To increase the effort required to correlate payments,
+ /// you should wait a random amount of time in roughly the range (now + time_forwardable,
+ /// now + 5*time_forwardable).
+ time_forwardable: Duration,
+ },
+ /// Used to indicate that we've intercepted an HTLC forward. This event will only be generated if
+ /// you've encoded an intercept scid in the receiver's invoice route hints using
+ /// [`ChannelManager::get_intercept_scid`] and have set [`UserConfig::accept_intercept_htlcs`].
+ ///
+ /// [`ChannelManager::forward_intercepted_htlc`] or
+ /// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event. See
+ /// their docs for more information.
+ ///
+ /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
+ /// [`UserConfig::accept_intercept_htlcs`]: crate::util::config::UserConfig::accept_intercept_htlcs
+ /// [`ChannelManager::forward_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::forward_intercepted_htlc
+ /// [`ChannelManager::fail_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::fail_intercepted_htlc
+ HTLCIntercepted {
+ /// An id to help LDK identify which HTLC is being forwarded or failed.
+ intercept_id: InterceptId,
+ /// The fake scid that was programmed as the next hop's scid, generated using
+ /// [`ChannelManager::get_intercept_scid`].
+ ///
+ /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
+ requested_next_hop_scid: u64,
+ /// The payment hash used for this HTLC.
+ payment_hash: PaymentHash,
+ /// How many msats were received on the inbound edge of this HTLC.
+ 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.
+ ///
+ /// 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,
+ /// LDK will not stop you from forwarding more than you received.
+ expected_outbound_amount_msat: u64,
+ },
+ /// Used to indicate that an output which you should know how to spend was confirmed on chain
+ /// and is now spendable.
+ /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
+ /// counterparty spending them due to some kind of timeout. Thus, you need to store them
+ /// somewhere and spend them when you create on-chain transactions.
+ SpendableOutputs {
+ /// The outputs which you should store as spendable by you.
+ outputs: Vec<SpendableOutputDescriptor>,
+ },
+ /// 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.
+ ///
+ /// 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
+ /// whole satoshi. Thus, the fee calculated here may be higher than expected as we still
+ /// claimed the full value in millisatoshis from the source. In this case,
+ /// `claim_from_onchain_tx` will be set.
+ ///
+ /// 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
+ /// `None`.
+ fee_earned_msat: Option<u64>,
+ /// If this is `true`, the forwarded HTLC was claimed by our counterparty via an on-chain
+ /// transaction.
+ claim_from_onchain_tx: bool,
+ },
+ /// 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 `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 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
+ /// resolving the channel are likely still awaiting confirmation.
+ channel_id: [u8; 32],
+ /// 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 inbound channels.
+ /// This may be zero for inbound channels serialized prior to 0.0.113 and will always be
+ /// zero for objects serialized with LDK versions prior to 0.0.102.
+ ///
+ /// [`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 reason the channel was closed.
+ reason: ClosureReason
+ },
+ /// Used to indicate to the user that they can abandon the funding transaction and recycle the
+ /// inputs for another purpose.
+ DiscardFunding {
+ /// The channel_id of the channel which has been closed.
+ channel_id: [u8; 32],
+ /// 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`].
+ ///
+ /// 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.
+ ///
+ /// [`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
+ /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
+ OpenChannelRequest {
+ /// The temporary channel ID of the channel requested to be opened.
+ ///
+ /// When responding to the request, the `temporary_channel_id` should be passed
+ /// back to the ChannelManager through [`ChannelManager::accept_inbound_channel`] to accept,
+ /// or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject.
+ ///
+ /// [`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],
+ /// The node_id of the counterparty requesting to open the channel.
+ ///
+ /// When responding to the request, the `counterparty_node_id` should be passed
+ /// back to the `ChannelManager` through [`ChannelManager::accept_inbound_channel`] to
+ /// accept the request, or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject the
+ /// request.
+ ///
+ /// [`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
+ counterparty_node_id: PublicKey,
+ /// The channel value of the requested channel.
+ funding_satoshis: u64,
+ /// Our starting balance in the channel if the request is accepted, in milli-satoshi.
+ push_msat: u64,
+ /// The features that this channel will operate with. If you reject the channel, a
+ /// well-behaved counterparty may automatically re-attempt the channel with a new set of
+ /// feature flags.
+ ///
+ /// Note that if [`ChannelTypeFeatures::supports_scid_privacy`] returns true on this type,
+ /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
+ /// 0.0.106.
+ ///
+ /// Furthermore, note that if [`ChannelTypeFeatures::supports_zero_conf`] returns true on this type,
+ /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
+ /// 0.0.107. Channels setting this type also need to get manually accepted via
+ /// [`crate::ln::channelmanager::ChannelManager::accept_inbound_channel_from_trusted_peer_0conf`],
+ /// or will be rejected otherwise.
+ ///
+ /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
+ channel_type: ChannelTypeFeatures,
+ },
+ /// Indicates that the HTLC was accepted, but could not be processed when or after attempting to
+ /// forward it.
+ ///
+ /// Some scenarios where this event may be sent include:
+ /// * 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.
+ /// * 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],
+ /// 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.
+ BumpTransaction(BumpTransactionEvent),
+}
+
+impl Writeable for Event {
+ fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
+ match self {
+ &Event::FundingGenerationReady { .. } => {
+ 0u8.write(writer)?;
+ // 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 } => {
+ 1u8.write(writer)?;
+ let mut payment_secret = None;
+ let payment_preimage;
+ match &purpose {
+ PaymentPurpose::InvoicePayment { payment_preimage: preimage, payment_secret: secret } => {
+ payment_secret = Some(secret);
+ payment_preimage = *preimage;
+ },
+ PaymentPurpose::SpontaneousPayment(preimage) => {
+ payment_preimage = Some(*preimage);
+ }
+ }
+ write_tlv_fields!(writer, {
+ (0, payment_hash, required),
+ (1, receiver_node_id, option),
+ (2, payment_secret, option),
+ (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
+ (8, payment_preimage, option),
+ });
+ },
+ &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
+ 2u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_preimage, required),
+ (1, payment_hash, required),
+ (3, payment_id, option),
+ (5, fee_paid_msat, option),
+ });
+ },
+ &Event::PaymentPathFailed {
+ ref payment_id, ref payment_hash, ref payment_failed_permanently, ref failure,
+ ref path, ref short_channel_id,
+ #[cfg(test)]
+ ref error_code,
+ #[cfg(test)]
+ ref error_data,
+ } => {
+ 3u8.write(writer)?;
+ #[cfg(test)]
+ error_code.write(writer)?;
+ #[cfg(test)]
+ error_data.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_hash, required),
+ (1, None::<NetworkUpdate>, 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),
+ (7, short_channel_id, option),
+ (9, None::<RouteParameters>, option), // retry in LDK versions prior to 0.0.115
+ (11, payment_id, option),
+ (13, failure, required),
+ });
+ },
+ &Event::PendingHTLCsForwardable { time_forwardable: _ } => {
+ 4u8.write(writer)?;
+ // 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 } => {
+ 5u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, WithoutLength(outputs), required),
+ });
+ },
+ &Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat, expected_outbound_amount_msat, intercept_id } => {
+ 6u8.write(writer)?;
+ let intercept_scid = InterceptNextHop::FakeScid { requested_next_hop_scid };
+ write_tlv_fields!(writer, {
+ (0, intercept_id, required),
+ (2, intercept_scid, required),
+ (4, payment_hash, required),
+ (6, inbound_amount_msat, required),
+ (8, expected_outbound_amount_msat, required),
+ });
+ }
+ &Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id } => {
+ 7u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, fee_earned_msat, option),
+ (1, prev_channel_id, option),
+ (2, claim_from_onchain_tx, required),
+ (3, next_channel_id, option),
+ });
+ },
+ &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => {
+ 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
+ // separate u64 values.
+ let user_channel_id_low = *user_channel_id as u64;
+ let user_channel_id_high = (*user_channel_id >> 64) as u64;
+ write_tlv_fields!(writer, {
+ (0, channel_id, required),
+ (1, user_channel_id_low, required),
+ (2, reason, required),
+ (3, user_channel_id_high, required),
+ });
+ },
+ &Event::DiscardFunding { ref channel_id, ref transaction } => {
+ 11u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, channel_id, required),
+ (2, transaction, required)
+ })
+ },
+ &Event::PaymentPathSuccessful { ref payment_id, ref payment_hash, ref path } => {
+ 13u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_id, required),
+ (2, payment_hash, option),
+ (4, *path, vec_type)
+ })
+ },
+ &Event::PaymentFailed { ref payment_id, ref payment_hash } => {
+ 15u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ })
+ },
+ &Event::OpenChannelRequest { .. } => {
+ 17u8.write(writer)?;
+ // 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 } => {
+ 19u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_hash, required),
+ (1, receiver_node_id, option),
+ (2, purpose, required),
+ (4, amount_msat, required),
+ });
+ },
+ &Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => {
+ 21u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ (4, *path, vec_type)
+ })
+ },
+ &Event::ProbeFailed { ref payment_id, ref payment_hash, ref path, ref short_channel_id } => {
+ 23u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ (4, *path, vec_type),
+ (6, short_channel_id, option),
+ })
+ },
+ &Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
+ 25u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, prev_channel_id, required),
+ (2, failed_next_destination, required),
+ })
+ },
+ #[cfg(anchors)]
+ &Event::BumpTransaction(ref event)=> {
+ 27u8.write(writer)?;
+ match event {
+ // We never write the ChannelClose|HTLCResolution events as they'll be replayed
+ // upon restarting anyway if they remain unresolved.
+ BumpTransactionEvent::ChannelClose { .. } => {}
+ BumpTransactionEvent::HTLCResolution { .. } => {}
+ }
+ write_tlv_fields!(writer, {}); // Write a length field for forwards compat
+ }
+ &Event::ChannelReady { ref channel_id, ref user_channel_id, ref counterparty_node_id, ref channel_type } => {
+ 29u8.write(writer)?;
+ write_tlv_fields!(writer, {
+ (0, channel_id, required),
+ (2, user_channel_id, required),
+ (4, counterparty_node_id, required),
+ (6, channel_type, required),
+ });
+ },
+ // 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`.
+ }
+ Ok(())
+ }
+}
+impl MaybeReadable for Event {
+ fn read<R: io::Read>(reader: &mut R) -> Result<Option<Self>, 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.
+ 0u8 => Ok(None),
+ 1u8 => {
+ let 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 receiver_node_id = None;
+ let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
+ let mut via_channel_id = None;
+ let mut via_user_channel_id = None;
+ read_tlv_fields!(reader, {
+ (0, payment_hash, required),
+ (1, receiver_node_id, option),
+ (2, payment_secret, option),
+ (3, via_channel_id, option),
+ (4, amount_msat, required),
+ (5, via_user_channel_id, option),
+ (6, _user_payment_id, option),
+ (8, payment_preimage, option),
+ });
+ let purpose = match payment_secret {
+ Some(secret) => PaymentPurpose::InvoicePayment {
+ payment_preimage,
+ payment_secret: secret
+ },
+ None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()),
+ None => return Err(msgs::DecodeError::InvalidValue),
+ };
+ Ok(Some(Event::PaymentClaimable {
+ receiver_node_id,
+ payment_hash,
+ amount_msat,
+ purpose,
+ via_channel_id,
+ via_user_channel_id,
+ }))
+ };
+ f()
+ },
+ 2u8 => {
+ let f = || {
+ let mut payment_preimage = PaymentPreimage([0; 32]);
+ let mut payment_hash = None;
+ let mut payment_id = None;
+ let mut fee_paid_msat = None;
+ read_tlv_fields!(reader, {
+ (0, payment_preimage, required),
+ (1, payment_hash, option),
+ (3, payment_id, option),
+ (5, fee_paid_msat, option),
+ });
+ if payment_hash.is_none() {
+ payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner()));
+ }
+ Ok(Some(Event::PaymentSent {
+ payment_id,
+ payment_preimage,
+ payment_hash: payment_hash.unwrap(),
+ fee_paid_msat,
+ }))
+ };
+ f()
+ },
+ 3u8 => {
+ let f = || {
+ #[cfg(test)]
+ let error_code = Readable::read(reader)?;
+ #[cfg(test)]
+ let error_data = Readable::read(reader)?;
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut payment_failed_permanently = false;
+ let mut network_update = None;
+ let mut path: Option<Vec<RouteHop>> = Some(vec![]);
+ let mut short_channel_id = None;
+ let mut payment_id = None;
+ let mut failure_opt = None;
+ read_tlv_fields!(reader, {
+ (0, payment_hash, required),
+ (1, network_update, upgradable_option),
+ (2, payment_failed_permanently, required),
+ (5, path, vec_type),
+ (7, short_channel_id, option),
+ (11, payment_id, option),
+ (13, failure_opt, upgradable_option),
+ });
+ let failure = failure_opt.unwrap_or_else(|| PathFailure::OnPath { network_update });
+ Ok(Some(Event::PaymentPathFailed {
+ payment_id,
+ payment_hash,
+ payment_failed_permanently,
+ failure,
+ path: path.unwrap(),
+ short_channel_id,
+ #[cfg(test)]
+ error_code,
+ #[cfg(test)]
+ error_data,
+ }))
+ };
+ f()
+ },
+ 4u8 => Ok(None),
+ 5u8 => {
+ let f = || {
+ let mut outputs = WithoutLength(Vec::new());
+ read_tlv_fields!(reader, {
+ (0, outputs, required),
+ });
+ Ok(Some(Event::SpendableOutputs { outputs: outputs.0 }))
+ };
+ f()
+ },
+ 6u8 => {
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut intercept_id = InterceptId([0; 32]);
+ let mut requested_next_hop_scid = InterceptNextHop::FakeScid { requested_next_hop_scid: 0 };
+ let mut inbound_amount_msat = 0;
+ let mut expected_outbound_amount_msat = 0;
+ read_tlv_fields!(reader, {
+ (0, intercept_id, required),
+ (2, requested_next_hop_scid, required),
+ (4, payment_hash, required),
+ (6, inbound_amount_msat, required),
+ (8, expected_outbound_amount_msat, required),
+ });
+ let next_scid = match requested_next_hop_scid {
+ InterceptNextHop::FakeScid { requested_next_hop_scid: scid } => scid
+ };
+ Ok(Some(Event::HTLCIntercepted {
+ payment_hash,
+ requested_next_hop_scid: next_scid,
+ inbound_amount_msat,
+ expected_outbound_amount_msat,
+ intercept_id,
+ }))
+ },
+ 7u8 => {
+ let f = || {
+ let mut fee_earned_msat = None;
+ let mut prev_channel_id = None;
+ let mut claim_from_onchain_tx = false;
+ let mut next_channel_id = None;
+ read_tlv_fields!(reader, {
+ (0, fee_earned_msat, option),
+ (1, prev_channel_id, option),
+ (2, claim_from_onchain_tx, required),
+ (3, next_channel_id, option),
+ });
+ Ok(Some(Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id }))
+ };
+ f()
+ },
+ 9u8 => {
+ let f = || {
+ let mut channel_id = [0; 32];
+ let mut reason = UpgradableRequired(None);
+ let mut user_channel_id_low_opt: Option<u64> = None;
+ let mut user_channel_id_high_opt: Option<u64> = 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),
+ });
+
+ // `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 separate u64 values.
+ 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) }))
+ };
+ 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() };
+ read_tlv_fields!(reader, {
+ (0, channel_id, required),
+ (2, transaction, required),
+ });
+ Ok(Some(Event::DiscardFunding { channel_id, transaction } ))
+ };
+ f()
+ },
+ 13u8 => {
+ let f = || {
+ let mut payment_id = PaymentId([0; 32]);
+ let mut payment_hash = None;
+ let mut path: Option<Vec<RouteHop>> = Some(vec![]);
+ read_tlv_fields!(reader, {
+ (0, payment_id, required),
+ (2, payment_hash, option),
+ (4, path, vec_type),
+ });
+ Ok(Some(Event::PaymentPathSuccessful {
+ payment_id,
+ payment_hash,
+ path: path.unwrap(),
+ }))
+ };
+ f()
+ },
+ 15u8 => {
+ let f = || {
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut payment_id = PaymentId([0; 32]);
+ read_tlv_fields!(reader, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ });
+ Ok(Some(Event::PaymentFailed {
+ payment_id,
+ payment_hash,
+ }))
+ };
+ f()
+ },
+ 17u8 => {
+ // Value 17 is used for `Event::OpenChannelRequest`.
+ Ok(None)
+ },
+ 19u8 => {
+ let f = || {
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut purpose = UpgradableRequired(None);
+ let mut amount_msat = 0;
+ let mut receiver_node_id = None;
+ read_tlv_fields!(reader, {
+ (0, payment_hash, required),
+ (1, receiver_node_id, option),
+ (2, purpose, upgradable_required),
+ (4, amount_msat, required),
+ });
+ Ok(Some(Event::PaymentClaimed {
+ receiver_node_id,
+ payment_hash,
+ purpose: _init_tlv_based_struct_field!(purpose, upgradable_required),
+ amount_msat,
+ }))
+ };
+ f()
+ },
+ 21u8 => {
+ let f = || {
+ let mut payment_id = PaymentId([0; 32]);
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut path: Option<Vec<RouteHop>> = Some(vec![]);
+ read_tlv_fields!(reader, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ (4, path, vec_type),
+ });
+ Ok(Some(Event::ProbeSuccessful {
+ payment_id,
+ payment_hash,
+ path: path.unwrap(),
+ }))
+ };
+ f()
+ },
+ 23u8 => {
+ let f = || {
+ let mut payment_id = PaymentId([0; 32]);
+ let mut payment_hash = PaymentHash([0; 32]);
+ let mut path: Option<Vec<RouteHop>> = Some(vec![]);
+ let mut short_channel_id = None;
+ read_tlv_fields!(reader, {
+ (0, payment_id, required),
+ (2, payment_hash, required),
+ (4, path, vec_type),
+ (6, short_channel_id, option),
+ });
+ Ok(Some(Event::ProbeFailed {
+ payment_id,
+ payment_hash,
+ path: path.unwrap(),
+ short_channel_id,
+ }))
+ };
+ f()
+ },
+ 25u8 => {
+ let f = || {
+ let mut prev_channel_id = [0; 32];
+ let mut failed_next_destination_opt = UpgradableRequired(None);
+ read_tlv_fields!(reader, {
+ (0, prev_channel_id, required),
+ (2, failed_next_destination_opt, upgradable_required),
+ });
+ Ok(Some(Event::HTLCHandlingFailed {
+ prev_channel_id,
+ failed_next_destination: _init_tlv_based_struct_field!(failed_next_destination_opt, upgradable_required),
+ }))
+ };
+ f()
+ },
+ 27u8 => Ok(None),
+ 29u8 => {
+ let f = || {
+ let mut channel_id = [0; 32];
+ let mut user_channel_id: u128 = 0;
+ let mut counterparty_node_id = RequiredWrapper(None);
+ let mut channel_type = RequiredWrapper(None);
+ read_tlv_fields!(reader, {
+ (0, channel_id, required),
+ (2, user_channel_id, required),
+ (4, counterparty_node_id, required),
+ (6, channel_type, required),
+ });
+
+ Ok(Some(Event::ChannelReady {
+ channel_id,
+ user_channel_id,
+ counterparty_node_id: counterparty_node_id.0.unwrap(),
+ channel_type: channel_type.0.unwrap()
+ }))
+ };
+ f()
+ },
+ // 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.
+ x if x % 2 == 1 => {
+ // If the event is of unknown type, assume it was written with `write_tlv_fields`,
+ // which prefixes the whole thing with a length BigSize. Because the event is
+ // odd-type unknown, we should treat it as `Ok(None)` even if it has some TLV
+ // fields that are even. Thus, we avoid using `read_tlv_fields` and simply read
+ // exactly the number of bytes specified, ignoring them entirely.
+ let tlv_len: BigSize = Readable::read(reader)?;
+ FixedLengthReader::new(reader, tlv_len.0)
+ .eat_remaining().map_err(|_| msgs::DecodeError::ShortRead)?;
+ Ok(None)
+ },
+ _ => Err(msgs::DecodeError::InvalidValue)
+ }
+ }
+}
+
+/// An event generated by ChannelManager which indicates a message should be sent to a peer (or
+/// broadcast to most peers).
+/// These events are handled by PeerManager::process_events if you are using a PeerManager.
+#[derive(Clone, Debug)]
+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.
+ SendAcceptChannel {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::AcceptChannel,
+ },
+ /// Used to indicate that we've initiated a channel open and should send the open_channel
+ /// message provided to the given peer.
+ SendOpenChannel {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::OpenChannel,
+ },
+ /// 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
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::FundingCreated,
+ },
+ /// Used to indicate that a funding_signed message should be sent to the peer with the given node_id.
+ SendFundingSigned {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::FundingSigned,
+ },
+ /// 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)
+ node_id: PublicKey,
+ /// The channel_ready message which should be sent.
+ msg: msgs::ChannelReady,
+ },
+ /// Used to indicate that an announcement_signatures message should be sent to the peer with the given node_id.
+ SendAnnouncementSignatures {
+ /// The node_id of the node which should receive these message(s)
+ node_id: PublicKey,
+ /// The announcement_signatures message which should be sent.
+ msg: msgs::AnnouncementSignatures,
+ },
+ /// Used to indicate that a series of HTLC update messages, as well as a commitment_signed
+ /// message should be sent to the peer with the given node_id.
+ UpdateHTLCs {
+ /// The node_id of the node which should receive these message(s)
+ node_id: PublicKey,
+ /// The update messages which should be sent. ALL messages in the struct should be sent!
+ updates: msgs::CommitmentUpdate,
+ },
+ /// Used to indicate that a revoke_and_ack message should be sent to the peer with the given node_id.
+ SendRevokeAndACK {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::RevokeAndACK,
+ },
+ /// Used to indicate that a closing_signed message should be sent to the peer with the given node_id.
+ SendClosingSigned {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::ClosingSigned,
+ },
+ /// Used to indicate that a shutdown message should be sent to the peer with the given node_id.
+ SendShutdown {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::Shutdown,
+ },
+ /// Used to indicate that a channel_reestablish message should be sent to the peer with the given node_id.
+ SendChannelReestablish {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The message which should be sent.
+ msg: msgs::ChannelReestablish,
+ },
+ /// Used to send a channel_announcement and channel_update to a specific peer, likely on
+ /// initial connection to ensure our peers know about our channels.
+ SendChannelAnnouncement {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The channel_announcement which should be sent.
+ msg: msgs::ChannelAnnouncement,
+ /// The followup channel_update which should be sent.
+ update_msg: msgs::ChannelUpdate,
+ },
+ /// Used to indicate that a channel_announcement and channel_update should be broadcast to all
+ /// peers (except the peer with node_id either msg.contents.node_id_1 or msg.contents.node_id_2).
+ ///
+ /// Note that after doing so, you very likely (unless you did so very recently) want to
+ /// broadcast a node_announcement (e.g. via [`PeerManager::broadcast_node_announcement`]). This
+ /// ensures that any nodes which see our channel_announcement also have a relevant
+ /// node_announcement, including relevant feature flags which may be important for routing
+ /// through or to us.
+ ///
+ /// [`PeerManager::broadcast_node_announcement`]: crate::ln::peer_handler::PeerManager::broadcast_node_announcement
+ BroadcastChannelAnnouncement {
+ /// The channel_announcement which should be sent.
+ msg: msgs::ChannelAnnouncement,
+ /// The followup channel_update which should be sent.
+ update_msg: Option<msgs::ChannelUpdate>,
+ },
+ /// Used to indicate that a channel_update should be broadcast to all peers.
+ BroadcastChannelUpdate {
+ /// The channel_update which should be sent.
+ msg: msgs::ChannelUpdate,
+ },
+ /// Used to indicate that a node_announcement should be broadcast to all peers.
+ BroadcastNodeAnnouncement {
+ /// The node_announcement which should be sent.
+ msg: msgs::NodeAnnouncement,
+ },
+ /// Used to indicate that a channel_update should be sent to a single peer.
+ /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a
+ /// private channel and we shouldn't be informing all of our peers of channel parameters.
+ SendChannelUpdate {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The channel_update which should be sent.
+ msg: msgs::ChannelUpdate,
+ },
+ /// Broadcast an error downstream to be handled
+ HandleError {
+ /// The node_id of the node which should receive this message
+ node_id: PublicKey,
+ /// The action which should be taken.
+ action: msgs::ErrorAction
+ },
+ /// Query a peer for channels with funding transaction UTXOs in a block range.
+ SendChannelRangeQuery {
+ /// The node_id of this message recipient
+ node_id: PublicKey,
+ /// The query_channel_range which should be sent.
+ msg: msgs::QueryChannelRange,
+ },
+ /// Request routing gossip messages from a peer for a list of channels identified by
+ /// their short_channel_ids.
+ SendShortIdsQuery {
+ /// The node_id of this message recipient
+ node_id: PublicKey,
+ /// The query_short_channel_ids which should be sent.
+ msg: msgs::QueryShortChannelIds,
+ },
+ /// Sends a reply to a channel range query. This may be one of several SendReplyChannelRange events
+ /// emitted during processing of the query.
+ SendReplyChannelRange {
+ /// The node_id of this message recipient
+ node_id: PublicKey,
+ /// The reply_channel_range which should be sent.
+ msg: msgs::ReplyChannelRange,
+ },
+ /// Sends a timestamp filter for inbound gossip. This should be sent on each new connection to
+ /// enable receiving gossip messages from the peer.
+ SendGossipTimestampFilter {
+ /// The node_id of this message recipient
+ node_id: PublicKey,
+ /// The gossip_timestamp_filter which should be sent.
+ msg: msgs::GossipTimestampFilter,
+ },
+}
+
+/// A trait indicating an object may generate message send events
+pub trait MessageSendEventsProvider {
+ /// Gets the list of pending events which were generated by previous actions, clearing the list
+ /// in the process.
+ fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
+}
+
+/// 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<msgs::OnionMessage>;
+}
+
+/// A trait indicating an object may generate events.
+///
+/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
+///
+/// Implementations of this trait may also feature an async version of event handling, as shown with
+/// [`ChannelManager::process_pending_events_async`] and
+/// [`ChainMonitor::process_pending_events_async`].
+///
+/// # Requirements
+///
+/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
+/// event since the last invocation.
+///
+/// In order to ensure no [`Event`]s are lost, implementors of this trait will persist [`Event`]s
+/// and replay any unhandled events on startup. An [`Event`] is considered handled when
+/// [`process_pending_events`] returns, thus handlers MUST fully handle [`Event`]s and persist any
+/// relevant changes to disk *before* returning.
+///
+/// Further, because an application may crash between an [`Event`] being handled and the
+/// implementor of this trait being re-serialized, [`Event`] handling must be idempotent - in
+/// effect, [`Event`]s may be replayed.
+///
+/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
+/// consult the provider's documentation on the implication of processing events and how a handler
+/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and
+/// [`ChainMonitor::process_pending_events`]).
+///
+/// (C-not implementable) As there is likely no reason for a user to implement this trait on their
+/// own type(s).
+///
+/// [`process_pending_events`]: Self::process_pending_events
+/// [`handle_event`]: EventHandler::handle_event
+/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events
+/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events
+/// [`ChannelManager::process_pending_events_async`]: crate::ln::channelmanager::ChannelManager::process_pending_events_async
+/// [`ChainMonitor::process_pending_events_async`]: crate::chain::chainmonitor::ChainMonitor::process_pending_events_async
+pub trait EventsProvider {
+ /// Processes any events generated since the last call using the given event handler.
+ ///
+ /// See the trait-level documentation for requirements.
+ fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
+}
+
+/// A trait implemented for objects handling events from [`EventsProvider`].
+///
+/// An async variation also exists for implementations of [`EventsProvider`] that support async
+/// event handling. The async event handler should satisfy the generic bounds: `F:
+/// core::future::Future, H: Fn(Event) -> F`.
+pub trait EventHandler {
+ /// Handles the given [`Event`].
+ ///
+ /// See [`EventsProvider`] for details that must be considered when implementing this method.
+ fn handle_event(&self, event: Event);
+}
+
+impl<F> EventHandler for F where F: Fn(Event) {
+ fn handle_event(&self, event: Event) {
+ self(event)
+ }
+}
+
+impl<T: EventHandler> EventHandler for Arc<T> {
+ fn handle_event(&self, event: Event) {
+ self.deref().handle_event(event)
+ }
+}
pub mod offers;
pub mod routing;
pub mod onion_message;
+pub mod events;
#[cfg(feature = "std")]
/// Re-export of either `core2::io` or `std::io`, depending on the `std` feature flag.
///
/// Only include HTLCs that are above the dust limit for the channel.
///
- /// (C-not exported) due to the generic though we likely should expose a version without
+ /// This is not exported to bindings users due to the generic though we likely should expose a version without
pub fn new_with_auxiliary_htlc_data<T>(commitment_number: u64, to_broadcaster_value_sat: u64, to_countersignatory_value_sat: u64, opt_anchors: bool, broadcaster_funding_key: PublicKey, countersignatory_funding_key: PublicKey, keys: TxCreationKeys, feerate_per_kw: u32, htlcs_with_aux: &mut Vec<(HTLCOutputInCommitment, T)>, channel_parameters: &DirectedChannelTransactionParameters) -> CommitmentTransaction {
// Sort outputs and populate output indices while keeping track of the auxiliary data
let (outputs, htlcs) = Self::internal_build_outputs(&keys, to_broadcaster_value_sat, to_countersignatory_value_sat, htlcs_with_aux, channel_parameters, opt_anchors, &broadcaster_funding_key, &countersignatory_funding_key).unwrap();
/// Use non-zero fee anchors
///
- /// (C-not exported) due to move, and also not likely to be useful for binding users
+ /// This is not exported to bindings users due to move, and also not likely to be useful for binding users
pub fn with_non_zero_fee_anchors(mut self) -> Self {
self.opt_non_zero_fee_anchors = Some(());
self
/// which were included in this commitment transaction in output order.
/// The transaction index is always populated.
///
- /// (C-not exported) as we cannot currently convert Vec references to/from C, though we should
+ /// This is not exported to bindings users as we cannot currently convert Vec references to/from C, though we should
/// expose a less effecient version which creates a Vec of references in the future.
pub fn htlcs(&self) -> &Vec<HTLCOutputInCommitment> {
&self.htlcs
use crate::chain::channelmonitor::{ANTI_REORG_DELAY, ChannelMonitor};
use crate::chain::transaction::OutPoint;
use crate::chain::{ChannelMonitorUpdateStatus, Listen, Watch};
+use crate::events::{Event, MessageSendEvent, MessageSendEventsProvider, PaymentPurpose, ClosureReason, HTLCDestination};
use crate::ln::channelmanager::{ChannelManager, RAACommitmentOrder, PaymentSendFailure, PaymentId};
use crate::ln::channel::AnnouncementSigsState;
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler, RoutingMessageHandler};
use crate::util::enforcing_trait_impls::EnforcingSigner;
-use crate::util::events::{Event, MessageSendEvent, MessageSendEventsProvider, PaymentPurpose, ClosureReason, HTLCDestination};
use crate::util::errors::APIError;
use crate::util::ser::{ReadableArgs, Writeable};
use crate::util::test_utils::TestBroadcaster;
use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateStep, LATENCY_GRACE_PERIOD_BLOCKS, CLOSED_CHANNEL_UPDATE_ID};
use crate::chain::transaction::{OutPoint, TransactionData};
use crate::chain::keysinterface::{WriteableEcdsaChannelSigner, EntropySource, ChannelSigner, SignerProvider, NodeSigner, Recipient};
+use crate::events::ClosureReason;
use crate::routing::gossip::NodeId;
-use crate::util::events::ClosureReason;
use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer, VecWriter};
use crate::util::logger::Logger;
use crate::util::errors::APIError;
use crate::chain::chaininterface::{BroadcasterInterface, ConfirmationTarget, FeeEstimator, LowerBoundedFeeEstimator};
use crate::chain::channelmonitor::{ChannelMonitor, ChannelMonitorUpdate, ChannelMonitorUpdateStep, HTLC_FAIL_BACK_BUFFER, CLTV_CLAIM_BUFFER, LATENCY_GRACE_PERIOD_BLOCKS, ANTI_REORG_DELAY, MonitorEvent, CLOSED_CHANNEL_UPDATE_ID};
use crate::chain::transaction::{OutPoint, TransactionData};
+use crate::events;
+use crate::events::{Event, EventHandler, EventsProvider, MessageSendEvent, MessageSendEventsProvider, ClosureReason, HTLCDestination};
// Since this struct is returned in `list_channels` methods, expose it here in case users want to
// construct one themselves.
use crate::ln::{inbound_payment, PaymentHash, PaymentPreimage, PaymentSecret};
use crate::ln::wire::Encode;
use crate::chain::keysinterface::{EntropySource, KeysManager, NodeSigner, Recipient, SignerProvider, ChannelSigner, WriteableEcdsaChannelSigner};
use crate::util::config::{UserConfig, ChannelConfig};
-use crate::util::events::{Event, EventHandler, EventsProvider, MessageSendEvent, MessageSendEventsProvider, ClosureReason, HTLCDestination};
-use crate::util::events;
use crate::util::wakers::{Future, Notifier};
use crate::util::scid_utils::fake_scid;
+use crate::util::string::UntrustedString;
use crate::util::ser::{BigSize, FixedLengthReader, Readable, ReadableArgs, MaybeReadable, Writeable, Writer, VecWriter};
use crate::util::logger::{Level, Logger};
use crate::util::errors::APIError;
pub(super) routing: PendingHTLCRouting,
pub(super) incoming_shared_secret: [u8; 32],
payment_hash: PaymentHash,
+ /// Amount received
pub(super) incoming_amt_msat: Option<u64>, // Added in 0.0.113
+ /// Sender intended amount to forward or receive (actual amount received
+ /// may overshoot this in either case)
pub(super) outgoing_amt_msat: u64,
pub(super) outgoing_cltv_value: u32,
}
cltv_expiry: u32,
/// The amount (in msats) of this MPP part
value: u64,
+ /// The amount (in msats) that the sender intended to be sent in this MPP
+ /// part (used for validating total MPP amount)
+ sender_intended_value: u64,
onion_payload: OnionPayload,
timer_ticks: u8,
- /// The sum total of all MPP parts
+ /// The total value received for a payment (sum of all MPP parts if the payment is a MPP).
+ /// Gets set to the amount reported when pushing [`Event::PaymentClaimable`].
+ total_value_received: Option<u64>,
+ /// The sender intended sum total of all MPP parts specified in the onion
total_msat: u64,
}
/// A payment identifier used to uniquely identify a payment to LDK.
-/// (C-not exported) as we just use [u8; 32] directly
+///
+/// This is not exported to bindings users as we just use [u8; 32] directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct PaymentId(pub [u8; 32]);
}
/// An identifier used to uniquely identify an intercepted HTLC to LDK.
-/// (C-not exported) as we just use [u8; 32] directly
+///
+/// This is not exported to bindings users as we just use [u8; 32] directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct InterceptId(pub [u8; 32]);
/// or, respectively, [`Router`] for its router, but this type alias chooses the concrete types
/// of [`KeysManager`] and [`DefaultRouter`].
///
-/// (C-not exported) as Arcs don't make sense in bindings
+/// This is not exported to bindings users as Arcs don't make sense in bindings
pub type SimpleArcChannelManager<M, T, F, L> = ChannelManager<
Arc<M>,
Arc<T>,
/// or, respectively, [`Router`] for its router, but this type alias chooses the concrete types
/// of [`KeysManager`] and [`DefaultRouter`].
///
-/// (C-not exported) as Arcs don't make sense in bindings
+/// This is not exported to bindings users as Arcs don't make sense in bindings
pub type SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, M, T, F, L> = ChannelManager<&'a M, &'b T, &'c KeysManager, &'c KeysManager, &'c KeysManager, &'d F, &'e DefaultRouter<&'f NetworkGraph<&'g L>, &'g L, &'h Mutex<ProbabilisticScorer<&'f NetworkGraph<&'g L>, &'g L>>>, &'g L>;
/// Manager which keeps track of a number of channels and sends messages to the appropriate
/// [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis
/// [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background
/// [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal
- /// [`SendShutdown`]: crate::util::events::MessageSendEvent::SendShutdown
+ /// [`SendShutdown`]: crate::events::MessageSendEvent::SendShutdown
pub fn close_channel(&self, channel_id: &[u8; 32], counterparty_node_id: &PublicKey) -> Result<(), APIError> {
self.close_channel_internal(channel_id, counterparty_node_id, None)
}
/// [`ChannelConfig::force_close_avoidance_max_fee_satoshis`]: crate::util::config::ChannelConfig::force_close_avoidance_max_fee_satoshis
/// [`Background`]: crate::chain::chaininterface::ConfirmationTarget::Background
/// [`Normal`]: crate::chain::chaininterface::ConfirmationTarget::Normal
- /// [`SendShutdown`]: crate::util::events::MessageSendEvent::SendShutdown
+ /// [`SendShutdown`]: crate::events::MessageSendEvent::SendShutdown
pub fn close_channel_with_target_feerate(&self, channel_id: &[u8; 32], counterparty_node_id: &PublicKey, target_feerate_sats_per_1000_weight: u32) -> Result<(), APIError> {
self.close_channel_internal(channel_id, counterparty_node_id, Some(target_feerate_sats_per_1000_weight))
}
let peer_state = &mut *peer_state_lock;
if let hash_map::Entry::Occupied(chan) = peer_state.channel_by_id.entry(channel_id.clone()) {
if let Some(peer_msg) = peer_msg {
- self.issue_channel_close_events(chan.get(),ClosureReason::CounterpartyForceClosed { peer_msg: peer_msg.to_string() });
+ self.issue_channel_close_events(chan.get(),ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(peer_msg.to_string()) });
} else {
self.issue_channel_close_events(chan.get(),ClosureReason::HolderForceClosed);
}
payment_hash: PaymentHash, amt_msat: u64, cltv_expiry: u32, phantom_shared_secret: Option<[u8; 32]>) -> Result<PendingHTLCInfo, ReceiveError>
{
// final_incorrect_cltv_expiry
- if hop_data.outgoing_cltv_value != cltv_expiry {
+ if hop_data.outgoing_cltv_value > cltv_expiry {
return Err(ReceiveError {
- msg: "Upstream node set CLTV to the wrong value",
+ msg: "Upstream node set CLTV to less than the CLTV set by the sender",
err_code: 18,
err_data: cltv_expiry.to_be_bytes().to_vec()
})
payment_hash,
incoming_shared_secret: shared_secret,
incoming_amt_msat: Some(amt_msat),
- outgoing_amt_msat: amt_msat,
+ outgoing_amt_msat: hop_data.amt_to_forward,
outgoing_cltv_value: hop_data.outgoing_cltv_value,
})
}
}
#[cfg(test)]
- fn test_send_payment_internal(&self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>, keysend_preimage: Option<PaymentPreimage>, payment_id: PaymentId, recv_value_msat: Option<u64>, onion_session_privs: Vec<[u8; 32]>) -> Result<(), PaymentSendFailure> {
+
pub(super) fn test_send_payment_internal(&self, route: &Route, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>, keysend_preimage: Option<PaymentPreimage>, payment_id: PaymentId, recv_value_msat: Option<u64>, onion_session_privs: Vec<[u8; 32]>) -> Result<(), PaymentSendFailure> {
let best_block_height = self.best_block.read().unwrap().height();
let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(&self.total_consistency_lock, &self.persistence_notifier);
self.pending_outbound_payments.test_send_payment_internal(route, payment_hash, payment_secret, keysend_preimage, payment_id, recv_value_msat, onion_session_privs, &self.node_signer, best_block_height,
/// implemented by Bitcoin Core wallet. See <https://bitcoinops.org/en/topics/fee-sniping/>
/// for more details.
///
- /// [`Event::FundingGenerationReady`]: crate::util::events::Event::FundingGenerationReady
- /// [`Event::ChannelClosed`]: crate::util::events::Event::ChannelClosed
+ /// [`Event::FundingGenerationReady`]: crate::events::Event::FundingGenerationReady
+ /// [`Event::ChannelClosed`]: crate::events::Event::ChannelClosed
pub fn funding_transaction_generated(&self, temporary_channel_id: &[u8; 32], counterparty_node_id: &PublicKey, funding_transaction: Transaction) -> Result<(), APIError> {
let _persistence_guard = PersistenceNotifierGuard::notify_on_drop(&self.total_consistency_lock, &self.persistence_notifier);
HTLCForwardInfo::AddHTLC(PendingAddHTLCInfo {
prev_short_channel_id, prev_htlc_id, prev_funding_outpoint, prev_user_channel_id,
forward_info: PendingHTLCInfo {
- routing, incoming_shared_secret, payment_hash, outgoing_amt_msat, ..
+ routing, incoming_shared_secret, payment_hash, incoming_amt_msat, outgoing_amt_msat, ..
}
}) => {
let (cltv_expiry, onion_payload, payment_data, phantom_shared_secret) = match routing {
panic!("short_channel_id == 0 should imply any pending_forward entries are of type Receive");
}
};
- let claimable_htlc = ClaimableHTLC {
+ let mut claimable_htlc = ClaimableHTLC {
prev_hop: HTLCPreviousHopData {
short_channel_id: prev_short_channel_id,
outpoint: prev_funding_outpoint,
incoming_packet_shared_secret: incoming_shared_secret,
phantom_shared_secret,
},
- value: outgoing_amt_msat,
+ // We differentiate the received value from the sender intended value
+ // if possible so that we don't prematurely mark MPP payments complete
+ // if routing nodes overpay
+ value: incoming_amt_msat.unwrap_or(outgoing_amt_msat),
+ sender_intended_value: outgoing_amt_msat,
timer_ticks: 0,
+ total_value_received: None,
total_msat: if let Some(data) = &payment_data { data.total_msat } else { outgoing_amt_msat },
cltv_expiry,
onion_payload,
fail_htlc!(claimable_htlc, payment_hash);
continue
}
- let (_, htlcs) = claimable_payments.claimable_htlcs.entry(payment_hash)
+ let (_, ref mut htlcs) = claimable_payments.claimable_htlcs.entry(payment_hash)
.or_insert_with(|| (purpose(), Vec::new()));
if htlcs.len() == 1 {
if let OnionPayload::Spontaneous(_) = htlcs[0].onion_payload {
continue
}
}
- let mut total_value = claimable_htlc.value;
+ let mut total_value = claimable_htlc.sender_intended_value;
for htlc in htlcs.iter() {
- total_value += htlc.value;
+ total_value += htlc.sender_intended_value;
match &htlc.onion_payload {
OnionPayload::Invoice { .. } => {
if htlc.total_msat != $payment_data.total_msat {
_ => unreachable!(),
}
}
- if total_value >= msgs::MAX_VALUE_MSAT || total_value > $payment_data.total_msat {
- log_trace!(self.logger, "Failing HTLCs with payment_hash {} as the total value {} ran over expected value {} (or HTLCs were inconsistent)",
- log_bytes!(payment_hash.0), total_value, $payment_data.total_msat);
+ // The condition determining whether an MPP is complete must
+ // match exactly the condition used in `timer_tick_occurred`
+ if total_value >= msgs::MAX_VALUE_MSAT {
fail_htlc!(claimable_htlc, payment_hash);
- } else if total_value == $payment_data.total_msat {
+ } else if total_value - claimable_htlc.sender_intended_value >= $payment_data.total_msat {
+ log_trace!(self.logger, "Failing HTLC with payment_hash {} as payment is already claimable",
+ log_bytes!(payment_hash.0));
+ fail_htlc!(claimable_htlc, payment_hash);
+ } else if total_value >= $payment_data.total_msat {
let prev_channel_id = prev_funding_outpoint.to_channel_id();
htlcs.push(claimable_htlc);
+ let amount_msat = htlcs.iter().map(|htlc| htlc.value).sum();
+ htlcs.iter_mut().for_each(|htlc| htlc.total_value_received = Some(amount_msat));
new_events.push(events::Event::PaymentClaimable {
receiver_node_id: Some(receiver_node_id),
payment_hash,
purpose: purpose(),
- amount_msat: total_value,
+ amount_msat,
via_channel_id: Some(prev_channel_id),
via_user_channel_id: Some(prev_user_channel_id),
});
}
match claimable_payments.claimable_htlcs.entry(payment_hash) {
hash_map::Entry::Vacant(e) => {
+ let amount_msat = claimable_htlc.value;
+ claimable_htlc.total_value_received = Some(amount_msat);
let purpose = events::PaymentPurpose::SpontaneousPayment(preimage);
e.insert((purpose.clone(), vec![claimable_htlc]));
let prev_channel_id = prev_funding_outpoint.to_channel_id();
new_events.push(events::Event::PaymentClaimable {
receiver_node_id: Some(receiver_node_id),
payment_hash,
- amount_msat: outgoing_amt_msat,
+ amount_msat,
purpose,
via_channel_id: Some(prev_channel_id),
via_user_channel_id: Some(prev_user_channel_id),
if let OnionPayload::Invoice { .. } = htlcs[0].onion_payload {
// Check if we've received all the parts we need for an MPP (the value of the parts adds to total_msat).
// In this case we're not going to handle any timeouts of the parts here.
- if htlcs[0].total_msat == htlcs.iter().fold(0, |total, htlc| total + htlc.value) {
+ // This condition determining whether the MPP is complete here must match
+ // exactly the condition used in `process_pending_htlc_forwards`.
+ if htlcs[0].total_msat <= htlcs.iter().fold(0, |total, htlc| total + htlc.sender_intended_value) {
return true;
} else if htlcs.into_iter().any(|htlc| {
htlc.timer_ticks += 1;
/// event matches your expectation. If you fail to do so and call this method, you may provide
/// the sender "proof-of-payment" when they did not fulfill the full expected payment.
///
- /// [`Event::PaymentClaimable`]: crate::util::events::Event::PaymentClaimable
- /// [`Event::PaymentClaimed`]: crate::util::events::Event::PaymentClaimed
+ /// [`Event::PaymentClaimable`]: crate::events::Event::PaymentClaimable
+ /// [`Event::PaymentClaimed`]: crate::events::Event::PaymentClaimed
/// [`process_pending_events`]: EventsProvider::process_pending_events
/// [`create_inbound_payment`]: Self::create_inbound_payment
/// [`create_inbound_payment_for_hash`]: Self::create_inbound_payment_for_hash
// provide the preimage, so worrying too much about the optimal handling isn't worth
// it.
let mut claimable_amt_msat = 0;
+ let mut prev_total_msat = None;
let mut expected_amt_msat = None;
let mut valid_mpp = true;
let mut errs = Vec::new();
break;
}
- if expected_amt_msat.is_some() && expected_amt_msat != Some(htlc.total_msat) {
- log_error!(self.logger, "Somehow ended up with an MPP payment with different total amounts - this should not be reachable!");
+ if prev_total_msat.is_some() && prev_total_msat != Some(htlc.total_msat) {
+ log_error!(self.logger, "Somehow ended up with an MPP payment with different expected total amounts - this should not be reachable!");
+ debug_assert!(false);
+ valid_mpp = false;
+ break;
+ }
+ prev_total_msat = Some(htlc.total_msat);
+
+ if expected_amt_msat.is_some() && expected_amt_msat != htlc.total_value_received {
+ log_error!(self.logger, "Somehow ended up with an MPP payment with different received total amounts - this should not be reachable!");
debug_assert!(false);
valid_mpp = false;
break;
}
+ expected_amt_msat = htlc.total_value_received;
- expected_amt_msat = Some(htlc.total_msat);
if let OnionPayload::Spontaneous(_) = &htlc.onion_payload {
// We don't currently support MPP for spontaneous payments, so just check
// that there's one payment here and move on.
(0, self.prev_hop, required),
(1, self.total_msat, required),
(2, self.value, required),
+ (3, self.sender_intended_value, required),
(4, payment_data, option),
+ (5, self.total_value_received, option),
(6, self.cltv_expiry, required),
(8, keysend_preimage, option),
});
fn read<R: Read>(reader: &mut R) -> Result<Self, DecodeError> {
let mut prev_hop = crate::util::ser::RequiredWrapper(None);
let mut value = 0;
+ let mut sender_intended_value = None;
let mut payment_data: Option<msgs::FinalOnionHopData> = None;
let mut cltv_expiry = 0;
+ let mut total_value_received = None;
let mut total_msat = None;
let mut keysend_preimage: Option<PaymentPreimage> = None;
read_tlv_fields!(reader, {
(0, prev_hop, required),
(1, total_msat, option),
(2, value, required),
+ (3, sender_intended_value, option),
(4, payment_data, option),
+ (5, total_value_received, option),
(6, cltv_expiry, required),
(8, keysend_preimage, option)
});
prev_hop: prev_hop.0.unwrap(),
timer_ticks: 0,
value,
+ sender_intended_value: sender_intended_value.unwrap_or(value),
+ total_value_received,
total_msat: total_msat.unwrap(),
onion_payload,
cltv_expiry,
/// In such cases the latest local transactions will be sent to the tx_broadcaster included in
/// this struct.
///
- /// (C-not exported) because we have no HashMap bindings
+ /// This is not exported to bindings users because we have no HashMap bindings
pub channel_monitors: HashMap<OutPoint, &'a mut ChannelMonitor<<SP::Target as SignerProvider>::Signer>>,
}
use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
use core::time::Duration;
use core::sync::atomic::Ordering;
+ use crate::events::{Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, ClosureReason};
use crate::ln::{PaymentPreimage, PaymentHash, PaymentSecret};
use crate::ln::channelmanager::{inbound_payment, PaymentId, PaymentSendFailure, InterceptId};
use crate::ln::functional_test_utils::*;
use crate::ln::msgs::ChannelMessageHandler;
use crate::routing::router::{PaymentParameters, RouteParameters, find_route};
use crate::util::errors::APIError;
- use crate::util::events::{Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, ClosureReason};
use crate::util::test_utils;
use crate::util::config::ChannelConfig;
use crate::chain::keysinterface::EntropySource;
use crate::chain::Listen;
use crate::chain::chainmonitor::{ChainMonitor, Persist};
use crate::chain::keysinterface::{EntropySource, KeysManager, InMemorySigner};
+ use crate::events::{Event, MessageSendEvent, MessageSendEventsProvider};
use crate::ln::channelmanager::{self, BestBlock, ChainParameters, ChannelManager, PaymentHash, PaymentPreimage, PaymentId};
use crate::ln::functional_test_utils::*;
use crate::ln::msgs::{ChannelMessageHandler, Init};
use crate::routing::router::{PaymentParameters, get_route};
use crate::util::test_utils;
use crate::util::config::UserConfig;
- use crate::util::events::{Event, MessageSendEvent, MessageSendEventsProvider};
use bitcoin::hashes::Hash;
use bitcoin::hashes::sha256::Hash as Sha256;
/// Tracks the set of features which a node implements, templated by the context in which it
/// appears.
///
-/// (C-not exported) as we map the concrete feature types below directly instead
+/// This is not exported to bindings users as we map the concrete feature types below directly instead
#[derive(Eq)]
pub struct Features<T: sealed::Context> {
/// Note that, for convenience, flags is LITTLE endian (despite being big-endian on the wire)
/// Create a Features given a set of flags, in little-endian. This is in reverse byte order from
/// most on-the-wire encodings.
- /// (C-not exported) as we don't support export across multiple T
+ ///
+ /// This is not exported to bindings users as we don't support export across multiple T
pub fn from_le_bytes(flags: Vec<u8>) -> Features<T> {
Features {
flags,
use crate::chain::{BestBlock, ChannelMonitorUpdateStatus, Confirm, Listen, Watch, keysinterface::EntropySource};
use crate::chain::channelmonitor::ChannelMonitor;
use crate::chain::transaction::OutPoint;
+use crate::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure, PaymentPurpose};
use crate::ln::{PaymentPreimage, PaymentHash, PaymentSecret};
use crate::ln::channelmanager::{ChainParameters, ChannelManager, ChannelManagerReadArgs, RAACommitmentOrder, PaymentSendFailure, PaymentId, MIN_CLTV_EXPIRY_DELTA};
use crate::routing::gossip::{P2PGossipSync, NetworkGraph, NetworkUpdate};
use crate::ln::features::InitFeatures;
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler,RoutingMessageHandler};
-use crate::util::events::ClosureReason;
use crate::util::enforcing_trait_impls::EnforcingSigner;
use crate::util::scid_utils;
use crate::util::test_utils;
use crate::util::test_utils::{panicking, TestChainMonitor, TestScorer, TestKeysInterface};
-use crate::util::events::{Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure, PaymentPurpose};
use crate::util::errors::APIError;
use crate::util::config::UserConfig;
use crate::util::ser::{ReadableArgs, Writeable};
($events: expr, $expected_failures: expr) => {{
for event in $events {
match event {
- $crate::util::events::Event::PendingHTLCsForwardable { .. } => { },
- $crate::util::events::Event::HTLCHandlingFailed { ref failed_next_destination, .. } => {
+ $crate::events::Event::PendingHTLCsForwardable { .. } => { },
+ $crate::events::Event::HTLCHandlingFailed { ref failed_next_destination, .. } => {
assert!($expected_failures.contains(&failed_next_destination))
},
_ => panic!("Unexpected destination"),
if fail_backwards {
expect_pending_htlcs_forwardable_and_htlc_handling_failed!(node_a,
- vec![crate::util::events::HTLCDestination::NextHopChannel{ node_id: Some(node_b.node.get_our_node_id()), channel_id: commitment_signed.channel_id }]);
+ vec![crate::events::HTLCDestination::NextHopChannel{ node_id: Some(node_b.node.get_our_node_id()), channel_id: commitment_signed.channel_id }]);
check_added_monitors!(node_a, 1);
let node_a_per_peer_state = node_a.node.per_peer_state.read().unwrap();
let events = $node.node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events[0] {
- $crate::util::events::Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id: _, via_user_channel_id: _ } => {
+ $crate::events::Event::PaymentClaimable { ref payment_hash, ref purpose, amount_msat, receiver_node_id, via_channel_id: _, via_user_channel_id: _ } => {
assert_eq!($expected_payment_hash, *payment_hash);
assert_eq!($expected_recv_value, amount_msat);
assert_eq!($expected_receiver_node_id, receiver_node_id.unwrap());
match purpose {
- $crate::util::events::PaymentPurpose::InvoicePayment { payment_preimage, payment_secret, .. } => {
+ $crate::events::PaymentPurpose::InvoicePayment { payment_preimage, payment_secret, .. } => {
assert_eq!(&$expected_payment_preimage, payment_preimage);
assert_eq!($expected_payment_secret, *payment_secret);
},
let events = $node.node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events[0] {
- $crate::util::events::Event::PaymentClaimed { ref payment_hash, amount_msat, .. } => {
+ $crate::events::Event::PaymentClaimed { ref payment_hash, amount_msat, .. } => {
assert_eq!($expected_payment_hash, *payment_hash);
assert_eq!($expected_recv_value, amount_msat);
},
assert_eq!(events.len(), 1);
}
let expected_payment_id = match events[0] {
- $crate::util::events::Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
+ $crate::events::Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
assert_eq!($expected_payment_preimage, *payment_preimage);
assert_eq!(expected_payment_hash, *payment_hash);
assert!(fee_paid_msat.is_some());
if $expect_paths {
for i in 1..events.len() {
match events[i] {
- $crate::util::events::Event::PaymentPathSuccessful { payment_id, payment_hash, .. } => {
+ $crate::events::Event::PaymentPathSuccessful { payment_id, payment_hash, .. } => {
assert_eq!(payment_id, expected_payment_id);
assert_eq!(payment_hash, Some(expected_payment_hash));
},
let events = $node.node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events[0] {
- $crate::util::events::Event::PaymentPathSuccessful { .. } => {},
+ $crate::events::Event::PaymentPathSuccessful { .. } => {},
_ => panic!("Unexpected event"),
}
}
let events = node.node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events[0] {
- crate::util::events::Event::ChannelReady{ ref counterparty_node_id, .. } => {
+ crate::events::Event::ChannelReady{ ref counterparty_node_id, .. } => {
assert_eq!(*expected_counterparty_node_id, *counterparty_node_id);
},
_ => panic!("Unexpected event"),
use crate::chain::channelmonitor::{CLTV_CLAIM_BUFFER, LATENCY_GRACE_PERIOD_BLOCKS, ANTI_REORG_DELAY};
use crate::chain::transaction::OutPoint;
use crate::chain::keysinterface::{ChannelSigner, EcdsaChannelSigner, EntropySource};
+use crate::events::{Event, MessageSendEvent, MessageSendEventsProvider, PathFailure, PaymentPurpose, ClosureReason, HTLCDestination};
use crate::ln::{PaymentPreimage, PaymentSecret, PaymentHash};
use crate::ln::channel::{commitment_tx_base_weight, COMMITMENT_TX_WEIGHT_PER_HTLC, CONCURRENT_INBOUND_HTLC_FEE_BUFFER, FEE_SPIKE_BUFFER_FEE_INCREASE_MULTIPLE, MIN_AFFORDABLE_HTLC_COUNT};
use crate::ln::channelmanager::{self, PaymentId, RAACommitmentOrder, PaymentSendFailure, BREAKDOWN_TIMEOUT, MIN_CLTV_EXPIRY_DELTA};
use crate::ln::msgs::{ChannelMessageHandler, RoutingMessageHandler, ErrorAction};
use crate::util::enforcing_trait_impls::EnforcingSigner;
use crate::util::test_utils;
-use crate::util::events::{Event, MessageSendEvent, MessageSendEventsProvider, PathFailure, PaymentPurpose, ClosureReason, HTLCDestination};
use crate::util::errors::APIError;
use crate::util::ser::{Writeable, ReadableArgs};
+use crate::util::string::UntrustedString;
use crate::util::config::UserConfig;
use bitcoin::hash_types::BlockHash;
assert_eq!(commitment_spend.input.len(), 2);
assert_eq!(commitment_spend.input[0].witness.last().unwrap().len(), OFFERED_HTLC_SCRIPT_WEIGHT);
assert_eq!(commitment_spend.input[1].witness.last().unwrap().len(), OFFERED_HTLC_SCRIPT_WEIGHT);
- assert_eq!(commitment_spend.lock_time.0, 0);
+ assert_eq!(commitment_spend.lock_time.0, nodes[1].best_block_info().1 + 1);
assert!(commitment_spend.output[0].script_pubkey.is_v0_p2wpkh()); // direct payment
// We don't bother to check that B can claim the HTLC output on its commitment tx here as
// we already checked the same situation with A.
check_spends!(b_txn[0], commitment_tx[0]);
assert_eq!(b_txn[0].input[0].witness.clone().last().unwrap().len(), OFFERED_HTLC_SCRIPT_WEIGHT);
assert!(b_txn[0].output[0].script_pubkey.is_v0_p2wpkh()); // direct payment
- assert_eq!(b_txn[0].lock_time.0, 0); // Success tx
+ assert_eq!(b_txn[0].lock_time.0, nodes[1].best_block_info().1 + 1); // Success tx
check_closed_broadcast!(nodes[1], true);
check_added_monitors!(nodes[1], 1);
if !revoked {
assert_eq!(timeout_tx[0].input[0].witness.last().unwrap().len(), ACCEPTED_HTLC_SCRIPT_WEIGHT);
} else {
- assert_eq!(timeout_tx[0].lock_time.0, 0);
+ assert_eq!(timeout_tx[0].lock_time.0, 12);
}
// We fail non-dust-HTLC 2 by broadcast of local timeout/revocation-claim tx
mine_transaction(&nodes[0], &timeout_tx[0]);
}
}
+#[test]
+fn test_onion_value_mpp_set_calculation() {
+ // Test that we use the onion value `amt_to_forward` when
+ // calculating whether we've reached the `total_msat` of an MPP
+ // by having a routing node forward more than `amt_to_forward`
+ // and checking that the receiving node doesn't generate
+ // a PaymentClaimable event too early
+ let node_count = 4;
+ let chanmon_cfgs = create_chanmon_cfgs(node_count);
+ let node_cfgs = create_node_cfgs(node_count, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(node_count, &node_cfgs, &vec![None; node_count]);
+ let mut nodes = create_network(node_count, &node_cfgs, &node_chanmgrs);
+
+ let chan_1_id = create_announced_chan_between_nodes(&nodes, 0, 1).0.contents.short_channel_id;
+ let chan_2_id = create_announced_chan_between_nodes(&nodes, 0, 2).0.contents.short_channel_id;
+ let chan_3_id = create_announced_chan_between_nodes(&nodes, 1, 3).0.contents.short_channel_id;
+ let chan_4_id = create_announced_chan_between_nodes(&nodes, 2, 3).0.contents.short_channel_id;
+
+ let total_msat = 100_000;
+ let expected_paths: &[&[&Node]] = &[&[&nodes[1], &nodes[3]], &[&nodes[2], &nodes[3]]];
+ let (mut route, our_payment_hash, our_payment_preimage, our_payment_secret) = get_route_and_payment_hash!(&nodes[0], nodes[3], total_msat);
+ let sample_path = route.paths.pop().unwrap();
+
+ let mut path_1 = sample_path.clone();
+ path_1[0].pubkey = nodes[1].node.get_our_node_id();
+ path_1[0].short_channel_id = chan_1_id;
+ path_1[1].pubkey = nodes[3].node.get_our_node_id();
+ path_1[1].short_channel_id = chan_3_id;
+ path_1[1].fee_msat = 100_000;
+ route.paths.push(path_1);
+
+ let mut path_2 = sample_path.clone();
+ path_2[0].pubkey = nodes[2].node.get_our_node_id();
+ path_2[0].short_channel_id = chan_2_id;
+ path_2[1].pubkey = nodes[3].node.get_our_node_id();
+ path_2[1].short_channel_id = chan_4_id;
+ path_2[1].fee_msat = 1_000;
+ route.paths.push(path_2);
+
+ // Send payment
+ let payment_id = PaymentId(nodes[0].keys_manager.backing.get_secure_random_bytes());
+ let onion_session_privs = nodes[0].node.test_add_new_pending_payment(our_payment_hash, Some(our_payment_secret), payment_id, &route).unwrap();
+ nodes[0].node.test_send_payment_internal(&route, our_payment_hash, &Some(our_payment_secret), None, payment_id, Some(total_msat), onion_session_privs).unwrap();
+ check_added_monitors!(nodes[0], expected_paths.len());
+
+ let mut events = nodes[0].node.get_and_clear_pending_msg_events();
+ assert_eq!(events.len(), expected_paths.len());
+
+ // First path
+ let ev = remove_first_msg_event_to_node(&expected_paths[0][0].node.get_our_node_id(), &mut events);
+ let mut payment_event = SendEvent::from_event(ev);
+ let mut prev_node = &nodes[0];
+
+ for (idx, &node) in expected_paths[0].iter().enumerate() {
+ assert_eq!(node.node.get_our_node_id(), payment_event.node_id);
+
+ if idx == 0 { // routing node
+ let session_priv = [3; 32];
+ let height = nodes[0].best_block_info().1;
+ let session_priv = SecretKey::from_slice(&session_priv).unwrap();
+ let mut onion_keys = onion_utils::construct_onion_keys(&Secp256k1::new(), &route.paths[0], &session_priv).unwrap();
+ let (mut onion_payloads, _, _) = onion_utils::build_onion_payloads(&route.paths[0], 100_000, &Some(our_payment_secret), height + 1, &None).unwrap();
+ // Edit amt_to_forward to simulate the sender having set
+ // the final amount and the routing node taking less fee
+ onion_payloads[1].amt_to_forward = 99_000;
+ let new_onion_packet = onion_utils::construct_onion_packet(onion_payloads, onion_keys, [0; 32], &our_payment_hash);
+ payment_event.msgs[0].onion_routing_packet = new_onion_packet;
+ }
+
+ node.node.handle_update_add_htlc(&prev_node.node.get_our_node_id(), &payment_event.msgs[0]);
+ check_added_monitors!(node, 0);
+ commitment_signed_dance!(node, prev_node, payment_event.commitment_msg, false);
+ expect_pending_htlcs_forwardable!(node);
+
+ if idx == 0 {
+ let mut events_2 = node.node.get_and_clear_pending_msg_events();
+ assert_eq!(events_2.len(), 1);
+ check_added_monitors!(node, 1);
+ payment_event = SendEvent::from_event(events_2.remove(0));
+ assert_eq!(payment_event.msgs.len(), 1);
+ } else {
+ let events_2 = node.node.get_and_clear_pending_events();
+ assert!(events_2.is_empty());
+ }
+
+ prev_node = node;
+ }
+
+ // Second path
+ let ev = remove_first_msg_event_to_node(&expected_paths[1][0].node.get_our_node_id(), &mut events);
+ pass_along_path(&nodes[0], expected_paths[1], 101_000, our_payment_hash.clone(), Some(our_payment_secret), ev, true, None);
+
+ claim_payment_along_route(&nodes[0], expected_paths, false, our_payment_preimage);
+}
+
+fn do_test_overshoot_mpp(msat_amounts: &[u64], total_msat: u64) {
+
+ let routing_node_count = msat_amounts.len();
+ let node_count = routing_node_count + 2;
+
+ let chanmon_cfgs = create_chanmon_cfgs(node_count);
+ let node_cfgs = create_node_cfgs(node_count, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(node_count, &node_cfgs, &vec![None; node_count]);
+ let nodes = create_network(node_count, &node_cfgs, &node_chanmgrs);
+
+ let src_idx = 0;
+ let dst_idx = 1;
+
+ // Create channels for each amount
+ let mut expected_paths = Vec::with_capacity(routing_node_count);
+ let mut src_chan_ids = Vec::with_capacity(routing_node_count);
+ let mut dst_chan_ids = Vec::with_capacity(routing_node_count);
+ for i in 0..routing_node_count {
+ let routing_node = 2 + i;
+ let src_chan_id = create_announced_chan_between_nodes(&nodes, src_idx, routing_node).0.contents.short_channel_id;
+ src_chan_ids.push(src_chan_id);
+ let dst_chan_id = create_announced_chan_between_nodes(&nodes, routing_node, dst_idx).0.contents.short_channel_id;
+ dst_chan_ids.push(dst_chan_id);
+ let path = vec![&nodes[routing_node], &nodes[dst_idx]];
+ expected_paths.push(path);
+ }
+ let expected_paths: Vec<&[&Node]> = expected_paths.iter().map(|route| route.as_slice()).collect();
+
+ // Create a route for each amount
+ let example_amount = 100000;
+ let (mut route, our_payment_hash, our_payment_preimage, our_payment_secret) = get_route_and_payment_hash!(&nodes[src_idx], nodes[dst_idx], example_amount);
+ let sample_path = route.paths.pop().unwrap();
+ for i in 0..routing_node_count {
+ let routing_node = 2 + i;
+ let mut path = sample_path.clone();
+ path[0].pubkey = nodes[routing_node].node.get_our_node_id();
+ path[0].short_channel_id = src_chan_ids[i];
+ path[1].pubkey = nodes[dst_idx].node.get_our_node_id();
+ path[1].short_channel_id = dst_chan_ids[i];
+ path[1].fee_msat = msat_amounts[i];
+ route.paths.push(path);
+ }
+
+ // Send payment with manually set total_msat
+ let payment_id = PaymentId(nodes[src_idx].keys_manager.backing.get_secure_random_bytes());
+ let onion_session_privs = nodes[src_idx].node.test_add_new_pending_payment(our_payment_hash, Some(our_payment_secret), payment_id, &route).unwrap();
+ nodes[src_idx].node.test_send_payment_internal(&route, our_payment_hash, &Some(our_payment_secret), None, payment_id, Some(total_msat), onion_session_privs).unwrap();
+ check_added_monitors!(nodes[src_idx], expected_paths.len());
+
+ let mut events = nodes[src_idx].node.get_and_clear_pending_msg_events();
+ assert_eq!(events.len(), expected_paths.len());
+ let mut amount_received = 0;
+ for (path_idx, expected_path) in expected_paths.iter().enumerate() {
+ let ev = remove_first_msg_event_to_node(&expected_path[0].node.get_our_node_id(), &mut events);
+
+ let current_path_amount = msat_amounts[path_idx];
+ amount_received += current_path_amount;
+ let became_claimable_now = amount_received >= total_msat && amount_received - current_path_amount < total_msat;
+ pass_along_path(&nodes[src_idx], expected_path, amount_received, our_payment_hash.clone(), Some(our_payment_secret), ev, became_claimable_now, None);
+ }
+
+ claim_payment_along_route(&nodes[src_idx], &expected_paths, false, our_payment_preimage);
+}
+
+#[test]
+fn test_overshoot_mpp() {
+ do_test_overshoot_mpp(&[100_000, 101_000], 200_000);
+ do_test_overshoot_mpp(&[100_000, 10_000, 100_000], 200_000);
+}
+
#[test]
fn test_simple_mpp() {
// Simple test of sending a multi-path payment.
let channel_id = crate::chain::transaction::OutPoint { txid: funding_created_msg.funding_txid, index: funding_created_msg.funding_output_index }.to_channel_id();
nodes[0].node.handle_error(&nodes[1].node.get_our_node_id(), &msgs::ErrorMessage { channel_id, data: "Hi".to_owned() });
assert!(nodes[0].chain_monitor.added_monitors.lock().unwrap().is_empty());
- check_closed_event!(nodes[0], 2, ClosureReason::CounterpartyForceClosed { peer_msg: "Hi".to_string() }, true);
+ check_closed_event!(nodes[0], 2, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString("Hi".to_string()) }, true);
}
#[test]
nodes[0].node.handle_error(&nodes[1].node.get_our_node_id(), &msgs::ErrorMessage { channel_id: chan_2.2, data: "ERR".to_owned() });
check_added_monitors!(nodes[0], 1);
check_closed_broadcast!(nodes[0], false);
- check_closed_event!(nodes[0], 1, ClosureReason::CounterpartyForceClosed { peer_msg: "ERR".to_string() });
+ check_closed_event!(nodes[0], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString("ERR".to_string()) });
assert_eq!(nodes[0].tx_broadcaster.txn_broadcasted.lock().unwrap().split_off(0).len(), 1);
assert_eq!(nodes[0].node.list_usable_channels().len(), 2);
assert!(nodes[0].node.list_usable_channels()[0].channel_id == chan_1.2 || nodes[0].node.list_usable_channels()[1].channel_id == chan_1.2);
let _chan_4 = create_announced_chan_between_nodes_with_value(&nodes, 0, 1, 100000, 10001);
nodes[0].node.handle_error(&nodes[1].node.get_our_node_id(), &msgs::ErrorMessage { channel_id: [0; 32], data: "ERR".to_owned() });
check_added_monitors!(nodes[0], 2);
- check_closed_event!(nodes[0], 2, ClosureReason::CounterpartyForceClosed { peer_msg: "ERR".to_string() });
+ check_closed_event!(nodes[0], 2, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString("ERR".to_string()) });
let events = nodes[0].node.get_and_clear_pending_msg_events();
assert_eq!(events.len(), 2);
match events[0] {
pub use self::peer_channel_encryptor::LN_MAX_MSG_LEN;
/// payment_hash type, use to cross-lock hop
-/// (C-not exported) as we just use [u8; 32] directly
+///
+/// This is not exported to bindings users as we just use [u8; 32] directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct PaymentHash(pub [u8; 32]);
/// payment_preimage type, use to route payment between hop
-/// (C-not exported) as we just use [u8; 32] directly
+///
+/// This is not exported to bindings users as we just use [u8; 32] directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct PaymentPreimage(pub [u8; 32]);
/// payment_secret type, use to authenticate sender to the receiver and tie MPP HTLCs together
-/// (C-not exported) as we just use [u8; 32] directly
+///
+/// This is not exported to bindings users as we just use [u8; 32] directly
#[derive(Hash, Copy, Clone, PartialEq, Eq, Debug)]
pub struct PaymentSecret(pub [u8; 32]);
use crate::chain::channelmonitor::{ANTI_REORG_DELAY, Balance};
use crate::chain::transaction::OutPoint;
use crate::chain::chaininterface::LowerBoundedFeeEstimator;
+#[cfg(anchors)]
+use crate::events::bump_transaction::BumpTransactionEvent;
+use crate::events::{Event, MessageSendEvent, MessageSendEventsProvider, ClosureReason, HTLCDestination};
use crate::ln::channel;
#[cfg(anchors)]
use crate::ln::chan_utils;
#[cfg(anchors)]
use crate::util::crypto::sign;
#[cfg(anchors)]
-use crate::util::events::BumpTransactionEvent;
-use crate::util::events::{Event, MessageSendEvent, MessageSendEventsProvider, ClosureReason, HTLCDestination};
-#[cfg(anchors)]
use crate::util::ser::Writeable;
#[cfg(anchors)]
use crate::util::test_utils;
let mut htlc_txs = Vec::with_capacity(2);
for event in holder_events {
match event {
- Event::BumpTransaction(BumpTransactionEvent::HTLCResolution { htlc_descriptors, .. }) => {
+ Event::BumpTransaction(BumpTransactionEvent::HTLCResolution { htlc_descriptors, tx_lock_time, .. }) => {
assert_eq!(htlc_descriptors.len(), 1);
let htlc_descriptor = &htlc_descriptors[0];
let signer = nodes[0].keys_manager.derive_channel_keys(
let per_commitment_point = signer.get_per_commitment_point(htlc_descriptor.per_commitment_number, &secp);
let mut htlc_tx = Transaction {
version: 2,
- lock_time: if htlc_descriptor.htlc.offered {
- PackedLockTime(htlc_descriptor.htlc.cltv_expiry)
- } else {
- PackedLockTime::ZERO
- },
+ lock_time: tx_lock_time,
input: vec![
htlc_descriptor.unsigned_tx_input(), // HTLC input
TxIn { ..Default::default() } // Fee input
};
let mut descriptors = Vec::with_capacity(4);
for event in events {
- if let Event::BumpTransaction(BumpTransactionEvent::HTLCResolution { mut htlc_descriptors, .. }) = event {
+ if let Event::BumpTransaction(BumpTransactionEvent::HTLCResolution { mut htlc_descriptors, tx_lock_time, .. }) = event {
assert_eq!(htlc_descriptors.len(), 2);
for htlc_descriptor in &htlc_descriptors {
assert!(!htlc_descriptor.htlc.offered);
htlc_tx.output.push(htlc_descriptor.tx_output(&per_commitment_point, &secp));
}
descriptors.append(&mut htlc_descriptors);
+ htlc_tx.lock_time = tx_lock_time;
} else {
panic!("Unexpected event");
}
use crate::io::{self, Read};
use crate::io_extras::read_to_end;
-use crate::util::events::{MessageSendEventsProvider, OnionMessageProvider};
+use crate::events::{MessageSendEventsProvider, OnionMessageProvider};
use crate::util::logger;
use crate::util::ser::{LengthReadable, Readable, ReadableArgs, Writeable, Writer, FixedLengthReader, HighZeroBytesDroppedBigSize, Hostname};
/// [`OptionalField`] simply gets `Present` if there are enough bytes to read into it), we have a
/// separate enum type for them.
///
-/// (C-not exported) due to a free generic in `T`
+/// This is not exported to bindings users due to a free generic in `T`
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum OptionalField<T> {
/// Optional field is included in message
use crate::chain::channelmonitor::{CLTV_CLAIM_BUFFER, LATENCY_GRACE_PERIOD_BLOCKS};
use crate::chain::keysinterface::{EntropySource, NodeSigner, Recipient};
+use crate::events::{Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure};
use crate::ln::{PaymentHash, PaymentSecret};
use crate::ln::channel::EXPIRE_PREV_CONFIG_TICKS;
use crate::ln::channelmanager::{HTLCForwardInfo, FailureCode, CLTV_FAR_FAR_AWAY, MIN_CLTV_EXPIRY_DELTA, PendingAddHTLCInfo, PendingHTLCInfo, PendingHTLCRouting, PaymentId};
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler, ChannelUpdate};
use crate::ln::wire::Encode;
-use crate::util::events::{Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure};
use crate::util::ser::{Writeable, Writer};
use crate::util::test_utils;
use crate::util::config::{UserConfig, ChannelConfig};
for f in pending_forwards.iter_mut() {
match f {
&mut HTLCForwardInfo::AddHTLC(PendingAddHTLCInfo { ref mut forward_info, .. }) =>
- forward_info.outgoing_cltv_value += 1,
+ forward_info.outgoing_cltv_value -= 1,
_ => {},
}
}
}, true, Some(23), None, None);
}
+#[test]
+fn test_overshoot_final_cltv() {
+ let chanmon_cfgs = create_chanmon_cfgs(3);
+ let node_cfgs = create_node_cfgs(3, &chanmon_cfgs);
+ let node_chanmgrs = create_node_chanmgrs(3, &node_cfgs, &[None; 3]);
+ let mut nodes = create_network(3, &node_cfgs, &node_chanmgrs);
+ create_announced_chan_between_nodes(&nodes, 0, 1);
+ create_announced_chan_between_nodes(&nodes, 1, 2);
+ let (route, payment_hash, payment_preimage, payment_secret) = get_route_and_payment_hash!(nodes[0], nodes[2], 40000);
+
+ let payment_id = PaymentId(nodes[0].keys_manager.backing.get_secure_random_bytes());
+ nodes[0].node.send_payment(&route, payment_hash, &Some(payment_secret), payment_id).unwrap();
+
+ check_added_monitors!(nodes[0], 1);
+ let update_0 = get_htlc_update_msgs!(nodes[0], nodes[1].node.get_our_node_id());
+ let mut update_add_0 = update_0.update_add_htlcs[0].clone();
+ nodes[1].node.handle_update_add_htlc(&nodes[0].node.get_our_node_id(), &update_add_0);
+ commitment_signed_dance!(nodes[1], nodes[0], &update_0.commitment_signed, false, true);
+
+ assert!(nodes[1].node.get_and_clear_pending_msg_events().is_empty());
+ for (_, pending_forwards) in nodes[1].node.forward_htlcs.lock().unwrap().iter_mut() {
+ for f in pending_forwards.iter_mut() {
+ match f {
+ &mut HTLCForwardInfo::AddHTLC(PendingAddHTLCInfo { ref mut forward_info, .. }) =>
+ forward_info.outgoing_cltv_value += 1,
+ _ => {},
+ }
+ }
+ }
+ expect_pending_htlcs_forwardable!(nodes[1]);
+
+ check_added_monitors!(&nodes[1], 1);
+ let update_1 = get_htlc_update_msgs!(nodes[1], nodes[2].node.get_our_node_id());
+ let mut update_add_1 = update_1.update_add_htlcs[0].clone();
+ nodes[2].node.handle_update_add_htlc(&nodes[1].node.get_our_node_id(), &update_add_1);
+ commitment_signed_dance!(nodes[2], nodes[1], update_1.commitment_signed, false, true);
+
+ expect_pending_htlcs_forwardable!(nodes[2]);
+ expect_payment_claimable!(nodes[2], payment_hash, payment_secret, 40_000);
+ claim_payment(&nodes[0], &[&nodes[1], &nodes[2]], payment_preimage);
+}
+
fn do_test_onion_failure_stale_channel_update(announced_channel: bool) {
// Create a network of three nodes and two channels connecting them. We'll be updating the
// HTLC relay policy of the second channel, causing forwarding failures at the first hop.
&mut HTLCForwardInfo::AddHTLC(PendingAddHTLCInfo {
forward_info: PendingHTLCInfo { ref mut outgoing_cltv_value, .. }, ..
}) => {
- *outgoing_cltv_value += 1;
+ *outgoing_cltv_value -= 1;
},
_ => panic!("Unexpected forward"),
}
commitment_signed_dance!(nodes[0], nodes[1], update_1.commitment_signed, false);
// Ensure the payment fails with the expected error.
- let expected_cltv: u32 = 82;
+ let expected_cltv: u32 = 80;
let error_data = expected_cltv.to_be_bytes().to_vec();
let mut fail_conditions = PaymentFailedConditions::new()
.blamed_scid(phantom_scid)
use bitcoin::secp256k1::{self, Secp256k1, SecretKey};
use crate::chain::keysinterface::{EntropySource, NodeSigner, Recipient};
+use crate::events;
use crate::ln::{PaymentHash, PaymentPreimage, PaymentSecret};
use crate::ln::channelmanager::{ChannelDetails, HTLCSource, IDEMPOTENCY_TIMEOUT_TICKS, PaymentId};
use crate::ln::onion_utils::HTLCFailReason;
use crate::routing::router::{InFlightHtlcs, PaymentParameters, Route, RouteHop, RouteParameters, RoutePath, Router};
use crate::util::errors::APIError;
-use crate::util::events;
use crate::util::logger::Logger;
use crate::util::time::Time;
#[cfg(all(not(feature = "no-std"), test))]
/// may be surfaced later via [`Event::PaymentPathFailed`] and [`Event::PaymentFailed`].
///
/// [`ChannelManager::send_payment_with_retry`]: crate::ln::channelmanager::ChannelManager::send_payment_with_retry
-/// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
-/// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
+/// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
#[derive(Clone, Debug)]
pub enum RetryableSendFailure {
/// The provided [`PaymentParameters::expiry_time`] indicated that the payment has expired. Note
/// yet completed (i.e. generated an [`Event::PaymentSent`] or [`Event::PaymentFailed`]).
///
/// [`PaymentId`]: crate::ln::channelmanager::PaymentId
- /// [`Event::PaymentSent`]: crate::util::events::Event::PaymentSent
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentSent`]: crate::events::Event::PaymentSent
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
DuplicatePayment,
}
/// Because the payment failed outright, no payment tracking is done and no
/// [`Event::PaymentPathFailed`] or [`Event::PaymentFailed`] events will be generated.
///
- /// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
ParameterError(APIError),
/// A parameter in a single path which was passed to send_payment was invalid, preventing us
/// from attempting to send the payment at all.
/// The results here are ordered the same as the paths in the route object which was passed to
/// send_payment.
///
- /// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
PathParameterError(Vec<Result<(), APIError>>),
/// All paths which were attempted failed to send, with no channel state change taking place.
/// You can freely resend the payment in full (though you probably want to do so over different
/// Because the payment failed outright, no payment tracking is done and no
/// [`Event::PaymentPathFailed`] or [`Event::PaymentFailed`] events will be generated.
///
- /// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
AllFailedResendSafe(Vec<APIError>),
/// Indicates that a payment for the provided [`PaymentId`] is already in-flight and has not
/// yet completed (i.e. generated an [`Event::PaymentSent`] or [`Event::PaymentFailed`]).
///
/// [`PaymentId`]: crate::ln::channelmanager::PaymentId
- /// [`Event::PaymentSent`]: crate::util::events::Event::PaymentSent
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentSent`]: crate::events::Event::PaymentSent
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
DuplicatePayment,
/// Some paths that were attempted failed to send, though some paths may have succeeded. At least
/// some paths have irrevocably committed to the HTLC.
/// Errors immediately on [`RetryableSendFailure`] error conditions. Otherwise, further errors may
/// be surfaced asynchronously via [`Event::PaymentPathFailed`] and [`Event::PaymentFailed`].
///
- /// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
- /// [`Event::PaymentFailed`]: crate::util::events::Event::PaymentFailed
+ /// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
+ /// [`Event::PaymentFailed`]: crate::events::Event::PaymentFailed
fn send_payment_internal<R: Deref, NS: Deref, ES: Deref, IH, SP, L: Deref>(
&self, payment_id: PaymentId, payment_hash: PaymentHash, payment_secret: &Option<PaymentSecret>,
keysend_preimage: Option<PaymentPreimage>, retry_strategy: Retry, route_params: RouteParameters,
return Err(PaymentSendFailure::PathParameterError(path_errs));
}
if let Some(amt_msat) = recv_value_msat {
- debug_assert!(amt_msat >= total_value);
total_value = amt_msat;
}
use bitcoin::network::constants::Network;
use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey};
+ use crate::events::{Event, PathFailure};
use crate::ln::PaymentHash;
use crate::ln::channelmanager::PaymentId;
use crate::ln::features::{ChannelFeatures, NodeFeatures};
use crate::routing::router::{InFlightHtlcs, PaymentParameters, Route, RouteHop, RouteParameters};
use crate::sync::{Arc, Mutex};
use crate::util::errors::APIError;
- use crate::util::events::{Event, PathFailure};
use crate::util::test_utils;
#[test]
use crate::chain::channelmonitor::{ANTI_REORG_DELAY, LATENCY_GRACE_PERIOD_BLOCKS};
use crate::chain::keysinterface::EntropySource;
use crate::chain::transaction::OutPoint;
+use crate::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure};
use crate::ln::channel::EXPIRE_PREV_CONFIG_TICKS;
use crate::ln::channelmanager::{BREAKDOWN_TIMEOUT, ChannelManager, MPP_TIMEOUT_TICKS, MIN_CLTV_EXPIRY_DELTA, PaymentId, PaymentSendFailure, IDEMPOTENCY_TIMEOUT_TICKS, RecentPaymentDetails};
use crate::ln::features::InvoiceFeatures;
use crate::routing::gossip::{EffectiveCapacity, RoutingFees};
use crate::routing::router::{get_route, PaymentParameters, Route, RouteHint, RouteHintHop, RouteHop, RouteParameters};
use crate::routing::scoring::ChannelUsage;
-use crate::util::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider, PathFailure};
use crate::util::test_utils;
use crate::util::errors::APIError;
use crate::util::ser::Writeable;
+use crate::util::string::UntrustedString;
use bitcoin::{Block, BlockHeader, TxMerkleNode};
use bitcoin::hashes::Hash;
MessageSendEvent::HandleError { node_id, action: msgs::ErrorAction::SendErrorMessage { ref msg } } => {
assert_eq!(node_id, nodes[1].node.get_our_node_id());
nodes[1].node.handle_error(&nodes[0].node.get_our_node_id(), msg);
- check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id()) });
+ check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id())) });
check_added_monitors!(nodes[1], 1);
assert_eq!(nodes[1].tx_broadcaster.txn_broadcasted.lock().unwrap().split_off(0).len(), 1);
},
MessageSendEvent::HandleError { node_id, action: msgs::ErrorAction::SendErrorMessage { ref msg } } => {
assert_eq!(node_id, nodes[1].node.get_our_node_id());
nodes[1].node.handle_error(&nodes[0].node.get_our_node_id(), msg);
- check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id()) });
+ check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id())) });
check_added_monitors!(nodes[1], 1);
bs_commitment_tx = nodes[1].tx_broadcaster.txn_broadcasted.lock().unwrap().split_off(0);
},
let mut events = nodes[0].node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events.drain(..).next().unwrap() {
- crate::util::events::Event::ProbeSuccessful { payment_id: ev_pid, payment_hash: ev_ph, .. } => {
+ crate::events::Event::ProbeSuccessful { payment_id: ev_pid, payment_hash: ev_ph, .. } => {
assert_eq!(payment_id, ev_pid);
assert_eq!(payment_hash, ev_ph);
},
let mut events = nodes[0].node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
match events.drain(..).next().unwrap() {
- crate::util::events::Event::ProbeFailed { payment_id: ev_pid, payment_hash: ev_ph, .. } => {
+ crate::events::Event::ProbeFailed { payment_id: ev_pid, payment_hash: ev_ph, .. } => {
assert_eq!(payment_id, ev_pid);
assert_eq!(payment_hash, ev_ph);
},
let events = nodes[1].node.get_and_clear_pending_events();
assert_eq!(events.len(), 1);
let (intercept_id, expected_outbound_amount_msat) = match events[0] {
- crate::util::events::Event::HTLCIntercepted {
+ crate::events::Event::HTLCIntercepted {
intercept_id, expected_outbound_amount_msat, payment_hash: pmt_hash, inbound_amount_msat, requested_next_hop_scid: short_channel_id
} => {
assert_eq!(pmt_hash, payment_hash);
use bitcoin::secp256k1::{self, Secp256k1, SecretKey, PublicKey};
use crate::chain::keysinterface::{KeysManager, NodeSigner, Recipient};
+use crate::events::{MessageSendEvent, MessageSendEventsProvider, OnionMessageProvider};
use crate::ln::features::{InitFeatures, NodeFeatures};
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler, LightningError, NetAddress, OnionMessageHandler, RoutingMessageHandler};
use crate::onion_message::{CustomOnionMessageContents, CustomOnionMessageHandler, SimpleArcOnionMessenger, SimpleRefOnionMessenger};
use crate::routing::gossip::{NetworkGraph, P2PGossipSync, NodeId};
use crate::util::atomic_counter::AtomicCounter;
-use crate::util::events::{MessageSendEvent, MessageSendEventsProvider, OnionMessageProvider};
use crate::util::logger::Logger;
use crate::prelude::*;
/// SimpleRefPeerManager is the more appropriate type. Defining these type aliases prevents
/// issues such as overly long function definitions.
///
-/// (C-not exported) as `Arc`s don't make sense in bindings.
+/// This is not exported to bindings users as `Arc`s don't make sense in bindings.
pub type SimpleArcPeerManager<SD, M, T, F, C, L> = PeerManager<SD, Arc<SimpleArcChannelManager<M, T, F, L>>, Arc<P2PGossipSync<Arc<NetworkGraph<Arc<L>>>, Arc<C>, Arc<L>>>, Arc<SimpleArcOnionMessenger<L>>, Arc<L>, IgnoringMessageHandler, Arc<KeysManager>>;
/// SimpleRefPeerManager is a type alias for a PeerManager reference, and is the reference
/// But if this is not necessary, using a reference is more efficient. Defining these type aliases
/// helps with issues such as long function definitions.
///
-/// (C-not exported) as general type aliases don't make sense in bindings.
+/// This is not exported to bindings users as general type aliases don't make sense in bindings.
pub type SimpleRefPeerManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'h, 'i, 'j, 'k, 'l, 'm, SD, M, T, F, C, L> = PeerManager<SD, SimpleRefChannelManager<'a, 'b, 'c, 'd, 'e, 'f, 'g, 'm, M, T, F, L>, &'f P2PGossipSync<&'g NetworkGraph<&'f L>, &'h C, &'f L>, &'i SimpleRefOnionMessenger<'j, 'k, L>, &'f L, IgnoringMessageHandler, &'c KeysManager>;
/// A PeerManager manages a set of peers, described by their [`SocketDescriptor`] and marshalls
/// timestamp, however if it is not available a persistent counter that increases once per
/// minute should suffice.
///
- /// (C-not exported) as we can't export a PeerManager with a dummy route handler
+ /// This is not exported to bindings users as we can't export a PeerManager with a dummy route handler
pub fn new_channel_only(channel_message_handler: CM, onion_message_handler: OM, current_time: u32, ephemeral_random_data: &[u8; 32], logger: L, node_signer: NS) -> Self {
Self::new(MessageHandler {
chan_handler: channel_message_handler,
/// `ephemeral_random_data` is used to derive per-connection ephemeral keys and must be
/// cryptographically secure random bytes.
///
- /// (C-not exported) as we can't export a PeerManager with a dummy channel handler
+ /// This is not exported to bindings users as we can't export a PeerManager with a dummy channel handler
pub fn new_routing_only(routing_message_handler: RM, current_time: u32, ephemeral_random_data: &[u8; 32], logger: L, node_signer: NS) -> Self {
Self::new(MessageHandler {
chan_handler: ErroringMessageHandler::new(),
#[cfg(test)]
mod tests {
use crate::chain::keysinterface::{NodeSigner, Recipient};
+ use crate::events;
use crate::ln::peer_channel_encryptor::PeerChannelEncryptor;
use crate::ln::peer_handler::{PeerManager, MessageHandler, SocketDescriptor, IgnoringMessageHandler, filter_addresses};
use crate::ln::{msgs, wire};
use crate::ln::msgs::NetAddress;
- use crate::util::events;
use crate::util::test_utils;
use bitcoin::secp256k1::SecretKey;
if peers[0].read_event(&mut fd_a, &b_data).is_err() { break; }
cfgs[0].chan_handler.pending_events.lock().unwrap()
- .push(crate::util::events::MessageSendEvent::SendShutdown {
+ .push(crate::events::MessageSendEvent::SendShutdown {
node_id: peers[1].node_signer.get_node_id(Recipient::Node).unwrap(),
msg: msgs::Shutdown {
channel_id: [0; 32],
},
});
cfgs[1].chan_handler.pending_events.lock().unwrap()
- .push(crate::util::events::MessageSendEvent::SendShutdown {
+ .push(crate::events::MessageSendEvent::SendShutdown {
node_id: peers[0].node_signer.get_node_id(Recipient::Node).unwrap(),
msg: msgs::Shutdown {
channel_id: [0; 32],
use crate::chain::ChannelMonitorUpdateStatus;
use crate::chain::keysinterface::NodeSigner;
+use crate::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider};
use crate::ln::channelmanager::{ChannelManager, MIN_CLTV_EXPIRY_DELTA, PaymentId};
use crate::routing::gossip::RoutingFees;
use crate::routing::router::{PaymentParameters, RouteHint, RouteHintHop};
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler, RoutingMessageHandler, ChannelUpdate, ErrorAction};
use crate::ln::wire::Encode;
-use crate::util::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider};
use crate::util::config::UserConfig;
use crate::util::ser::Writeable;
use crate::util::test_utils;
use crate::chain::channelmonitor::ChannelMonitor;
use crate::chain::keysinterface::EntropySource;
use crate::chain::transaction::OutPoint;
+use crate::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider};
use crate::ln::channelmanager::{ChannelManager, ChannelManagerReadArgs, PaymentId};
use crate::ln::msgs;
use crate::ln::msgs::{ChannelMessageHandler, RoutingMessageHandler, ErrorAction};
use crate::util::enforcing_trait_impls::EnforcingSigner;
use crate::util::test_utils;
use crate::util::errors::APIError;
-use crate::util::events::{ClosureReason, Event, HTLCDestination, MessageSendEvent, MessageSendEventsProvider};
use crate::util::ser::{Writeable, ReadableArgs};
use crate::util::config::UserConfig;
+use crate::util::string::UntrustedString;
use bitcoin::hash_types::BlockHash;
nodes[1].node.handle_error(&nodes[0].node.get_our_node_id(), &err_msgs_0[0]);
assert!(nodes[1].node.list_usable_channels().is_empty());
check_added_monitors!(nodes[1], 1);
- check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id()) });
+ check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id())) });
check_closed_broadcast!(nodes[1], false);
}
use crate::chain::channelmonitor::ANTI_REORG_DELAY;
use crate::chain::transaction::OutPoint;
use crate::chain::Confirm;
+use crate::events::{Event, MessageSendEventsProvider, ClosureReason, HTLCDestination};
use crate::ln::channelmanager::ChannelManager;
use crate::ln::msgs::{ChannelMessageHandler, Init};
-use crate::util::events::{Event, MessageSendEventsProvider, ClosureReason, HTLCDestination};
use crate::util::test_utils;
use crate::util::ser::Writeable;
+use crate::util::string::UntrustedString;
use bitcoin::blockdata::block::{Block, BlockHeader};
use bitcoin::blockdata::script::Builder;
nodes[0].node.test_process_background_events(); // Required to free the pending background monitor update
check_added_monitors!(nodes[0], 1);
let expected_err = "Funding transaction was un-confirmed. Locked at 6 confs, now have 0 confs.";
- check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: "Channel closed because of an exception: ".to_owned() + expected_err });
+ check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(format!("Channel closed because of an exception: {}", expected_err)) });
check_closed_event!(nodes[0], 1, ClosureReason::ProcessingError { err: expected_err.to_owned() });
assert_eq!(nodes[0].tx_broadcaster.txn_broadcasted.lock().unwrap().len(), 1);
nodes[0].tx_broadcaster.txn_broadcasted.lock().unwrap().clear();
use crate::chain::keysinterface::{EntropySource, SignerProvider};
use crate::chain::transaction::OutPoint;
+use crate::events::{Event, MessageSendEvent, MessageSendEventsProvider, ClosureReason};
use crate::ln::channelmanager::{self, PaymentSendFailure, PaymentId};
use crate::routing::router::{PaymentParameters, get_route};
use crate::ln::msgs;
use crate::ln::script::ShutdownScript;
use crate::util::test_utils;
use crate::util::test_utils::OnGetShutdownScriptpubkey;
-use crate::util::events::{Event, MessageSendEvent, MessageSendEventsProvider, ClosureReason};
use crate::util::errors::APIError;
use crate::util::config::UserConfig;
+use crate::util::string::UntrustedString;
use bitcoin::blockdata::script::Builder;
use bitcoin::blockdata::opcodes;
// closing_signed so we do it ourselves
check_closed_broadcast!(nodes[1], false);
check_added_monitors!(nodes[1], 1);
- check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id()) });
+ check_closed_event!(nodes[1], 1, ClosureReason::CounterpartyForceClosed { peer_msg: UntrustedString(format!("Got a message for a channel from the wrong node! No such channel for the passed counterparty_node_id {}", &nodes[1].node.get_our_node_id())) });
}
assert!(nodes[0].node.list_channels().is_empty());
use bitcoin::secp256k1::{self, PublicKey, Scalar, Secp256k1, SecretKey};
use crate::chain::keysinterface::{EntropySource, KeysManager, NodeSigner, Recipient};
+use crate::events::OnionMessageProvider;
use crate::ln::features::{InitFeatures, NodeFeatures};
use crate::ln::msgs::{self, OnionMessageHandler};
use crate::ln::onion_utils;
pub use super::packet::{CustomOnionMessageContents, OnionMessageContents};
use super::packet::{BIG_PACKET_HOP_DATA_LEN, ForwardControlTlvs, Packet, Payload, ReceiveControlTlvs, SMALL_PACKET_HOP_DATA_LEN};
use super::utils;
-use crate::util::events::OnionMessageProvider;
use crate::util::logger::Logger;
use crate::util::ser::Writeable;
/// Useful for simplifying the parameters of [`SimpleArcChannelManager`] and
/// [`SimpleArcPeerManager`]. See their docs for more details.
///
-/// (C-not exported) as `Arc`s don't make sense in bindings.
+/// This is not exported to bindings users as `Arc`s don't make sense in bindings.
///
/// [`SimpleArcChannelManager`]: crate::ln::channelmanager::SimpleArcChannelManager
/// [`SimpleArcPeerManager`]: crate::ln::peer_handler::SimpleArcPeerManager
/// Useful for simplifying the parameters of [`SimpleRefChannelManager`] and
/// [`SimpleRefPeerManager`]. See their docs for more details.
///
-/// (C-not exported) as general type aliases don't make sense in bindings.
+/// This is not exported to bindings users as general type aliases don't make sense in bindings.
///
/// [`SimpleRefChannelManager`]: crate::ln::channelmanager::SimpleRefChannelManager
/// [`SimpleRefPeerManager`]: crate::ln::peer_handler::SimpleRefPeerManager
impl<T: CustomOnionMessageContents> OnionMessageContents<T> {
/// Returns the type that was used to decode the message payload.
///
- /// (C-not exported) as methods on non-cloneable enums are not currently exportable
+ /// This is not exported to bindings users as methods on non-cloneable enums are not currently exportable
pub fn tlv_type(&self) -> u64 {
match self {
&OnionMessageContents::Custom(ref msg) => msg.tlv_type(),
}
}
-/// (C-not exported) as methods on non-cloneable enums are not currently exportable
+/// This is not exported to bindings users as methods on non-cloneable enums are not currently exportable
impl<T: CustomOnionMessageContents> Writeable for OnionMessageContents<T> {
fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
match self {
use bitcoin::network::constants::Network;
use bitcoin::blockdata::constants::genesis_block;
+use crate::events::{MessageSendEvent, MessageSendEventsProvider};
use crate::ln::features::{ChannelFeatures, NodeFeatures, InitFeatures};
use crate::ln::msgs::{DecodeError, ErrorAction, Init, LightningError, RoutingMessageHandler, NetAddress, MAX_VALUE_MSAT};
use crate::ln::msgs::{ChannelAnnouncement, ChannelUpdate, NodeAnnouncement, GossipTimestampFilter};
use crate::routing::utxo::{self, UtxoLookup};
use crate::util::ser::{Readable, ReadableArgs, Writeable, Writer, MaybeReadable};
use crate::util::logger::{Logger, Level};
-use crate::util::events::{MessageSendEvent, MessageSendEventsProvider};
use crate::util::scid_utils::{block_from_scid, scid_from_parts, MAX_SCID_BLOCK};
use crate::util::string::PrintableString;
use crate::util::indexed_map::{IndexedMap, Entry as IndexedMapEntry};
/// Gets a reference to the underlying [`NetworkGraph`] which was provided in
/// [`P2PGossipSync::new`].
///
- /// (C-not exported) as bindings don't support a reference-to-a-reference yet
+ /// This is not exported to bindings users as bindings don't support a reference-to-a-reference yet
pub fn network_graph(&self) -> &G {
&self.network_graph
}
impl<L: Deref> NetworkGraph<L> where L::Target: Logger {
/// Handles any network updates originating from [`Event`]s.
///
- /// [`Event`]: crate::util::events::Event
+ /// [`Event`]: crate::events::Event
pub fn handle_network_update(&self, network_update: &NetworkUpdate) {
match *network_update {
NetworkUpdate::ChannelUpdateMessage { ref msg } => {
impl ReadOnlyNetworkGraph<'_> {
/// Returns all known valid channels' short ids along with announced channel info.
///
- /// (C-not exported) because we don't want to return lifetime'd references
+ /// This is not exported to bindings users because we don't want to return lifetime'd references
pub fn channels(&self) -> &IndexedMap<u64, ChannelInfo> {
&*self.channels
}
/// Returns all known nodes' public keys along with announced node info.
///
- /// (C-not exported) because we don't want to return lifetime'd references
+ /// This is not exported to bindings users because we don't want to return lifetime'd references
pub fn nodes(&self) -> &IndexedMap<NodeId, NodeInfo> {
&*self.nodes
}
#[cfg(test)]
pub(crate) mod tests {
+ use crate::events::{MessageSendEvent, MessageSendEventsProvider};
use crate::ln::channelmanager;
use crate::ln::chan_utils::make_funding_redeemscript;
#[cfg(feature = "std")]
use crate::util::config::UserConfig;
use crate::util::test_utils;
use crate::util::ser::{ReadableArgs, Readable, Writeable};
- use crate::util::events::{MessageSendEvent, MessageSendEventsProvider};
use crate::util::scid_utils::scid_from_parts;
use crate::routing::gossip::REMOVED_ENTRIES_TRACKING_AGE_LIMIT_SECS;
/// This is used by `ChannelManager` to track information which may be required for retries,
/// provided back to you via [`Event::PaymentPathFailed`].
///
- /// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
+ /// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
pub payment_params: Option<PaymentParameters>,
}
/// Passed to [`find_route`] and [`build_route_from_hops`], but also provided in
/// [`Event::PaymentPathFailed`].
///
-/// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
+/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RouteParameters {
/// The parameters of the failed payment path.
/// Includes the payee's features.
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_features(self, features: InvoiceFeatures) -> Self {
Self { features: Some(features), ..self }
}
/// Includes hints for routing to the payee.
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_route_hints(self, route_hints: Vec<RouteHint>) -> Self {
Self { route_hints, ..self }
}
/// Includes a payment expiration in seconds relative to the UNIX epoch.
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_expiry_time(self, expiry_time: u64) -> Self {
Self { expiry_time: Some(expiry_time), ..self }
}
/// Includes a limit for the total CLTV expiry delta which is considered during routing
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_max_total_cltv_expiry_delta(self, max_total_cltv_expiry_delta: u32) -> Self {
Self { max_total_cltv_expiry_delta, ..self }
}
/// Includes a limit for the maximum number of payment paths that may be used.
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_max_path_count(self, max_path_count: u8) -> Self {
Self { max_path_count, ..self }
}
/// Includes a limit for the maximum number of payment paths that may be used.
///
- /// (C-not exported) since bindings don't support move semantics
+ /// This is not exported to bindings users since bindings don't support move semantics
pub fn with_max_channel_saturation_power_of_half(self, max_channel_saturation_power_of_half: u8) -> Self {
Self { max_channel_saturation_power_of_half, ..self }
}
/// [`ChannelManager::list_usable_channels`] will never include such channels.
///
/// [`ChannelManager::list_usable_channels`]: crate::ln::channelmanager::ChannelManager::list_usable_channels
-/// [`Event::PaymentPathFailed`]: crate::util::events::Event::PaymentPathFailed
+/// [`Event::PaymentPathFailed`]: crate::events::Event::PaymentPathFailed
/// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
pub fn find_route<L: Deref, GL: Deref, S: Score>(
our_node_pubkey: &PublicKey, route_params: &RouteParameters,
#[cfg(not(c_bindings))]
impl<'a, T> WriteableScore<'a> for T where T: LockableScore<'a> + Writeable {}
-
-/// (C-not exported)
+/// This is not exported to bindings users
impl<'a, T: 'a + Score> LockableScore<'a> for Mutex<T> {
type Locked = MutexGuard<'a, T>;
}
#[cfg(c_bindings)]
-/// (C-not exported)
+/// This is not exported to bindings users
impl<'a, T: Writeable> Writeable for RefMut<'a, T> {
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
T::write(&**self, writer)
}
#[cfg(c_bindings)]
-/// (C-not exported)
+/// This is not exported to bindings users
impl<'a, S: Writeable> Writeable for MutexGuard<'a, S> {
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
S::write(&**self, writer)
/// Probabilistic [`Score`] implementation.
///
-/// (C-not exported) generally all users should use the [`ProbabilisticScorer`] type alias.
+/// This is not exported to bindings users generally all users should use the [`ProbabilisticScorer`] type alias.
pub struct ProbabilisticScorerUsingTime<G: Deref<Target = NetworkGraph<L>>, L: Deref, T: Time>
where L::Target: Logger {
params: ProbabilisticScoringParameters,
/// node. Note that a manual penalty of `u64::max_value()` means the node would not ever be
/// considered during path finding.
///
- /// (C-not exported)
+ /// This is not exported to bindings users
pub manual_node_penalties: HashMap<NodeId, u64>,
/// This penalty is applied when `htlc_maximum_msat` is equal to or larger than half of the
use bitcoin::{BlockHash, TxOut};
use bitcoin::hashes::hex::ToHex;
+use crate::events::MessageSendEvent;
use crate::ln::chan_utils::make_funding_redeemscript_from_slices;
use crate::ln::msgs::{self, LightningError, ErrorAction};
use crate::routing::gossip::{NetworkGraph, NodeId, P2PGossipSync};
-use crate::util::events::MessageSendEvent;
use crate::util::logger::{Level, Logger};
use crate::util::ser::Writeable;
///
/// Default value: false.
///
- /// [`Event::OpenChannelRequest`]: crate::util::events::Event::OpenChannelRequest
+ /// [`Event::OpenChannelRequest`]: crate::events::Event::OpenChannelRequest
/// [`msgs::OpenChannel`]: crate::ln::msgs::OpenChannel
/// [`msgs::AcceptChannel`]: crate::ln::msgs::AcceptChannel
pub manually_accept_inbound_channels: bool,
/// Default value: false.
///
/// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
- /// [`Event::HTLCIntercepted`]: crate::util::events::Event::HTLCIntercepted
+ /// [`Event::HTLCIntercepted`]: crate::events::Event::HTLCIntercepted
pub accept_intercept_htlcs: bool,
}
use bitcoin::secp256k1::{SecretKey, PublicKey};
use bitcoin::secp256k1::{Secp256k1, ecdsa::Signature};
#[cfg(anchors)]
-use crate::util::events::HTLCDescriptor;
+use crate::events::bump_transaction::HTLCDescriptor;
use crate::util::ser::{Writeable, Writer};
use crate::io::Error;
+++ /dev/null
-// This file is Copyright its original authors, visible in version control
-// history.
-//
-// This file is licensed under the Apache License, Version 2.0 <LICENSE-APACHE
-// or http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your option.
-// You may not use this file except in accordance with one or both of these
-// licenses.
-
-//! Events are returned from various bits in the library which indicate some action must be taken
-//! by the client.
-//!
-//! Because we don't have a built-in runtime, it's up to the client to call events at a time in the
-//! 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};
-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::routing::gossip::NetworkUpdate;
-use crate::util::errors::APIError;
-use crate::util::ser::{BigSize, FixedLengthReader, Writeable, Writer, MaybeReadable, Readable, RequiredWrapper, UpgradableRequired, WithoutLength};
-use crate::routing::router::{RouteHop, RouteParameters};
-
-use bitcoin::{PackedLockTime, Transaction};
-#[cfg(anchors)]
-use bitcoin::{OutPoint, Txid, TxIn, TxOut, Witness};
-use bitcoin::blockdata::script::Script;
-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;
-
-/// 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 {
- /// 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`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
- /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
- payment_preimage: Option<PaymentPreimage>,
- /// The "payment secret". This authenticates the sender to the recipient, preventing a
- /// number of deanonymization attacks during the routing process.
- /// It is provided here for your reference, however its accuracy is enforced directly by
- /// [`ChannelManager`] using the values you previously provided to
- /// [`ChannelManager::create_inbound_payment`] or
- /// [`ChannelManager::create_inbound_payment_for_hash`].
- ///
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
- /// [`ChannelManager::create_inbound_payment`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment
- /// [`ChannelManager::create_inbound_payment_for_hash`]: crate::ln::channelmanager::ChannelManager::create_inbound_payment_for_hash
- payment_secret: PaymentSecret,
- },
- /// Because this is a spontaneous payment, the payer generated their own preimage rather than us
- /// (the payee) providing a preimage.
- SpontaneousPayment(PaymentPreimage),
-}
-
-impl_writeable_tlv_based_enum!(PaymentPurpose,
- (0, InvoicePayment) => {
- (0, payment_preimage, option),
- (2, payment_secret, required),
- };
- (2, SpontaneousPayment)
-);
-
-/// 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`].
-///
-/// [`NetworkUpdate`]: crate::routing::gossip::NetworkUpdate
-/// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
-#[derive(Clone, Debug, Eq, PartialEq)]
-pub enum PathFailure {
- /// We failed to initially send the payment and no HTLC was committed to. Contains the relevant
- /// error.
- InitialSend {
- /// The error surfaced from initial send.
- err: APIError,
- },
- /// A hop on the path failed to forward our payment.
- OnPath {
- /// If present, this [`NetworkUpdate`] should be applied to the [`NetworkGraph`] so that routing
- /// decisions can take into account the update.
- ///
- /// [`NetworkUpdate`]: crate::routing::gossip::NetworkUpdate
- /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
- network_update: Option<NetworkUpdate>,
- },
-}
-
-impl_writeable_tlv_based_enum_upgradable!(PathFailure,
- (0, OnPath) => {
- (0, network_update, upgradable_option),
- },
- (2, InitialSend) => {
- (0, err, upgradable_required),
- },
-);
-
-#[derive(Clone, Debug, PartialEq, Eq)]
-/// The reason the channel was closed. See individual variants more details.
-pub enum ClosureReason {
- /// Closure generated from receiving a peer error message.
- ///
- /// Our counterparty may have broadcasted their latest commitment state, and we have
- /// as well.
- CounterpartyForceClosed {
- /// The error which the peer sent us.
- ///
- /// The string should be sanitized before it is used (e.g emitted to logs
- /// or printed to stdout). Otherwise, a well crafted error message may exploit
- /// a security vulnerability in the terminal emulator or the logging subsystem.
- peer_msg: String,
- },
- /// Closure generated from [`ChannelManager::force_close_channel`], called by the user.
- ///
- /// [`ChannelManager::force_close_channel`]: crate::ln::channelmanager::ChannelManager::force_close_channel.
- 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,
- /// 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`.
- CommitmentTxConfirmed,
- /// The funding transaction failed to confirm in a timely manner on an inbound channel.
- FundingTimedOut,
- /// Closure generated from processing an event, likely a HTLC forward/relay/reception.
- ProcessingError {
- /// A developer-readable error message which we generated.
- err: String,
- },
- /// The peer disconnected prior to funding completing. In this case the spec mandates that we
- /// forget the channel entirely - we can attempt again if the peer reconnects.
- ///
- /// This includes cases where we restarted prior to funding completion, including prior to the
- /// initial [`ChannelMonitor`] persistence completing.
- ///
- /// In LDK versions prior to 0.0.107 this could also occur if we were unable to connect to the
- /// peer because of mutual incompatibility between us and our channel counterparty.
- ///
- /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
- DisconnectedPeer,
- /// Closure generated from `ChannelManager::read` if the [`ChannelMonitor`] is newer than
- /// the [`ChannelManager`] deserialized.
- ///
- /// [`ChannelMonitor`]: crate::chain::channelmonitor::ChannelMonitor
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
- OutdatedChannelManager
-}
-
-impl core::fmt::Display for ClosureReason {
- fn fmt(&self, f: &mut core::fmt::Formatter) -> Result<(), core::fmt::Error> {
- f.write_str("Channel closed because ")?;
- match self {
- ClosureReason::CounterpartyForceClosed { peer_msg } => {
- f.write_str("counterparty force-closed with message ")?;
- f.write_str(&peer_msg)
- },
- ClosureReason::HolderForceClosed => f.write_str("user manually force-closed the channel"),
- ClosureReason::CooperativeClosure => f.write_str("the channel was cooperatively closed"),
- 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 } => {
- f.write_str("of an exception: ")?;
- f.write_str(&err)
- },
- 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)"),
- }
- }
-}
-
-impl_writeable_tlv_based_enum_upgradable!(ClosureReason,
- (0, CounterpartyForceClosed) => { (1, peer_msg, required) },
- (1, FundingTimedOut) => {},
- (2, HolderForceClosed) => {},
- (6, CommitmentTxConfirmed) => {},
- (4, CooperativeClosure) => {},
- (8, ProcessingError) => { (1, err, required) },
- (10, DisconnectedPeer) => {},
- (12, OutdatedChannelManager) => {},
-);
-
-/// Intended destination of a failed HTLC as indicated in [`Event::HTLCHandlingFailed`].
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum HTLCDestination {
- /// We tried forwarding to a channel but failed to do so. An example of such an instance is when
- /// there is insufficient capacity in our outbound channel.
- NextHopChannel {
- /// The `node_id` of the next node. For backwards compatibility, this field is
- /// marked as optional, versions prior to 0.0.110 may not always be able to provide
- /// counterparty node information.
- node_id: Option<PublicKey>,
- /// The outgoing `channel_id` between us and the next node.
- channel_id: [u8; 32],
- },
- /// Scenario where we are unsure of the next node to forward the HTLC to.
- UnknownNextHop {
- /// Short channel id we are requesting to forward an HTLC to.
- requested_forward_scid: u64,
- },
- /// We couldn't forward to the outgoing scid. An example would be attempting to send a duplicate
- /// intercept HTLC.
- InvalidForward {
- /// Short channel id we are requesting to forward an HTLC to.
- requested_forward_scid: u64
- },
- /// 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
- FailedPayment {
- /// The payment hash of the payment we attempted to process.
- payment_hash: PaymentHash
- },
-}
-
-impl_writeable_tlv_based_enum_upgradable!(HTLCDestination,
- (0, NextHopChannel) => {
- (0, node_id, required),
- (2, channel_id, required),
- },
- (1, InvalidForward) => {
- (0, requested_forward_scid, required),
- },
- (2, UnknownNextHop) => {
- (0, requested_forward_scid, required),
- },
- (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<PaymentPreimage>,
- /// 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<C: secp256k1::Signing + secp256k1::Verification>(
- &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
- ) -> 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<C: secp256k1::Signing + secp256k1::Verification>(
- &self, per_commitment_point: &PublicKey, secp: &Secp256k1<C>
- ) -> 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<HTLCOutputInCommitment>,
- },
- /// 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<HTLCDescriptor>,
- },
-}
-
-/// 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
-/// intercepts in upcoming work.
-enum InterceptNextHop {
- FakeScid {
- requested_next_hop_scid: u64,
- },
-}
-
-impl_writeable_tlv_based_enum!(InterceptNextHop,
- (0, FakeScid) => {
- (0, requested_next_hop_scid, required),
- };
-);
-
-/// 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
-/// them directly as they don't round-trip exactly (for example FundingGenerationReady is never
-/// written as it makes no sense to respond to it after reconnecting to peers).
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub enum Event {
- /// Used to indicate that the client should generate a funding transaction with the given
- /// parameters and then call [`ChannelManager::funding_transaction_generated`].
- /// Generated in [`ChannelManager`] message handling.
- /// Note that *all inputs* in the funding transaction must spend SegWit outputs or your
- /// counterparty can steal your funds!
- ///
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
- /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
- FundingGenerationReady {
- /// The random channel_id we picked which you'll need to pass into
- /// [`ChannelManager::funding_transaction_generated`].
- ///
- /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
- temporary_channel_id: [u8; 32],
- /// The counterparty's node_id, which you'll need to pass back into
- /// [`ChannelManager::funding_transaction_generated`].
- ///
- /// [`ChannelManager::funding_transaction_generated`]: crate::ln::channelmanager::ChannelManager::funding_transaction_generated
- counterparty_node_id: PublicKey,
- /// 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.
- ///
- /// [`ChannelManager::create_channel`]: crate::ln::channelmanager::ChannelManager::create_channel
- user_channel_id: u128,
- },
- /// Indicates that we've been offered a payment and it needs to be claimed via calling
- /// [`ChannelManager::claim_funds`] with the preimage given in [`PaymentPurpose`].
- ///
- /// 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.
- ///
- /// # Note
- /// LDK will not stop an inbound payment from being paid multiple times, so multiple
- /// `PaymentClaimable` events may be generated for the same 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::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 {
- /// The node that will receive the payment after it has been claimed.
- /// This is useful to identify payments received via [phantom nodes].
- /// 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
- receiver_node_id: Option<PublicKey>,
- /// 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.
- amount_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]>,
- /// The `user_channel_id` indicating over which channel we received the payment.
- via_user_channel_id: Option<u128>,
- },
- /// Indicates a payment has been claimed and we've received money!
- ///
- /// This most likely occurs when [`ChannelManager::claim_funds`] has been called in response
- /// to an [`Event::PaymentClaimable`]. However, if we previously crashed during a
- /// [`ChannelManager::claim_funds`] call you may see this event without a corresponding
- /// [`Event::PaymentClaimable`] event.
- ///
- /// # Note
- /// LDK will not stop an inbound payment from being paid multiple times, so multiple
- /// `PaymentClaimable` events may be generated for the same payment. If you then call
- /// [`ChannelManager::claim_funds`] twice for the same [`Event::PaymentClaimable`] you may get
- /// multiple `PaymentClaimed` events.
- ///
- /// [`ChannelManager::claim_funds`]: crate::ln::channelmanager::ChannelManager::claim_funds
- PaymentClaimed {
- /// The node that received the payment.
- /// This is useful to identify payments which were received via [phantom nodes].
- /// 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
- receiver_node_id: Option<PublicKey>,
- /// 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.
- amount_msat: u64,
- /// The purpose of the claimed payment, i.e. whether the payment was for an invoice or a
- /// spontaneous payment.
- purpose: PaymentPurpose,
- },
- /// 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).
- ///
- /// 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`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- payment_id: Option<PaymentId>,
- /// The preimage to the hash given to ChannelManager::send_payment.
- /// Note that this serves as a payment receipt, if you wish to have such a thing, you must
- /// store it somehow!
- payment_preimage: PaymentPreimage,
- /// The hash that was given to [`ChannelManager::send_payment`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- payment_hash: PaymentHash,
- /// The total fee which was spent at intermediate hops in this payment, across all paths.
- ///
- /// Note that, like [`Route::get_total_fees`] this does *not* include any potential
- /// overpayment to the recipient node.
- ///
- /// If the recipient or an intermediate node misbehaves and gives us free money, this may
- /// overstate the amount paid, though this is unlikely.
- ///
- /// [`Route::get_total_fees`]: crate::routing::router::Route::get_total_fees
- fee_paid_msat: Option<u64>,
- },
- /// Indicates an outbound payment failed. Individual [`Event::PaymentPathFailed`] events
- /// provide failure information for each path attempt in the payment, including retries.
- ///
- /// This event is provided once there are no further pending HTLCs for the payment and the
- /// payment is no longer retryable, due either to the [`Retry`] provided or
- /// [`ChannelManager::abandon_payment`] having been called for the corresponding payment.
- ///
- /// [`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`].
- ///
- /// [`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,
- },
- /// 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`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- payment_id: PaymentId,
- /// The hash that was given to [`ChannelManager::send_payment`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- payment_hash: Option<PaymentHash>,
- /// The payment path that was successful.
- ///
- /// May contain a closed channel if the HTLC sent along the path was fulfilled on chain.
- path: Vec<RouteHop>,
- },
- /// Indicates an outbound HTLC we sent failed, likely due to an intermediary node being unable to
- /// handle the HTLC.
- ///
- /// Note that this does *not* indicate that all paths for an MPP payment have failed, see
- /// [`Event::PaymentFailed`].
- ///
- /// See [`ChannelManager::abandon_payment`] for giving up on this payment before its retries have
- /// been exhausted.
- ///
- /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
- PaymentPathFailed {
- /// The id returned by [`ChannelManager::send_payment`] and used with
- /// [`ChannelManager::abandon_payment`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- /// [`ChannelManager::abandon_payment`]: crate::ln::channelmanager::ChannelManager::abandon_payment
- payment_id: Option<PaymentId>,
- /// The hash that was given to [`ChannelManager::send_payment`].
- ///
- /// [`ChannelManager::send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment
- payment_hash: PaymentHash,
- /// Indicates the payment was rejected for some reason by the recipient. This implies that
- /// the payment has failed, not just the route in question. If this is not set, the payment may
- /// be retried via a different route.
- payment_failed_permanently: bool,
- /// Extra error details based on the failure type. May contain an update that needs to be
- /// applied to the [`NetworkGraph`].
- ///
- /// [`NetworkGraph`]: crate::routing::gossip::NetworkGraph
- failure: PathFailure,
- /// The payment path that failed.
- path: Vec<RouteHop>,
- /// 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
- /// may not refer to a channel in the public network graph. These aliases may also collide
- /// with channels in the public network graph.
- ///
- /// If this is `Some`, then the corresponding channel should be avoided when the payment is
- /// retried. May be `None` for older [`Event`] serializations.
- short_channel_id: Option<u64>,
-#[cfg(test)]
- error_code: Option<u16>,
-#[cfg(test)]
- error_data: Option<Vec<u8>>,
- },
- /// Indicates that a probe payment we sent returned successful, i.e., only failed at the destination.
- ProbeSuccessful {
- /// The id returned by [`ChannelManager::send_probe`].
- ///
- /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
- payment_id: PaymentId,
- /// The hash generated by [`ChannelManager::send_probe`].
- ///
- /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
- payment_hash: PaymentHash,
- /// The payment path that was successful.
- path: Vec<RouteHop>,
- },
- /// Indicates that a probe payment we sent failed at an intermediary node on the path.
- ProbeFailed {
- /// The id returned by [`ChannelManager::send_probe`].
- ///
- /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
- payment_id: PaymentId,
- /// The hash generated by [`ChannelManager::send_probe`].
- ///
- /// [`ChannelManager::send_probe`]: crate::ln::channelmanager::ChannelManager::send_probe
- payment_hash: PaymentHash,
- /// The payment path that failed.
- path: Vec<RouteHop>,
- /// 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
- /// may not refer to a channel in the public network graph. These aliases may also collide
- /// with channels in the public network graph.
- short_channel_id: Option<u64>,
- },
- /// Used to indicate that [`ChannelManager::process_pending_htlc_forwards`] should be called at
- /// a time in the future.
- ///
- /// [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards
- PendingHTLCsForwardable {
- /// The minimum amount of time that should be waited prior to calling
- /// process_pending_htlc_forwards. To increase the effort required to correlate payments,
- /// you should wait a random amount of time in roughly the range (now + time_forwardable,
- /// now + 5*time_forwardable).
- time_forwardable: Duration,
- },
- /// Used to indicate that we've intercepted an HTLC forward. This event will only be generated if
- /// you've encoded an intercept scid in the receiver's invoice route hints using
- /// [`ChannelManager::get_intercept_scid`] and have set [`UserConfig::accept_intercept_htlcs`].
- ///
- /// [`ChannelManager::forward_intercepted_htlc`] or
- /// [`ChannelManager::fail_intercepted_htlc`] MUST be called in response to this event. See
- /// their docs for more information.
- ///
- /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
- /// [`UserConfig::accept_intercept_htlcs`]: crate::util::config::UserConfig::accept_intercept_htlcs
- /// [`ChannelManager::forward_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::forward_intercepted_htlc
- /// [`ChannelManager::fail_intercepted_htlc`]: crate::ln::channelmanager::ChannelManager::fail_intercepted_htlc
- HTLCIntercepted {
- /// An id to help LDK identify which HTLC is being forwarded or failed.
- intercept_id: InterceptId,
- /// The fake scid that was programmed as the next hop's scid, generated using
- /// [`ChannelManager::get_intercept_scid`].
- ///
- /// [`ChannelManager::get_intercept_scid`]: crate::ln::channelmanager::ChannelManager::get_intercept_scid
- requested_next_hop_scid: u64,
- /// The payment hash used for this HTLC.
- payment_hash: PaymentHash,
- /// How many msats were received on the inbound edge of this HTLC.
- 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.
- ///
- /// 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,
- /// LDK will not stop you from forwarding more than you received.
- expected_outbound_amount_msat: u64,
- },
- /// Used to indicate that an output which you should know how to spend was confirmed on chain
- /// and is now spendable.
- /// Such an output will *not* ever be spent by rust-lightning, and are not at risk of your
- /// counterparty spending them due to some kind of timeout. Thus, you need to store them
- /// somewhere and spend them when you create on-chain transactions.
- SpendableOutputs {
- /// The outputs which you should store as spendable by you.
- outputs: Vec<SpendableOutputDescriptor>,
- },
- /// 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.
- ///
- /// 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
- /// whole satoshi. Thus, the fee calculated here may be higher than expected as we still
- /// claimed the full value in millisatoshis from the source. In this case,
- /// `claim_from_onchain_tx` will be set.
- ///
- /// 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
- /// `None`.
- fee_earned_msat: Option<u64>,
- /// If this is `true`, the forwarded HTLC was claimed by our counterparty via an on-chain
- /// transaction.
- claim_from_onchain_tx: bool,
- },
- /// 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 `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 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
- /// resolving the channel are likely still awaiting confirmation.
- channel_id: [u8; 32],
- /// 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 inbound channels.
- /// This may be zero for inbound channels serialized prior to 0.0.113 and will always be
- /// zero for objects serialized with LDK versions prior to 0.0.102.
- ///
- /// [`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 reason the channel was closed.
- reason: ClosureReason
- },
- /// Used to indicate to the user that they can abandon the funding transaction and recycle the
- /// inputs for another purpose.
- DiscardFunding {
- /// The channel_id of the channel which has been closed.
- channel_id: [u8; 32],
- /// 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`].
- ///
- /// 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.
- ///
- /// [`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
- /// [`UserConfig::manually_accept_inbound_channels`]: crate::util::config::UserConfig::manually_accept_inbound_channels
- OpenChannelRequest {
- /// The temporary channel ID of the channel requested to be opened.
- ///
- /// When responding to the request, the `temporary_channel_id` should be passed
- /// back to the ChannelManager through [`ChannelManager::accept_inbound_channel`] to accept,
- /// or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject.
- ///
- /// [`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],
- /// The node_id of the counterparty requesting to open the channel.
- ///
- /// When responding to the request, the `counterparty_node_id` should be passed
- /// back to the `ChannelManager` through [`ChannelManager::accept_inbound_channel`] to
- /// accept the request, or through [`ChannelManager::force_close_without_broadcasting_txn`] to reject the
- /// request.
- ///
- /// [`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
- counterparty_node_id: PublicKey,
- /// The channel value of the requested channel.
- funding_satoshis: u64,
- /// Our starting balance in the channel if the request is accepted, in milli-satoshi.
- push_msat: u64,
- /// The features that this channel will operate with. If you reject the channel, a
- /// well-behaved counterparty may automatically re-attempt the channel with a new set of
- /// feature flags.
- ///
- /// Note that if [`ChannelTypeFeatures::supports_scid_privacy`] returns true on this type,
- /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
- /// 0.0.106.
- ///
- /// Furthermore, note that if [`ChannelTypeFeatures::supports_zero_conf`] returns true on this type,
- /// the resulting [`ChannelManager`] will not be readable by versions of LDK prior to
- /// 0.0.107. Channels setting this type also need to get manually accepted via
- /// [`crate::ln::channelmanager::ChannelManager::accept_inbound_channel_from_trusted_peer_0conf`],
- /// or will be rejected otherwise.
- ///
- /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager
- channel_type: ChannelTypeFeatures,
- },
- /// Indicates that the HTLC was accepted, but could not be processed when or after attempting to
- /// forward it.
- ///
- /// Some scenarios where this event may be sent include:
- /// * 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
- /// * 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],
- /// 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.
- BumpTransaction(BumpTransactionEvent),
-}
-
-impl Writeable for Event {
- fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error> {
- match self {
- &Event::FundingGenerationReady { .. } => {
- 0u8.write(writer)?;
- // 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 } => {
- 1u8.write(writer)?;
- let mut payment_secret = None;
- let payment_preimage;
- match &purpose {
- PaymentPurpose::InvoicePayment { payment_preimage: preimage, payment_secret: secret } => {
- payment_secret = Some(secret);
- payment_preimage = *preimage;
- },
- PaymentPurpose::SpontaneousPayment(preimage) => {
- payment_preimage = Some(*preimage);
- }
- }
- write_tlv_fields!(writer, {
- (0, payment_hash, required),
- (1, receiver_node_id, option),
- (2, payment_secret, option),
- (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
- (8, payment_preimage, option),
- });
- },
- &Event::PaymentSent { ref payment_id, ref payment_preimage, ref payment_hash, ref fee_paid_msat } => {
- 2u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_preimage, required),
- (1, payment_hash, required),
- (3, payment_id, option),
- (5, fee_paid_msat, option),
- });
- },
- &Event::PaymentPathFailed {
- ref payment_id, ref payment_hash, ref payment_failed_permanently, ref failure,
- ref path, ref short_channel_id,
- #[cfg(test)]
- ref error_code,
- #[cfg(test)]
- ref error_data,
- } => {
- 3u8.write(writer)?;
- #[cfg(test)]
- error_code.write(writer)?;
- #[cfg(test)]
- error_data.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_hash, required),
- (1, None::<NetworkUpdate>, 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),
- (7, short_channel_id, option),
- (9, None::<RouteParameters>, option), // retry in LDK versions prior to 0.0.115
- (11, payment_id, option),
- (13, failure, required),
- });
- },
- &Event::PendingHTLCsForwardable { time_forwardable: _ } => {
- 4u8.write(writer)?;
- // 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 } => {
- 5u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, WithoutLength(outputs), required),
- });
- },
- &Event::HTLCIntercepted { requested_next_hop_scid, payment_hash, inbound_amount_msat, expected_outbound_amount_msat, intercept_id } => {
- 6u8.write(writer)?;
- let intercept_scid = InterceptNextHop::FakeScid { requested_next_hop_scid };
- write_tlv_fields!(writer, {
- (0, intercept_id, required),
- (2, intercept_scid, required),
- (4, payment_hash, required),
- (6, inbound_amount_msat, required),
- (8, expected_outbound_amount_msat, required),
- });
- }
- &Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id } => {
- 7u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, fee_earned_msat, option),
- (1, prev_channel_id, option),
- (2, claim_from_onchain_tx, required),
- (3, next_channel_id, option),
- });
- },
- &Event::ChannelClosed { ref channel_id, ref user_channel_id, ref reason } => {
- 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
- // separate u64 values.
- let user_channel_id_low = *user_channel_id as u64;
- let user_channel_id_high = (*user_channel_id >> 64) as u64;
- write_tlv_fields!(writer, {
- (0, channel_id, required),
- (1, user_channel_id_low, required),
- (2, reason, required),
- (3, user_channel_id_high, required),
- });
- },
- &Event::DiscardFunding { ref channel_id, ref transaction } => {
- 11u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, channel_id, required),
- (2, transaction, required)
- })
- },
- &Event::PaymentPathSuccessful { ref payment_id, ref payment_hash, ref path } => {
- 13u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_id, required),
- (2, payment_hash, option),
- (4, *path, vec_type)
- })
- },
- &Event::PaymentFailed { ref payment_id, ref payment_hash } => {
- 15u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_id, required),
- (2, payment_hash, required),
- })
- },
- &Event::OpenChannelRequest { .. } => {
- 17u8.write(writer)?;
- // 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 } => {
- 19u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_hash, required),
- (1, receiver_node_id, option),
- (2, purpose, required),
- (4, amount_msat, required),
- });
- },
- &Event::ProbeSuccessful { ref payment_id, ref payment_hash, ref path } => {
- 21u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_id, required),
- (2, payment_hash, required),
- (4, *path, vec_type)
- })
- },
- &Event::ProbeFailed { ref payment_id, ref payment_hash, ref path, ref short_channel_id } => {
- 23u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, payment_id, required),
- (2, payment_hash, required),
- (4, *path, vec_type),
- (6, short_channel_id, option),
- })
- },
- &Event::HTLCHandlingFailed { ref prev_channel_id, ref failed_next_destination } => {
- 25u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, prev_channel_id, required),
- (2, failed_next_destination, required),
- })
- },
- #[cfg(anchors)]
- &Event::BumpTransaction(ref event)=> {
- 27u8.write(writer)?;
- match event {
- // We never write the ChannelClose|HTLCResolution events as they'll be replayed
- // upon restarting anyway if they remain unresolved.
- BumpTransactionEvent::ChannelClose { .. } => {}
- BumpTransactionEvent::HTLCResolution { .. } => {}
- }
- write_tlv_fields!(writer, {}); // Write a length field for forwards compat
- }
- &Event::ChannelReady { ref channel_id, ref user_channel_id, ref counterparty_node_id, ref channel_type } => {
- 29u8.write(writer)?;
- write_tlv_fields!(writer, {
- (0, channel_id, required),
- (2, user_channel_id, required),
- (4, counterparty_node_id, required),
- (6, channel_type, required),
- });
- },
- // 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`.
- }
- Ok(())
- }
-}
-impl MaybeReadable for Event {
- fn read<R: io::Read>(reader: &mut R) -> Result<Option<Self>, 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.
- 0u8 => Ok(None),
- 1u8 => {
- let 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 receiver_node_id = None;
- let mut _user_payment_id = None::<u64>; // For compatibility with 0.0.103 and earlier
- let mut via_channel_id = None;
- let mut via_user_channel_id = None;
- read_tlv_fields!(reader, {
- (0, payment_hash, required),
- (1, receiver_node_id, option),
- (2, payment_secret, option),
- (3, via_channel_id, option),
- (4, amount_msat, required),
- (5, via_user_channel_id, option),
- (6, _user_payment_id, option),
- (8, payment_preimage, option),
- });
- let purpose = match payment_secret {
- Some(secret) => PaymentPurpose::InvoicePayment {
- payment_preimage,
- payment_secret: secret
- },
- None if payment_preimage.is_some() => PaymentPurpose::SpontaneousPayment(payment_preimage.unwrap()),
- None => return Err(msgs::DecodeError::InvalidValue),
- };
- Ok(Some(Event::PaymentClaimable {
- receiver_node_id,
- payment_hash,
- amount_msat,
- purpose,
- via_channel_id,
- via_user_channel_id,
- }))
- };
- f()
- },
- 2u8 => {
- let f = || {
- let mut payment_preimage = PaymentPreimage([0; 32]);
- let mut payment_hash = None;
- let mut payment_id = None;
- let mut fee_paid_msat = None;
- read_tlv_fields!(reader, {
- (0, payment_preimage, required),
- (1, payment_hash, option),
- (3, payment_id, option),
- (5, fee_paid_msat, option),
- });
- if payment_hash.is_none() {
- payment_hash = Some(PaymentHash(Sha256::hash(&payment_preimage.0[..]).into_inner()));
- }
- Ok(Some(Event::PaymentSent {
- payment_id,
- payment_preimage,
- payment_hash: payment_hash.unwrap(),
- fee_paid_msat,
- }))
- };
- f()
- },
- 3u8 => {
- let f = || {
- #[cfg(test)]
- let error_code = Readable::read(reader)?;
- #[cfg(test)]
- let error_data = Readable::read(reader)?;
- let mut payment_hash = PaymentHash([0; 32]);
- let mut payment_failed_permanently = false;
- let mut network_update = None;
- let mut path: Option<Vec<RouteHop>> = Some(vec![]);
- let mut short_channel_id = None;
- let mut payment_id = None;
- let mut failure_opt = None;
- read_tlv_fields!(reader, {
- (0, payment_hash, required),
- (1, network_update, upgradable_option),
- (2, payment_failed_permanently, required),
- (5, path, vec_type),
- (7, short_channel_id, option),
- (11, payment_id, option),
- (13, failure_opt, upgradable_option),
- });
- let failure = failure_opt.unwrap_or_else(|| PathFailure::OnPath { network_update });
- Ok(Some(Event::PaymentPathFailed {
- payment_id,
- payment_hash,
- payment_failed_permanently,
- failure,
- path: path.unwrap(),
- short_channel_id,
- #[cfg(test)]
- error_code,
- #[cfg(test)]
- error_data,
- }))
- };
- f()
- },
- 4u8 => Ok(None),
- 5u8 => {
- let f = || {
- let mut outputs = WithoutLength(Vec::new());
- read_tlv_fields!(reader, {
- (0, outputs, required),
- });
- Ok(Some(Event::SpendableOutputs { outputs: outputs.0 }))
- };
- f()
- },
- 6u8 => {
- let mut payment_hash = PaymentHash([0; 32]);
- let mut intercept_id = InterceptId([0; 32]);
- let mut requested_next_hop_scid = InterceptNextHop::FakeScid { requested_next_hop_scid: 0 };
- let mut inbound_amount_msat = 0;
- let mut expected_outbound_amount_msat = 0;
- read_tlv_fields!(reader, {
- (0, intercept_id, required),
- (2, requested_next_hop_scid, required),
- (4, payment_hash, required),
- (6, inbound_amount_msat, required),
- (8, expected_outbound_amount_msat, required),
- });
- let next_scid = match requested_next_hop_scid {
- InterceptNextHop::FakeScid { requested_next_hop_scid: scid } => scid
- };
- Ok(Some(Event::HTLCIntercepted {
- payment_hash,
- requested_next_hop_scid: next_scid,
- inbound_amount_msat,
- expected_outbound_amount_msat,
- intercept_id,
- }))
- },
- 7u8 => {
- let f = || {
- let mut fee_earned_msat = None;
- let mut prev_channel_id = None;
- let mut claim_from_onchain_tx = false;
- let mut next_channel_id = None;
- read_tlv_fields!(reader, {
- (0, fee_earned_msat, option),
- (1, prev_channel_id, option),
- (2, claim_from_onchain_tx, required),
- (3, next_channel_id, option),
- });
- Ok(Some(Event::PaymentForwarded { fee_earned_msat, prev_channel_id, claim_from_onchain_tx, next_channel_id }))
- };
- f()
- },
- 9u8 => {
- let f = || {
- let mut channel_id = [0; 32];
- let mut reason = UpgradableRequired(None);
- let mut user_channel_id_low_opt: Option<u64> = None;
- let mut user_channel_id_high_opt: Option<u64> = 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),
- });
-
- // `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 separate u64 values.
- 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) }))
- };
- 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() };
- read_tlv_fields!(reader, {
- (0, channel_id, required),
- (2, transaction, required),
- });
- Ok(Some(Event::DiscardFunding { channel_id, transaction } ))
- };
- f()
- },
- 13u8 => {
- let f = || {
- let mut payment_id = PaymentId([0; 32]);
- let mut payment_hash = None;
- let mut path: Option<Vec<RouteHop>> = Some(vec![]);
- read_tlv_fields!(reader, {
- (0, payment_id, required),
- (2, payment_hash, option),
- (4, path, vec_type),
- });
- Ok(Some(Event::PaymentPathSuccessful {
- payment_id,
- payment_hash,
- path: path.unwrap(),
- }))
- };
- f()
- },
- 15u8 => {
- let f = || {
- let mut payment_hash = PaymentHash([0; 32]);
- let mut payment_id = PaymentId([0; 32]);
- read_tlv_fields!(reader, {
- (0, payment_id, required),
- (2, payment_hash, required),
- });
- Ok(Some(Event::PaymentFailed {
- payment_id,
- payment_hash,
- }))
- };
- f()
- },
- 17u8 => {
- // Value 17 is used for `Event::OpenChannelRequest`.
- Ok(None)
- },
- 19u8 => {
- let f = || {
- let mut payment_hash = PaymentHash([0; 32]);
- let mut purpose = UpgradableRequired(None);
- let mut amount_msat = 0;
- let mut receiver_node_id = None;
- read_tlv_fields!(reader, {
- (0, payment_hash, required),
- (1, receiver_node_id, option),
- (2, purpose, upgradable_required),
- (4, amount_msat, required),
- });
- Ok(Some(Event::PaymentClaimed {
- receiver_node_id,
- payment_hash,
- purpose: _init_tlv_based_struct_field!(purpose, upgradable_required),
- amount_msat,
- }))
- };
- f()
- },
- 21u8 => {
- let f = || {
- let mut payment_id = PaymentId([0; 32]);
- let mut payment_hash = PaymentHash([0; 32]);
- let mut path: Option<Vec<RouteHop>> = Some(vec![]);
- read_tlv_fields!(reader, {
- (0, payment_id, required),
- (2, payment_hash, required),
- (4, path, vec_type),
- });
- Ok(Some(Event::ProbeSuccessful {
- payment_id,
- payment_hash,
- path: path.unwrap(),
- }))
- };
- f()
- },
- 23u8 => {
- let f = || {
- let mut payment_id = PaymentId([0; 32]);
- let mut payment_hash = PaymentHash([0; 32]);
- let mut path: Option<Vec<RouteHop>> = Some(vec![]);
- let mut short_channel_id = None;
- read_tlv_fields!(reader, {
- (0, payment_id, required),
- (2, payment_hash, required),
- (4, path, vec_type),
- (6, short_channel_id, option),
- });
- Ok(Some(Event::ProbeFailed {
- payment_id,
- payment_hash,
- path: path.unwrap(),
- short_channel_id,
- }))
- };
- f()
- },
- 25u8 => {
- let f = || {
- let mut prev_channel_id = [0; 32];
- let mut failed_next_destination_opt = UpgradableRequired(None);
- read_tlv_fields!(reader, {
- (0, prev_channel_id, required),
- (2, failed_next_destination_opt, upgradable_required),
- });
- Ok(Some(Event::HTLCHandlingFailed {
- prev_channel_id,
- failed_next_destination: _init_tlv_based_struct_field!(failed_next_destination_opt, upgradable_required),
- }))
- };
- f()
- },
- 27u8 => Ok(None),
- 29u8 => {
- let f = || {
- let mut channel_id = [0; 32];
- let mut user_channel_id: u128 = 0;
- let mut counterparty_node_id = RequiredWrapper(None);
- let mut channel_type = RequiredWrapper(None);
- read_tlv_fields!(reader, {
- (0, channel_id, required),
- (2, user_channel_id, required),
- (4, counterparty_node_id, required),
- (6, channel_type, required),
- });
-
- Ok(Some(Event::ChannelReady {
- channel_id,
- user_channel_id,
- counterparty_node_id: counterparty_node_id.0.unwrap(),
- channel_type: channel_type.0.unwrap()
- }))
- };
- f()
- },
- // 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.
- x if x % 2 == 1 => {
- // If the event is of unknown type, assume it was written with `write_tlv_fields`,
- // which prefixes the whole thing with a length BigSize. Because the event is
- // odd-type unknown, we should treat it as `Ok(None)` even if it has some TLV
- // fields that are even. Thus, we avoid using `read_tlv_fields` and simply read
- // exactly the number of bytes specified, ignoring them entirely.
- let tlv_len: BigSize = Readable::read(reader)?;
- FixedLengthReader::new(reader, tlv_len.0)
- .eat_remaining().map_err(|_| msgs::DecodeError::ShortRead)?;
- Ok(None)
- },
- _ => Err(msgs::DecodeError::InvalidValue)
- }
- }
-}
-
-/// An event generated by ChannelManager which indicates a message should be sent to a peer (or
-/// broadcast to most peers).
-/// These events are handled by PeerManager::process_events if you are using a PeerManager.
-#[derive(Clone, Debug)]
-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.
- SendAcceptChannel {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::AcceptChannel,
- },
- /// Used to indicate that we've initiated a channel open and should send the open_channel
- /// message provided to the given peer.
- SendOpenChannel {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::OpenChannel,
- },
- /// 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
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::FundingCreated,
- },
- /// Used to indicate that a funding_signed message should be sent to the peer with the given node_id.
- SendFundingSigned {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::FundingSigned,
- },
- /// 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)
- node_id: PublicKey,
- /// The channel_ready message which should be sent.
- msg: msgs::ChannelReady,
- },
- /// Used to indicate that an announcement_signatures message should be sent to the peer with the given node_id.
- SendAnnouncementSignatures {
- /// The node_id of the node which should receive these message(s)
- node_id: PublicKey,
- /// The announcement_signatures message which should be sent.
- msg: msgs::AnnouncementSignatures,
- },
- /// Used to indicate that a series of HTLC update messages, as well as a commitment_signed
- /// message should be sent to the peer with the given node_id.
- UpdateHTLCs {
- /// The node_id of the node which should receive these message(s)
- node_id: PublicKey,
- /// The update messages which should be sent. ALL messages in the struct should be sent!
- updates: msgs::CommitmentUpdate,
- },
- /// Used to indicate that a revoke_and_ack message should be sent to the peer with the given node_id.
- SendRevokeAndACK {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::RevokeAndACK,
- },
- /// Used to indicate that a closing_signed message should be sent to the peer with the given node_id.
- SendClosingSigned {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::ClosingSigned,
- },
- /// Used to indicate that a shutdown message should be sent to the peer with the given node_id.
- SendShutdown {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::Shutdown,
- },
- /// Used to indicate that a channel_reestablish message should be sent to the peer with the given node_id.
- SendChannelReestablish {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The message which should be sent.
- msg: msgs::ChannelReestablish,
- },
- /// Used to send a channel_announcement and channel_update to a specific peer, likely on
- /// initial connection to ensure our peers know about our channels.
- SendChannelAnnouncement {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The channel_announcement which should be sent.
- msg: msgs::ChannelAnnouncement,
- /// The followup channel_update which should be sent.
- update_msg: msgs::ChannelUpdate,
- },
- /// Used to indicate that a channel_announcement and channel_update should be broadcast to all
- /// peers (except the peer with node_id either msg.contents.node_id_1 or msg.contents.node_id_2).
- ///
- /// Note that after doing so, you very likely (unless you did so very recently) want to
- /// broadcast a node_announcement (e.g. via [`PeerManager::broadcast_node_announcement`]). This
- /// ensures that any nodes which see our channel_announcement also have a relevant
- /// node_announcement, including relevant feature flags which may be important for routing
- /// through or to us.
- ///
- /// [`PeerManager::broadcast_node_announcement`]: crate::ln::peer_handler::PeerManager::broadcast_node_announcement
- BroadcastChannelAnnouncement {
- /// The channel_announcement which should be sent.
- msg: msgs::ChannelAnnouncement,
- /// The followup channel_update which should be sent.
- update_msg: Option<msgs::ChannelUpdate>,
- },
- /// Used to indicate that a channel_update should be broadcast to all peers.
- BroadcastChannelUpdate {
- /// The channel_update which should be sent.
- msg: msgs::ChannelUpdate,
- },
- /// Used to indicate that a node_announcement should be broadcast to all peers.
- BroadcastNodeAnnouncement {
- /// The node_announcement which should be sent.
- msg: msgs::NodeAnnouncement,
- },
- /// Used to indicate that a channel_update should be sent to a single peer.
- /// In contrast to [`Self::BroadcastChannelUpdate`], this is used when the channel is a
- /// private channel and we shouldn't be informing all of our peers of channel parameters.
- SendChannelUpdate {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The channel_update which should be sent.
- msg: msgs::ChannelUpdate,
- },
- /// Broadcast an error downstream to be handled
- HandleError {
- /// The node_id of the node which should receive this message
- node_id: PublicKey,
- /// The action which should be taken.
- action: msgs::ErrorAction
- },
- /// Query a peer for channels with funding transaction UTXOs in a block range.
- SendChannelRangeQuery {
- /// The node_id of this message recipient
- node_id: PublicKey,
- /// The query_channel_range which should be sent.
- msg: msgs::QueryChannelRange,
- },
- /// Request routing gossip messages from a peer for a list of channels identified by
- /// their short_channel_ids.
- SendShortIdsQuery {
- /// The node_id of this message recipient
- node_id: PublicKey,
- /// The query_short_channel_ids which should be sent.
- msg: msgs::QueryShortChannelIds,
- },
- /// Sends a reply to a channel range query. This may be one of several SendReplyChannelRange events
- /// emitted during processing of the query.
- SendReplyChannelRange {
- /// The node_id of this message recipient
- node_id: PublicKey,
- /// The reply_channel_range which should be sent.
- msg: msgs::ReplyChannelRange,
- },
- /// Sends a timestamp filter for inbound gossip. This should be sent on each new connection to
- /// enable receiving gossip messages from the peer.
- SendGossipTimestampFilter {
- /// The node_id of this message recipient
- node_id: PublicKey,
- /// The gossip_timestamp_filter which should be sent.
- msg: msgs::GossipTimestampFilter,
- },
-}
-
-/// A trait indicating an object may generate message send events
-pub trait MessageSendEventsProvider {
- /// Gets the list of pending events which were generated by previous actions, clearing the list
- /// in the process.
- fn get_and_clear_pending_msg_events(&self) -> Vec<MessageSendEvent>;
-}
-
-/// 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<msgs::OnionMessage>;
-}
-
-/// A trait indicating an object may generate events.
-///
-/// Events are processed by passing an [`EventHandler`] to [`process_pending_events`].
-///
-/// Implementations of this trait may also feature an async version of event handling, as shown with
-/// [`ChannelManager::process_pending_events_async`] and
-/// [`ChainMonitor::process_pending_events_async`].
-///
-/// # Requirements
-///
-/// When using this trait, [`process_pending_events`] will call [`handle_event`] for each pending
-/// event since the last invocation.
-///
-/// In order to ensure no [`Event`]s are lost, implementors of this trait will persist [`Event`]s
-/// and replay any unhandled events on startup. An [`Event`] is considered handled when
-/// [`process_pending_events`] returns, thus handlers MUST fully handle [`Event`]s and persist any
-/// relevant changes to disk *before* returning.
-///
-/// Further, because an application may crash between an [`Event`] being handled and the
-/// implementor of this trait being re-serialized, [`Event`] handling must be idempotent - in
-/// effect, [`Event`]s may be replayed.
-///
-/// Note, handlers may call back into the provider and thus deadlocking must be avoided. Be sure to
-/// consult the provider's documentation on the implication of processing events and how a handler
-/// may safely use the provider (e.g., see [`ChannelManager::process_pending_events`] and
-/// [`ChainMonitor::process_pending_events`]).
-///
-/// (C-not implementable) As there is likely no reason for a user to implement this trait on their
-/// own type(s).
-///
-/// [`process_pending_events`]: Self::process_pending_events
-/// [`handle_event`]: EventHandler::handle_event
-/// [`ChannelManager::process_pending_events`]: crate::ln::channelmanager::ChannelManager#method.process_pending_events
-/// [`ChainMonitor::process_pending_events`]: crate::chain::chainmonitor::ChainMonitor#method.process_pending_events
-/// [`ChannelManager::process_pending_events_async`]: crate::ln::channelmanager::ChannelManager::process_pending_events_async
-/// [`ChainMonitor::process_pending_events_async`]: crate::chain::chainmonitor::ChainMonitor::process_pending_events_async
-pub trait EventsProvider {
- /// Processes any events generated since the last call using the given event handler.
- ///
- /// See the trait-level documentation for requirements.
- fn process_pending_events<H: Deref>(&self, handler: H) where H::Target: EventHandler;
-}
-
-/// A trait implemented for objects handling events from [`EventsProvider`].
-///
-/// An async variation also exists for implementations of [`EventsProvider`] that support async
-/// event handling. The async event handler should satisfy the generic bounds: `F:
-/// core::future::Future, H: Fn(Event) -> F`.
-pub trait EventHandler {
- /// Handles the given [`Event`].
- ///
- /// See [`EventsProvider`] for details that must be considered when implementing this method.
- fn handle_event(&self, event: Event);
-}
-
-impl<F> EventHandler for F where F: Fn(Event) {
- fn handle_event(&self, event: Event) {
- self(event)
- }
-}
-
-impl<T: EventHandler> EventHandler for Arc<T> {
- fn handle_event(&self, event: Event) {
- self.deref().handle_event(event)
- }
-}
/// actually backed by a [`HashMap`], with some additional tracking to ensure we can iterate over
/// keys in the order defined by [`Ord`].
///
-/// (C-not exported) as bindings provide alternate accessors rather than exposing maps directly.
+/// This is not exported to bindings users as bindings provide alternate accessors rather than exposing maps directly.
///
/// [`BTreeMap`]: alloc::collections::BTreeMap
#[derive(Clone, Debug, Eq)]
/// An iterator over a range of values in an [`IndexedMap`]
///
-/// (C-not exported) as bindings provide alternate accessors rather than exposing maps directly.
+/// This is not exported to bindings users as bindings provide alternate accessors rather than exposing maps directly.
pub struct Range<'a, K: Hash + Ord, V> {
inner_range: Iter<'a, K>,
map: &'a HashMap<K, V>,
/// An [`Entry`] for a key which currently has no value
///
-/// (C-not exported) as bindings provide alternate accessors rather than exposing maps directly.
+/// This is not exported to bindings users as bindings provide alternate accessors rather than exposing maps directly.
pub struct VacantEntry<'a, K: Hash + Ord, V> {
#[cfg(feature = "hashbrown")]
underlying_entry: hash_map::VacantEntry<'a, K, V, hash_map::DefaultHashBuilder>,
/// An [`Entry`] for an existing key-value pair
///
-/// (C-not exported) as bindings provide alternate accessors rather than exposing maps directly.
+/// This is not exported to bindings users as bindings provide alternate accessors rather than exposing maps directly.
pub struct OccupiedEntry<'a, K: Hash + Ord, V> {
#[cfg(feature = "hashbrown")]
underlying_entry: hash_map::OccupiedEntry<'a, K, V, hash_map::DefaultHashBuilder>,
/// A mutable reference to a position in the map. This can be used to reference, add, or update the
/// value at a fixed key.
///
-/// (C-not exported) as bindings provide alternate accessors rather than exposing maps directly.
+/// This is not exported to bindings users as bindings provide alternate accessors rather than exposing maps directly.
pub enum Entry<'a, K: Hash + Ord, V> {
/// A mutable reference to a position within the map where there is no value.
Vacant(VacantEntry<'a, K, V>),
impl<'a> Record<'a> {
/// Returns a new Record.
- /// (C-not exported) as fmt can't be used in C
+ ///
+ /// This is not exported to bindings users as fmt can't be used in C
#[inline]
pub fn new(level: Level, args: fmt::Arguments<'a>, module_path: &'static str, file: &'static str, line: u32) -> Record<'a> {
Record {
}
/// Wrapper for logging a [`PublicKey`] in hex format.
-/// (C-not exported) as fmt can't be used in C
+///
+/// This is not exported to bindings users as fmt can't be used in C
#[doc(hidden)]
pub struct DebugPubKey<'a>(pub &'a PublicKey);
impl<'a> core::fmt::Display for DebugPubKey<'a> {
}
/// Wrapper for logging byte slices in hex format.
-/// (C-not exported) as fmt can't be used in C
+///
+/// This is not exported to bindings users as fmt can't be used in C
#[doc(hidden)]
pub struct DebugBytes<'a>(pub &'a [u8]);
impl<'a> core::fmt::Display for DebugBytes<'a> {
#[macro_use]
pub mod ser_macros;
-pub mod events;
pub mod errors;
pub mod ser;
pub mod message_signing;
/// A simplified version of [`std::io::Write`] that exists largely for backwards compatibility.
/// An impl is provided for any type that also impls [`std::io::Write`].
///
-/// (C-not exported) as we only export serialization to/from byte arrays instead
+/// This is not exported to bindings users as we only export serialization to/from byte arrays instead
pub trait Writer {
/// Writes the given buf out. See std::io::Write::write_all for more
fn write_all(&mut self, buf: &[u8]) -> Result<(), io::Error>;
/// Writer that only tracks the amount of data written - useful if you need to calculate the length
/// of some data when serialized but don't yet need the full data.
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct LengthCalculatingWriter(pub usize);
impl Writer for LengthCalculatingWriter {
#[inline]
/// Essentially [`std::io::Take`] but a bit simpler and with a method to walk the underlying stream
/// forward to ensure we always consume exactly the fixed length specified.
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct FixedLengthReader<R: Read> {
read: R,
bytes_read: u64,
/// A [`Read`] implementation which tracks whether any bytes have been read at all. This allows us to distinguish
/// between "EOF reached before we started" and "EOF reached mid-read".
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct ReadTrackingReader<R: Read> {
read: R,
/// Returns whether we have read from this reader or not yet.
/// A trait that various LDK types implement allowing them to be written out to a [`Writer`].
///
-/// (C-not exported) as we only export serialization to/from byte arrays instead
+/// This is not exported to bindings users as we only export serialization to/from byte arrays instead
pub trait Writeable {
/// Writes `self` out to the given [`Writer`].
fn write<W: Writer>(&self, writer: &mut W) -> Result<(), io::Error>;
/// A trait that various LDK types implement allowing them to be read in from a [`Read`].
///
-/// (C-not exported) as we only export serialization to/from byte arrays instead
+/// This is not exported to bindings users as we only export serialization to/from byte arrays instead
pub trait Readable
where Self: Sized
{
/// A trait that various higher-level LDK types implement allowing them to be read in
/// from a [`Read`] given some additional set of arguments which is required to deserialize.
///
-/// (C-not exported) as we only export serialization to/from byte arrays instead
+/// This is not exported to bindings users as we only export serialization to/from byte arrays instead
pub trait ReadableArgs<P>
where Self: Sized
{
/// A trait that various LDK types implement allowing them to (maybe) be read in from a [`Read`].
///
-/// (C-not exported) as we only export serialization to/from byte arrays instead
+/// This is not exported to bindings users as we only export serialization to/from byte arrays instead
pub trait MaybeReadable
where Self: Sized
{
/// Wrapper to read a required (non-optional) TLV record.
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct RequiredWrapper<T>(pub Option<T>);
impl<T: Readable> Readable for RequiredWrapper<T> {
#[inline]
/// Wrapper to read a required (non-optional) TLV record that may have been upgraded without
/// backwards compat.
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct UpgradableRequired<T: MaybeReadable>(pub Option<T>);
impl<T: MaybeReadable> MaybeReadable for UpgradableRequired<T> {
#[inline]
/// A type for variable-length values within TLV record where the length is encoded as part of the record.
/// Used to prevent encoding the length twice.
///
-/// (C-not exported) as manual TLV building is not currently supported in bindings
+/// This is not exported to bindings users as manual TLV building is not currently supported in bindings
pub struct WithoutLength<T>(pub T);
impl Writeable for WithoutLength<&String> {
//! Utilities for strings.
+use alloc::string::String;
use core::fmt;
+use crate::io::{self, Read};
+use crate::ln::msgs;
+use crate::util::ser::{Writeable, Writer, Readable};
+
+/// Struct to `Display` fields in a safe way using `PrintableString`
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct UntrustedString(pub String);
+
+impl Writeable for UntrustedString {
+ fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
+ self.0.write(w)
+ }
+}
+
+impl Readable for UntrustedString {
+ fn read<R: Read>(r: &mut R) -> Result<Self, msgs::DecodeError> {
+ let s: String = Readable::read(r)?;
+ Ok(Self(s))
+ }
+}
+
+impl fmt::Display for UntrustedString {
+ fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+ PrintableString(&self.0).fmt(f)
+ }
+}
/// A string that displays only printable characters, replacing control characters with
/// [`core::char::REPLACEMENT_CHARACTER`].
use crate::chain::channelmonitor::MonitorEvent;
use crate::chain::transaction::OutPoint;
use crate::chain::keysinterface;
+use crate::events;
use crate::ln::channelmanager;
use crate::ln::features::{ChannelFeatures, InitFeatures, NodeFeatures};
use crate::ln::{msgs, wire};
use crate::routing::scoring::{ChannelUsage, Score};
use crate::util::config::UserConfig;
use crate::util::enforcing_trait_impls::{EnforcingSigner, EnforcementState};
-use crate::util::events;
use crate::util::logger::{Logger, Level, Record};
use crate::util::ser::{Readable, ReadableArgs, Writer, Writeable};
/// Registers a callback to be called upon completion of this future. If the future has already
/// completed, the callback will be called immediately.
///
- /// (C-not exported) use the bindings-only `register_callback_fn` instead
+ /// This is not exported to bindings users, use the bindings-only `register_callback_fn` instead
pub fn register_callback(&self, callback: Box<dyn FutureCallback>) {
let mut state = self.state.lock().unwrap();
if state.complete {
fn call(&self) { self.0.wake_by_ref() }
}
-/// (C-not exported) as Rust Futures aren't usable in language bindings.
+/// This is not exported to bindings users as Rust Futures aren't usable in language bindings.
impl<'a> StdFuture for Future {
type Output = ();
projects / rust-lightning / commitdiff