X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-c-bindings;a=blobdiff_plain;f=lightning-c-bindings%2Fsrc%2Fln%2Fchannelmanager.rs;h=cad534b0cb66158fe1dd7daef0bcdbb9ba3f9b14;hp=86257f77e124d20f86c5ad81ccd182a02661a49b;hb=933eac0670cad94354d73ef144cbaf2c0e81be50;hpb=1495575b517c90da925698da14f627bf0d5b313f diff --git a/lightning-c-bindings/src/ln/channelmanager.rs b/lightning-c-bindings/src/ln/channelmanager.rs index 86257f7..cad534b 100644 --- a/lightning-c-bindings/src/ln/channelmanager.rs +++ b/lightning-c-bindings/src/ln/channelmanager.rs @@ -1,3 +1,11 @@ +// This file is Copyright its original authors, visible in version control +// history and in the source files from which this was generated. +// +// This file is licensed under the license available in the LICENSE or LICENSE.md +// file in the root of this repository or, if no such file exists, the same +// license as that which applies to the original source files from which this +// source was automatically generated. + //! The top-level channel management and payment tracking stuff lives here. //! //! The ChannelManager is the main chunk of logic implementing the lightning protocol and is @@ -56,9 +64,15 @@ type nativeChannelManager = nativeChannelManagerImport ChainParameters { @@ -174,6 +197,24 @@ pub extern "C" fn ChainParameters_new(mut network_arg: crate::bitcoin::network:: latest_height: latest_height_arg, })), is_owned: true } } +/// The amount of time in blocks we require our counterparty wait to claim their money (ie time +/// between when we, or our watchtower, must check for them having broadcast a theft transaction). +/// +/// This can be increased (but not decreased) through [`ChannelHandshakeConfig::our_to_self_delay`] +/// +/// [`ChannelHandshakeConfig::our_to_self_delay`]: crate::util::config::ChannelHandshakeConfig::our_to_self_delay + +#[no_mangle] +pub static BREAKDOWN_TIMEOUT: u16 = lightning::ln::channelmanager::BREAKDOWN_TIMEOUT; +/// The minimum number of blocks between an inbound HTLC's CLTV and the corresponding outbound +/// HTLC's CLTV. The current default represents roughly six hours of blocks at six blocks/hour. +/// +/// This can be increased (but not decreased) through [`ChannelConfig::cltv_expiry_delta`] +/// +/// [`ChannelConfig::cltv_expiry_delta`]: crate::util::config::ChannelConfig::cltv_expiry_delta + +#[no_mangle] +pub static MIN_CLTV_EXPIRY_DELTA: u16 = lightning::ln::channelmanager::MIN_CLTV_EXPIRY_DELTA; use lightning::ln::channelmanager::ChannelDetails as nativeChannelDetailsImport; type nativeChannelDetails = nativeChannelDetailsImport; @@ -182,9 +223,15 @@ type nativeChannelDetails = nativeChannelDetailsImport; #[must_use] #[repr(C)] pub struct ChannelDetails { + /// A pointer to the opaque Rust object. + /// Nearly everywhere, inner must be non-null, however in places where /// the Rust equivalent takes an Option, it may be set to null to indicate None. pub inner: *mut nativeChannelDetails, + /// Indicates that this is the only struct which contains the same pointer. + + /// Rust functions which take ownership of an object provided via an argument require + /// this to be true and invalidate the object pointed to by inner. pub is_owned: bool, } @@ -195,8 +242,9 @@ impl Drop for ChannelDetails { } } } +/// Frees any resources used by the ChannelDetails, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn ChannelDetails_free(this_ptr: ChannelDetails) { } +pub extern "C" fn ChannelDetails_free(this_obj: ChannelDetails) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn ChannelDetails_free_void(this_ptr: *mut c_void) { @@ -229,6 +277,21 @@ pub extern "C" fn ChannelDetails_get_channel_id(this_ptr: &ChannelDetails) -> *c pub extern "C" fn ChannelDetails_set_channel_id(this_ptr: &mut ChannelDetails, mut val: crate::c_types::ThirtyTwoBytes) { unsafe { &mut *this_ptr.inner }.channel_id = val.data; } +/// The position of the funding transaction in the chain. None if the funding transaction has +/// not yet been confirmed and the channel fully opened. +#[no_mangle] +pub extern "C" fn ChannelDetails_get_short_channel_id(this_ptr: &ChannelDetails) -> crate::c_types::derived::COption_u64Z { + let mut inner_val = &mut unsafe { &mut *this_ptr.inner }.short_channel_id; + let mut local_inner_val = if inner_val.is_none() { crate::c_types::derived::COption_u64Z::None } else { { crate::c_types::derived::COption_u64Z::Some(inner_val.unwrap()) } }; + local_inner_val +} +/// The position of the funding transaction in the chain. None if the funding transaction has +/// not yet been confirmed and the channel fully opened. +#[no_mangle] +pub extern "C" fn ChannelDetails_set_short_channel_id(this_ptr: &mut ChannelDetails, mut val: crate::c_types::derived::COption_u64Z) { + let mut local_val = if val.is_some() { Some( { val.take() }) } else { None }; + unsafe { &mut *this_ptr.inner }.short_channel_id = local_val; +} /// The node_id of our counterparty #[no_mangle] pub extern "C" fn ChannelDetails_get_remote_network_id(this_ptr: &ChannelDetails) -> crate::c_types::PublicKey { @@ -341,6 +404,7 @@ pub(crate) extern "C" fn ChannelDetails_clone_void(this_ptr: *const c_void) -> * Box::into_raw(Box::new(unsafe { (*(this_ptr as *mut nativeChannelDetails)).clone() })) as *mut c_void } #[no_mangle] +/// Creates a copy of the ChannelDetails pub extern "C" fn ChannelDetails_clone(orig: &ChannelDetails) -> ChannelDetails { orig.clone() } @@ -504,8 +568,10 @@ impl PaymentSendFailure { } } } +/// Frees any resources used by the PaymentSendFailure #[no_mangle] pub extern "C" fn PaymentSendFailure_free(this_ptr: PaymentSendFailure) { } +/// Creates a copy of the PaymentSendFailure #[no_mangle] pub extern "C" fn PaymentSendFailure_clone(orig: &PaymentSendFailure) -> PaymentSendFailure { orig.clone() @@ -531,10 +597,11 @@ pub extern "C" fn ChannelManager_new(mut fee_est: crate::chain::chaininterface:: /// Creates a new outbound channel to the given remote node and with the given value. /// -/// user_id will be provided back as user_channel_id in FundingGenerationReady and -/// FundingBroadcastSafe events to allow tracking of which events correspond with which -/// create_channel call. Note that user_channel_id defaults to 0 for inbound channels, so you -/// may wish to avoid using 0 for user_id here. +/// user_id will be provided back as user_channel_id in FundingGenerationReady events to allow +/// tracking of which events correspond with which create_channel call. Note that the +/// user_channel_id defaults to 0 for inbound channels, so you may wish to avoid using 0 for +/// user_id here. user_id has no meaning inside of LDK, it is simply copied to events and +/// otherwise ignored. /// /// If successful, will generate a SendOpenChannel message event, so you should probably poll /// PeerManager::process_events afterwards. @@ -653,16 +720,28 @@ pub extern "C" fn ChannelManager_send_payment(this_arg: &ChannelManager, route: /// Call this upon creation of a funding transaction for the given channel. /// -/// Note that ALL inputs in the transaction pointed to by funding_txo MUST spend SegWit outputs -/// or your counterparty can steal your funds! +/// Returns an [`APIError::APIMisuseError`] if the funding_transaction spent non-SegWit outputs +/// or if no output was found which matches the parameters in [`Event::FundingGenerationReady`]. /// /// Panics if a funding transaction has already been provided for this channel. /// -/// May panic if the funding_txo is duplicative with some other channel (note that this should -/// be trivially prevented by using unique funding transaction keys per-channel). +/// May panic if the output found in the funding transaction is duplicative with some other +/// channel (note that this should be trivially prevented by using unique funding transaction +/// keys per-channel). +/// +/// Do NOT broadcast the funding transaction yourself. When we have safely received our +/// counterparty's signature the funding transaction will automatically be broadcast via the +/// [`BroadcasterInterface`] provided when this `ChannelManager` was constructed. +/// +/// Note that this includes RBF or similar transaction replacement strategies - lightning does +/// not currently support replacing a funding transaction on an existing channel. Instead, +/// create a new channel with a conflicting funding transaction. +#[must_use] #[no_mangle] -pub extern "C" fn ChannelManager_funding_transaction_generated(this_arg: &ChannelManager, temporary_channel_id: *const [u8; 32], mut funding_txo: crate::chain::transaction::OutPoint) { - unsafe { &*this_arg.inner }.funding_transaction_generated(unsafe { &*temporary_channel_id}, *unsafe { Box::from_raw(funding_txo.take_inner()) }) +pub extern "C" fn ChannelManager_funding_transaction_generated(this_arg: &ChannelManager, temporary_channel_id: *const [u8; 32], mut funding_transaction: crate::c_types::Transaction) -> crate::c_types::derived::CResult_NoneAPIErrorZ { + let mut ret = unsafe { &*this_arg.inner }.funding_transaction_generated(unsafe { &*temporary_channel_id}, funding_transaction.into_bitcoin()); + let mut local_ret = match ret { Ok(mut o) => crate::c_types::CResultTempl::ok( { 0u8 /*o*/ }).into(), Err(mut e) => crate::c_types::CResultTempl::err( { crate::util::errors::APIError::native_into(e) }).into() }; + local_ret } /// Generates a signed node_announcement from the given arguments and creates a @@ -784,6 +863,8 @@ impl From for crate::util::events::MessageSendEventsProvid ret } } +/// Constructs a new MessageSendEventsProvider which calls the relevant methods on this_arg. +/// This copies the `inner` pointer in this_arg and thus the returned MessageSendEventsProvider must be freed before this_arg is #[no_mangle] pub extern "C" fn ChannelManager_as_MessageSendEventsProvider(this_arg: &ChannelManager) -> crate::util::events::MessageSendEventsProvider { crate::util::events::MessageSendEventsProvider { @@ -810,6 +891,8 @@ impl From for crate::util::events::EventsProvider { ret } } +/// 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 ChannelManager_as_EventsProvider(this_arg: &ChannelManager) -> crate::util::events::EventsProvider { crate::util::events::EventsProvider { @@ -836,6 +919,8 @@ impl From for crate::chain::Listen { ret } } +/// Constructs a new Listen which calls the relevant methods on this_arg. +/// This copies the `inner` pointer in this_arg and thus the returned Listen must be freed before this_arg is #[no_mangle] pub extern "C" fn ChannelManager_as_Listen(this_arg: &ChannelManager) -> crate::chain::Listen { crate::chain::Listen { @@ -849,24 +934,61 @@ pub extern "C" fn ChannelManager_as_Listen(this_arg: &ChannelManager) -> crate:: extern "C" fn ChannelManager_Listen_block_connected(this_arg: *const c_void, mut block: crate::c_types::u8slice, mut height: u32) { >::block_connected(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &::bitcoin::consensus::encode::deserialize(block.to_slice()).unwrap(), height) } -extern "C" fn ChannelManager_Listen_block_disconnected(this_arg: *const c_void, header: *const [u8; 80], mut _height: u32) { - >::block_disconnected(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), _height) +extern "C" fn ChannelManager_Listen_block_disconnected(this_arg: *const c_void, header: *const [u8; 80], mut height: u32) { + >::block_disconnected(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), height) } -/// Updates channel state based on transactions seen in a connected block. +/// Updates channel state to take note of transactions which were confirmed in the given block +/// at the given height. +/// +/// Note that you must still call (or have called) [`update_best_block`] with the block +/// information which is included here. +/// +/// This method may be called before or after [`update_best_block`] for a given block's +/// transaction data and may be called multiple times with additional transaction data for a +/// given block. +/// +/// This method may be called for a previous block after an [`update_best_block`] call has +/// been made for a later block, however it must *not* be called with transaction data from a +/// block which is no longer in the best chain (ie where [`update_best_block`] has already +/// been informed about a blockchain reorganization which no longer includes the block which +/// corresponds to `header`). +/// +/// [`update_best_block`]: `Self::update_best_block` #[no_mangle] -pub extern "C" fn ChannelManager_block_connected(this_arg: &ChannelManager, header: *const [u8; 80], mut txdata: crate::c_types::derived::CVec_C2Tuple_usizeTransactionZZ, mut height: u32) { +pub extern "C" fn ChannelManager_transactions_confirmed(this_arg: &ChannelManager, header: *const [u8; 80], mut height: u32, mut txdata: crate::c_types::derived::CVec_C2Tuple_usizeTransactionZZ) { let mut local_txdata = Vec::new(); for mut item in txdata.into_rust().drain(..) { local_txdata.push( { let (mut orig_txdata_0_0, mut orig_txdata_0_1) = item.to_rust(); let mut local_txdata_0 = (orig_txdata_0_0, orig_txdata_0_1.into_bitcoin()); local_txdata_0 }); }; - unsafe { &*this_arg.inner }.block_connected(&::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), &local_txdata.iter().map(|(a, b)| (*a, b)).collect::>()[..], height) + unsafe { &*this_arg.inner }.transactions_confirmed(&::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), height, &local_txdata.iter().map(|(a, b)| (*a, b)).collect::>()[..]) } -/// Updates channel state based on a disconnected block. +/// Updates channel state with the current best blockchain tip. You should attempt to call this +/// quickly after a new block becomes available, however if multiple new blocks become +/// available at the same time, only a single `update_best_block()` call needs to be made. /// -/// If necessary, the channel may be force-closed without letting the counterparty participate -/// in the shutdown. +/// This method should also be called immediately after any block disconnections, once at the +/// reorganization fork point, and once with the new chain tip. Calling this method at the +/// blockchain reorganization fork point ensures we learn when a funding transaction which was +/// previously confirmed is reorganized out of the blockchain, ensuring we do not continue to +/// accept payments which cannot be enforced on-chain. +/// +/// In both the block-connection and block-disconnection case, this method may be called either +/// once per block connected or disconnected, or simply at the fork point and new tip(s), +/// skipping any intermediary blocks. +#[no_mangle] +pub extern "C" fn ChannelManager_update_best_block(this_arg: &ChannelManager, header: *const [u8; 80], mut height: u32) { + unsafe { &*this_arg.inner }.update_best_block(&::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap(), height) +} + +/// Blocks until ChannelManager needs to be persisted or a timeout is reached. It returns a bool +/// indicating whether persistence is necessary. Only one listener on +/// `await_persistable_update` or `await_persistable_update_timeout` is guaranteed to be woken +/// up. +/// Note that the feature `allow_wallclock_use` must be enabled to use this function. +#[must_use] #[no_mangle] -pub extern "C" fn ChannelManager_block_disconnected(this_arg: &ChannelManager, header: *const [u8; 80]) { - unsafe { &*this_arg.inner }.block_disconnected(&::bitcoin::consensus::encode::deserialize(unsafe { &*header }).unwrap()) +pub extern "C" fn ChannelManager_await_persistable_update_timeout(this_arg: &ChannelManager, mut max_wait: u64) -> bool { + let mut ret = unsafe { &*this_arg.inner }.await_persistable_update_timeout(std::time::Duration::from_secs(max_wait)); + ret } /// Blocks until ChannelManager needs to be persisted. Only one listener on @@ -887,6 +1009,8 @@ impl From for crate::ln::msgs::ChannelMessageHandler { ret } } +/// Constructs a new ChannelMessageHandler which calls the relevant methods on this_arg. +/// This copies the `inner` pointer in this_arg and thus the returned ChannelMessageHandler must be freed before this_arg is #[no_mangle] pub extern "C" fn ChannelManager_as_ChannelMessageHandler(this_arg: &ChannelManager) -> crate::ln::msgs::ChannelMessageHandler { crate::ln::msgs::ChannelMessageHandler { @@ -910,11 +1034,12 @@ pub extern "C" fn ChannelManager_as_ChannelMessageHandler(this_arg: &ChannelMana peer_disconnected: ChannelManager_ChannelMessageHandler_peer_disconnected, peer_connected: ChannelManager_ChannelMessageHandler_peer_connected, handle_channel_reestablish: ChannelManager_ChannelMessageHandler_handle_channel_reestablish, + handle_channel_update: ChannelManager_ChannelMessageHandler_handle_channel_update, handle_error: ChannelManager_ChannelMessageHandler_handle_error, MessageSendEventsProvider: crate::util::events::MessageSendEventsProvider { this_arg: unsafe { (*this_arg).inner as *mut c_void }, free: None, - get_and_clear_pending_msg_events: ChannelManager_ChannelMessageHandler_get_and_clear_pending_msg_events, + get_and_clear_pending_msg_events: ChannelManager_MessageSendEventsProvider_get_and_clear_pending_msg_events, }, } } @@ -964,6 +1089,9 @@ extern "C" fn ChannelManager_ChannelMessageHandler_handle_update_fee(this_arg: * extern "C" fn ChannelManager_ChannelMessageHandler_handle_announcement_signatures(this_arg: *const c_void, mut counterparty_node_id: crate::c_types::PublicKey, msg: &crate::ln::msgs::AnnouncementSignatures) { >::handle_announcement_signatures(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &counterparty_node_id.into_rust(), unsafe { &*msg.inner }) } +extern "C" fn ChannelManager_ChannelMessageHandler_handle_channel_update(this_arg: *const c_void, mut counterparty_node_id: crate::c_types::PublicKey, msg: &crate::ln::msgs::ChannelUpdate) { + >::handle_channel_update(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &counterparty_node_id.into_rust(), unsafe { &*msg.inner }) +} extern "C" fn ChannelManager_ChannelMessageHandler_handle_channel_reestablish(this_arg: *const c_void, mut counterparty_node_id: crate::c_types::PublicKey, msg: &crate::ln::msgs::ChannelReestablish) { >::handle_channel_reestablish(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &counterparty_node_id.into_rust(), unsafe { &*msg.inner }) } @@ -976,14 +1104,9 @@ extern "C" fn ChannelManager_ChannelMessageHandler_peer_connected(this_arg: *con extern "C" fn ChannelManager_ChannelMessageHandler_handle_error(this_arg: *const c_void, mut counterparty_node_id: crate::c_types::PublicKey, msg: &crate::ln::msgs::ErrorMessage) { >::handle_error(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, &counterparty_node_id.into_rust(), unsafe { &*msg.inner }) } -#[must_use] -extern "C" fn ChannelManager_ChannelMessageHandler_get_and_clear_pending_msg_events(this_arg: *const c_void) -> crate::c_types::derived::CVec_MessageSendEventZ { - let mut ret = >::get_and_clear_pending_msg_events(unsafe { &mut *(this_arg as *mut nativeChannelManager) }, ); - let mut local_ret = Vec::new(); for mut item in ret.drain(..) { local_ret.push( { crate::util::events::MessageSendEvent::native_into(item) }); }; - local_ret.into() -} #[no_mangle] +/// Serialize the ChannelManager object into a byte array which can be read by ChannelManager_read pub extern "C" fn ChannelManager_write(obj: &ChannelManager) -> crate::c_types::derived::CVec_u8Z { crate::c_types::serialize_obj(unsafe { &*unsafe { &*obj }.inner }) } @@ -1023,9 +1146,15 @@ type nativeChannelManagerReadArgs = nativeChannelManagerReadArgsImport<'static, #[must_use] #[repr(C)] pub struct ChannelManagerReadArgs { + /// A pointer to the opaque Rust object. + /// Nearly everywhere, inner must be non-null, however in places where /// the Rust equivalent takes an Option, it may be set to null to indicate None. pub inner: *mut nativeChannelManagerReadArgs, + /// Indicates that this is the only struct which contains the same pointer. + + /// Rust functions which take ownership of an object provided via an argument require + /// this to be true and invalidate the object pointed to by inner. pub is_owned: bool, } @@ -1036,8 +1165,9 @@ impl Drop for ChannelManagerReadArgs { } } } +/// Frees any resources used by the ChannelManagerReadArgs, if is_owned is set and inner is non-NULL. #[no_mangle] -pub extern "C" fn ChannelManagerReadArgs_free(this_ptr: ChannelManagerReadArgs) { } +pub extern "C" fn ChannelManagerReadArgs_free(this_obj: ChannelManagerReadArgs) { } #[allow(unused)] /// Used only if an object of this type is returned as a trait impl by a method extern "C" fn ChannelManagerReadArgs_free_void(this_ptr: *mut c_void) { @@ -1155,6 +1285,7 @@ pub extern "C" fn ChannelManagerReadArgs_new(mut keys_manager: crate::chain::key } #[no_mangle] +/// Read a C2Tuple_BlockHashChannelManagerZ from a byte array, created by C2Tuple_BlockHashChannelManagerZ_write pub extern "C" fn C2Tuple_BlockHashChannelManagerZ_read(ser: crate::c_types::u8slice, arg: crate::ln::channelmanager::ChannelManagerReadArgs) -> crate::c_types::derived::CResult_C2Tuple_BlockHashChannelManagerZDecodeErrorZ { let arg_conv = *unsafe { Box::from_raw(arg.take_inner()) }; let res: Result<(bitcoin::hash_types::BlockHash, lightning::ln::channelmanager::ChannelManager), lightning::ln::msgs::DecodeError> = crate::c_types::deserialize_obj_arg(ser, arg_conv);