X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Flightning%2Fchain%2Fchannelmonitor.rs;h=88fcd36749e73b3d3642cb7997d95672a5c7ce33;hb=709706e247c4210ce80f54b597b4e5d5607f3fed;hp=df25ef63585ca540c26111113488ee8a90d69d92;hpb=45ad3320df3768514d968c70fc4b6a9d50028050;p=ldk-c-bindings diff --git a/lightning-c-bindings/src/lightning/chain/channelmonitor.rs b/lightning-c-bindings/src/lightning/chain/channelmonitor.rs index df25ef6..88fcd36 100644 --- a/lightning-c-bindings/src/lightning/chain/channelmonitor.rs +++ b/lightning-c-bindings/src/lightning/chain/channelmonitor.rs @@ -31,8 +31,13 @@ use alloc::{vec::Vec, boxed::Box}; use lightning::chain::channelmonitor::ChannelMonitorUpdate as nativeChannelMonitorUpdateImport; pub(crate) type nativeChannelMonitorUpdate = nativeChannelMonitorUpdateImport; -/// An update generated by the underlying Channel itself which contains some new information the -/// ChannelMonitor should be made aware of. +/// An update generated by the underlying channel itself which contains some new information the +/// [`ChannelMonitor`] should be made aware of. +/// +/// Because this represents only a small number of updates to the underlying state, it is generally +/// much smaller than a full [`ChannelMonitor`]. However, for large single commitment transaction +/// updates (e.g. ones during which there are hundreds of HTLCs pending on the commitment +/// transaction), a single update may reach upwards of 1 MiB in serialized size. #[must_use] #[repr(C)] pub struct ChannelMonitorUpdate { @@ -491,14 +496,37 @@ pub enum Balance { /// HTLCs which we sent to our counterparty which are claimable after a timeout (less on-chain /// fees) if the counterparty does not know the preimage for the HTLCs. These are somewhat /// likely to be claimed by our counterparty before we do. - MaybeClaimableHTLCAwaitingTimeout { - /// The amount available to claim, in satoshis, excluding the on-chain fees which will be - /// required to do so. + MaybeTimeoutClaimableHTLC { + /// The amount potentially available to claim, in satoshis, excluding the on-chain fees + /// which will be required to do so. claimable_amount_satoshis: u64, /// The height at which we will be able to claim the balance if our counterparty has not /// done so. claimable_height: u32, }, + /// HTLCs which we received from our counterparty which are claimable with a preimage which we + /// do not currently have. This will only be claimable if we receive the preimage from the node + /// to which we forwarded this HTLC before the timeout. + MaybePreimageClaimableHTLC { + /// The amount potentially available to claim, in satoshis, excluding the on-chain fees + /// which will be required to do so. + claimable_amount_satoshis: u64, + /// The height at which our counterparty will be able to claim the balance if we have not + /// yet received the preimage and claimed it ourselves. + expiry_height: u32, + }, + /// The channel has been closed, and our counterparty broadcasted a revoked commitment + /// transaction. + /// + /// Thus, we're able to claim all outputs in the commitment transaction, one of which has the + /// following amount. + CounterpartyRevokedOutputClaimable { + /// The amount, in satoshis, of the output which we can claim. + /// + /// Note that for outputs from HTLC balances this may be excluding some on-chain fees that + /// were already spent. + claimable_amount_satoshis: u64, + }, } use lightning::chain::channelmonitor::Balance as BalanceImport; pub(crate) type nativeBalance = BalanceImport; @@ -529,14 +557,28 @@ impl Balance { timeout_height: timeout_height_nonref, } }, - Balance::MaybeClaimableHTLCAwaitingTimeout {ref claimable_amount_satoshis, ref claimable_height, } => { + Balance::MaybeTimeoutClaimableHTLC {ref claimable_amount_satoshis, ref claimable_height, } => { let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); let mut claimable_height_nonref = (*claimable_height).clone(); - nativeBalance::MaybeClaimableHTLCAwaitingTimeout { + nativeBalance::MaybeTimeoutClaimableHTLC { claimable_amount_satoshis: claimable_amount_satoshis_nonref, claimable_height: claimable_height_nonref, } }, + Balance::MaybePreimageClaimableHTLC {ref claimable_amount_satoshis, ref expiry_height, } => { + let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); + let mut expiry_height_nonref = (*expiry_height).clone(); + nativeBalance::MaybePreimageClaimableHTLC { + claimable_amount_satoshis: claimable_amount_satoshis_nonref, + expiry_height: expiry_height_nonref, + } + }, + Balance::CounterpartyRevokedOutputClaimable {ref claimable_amount_satoshis, } => { + let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); + nativeBalance::CounterpartyRevokedOutputClaimable { + claimable_amount_satoshis: claimable_amount_satoshis_nonref, + } + }, } } #[allow(unused)] @@ -559,12 +601,23 @@ impl Balance { timeout_height: timeout_height, } }, - Balance::MaybeClaimableHTLCAwaitingTimeout {mut claimable_amount_satoshis, mut claimable_height, } => { - nativeBalance::MaybeClaimableHTLCAwaitingTimeout { + Balance::MaybeTimeoutClaimableHTLC {mut claimable_amount_satoshis, mut claimable_height, } => { + nativeBalance::MaybeTimeoutClaimableHTLC { claimable_amount_satoshis: claimable_amount_satoshis, claimable_height: claimable_height, } }, + Balance::MaybePreimageClaimableHTLC {mut claimable_amount_satoshis, mut expiry_height, } => { + nativeBalance::MaybePreimageClaimableHTLC { + claimable_amount_satoshis: claimable_amount_satoshis, + expiry_height: expiry_height, + } + }, + Balance::CounterpartyRevokedOutputClaimable {mut claimable_amount_satoshis, } => { + nativeBalance::CounterpartyRevokedOutputClaimable { + claimable_amount_satoshis: claimable_amount_satoshis, + } + }, } } #[allow(unused)] @@ -592,14 +645,28 @@ impl Balance { timeout_height: timeout_height_nonref, } }, - nativeBalance::MaybeClaimableHTLCAwaitingTimeout {ref claimable_amount_satoshis, ref claimable_height, } => { + nativeBalance::MaybeTimeoutClaimableHTLC {ref claimable_amount_satoshis, ref claimable_height, } => { let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); let mut claimable_height_nonref = (*claimable_height).clone(); - Balance::MaybeClaimableHTLCAwaitingTimeout { + Balance::MaybeTimeoutClaimableHTLC { claimable_amount_satoshis: claimable_amount_satoshis_nonref, claimable_height: claimable_height_nonref, } }, + nativeBalance::MaybePreimageClaimableHTLC {ref claimable_amount_satoshis, ref expiry_height, } => { + let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); + let mut expiry_height_nonref = (*expiry_height).clone(); + Balance::MaybePreimageClaimableHTLC { + claimable_amount_satoshis: claimable_amount_satoshis_nonref, + expiry_height: expiry_height_nonref, + } + }, + nativeBalance::CounterpartyRevokedOutputClaimable {ref claimable_amount_satoshis, } => { + let mut claimable_amount_satoshis_nonref = (*claimable_amount_satoshis).clone(); + Balance::CounterpartyRevokedOutputClaimable { + claimable_amount_satoshis: claimable_amount_satoshis_nonref, + } + }, } } #[allow(unused)] @@ -622,12 +689,23 @@ impl Balance { timeout_height: timeout_height, } }, - nativeBalance::MaybeClaimableHTLCAwaitingTimeout {mut claimable_amount_satoshis, mut claimable_height, } => { - Balance::MaybeClaimableHTLCAwaitingTimeout { + nativeBalance::MaybeTimeoutClaimableHTLC {mut claimable_amount_satoshis, mut claimable_height, } => { + Balance::MaybeTimeoutClaimableHTLC { claimable_amount_satoshis: claimable_amount_satoshis, claimable_height: claimable_height, } }, + nativeBalance::MaybePreimageClaimableHTLC {mut claimable_amount_satoshis, mut expiry_height, } => { + Balance::MaybePreimageClaimableHTLC { + claimable_amount_satoshis: claimable_amount_satoshis, + expiry_height: expiry_height, + } + }, + nativeBalance::CounterpartyRevokedOutputClaimable {mut claimable_amount_satoshis, } => { + Balance::CounterpartyRevokedOutputClaimable { + claimable_amount_satoshis: claimable_amount_satoshis, + } + }, } } } @@ -663,13 +741,28 @@ pub extern "C" fn Balance_contentious_claimable(claimable_amount_satoshis: u64, } } #[no_mangle] -/// Utility method to constructs a new MaybeClaimableHTLCAwaitingTimeout-variant Balance -pub extern "C" fn Balance_maybe_claimable_htlcawaiting_timeout(claimable_amount_satoshis: u64, claimable_height: u32) -> Balance { - Balance::MaybeClaimableHTLCAwaitingTimeout { +/// Utility method to constructs a new MaybeTimeoutClaimableHTLC-variant Balance +pub extern "C" fn Balance_maybe_timeout_claimable_htlc(claimable_amount_satoshis: u64, claimable_height: u32) -> Balance { + Balance::MaybeTimeoutClaimableHTLC { claimable_amount_satoshis, claimable_height, } } +#[no_mangle] +/// Utility method to constructs a new MaybePreimageClaimableHTLC-variant Balance +pub extern "C" fn Balance_maybe_preimage_claimable_htlc(claimable_amount_satoshis: u64, expiry_height: u32) -> Balance { + Balance::MaybePreimageClaimableHTLC { + claimable_amount_satoshis, + expiry_height, + } +} +#[no_mangle] +/// Utility method to constructs a new CounterpartyRevokedOutputClaimable-variant Balance +pub extern "C" fn Balance_counterparty_revoked_output_claimable(claimable_amount_satoshis: u64) -> Balance { + Balance::CounterpartyRevokedOutputClaimable { + claimable_amount_satoshis, + } +} /// Checks if two Balances contain equal inner contents. /// This ignores pointers and is_owned flags and looks at the values in fields. #[no_mangle] @@ -757,7 +850,7 @@ pub(crate) extern "C" fn ChannelMonitor_write_void(obj: *const c_void) -> crate: /// panics if the given update is not the next update by update_id. #[must_use] #[no_mangle] -pub extern "C" fn ChannelMonitor_update_monitor(this_arg: &crate::lightning::chain::channelmonitor::ChannelMonitor, updates: &crate::lightning::chain::channelmonitor::ChannelMonitorUpdate, broadcaster: &crate::lightning::chain::chaininterface::BroadcasterInterface, fee_estimator: &crate::lightning::chain::chaininterface::FeeEstimator, logger: &crate::lightning::util::logger::Logger) -> crate::c_types::derived::CResult_NoneNoneZ { +pub extern "C" fn ChannelMonitor_update_monitor(this_arg: &crate::lightning::chain::channelmonitor::ChannelMonitor, updates: &crate::lightning::chain::channelmonitor::ChannelMonitorUpdate, broadcaster: &crate::lightning::chain::chaininterface::BroadcasterInterface, mut fee_estimator: crate::lightning::chain::chaininterface::FeeEstimator, logger: &crate::lightning::util::logger::Logger) -> crate::c_types::derived::CResult_NoneNoneZ { let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.update_monitor(updates.get_native_ref(), broadcaster, fee_estimator, logger); let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { () /*o*/ }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { () /*e*/ }).into() }; local_ret @@ -823,6 +916,20 @@ pub extern "C" fn ChannelMonitor_get_and_clear_pending_events(this_arg: &crate:: local_ret.into() } +/// Gets the `node_id` of the counterparty for this channel. +/// +/// Will be `None` for channels constructed on LDK versions prior to 0.0.110 and always `Some` +/// otherwise. +/// +/// Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None +#[must_use] +#[no_mangle] +pub extern "C" fn ChannelMonitor_get_counterparty_node_id(this_arg: &crate::lightning::chain::channelmonitor::ChannelMonitor) -> crate::c_types::PublicKey { + let mut ret = unsafe { &*ObjOps::untweak_ptr(this_arg.inner) }.get_counterparty_node_id(); + let mut local_ret = if ret.is_none() { crate::c_types::PublicKey::null() } else { { crate::c_types::PublicKey::from_rust(&(ret.unwrap())) } }; + local_ret +} + /// Used by ChannelManager deserialization to broadcast the latest holder state if its copy of /// the Channel was out-of-date. You may use it to get a broadcastable holder toxic tx in case of /// fallen-behind, i.e when receiving a channel_reestablish with a proof that our counterparty side knows @@ -936,8 +1043,9 @@ pub extern "C" fn ChannelMonitor_current_best_block(this_arg: &crate::lightning: /// balance, or until our counterparty has claimed the balance and accrued several /// confirmations on the claim transaction. /// -/// Note that the balances available when you or your counterparty have broadcasted revoked -/// state(s) may not be fully captured here. +/// Note that for `ChannelMonitors` which track a channel which went on-chain with versions of +/// LDK prior to 0.0.111, balances may not be fully captured if our counterparty broadcasted +/// a revoked state. /// /// See [`Balance`] for additional details on the types of claimable balances which /// may be returned here and their meanings.