X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning%2Fchain%2Fchainmonitor.rs;h=a70ceb015cf58d27320d340a2ad3d063a7421b0c;hb=3e46e1794f14640e35f09cc6da4169c152de34ce;hp=9faddada0b0ed3041f9befda51b58d25d2868e61;hpb=f87b75f30a64032b1d76a13fa45233bc4ceecf86;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/lightning/chain/chainmonitor.rs b/lightning-c-bindings/src/lightning/chain/chainmonitor.rs index 9faddad..a70ceb0 100644 --- a/lightning-c-bindings/src/lightning/chain/chainmonitor.rs +++ b/lightning-c-bindings/src/lightning/chain/chainmonitor.rs @@ -23,6 +23,7 @@ //! servicing [`ChannelMonitor`] updates from the client. use alloc::str::FromStr; +use alloc::string::String; use core::ffi::c_void; use core::convert::Infallible; use bitcoin::hashes::Hash; @@ -30,6 +31,18 @@ use crate::c_types::*; #[cfg(feature="no-std")] use alloc::{vec::Vec, boxed::Box}; +mod update_origin { + +use alloc::str::FromStr; +use alloc::string::String; +use core::ffi::c_void; +use core::convert::Infallible; +use bitcoin::hashes::Hash; +use crate::c_types::*; +#[cfg(feature="no-std")] +use alloc::{vec::Vec, boxed::Box}; + +} use lightning::chain::chainmonitor::MonitorUpdateId as nativeMonitorUpdateIdImport; pub(crate) type nativeMonitorUpdateId = nativeMonitorUpdateIdImport; @@ -100,7 +113,7 @@ pub(crate) extern "C" fn MonitorUpdateId_clone_void(this_ptr: *const c_void) -> pub extern "C" fn MonitorUpdateId_clone(orig: &MonitorUpdateId) -> MonitorUpdateId { orig.clone() } -/// Checks if two MonitorUpdateIds contain equal inner contents. +/// Generates a non-cryptographic 64-bit hash of the MonitorUpdateId. #[no_mangle] pub extern "C" fn MonitorUpdateId_hash(o: &MonitorUpdateId) -> u64 { if o.inner.is_null() { return 0; } @@ -122,23 +135,58 @@ pub extern "C" fn MonitorUpdateId_eq(a: &MonitorUpdateId, b: &MonitorUpdateId) - /// `Persist` defines behavior for persisting channel monitors: this could mean /// writing once to disk, and/or uploading to one or more backup services. /// -/// Each method can return three possible values: -/// * If persistence (including any relevant `fsync()` calls) happens immediately, the -/// implementation should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal -/// channel operation should continue. -/// * If persistence happens asynchronously, implementations should first ensure the -/// [`ChannelMonitor`] or [`ChannelMonitorUpdate`] are written durably to disk, and then return -/// [`ChannelMonitorUpdateStatus::InProgress`] while the update continues in the background. -/// Once the update completes, [`ChainMonitor::channel_monitor_updated`] should be called with -/// the corresponding [`MonitorUpdateId`]. +/// Persistence can happen in one of two ways - synchronously completing before the trait method +/// calls return or asynchronously in the background. +/// +/// # For those implementing synchronous persistence +/// +/// * If persistence completes fully (including any relevant `fsync()` calls), the implementation +/// should return [`ChannelMonitorUpdateStatus::Completed`], indicating normal channel operation +/// should continue. +/// +/// * If persistence fails for some reason, implementations should consider returning +/// [`ChannelMonitorUpdateStatus::InProgress`] and retry all pending persistence operations in +/// the background with [`ChainMonitor::list_pending_monitor_updates`] and +/// [`ChainMonitor::get_monitor`]. +/// +/// Once a full [`ChannelMonitor`] has been persisted, all pending updates for that channel can +/// be marked as complete via [`ChainMonitor::channel_monitor_updated`]. +/// +/// If at some point no further progress can be made towards persisting the pending updates, the +/// node should simply shut down. +/// +/// * If the persistence has failed and cannot be retried further (e.g. because of an outage), +/// [`ChannelMonitorUpdateStatus::UnrecoverableError`] can be used, though this will result in +/// an immediate panic and future operations in LDK generally failing. +/// +/// # For those implementing asynchronous persistence +/// +/// All calls should generally spawn a background task and immediately return +/// [`ChannelMonitorUpdateStatus::InProgress`]. Once the update completes, +/// [`ChainMonitor::channel_monitor_updated`] should be called with the corresponding +/// [`MonitorUpdateId`]. /// -/// Note that unlike the direct [`chain::Watch`] interface, -/// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs. +/// Note that unlike the direct [`chain::Watch`] interface, +/// [`ChainMonitor::channel_monitor_updated`] must be called once for *each* update which occurs. /// -/// * If persistence fails for some reason, implementations should return -/// [`ChannelMonitorUpdateStatus::PermanentFailure`], in which case the channel will likely be -/// closed without broadcasting the latest state. See -/// [`ChannelMonitorUpdateStatus::PermanentFailure`] for more details. +/// If at some point no further progress can be made towards persisting a pending update, the node +/// should simply shut down. Until then, the background task should either loop indefinitely, or +/// persistence should be regularly retried with [`ChainMonitor::list_pending_monitor_updates`] +/// and [`ChainMonitor::get_monitor`] (note that if a full monitor is persisted all pending +/// monitor updates may be marked completed). +/// +/// # Using remote watchtowers +/// +/// Watchtowers may be updated as a part of an implementation of this trait, utilizing the async +/// update process described above while the watchtower is being updated. The following methods are +/// provided for bulding transactions for a watchtower: +/// [`ChannelMonitor::initial_counterparty_commitment_tx`], +/// [`ChannelMonitor::counterparty_commitment_txs_from_update`], +/// [`ChannelMonitor::sign_to_local_justice_tx`], [`TrustedCommitmentTransaction::revokeable_output_index`], +/// [`TrustedCommitmentTransaction::build_to_local_justice_tx`]. +/// +/// [`TrustedCommitmentTransaction::revokeable_output_index`]: crate::ln::chan_utils::TrustedCommitmentTransaction::revokeable_output_index +/// [`TrustedCommitmentTransaction::build_to_local_justice_tx`]: crate::ln::chan_utils::TrustedCommitmentTransaction::build_to_local_justice_tx #[repr(C)] pub struct Persist { /// An opaque pointer which is passed to your function implementations as an argument. @@ -159,7 +207,6 @@ pub struct Persist { /// /// [`ChannelManager`]: crate::ln::channelmanager::ChannelManager /// [`Writeable::write`]: crate::util::ser::Writeable::write - #[must_use] pub persist_new_channel: extern "C" fn (this_arg: *const c_void, channel_id: crate::lightning::chain::transaction::OutPoint, data: &crate::lightning::chain::channelmonitor::ChannelMonitor, update_id: crate::lightning::chain::chainmonitor::MonitorUpdateId) -> crate::lightning::chain::ChannelMonitorUpdateStatus, /// Update one channel's data. The provided [`ChannelMonitor`] has already applied the given /// update. @@ -168,8 +215,8 @@ pub struct Persist { /// updated monitor itself to disk/backups. See the [`Persist`] trait documentation for more /// details. /// - /// During blockchain synchronization operations, this may be called with no - /// [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. + /// During blockchain synchronization operations, and in some rare cases, this may be called with + /// no [`ChannelMonitorUpdate`], in which case the full [`ChannelMonitor`] needs to be persisted. /// Note that after the full [`ChannelMonitor`] is persisted any previous /// [`ChannelMonitorUpdate`]s which were persisted should be discarded - they can no longer be /// applied to the persisted [`ChannelMonitor`] as they were already applied. @@ -196,16 +243,14 @@ pub struct Persist { /// [`Writeable::write`]: crate::util::ser::Writeable::write /// /// Note that update (or a relevant inner pointer) may be NULL or all-0s to represent None - #[must_use] - pub update_persisted_channel: extern "C" fn (this_arg: *const c_void, channel_id: crate::lightning::chain::transaction::OutPoint, update: &crate::lightning::chain::channelmonitor::ChannelMonitorUpdate, data: &crate::lightning::chain::channelmonitor::ChannelMonitor, update_id: crate::lightning::chain::chainmonitor::MonitorUpdateId) -> crate::lightning::chain::ChannelMonitorUpdateStatus, + pub update_persisted_channel: extern "C" fn (this_arg: *const c_void, channel_id: crate::lightning::chain::transaction::OutPoint, update: crate::lightning::chain::channelmonitor::ChannelMonitorUpdate, data: &crate::lightning::chain::channelmonitor::ChannelMonitor, update_id: crate::lightning::chain::chainmonitor::MonitorUpdateId) -> crate::lightning::chain::ChannelMonitorUpdateStatus, /// Frees any resources associated with this object given its this_arg pointer. /// Does not need to free the outer struct containing function pointers and may be NULL is no resources need to be freed. pub free: Option, } unsafe impl Send for Persist {} unsafe impl Sync for Persist {} -#[no_mangle] -pub(crate) extern "C" fn Persist_clone_fields(orig: &Persist) -> Persist { +pub(crate) fn Persist_clone_fields(orig: &Persist) -> Persist { Persist { this_arg: orig.this_arg, persist_new_channel: Clone::clone(&orig.persist_new_channel), @@ -215,13 +260,13 @@ pub(crate) extern "C" fn Persist_clone_fields(orig: &Persist) -> Persist { } use lightning::chain::chainmonitor::Persist as rustPersist; -impl rustPersist for Persist { - fn persist_new_channel(&self, mut channel_id: lightning::chain::transaction::OutPoint, mut data: &lightning::chain::channelmonitor::ChannelMonitor, mut update_id: lightning::chain::chainmonitor::MonitorUpdateId) -> lightning::chain::ChannelMonitorUpdateStatus { +impl rustPersist for Persist { + fn persist_new_channel(&self, mut channel_id: lightning::chain::transaction::OutPoint, mut data: &lightning::chain::channelmonitor::ChannelMonitor, mut update_id: lightning::chain::chainmonitor::MonitorUpdateId) -> lightning::chain::ChannelMonitorUpdateStatus { let mut ret = (self.persist_new_channel)(self.this_arg, crate::lightning::chain::transaction::OutPoint { inner: ObjOps::heap_alloc(channel_id), is_owned: true }, &crate::lightning::chain::channelmonitor::ChannelMonitor { inner: unsafe { ObjOps::nonnull_ptr_to_inner((data as *const lightning::chain::channelmonitor::ChannelMonitor<_, >) as *mut _) }, is_owned: false }, crate::lightning::chain::chainmonitor::MonitorUpdateId { inner: ObjOps::heap_alloc(update_id), is_owned: true }); ret.into_native() } - fn update_persisted_channel(&self, mut channel_id: lightning::chain::transaction::OutPoint, mut update: &Option, mut data: &lightning::chain::channelmonitor::ChannelMonitor, mut update_id: lightning::chain::chainmonitor::MonitorUpdateId) -> lightning::chain::ChannelMonitorUpdateStatus { - let mut local_update = &crate::lightning::chain::channelmonitor::ChannelMonitorUpdate { inner: unsafe { (if update.is_none() { core::ptr::null() } else { ObjOps::nonnull_ptr_to_inner( { (update.as_ref().unwrap()) }) } as *const lightning::chain::channelmonitor::ChannelMonitorUpdate<>) as *mut _ }, is_owned: false }; + fn update_persisted_channel(&self, mut channel_id: lightning::chain::transaction::OutPoint, mut update: Option<&lightning::chain::channelmonitor::ChannelMonitorUpdate>, mut data: &lightning::chain::channelmonitor::ChannelMonitor, mut update_id: lightning::chain::chainmonitor::MonitorUpdateId) -> lightning::chain::ChannelMonitorUpdateStatus { + let mut local_update = crate::lightning::chain::channelmonitor::ChannelMonitorUpdate { inner: unsafe { (if update.is_none() { core::ptr::null() } else { ObjOps::nonnull_ptr_to_inner( { (update.unwrap()) }) } as *const lightning::chain::channelmonitor::ChannelMonitorUpdate<>) as *mut _ }, is_owned: false }; let mut ret = (self.update_persisted_channel)(self.this_arg, crate::lightning::chain::transaction::OutPoint { inner: ObjOps::heap_alloc(channel_id), is_owned: true }, local_update, &crate::lightning::chain::channelmonitor::ChannelMonitor { inner: unsafe { ObjOps::nonnull_ptr_to_inner((data as *const lightning::chain::channelmonitor::ChannelMonitor<_, >) as *mut _) }, is_owned: false }, crate::lightning::chain::chainmonitor::MonitorUpdateId { inner: ObjOps::heap_alloc(update_id), is_owned: true }); ret.into_native() } @@ -235,6 +280,11 @@ impl core::ops::Deref for Persist { self } } +impl core::ops::DerefMut for Persist { + fn deref_mut(&mut self) -> &mut Self { + self + } +} /// Calls the free function if one is set #[no_mangle] pub extern "C" fn Persist_free(this_ptr: Persist) { } @@ -247,7 +297,7 @@ impl Drop for Persist { } use lightning::chain::chainmonitor::LockedChannelMonitor as nativeLockedChannelMonitorImport; -pub(crate) type nativeLockedChannelMonitor = nativeLockedChannelMonitorImport<'static, crate::lightning::chain::keysinterface::Sign>; +pub(crate) type nativeLockedChannelMonitor = nativeLockedChannelMonitorImport<'static, crate::lightning::sign::WriteableEcdsaChannelSigner>; /// A read-only reference to a current ChannelMonitor. /// @@ -301,7 +351,7 @@ impl LockedChannelMonitor { } use lightning::chain::chainmonitor::ChainMonitor as nativeChainMonitorImport; -pub(crate) type nativeChainMonitor = nativeChainMonitorImport; +pub(crate) type nativeChainMonitor = nativeChainMonitorImport; /// An implementation of [`chain::Watch`] for monitoring channels. /// @@ -310,8 +360,15 @@ pub(crate) type nativeChainMonitor = nativeChainMonitorImport crate::lightning::chain::chainmonitor::ChainMonitor { - let mut local_chain_source = { /* chain_source*/ let chain_source_opt = chain_source; { } if chain_source_opt.is_none() { None } else { Some({ chain_source_opt.take() }) } }; + let mut local_chain_source = { /*chain_source*/ let chain_source_opt = chain_source; if chain_source_opt.is_none() { None } else { Some({ { { chain_source_opt.take() } }})} }; let mut ret = lightning::chain::chainmonitor::ChainMonitor::new(local_chain_source, broadcaster, logger, feeest, persister); crate::lightning::chain::chainmonitor::ChainMonitor { inner: ObjOps::heap_alloc(ret), is_owned: true } } @@ -446,6 +503,31 @@ pub extern "C" fn ChainMonitor_channel_monitor_updated(this_arg: &crate::lightni local_ret } +/// Gets a [`Future`] that completes when an event is available either via +/// [`chain::Watch::release_pending_monitor_events`] or +/// [`EventsProvider::process_pending_events`]. +/// +/// Note that callbacks registered on the [`Future`] MUST NOT call back into this +/// [`ChainMonitor`] and should instead register actions to be taken later. +/// +/// [`EventsProvider::process_pending_events`]: crate::events::EventsProvider::process_pending_events +#[must_use] +#[no_mangle] +pub extern "C" fn ChainMonitor_get_update_future(this_arg: &crate::lightning::chain::chainmonitor::ChainMonitor) -> crate::lightning::util::wakers::Future { + let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.get_update_future(); + crate::lightning::util::wakers::Future { inner: ObjOps::heap_alloc(ret), is_owned: true } +} + +/// Triggers rebroadcasts/fee-bumps of pending claims from a force-closed channel. This is +/// crucial in preventing certain classes of pinning attacks, detecting substantial mempool +/// feerate changes between blocks, and ensuring reliability if broadcasting fails. We recommend +/// invoking this every 30 seconds, or lower if running in an environment with spotty +/// connections, like on mobile. +#[no_mangle] +pub extern "C" fn ChainMonitor_rebroadcast_pending_claims(this_arg: &crate::lightning::chain::chainmonitor::ChainMonitor) { + unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.rebroadcast_pending_claims() +} + impl From for crate::lightning::chain::Listen { fn from(obj: nativeChainMonitor) -> Self { let mut rust_obj = ChainMonitor { inner: ObjOps::heap_alloc(obj), is_owned: true }; @@ -515,9 +597,9 @@ extern "C" fn ChainMonitor_Confirm_best_block_updated(this_arg: *const c_void, h >::best_block_updated(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, &::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), height) } #[must_use] -extern "C" fn ChainMonitor_Confirm_get_relevant_txids(this_arg: *const c_void) -> crate::c_types::derived::CVec_C2Tuple_TxidBlockHashZZ { +extern "C" fn ChainMonitor_Confirm_get_relevant_txids(this_arg: *const c_void) -> crate::c_types::derived::CVec_C2Tuple_ThirtyTwoBytesCOption_ThirtyTwoBytesZZZ { let mut ret = >::get_relevant_txids(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, ); - let mut local_ret = Vec::new(); for mut item in ret.drain(..) { local_ret.push( { let (mut orig_ret_0_0, mut orig_ret_0_1) = item; let mut local_orig_ret_0_1 = if orig_ret_0_1.is_none() { crate::c_types::ThirtyTwoBytes::null() } else { { crate::c_types::ThirtyTwoBytes { data: (orig_ret_0_1.unwrap()).into_inner() } } }; let mut local_ret_0 = (crate::c_types::ThirtyTwoBytes { data: orig_ret_0_0.into_inner() }, local_orig_ret_0_1).into(); local_ret_0 }); }; + let mut local_ret = Vec::new(); for mut item in ret.drain(..) { local_ret.push( { let (mut orig_ret_0_0, mut orig_ret_0_1) = item; let mut local_orig_ret_0_1 = if orig_ret_0_1.is_none() { crate::c_types::derived::COption_ThirtyTwoBytesZ::None } else { crate::c_types::derived::COption_ThirtyTwoBytesZ::Some( { crate::c_types::ThirtyTwoBytes { data: orig_ret_0_1.unwrap().into_inner() } }) }; let mut local_ret_0 = (crate::c_types::ThirtyTwoBytes { data: orig_ret_0_0.into_inner() }, local_orig_ret_0_1).into(); local_ret_0 }); }; local_ret.into() } @@ -545,13 +627,14 @@ pub extern "C" fn ChainMonitor_as_Watch(this_arg: &ChainMonitor) -> crate::light } #[must_use] -extern "C" fn ChainMonitor_Watch_watch_channel(this_arg: *const c_void, mut funding_txo: crate::lightning::chain::transaction::OutPoint, mut monitor: crate::lightning::chain::channelmonitor::ChannelMonitor) -> crate::lightning::chain::ChannelMonitorUpdateStatus { +extern "C" fn ChainMonitor_Watch_watch_channel(this_arg: *const c_void, mut funding_txo: crate::lightning::chain::transaction::OutPoint, mut monitor: crate::lightning::chain::channelmonitor::ChannelMonitor) -> crate::c_types::derived::CResult_ChannelMonitorUpdateStatusNoneZ { let mut ret = >::watch_channel(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, *unsafe { Box::from_raw(funding_txo.take_inner()) }, *unsafe { Box::from_raw(monitor.take_inner()) }); - crate::lightning::chain::ChannelMonitorUpdateStatus::native_into(ret) + let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { crate::lightning::chain::ChannelMonitorUpdateStatus::native_into(o) }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { () /*e*/ }).into() }; + local_ret } #[must_use] -extern "C" fn ChainMonitor_Watch_update_channel(this_arg: *const c_void, mut funding_txo: crate::lightning::chain::transaction::OutPoint, mut update: crate::lightning::chain::channelmonitor::ChannelMonitorUpdate) -> crate::lightning::chain::ChannelMonitorUpdateStatus { - let mut ret = >::update_channel(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, *unsafe { Box::from_raw(funding_txo.take_inner()) }, *unsafe { Box::from_raw(update.take_inner()) }); +extern "C" fn ChainMonitor_Watch_update_channel(this_arg: *const c_void, mut funding_txo: crate::lightning::chain::transaction::OutPoint, update: &crate::lightning::chain::channelmonitor::ChannelMonitorUpdate) -> crate::lightning::chain::ChannelMonitorUpdateStatus { + let mut ret = >::update_channel(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, *unsafe { Box::from_raw(funding_txo.take_inner()) }, update.get_native_ref()); crate::lightning::chain::ChannelMonitorUpdateStatus::native_into(ret) } #[must_use] @@ -561,7 +644,7 @@ extern "C" fn ChainMonitor_Watch_release_pending_monitor_events(this_arg: *const local_ret.into() } -impl From for crate::lightning::util::events::EventsProvider { +impl From for crate::lightning::events::EventsProvider { fn from(obj: nativeChainMonitor) -> Self { let mut rust_obj = ChainMonitor { inner: ObjOps::heap_alloc(obj), is_owned: true }; let mut ret = ChainMonitor_as_EventsProvider(&rust_obj); @@ -574,15 +657,15 @@ impl From for crate::lightning::util::events::EventsProvider /// Constructs a new EventsProvider which calls the relevant methods on this_arg. /// This copies the `inner` pointer in this_arg and thus the returned EventsProvider must be freed before this_arg is #[no_mangle] -pub extern "C" fn ChainMonitor_as_EventsProvider(this_arg: &ChainMonitor) -> crate::lightning::util::events::EventsProvider { - crate::lightning::util::events::EventsProvider { +pub extern "C" fn ChainMonitor_as_EventsProvider(this_arg: &ChainMonitor) -> crate::lightning::events::EventsProvider { + crate::lightning::events::EventsProvider { this_arg: unsafe { ObjOps::untweak_ptr((*this_arg).inner) as *mut c_void }, free: None, process_pending_events: ChainMonitor_EventsProvider_process_pending_events, } } -extern "C" fn ChainMonitor_EventsProvider_process_pending_events(this_arg: *const c_void, mut handler: crate::lightning::util::events::EventHandler) { - >::process_pending_events(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, handler) +extern "C" fn ChainMonitor_EventsProvider_process_pending_events(this_arg: *const c_void, mut handler: crate::lightning::events::EventHandler) { + >::process_pending_events(unsafe { &mut *(this_arg as *mut nativeChainMonitor) }, handler) }