X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Finclude%2Flightning.h;h=608dfd5eefdf5c04e313aae19a146edcc8ed1049;hb=7e0d8189ef1fab54216e446938ac473588bf21cb;hp=bdeb29858d5c9e60954c4eaebab3f4e1e0909a5f;hpb=1a31801f2d38663b22ac044ec9bd0b41aa1a02f9;p=ldk-c-bindings diff --git a/lightning-c-bindings/include/lightning.h b/lightning-c-bindings/include/lightning.h index bdeb298..608dfd5 100644 --- a/lightning-c-bindings/include/lightning.h +++ b/lightning-c-bindings/include/lightning.h @@ -2917,6 +2917,22 @@ typedef struct LDKCVec_C2Tuple_usizeTransactionZZ { uintptr_t datalen; } LDKCVec_C2Tuple_usizeTransactionZZ; +/** + * A dynamically-allocated array of crate::c_types::ThirtyTwoBytess of arbitrary size. + * This corresponds to std::vector in C++ + */ +typedef struct LDKCVec_TxidZ { + /** + * The elements in the array. + * If datalen is non-0 this must be a valid, non-NULL pointer allocated by malloc(). + */ + struct LDKThirtyTwoBytes *data; + /** + * The number of elements pointed to by `data`. + */ + uintptr_t datalen; +} LDKCVec_TxidZ; + /** * The contents of CResult_NoneChannelMonitorUpdateErrZ */ @@ -3201,12 +3217,6 @@ typedef enum LDKEvent_Tag { * counterparty can steal your funds! */ LDKEvent_FundingGenerationReady, - /** - * Used to indicate that the client may now broadcast the funding transaction it created for a - * channel. Broadcasting such a transaction prior to this event may lead to our counterparty - * trivially stealing all funds in the funding transaction! - */ - LDKEvent_FundingBroadcastSafe, /** * Indicates we've received money! Just gotta dig out that payment preimage and feed it to * ChannelManager::claim_funds to get it.... @@ -3272,18 +3282,6 @@ typedef struct LDKEvent_LDKFundingGenerationReady_Body { uint64_t user_channel_id; } LDKEvent_LDKFundingGenerationReady_Body; -typedef struct LDKEvent_LDKFundingBroadcastSafe_Body { - /** - * The output, which was passed to ChannelManager::funding_transaction_generated, which is - * now safe to broadcast. - */ - struct LDKOutPoint funding_txo; - /** - * The value passed in to ChannelManager::create_channel - */ - uint64_t user_channel_id; -} LDKEvent_LDKFundingBroadcastSafe_Body; - typedef struct LDKEvent_LDKPaymentReceived_Body { /** * The hash for which the preimage should be handed to the ChannelManager. @@ -3352,7 +3350,6 @@ typedef struct MUST_USE_STRUCT LDKEvent { LDKEvent_Tag tag; union { LDKEvent_LDKFundingGenerationReady_Body funding_generation_ready; - LDKEvent_LDKFundingBroadcastSafe_Body funding_broadcast_safe; LDKEvent_LDKPaymentReceived_Body payment_received; LDKEvent_LDKPaymentSent_Body payment_sent; LDKEvent_LDKPaymentFailed_Body payment_failed; @@ -3691,7 +3688,7 @@ typedef struct LDKC2Tuple_TxidCVec_C2Tuple_u32TxOutZZZ { * A dynamically-allocated array of crate::c_types::derived::C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZs of arbitrary size. * This corresponds to std::vector in C++ */ -typedef struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ { +typedef struct LDKCVec_TransactionOutputsZ { /** * The elements in the array. * If datalen is non-0 this must be a valid, non-NULL pointer allocated by malloc(). @@ -3701,7 +3698,7 @@ typedef struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ { * The number of elements pointed to by `data`. */ uintptr_t datalen; -} LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ; +} LDKCVec_TransactionOutputsZ; /** * A tuple of 2 elements. See the individual fields for the types contained. @@ -3820,7 +3817,7 @@ typedef struct MUST_USE_STRUCT LDKUnsignedChannelAnnouncement { * to act, as liveness and breach reply correctness are always going to be hard requirements * of LN security model, orthogonal of key management issues. */ -typedef struct LDKSign { +typedef struct LDKBaseSign { /** * An opaque pointer which is passed to your function implementations as an argument. * This has no meaning in the LDK, and can be NULL or any other value. @@ -3852,7 +3849,7 @@ typedef struct LDKSign { * Note that this takes a pointer to this object, not the this_ptr like other methods do * This function pointer may be NULL if pubkeys is filled in when this object is created and never needs updating. */ - void (*set_pubkeys)(const struct LDKSign*NONNULL_PTR ); + void (*set_pubkeys)(const struct LDKBaseSign*NONNULL_PTR ); /** * Gets an arbitrary identifier describing the set of keys which are provided back to you in * some SpendableOutputDescriptor types. This should be sufficient to identify this @@ -3950,15 +3947,44 @@ typedef struct LDKSign { */ void (*ready_channel)(void *this_arg, const struct LDKChannelTransactionParameters *NONNULL_PTR channel_parameters); /** - * Creates a copy of the object pointed to by this_arg, for a copy of this Sign. - * Note that the ultimate copy of the Sign will have all function pointers the same as the original. - * May be NULL if no action needs to be taken, the this_arg pointer will be copied into the new Sign. + * 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. */ - void *(*clone)(const void *this_arg); + void (*free)(void *this_arg); +} LDKBaseSign; + +/** + * A cloneable signer. + * + * Although we require signers to be cloneable, it may be useful for developers to be able to use + * signers in an un-sized way, for example as `dyn BaseSign`. Therefore we separate the Clone trait, + * which implies Sized, into this derived trait. + */ +typedef struct LDKSign { + /** + * An opaque pointer which is passed to your function implementations as an argument. + * This has no meaning in the LDK, and can be NULL or any other value. + */ + void *this_arg; + /** + * Implementation of BaseSign for this object. + */ + struct LDKBaseSign BaseSign; + /** + * Creates a copy of the BaseSign, for a copy of this Sign. + * Because BaseSign doesn't natively support copying itself, you have to provide a full copy implementation here. + */ + struct LDKBaseSign (*BaseSign_clone)(const struct LDKBaseSign *NONNULL_PTR orig_BaseSign); /** * Serialize the object into a byte array */ struct LDKCVec_u8Z (*write)(const void *this_arg); + /** + * Creates a copy of the object pointed to by this_arg, for a copy of this Sign. + * Note that the ultimate copy of the Sign will have all function pointers the same as the original. + * May be NULL if no action needs to be taken, the this_arg pointer will be copied into the new Sign. + */ + void *(*clone)(const void *this_arg); /** * 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. @@ -4693,7 +4719,7 @@ typedef struct LDKLogger { * ChannelUpdate messages informing peers that the channel is temporarily disabled. To avoid * spam due to quick disconnection/reconnection, updates are not sent until the channel has been * offline for a full minute. In order to track this, you must call - * timer_chan_freshness_every_min roughly once per minute, though it doesn't have to be perfect. + * timer_tick_occurred roughly once per minute, though it doesn't have to be perfect. * * Rather than using a plain ChannelManager, it is preferable to use either a SimpleArcChannelManager * a SimpleRefChannelManager, for conciseness. See their documentation for more details, but @@ -6932,6 +6958,26 @@ typedef struct MUST_USE_STRUCT LDKChainParameters { bool is_owned; } LDKChainParameters; + + +/** + * The best known block as identified by its hash and height. + */ +typedef struct MUST_USE_STRUCT LDKBestBlock { + /** + * 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. + */ + LDKnativeBestBlock *inner; + /** + * 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. + */ + bool is_owned; +} LDKBestBlock; + /** * A 3-byte byte array. */ @@ -8128,6 +8174,11 @@ void C2Tuple_usizeTransactionZ_free(struct LDKC2Tuple_usizeTransactionZ _res); */ void CVec_C2Tuple_usizeTransactionZZ_free(struct LDKCVec_C2Tuple_usizeTransactionZZ _res); +/** + * Frees the buffer pointed to by `data` if `datalen` is non-0. + */ +void CVec_TxidZ_free(struct LDKCVec_TxidZ _res); + /** * Creates a new CResult_NoneChannelMonitorUpdateErrZ in the success state. */ @@ -8334,7 +8385,7 @@ void C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZ_free(struct LDKC2Tuple_TxidCVec_C2Tupl /** * Frees the buffer pointed to by `data` if `datalen` is non-0. */ -void CVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ_free(struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ _res); +void CVec_TransactionOutputsZ_free(struct LDKCVec_TransactionOutputsZ _res); /** * Creates a new C2Tuple_BlockHashChannelMonitorZ from the contained elements. @@ -10092,6 +10143,40 @@ void ChainMonitor_free(struct LDKChainMonitor this_obj); */ void ChainMonitor_block_connected(const struct LDKChainMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height); +/** + * Dispatches to per-channel monitors, which are responsible for updating their on-chain view + * of a channel and reacting accordingly to newly confirmed transactions. For details, see + * [`ChannelMonitor::transactions_confirmed`]. + * + * Used instead of [`block_connected`] by clients that are notified of transactions rather than + * blocks. May be called before or after [`update_best_block`] for transactions in the + * corresponding block. See [`update_best_block`] for further calling expectations. + * + * [`block_connected`]: Self::block_connected + * [`update_best_block`]: Self::update_best_block + */ +void ChainMonitor_transactions_confirmed(const struct LDKChainMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height); + +/** + * Dispatches to per-channel monitors, which are responsible for updating their on-chain view + * of a channel and reacting accordingly based on the new chain tip. For details, see + * [`ChannelMonitor::update_best_block`]. + * + * Used instead of [`block_connected`] by clients that are notified of transactions rather than + * blocks. May be called before or after [`transactions_confirmed`] for the corresponding + * block. + * + * Must be called after new blocks become available for the most recent block. Intermediary + * blocks, however, may be safely skipped. In the event of a chain re-organization, this only + * needs to be called for the most recent block assuming `transaction_unconfirmed` is called + * for any affected transactions. + * + * [`block_connected`]: Self::block_connected + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + */ +void ChainMonitor_update_best_block(const struct LDKChainMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t height); + /** * Dispatches to per-channel monitors, which are responsible for updating their on-chain view * of a channel based on the disconnected block. See [`ChannelMonitor::block_disconnected`] for @@ -10099,6 +10184,25 @@ void ChainMonitor_block_connected(const struct LDKChainMonitor *NONNULL_PTR this */ void ChainMonitor_block_disconnected(const struct LDKChainMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t disconnected_height); +/** + * Dispatches to per-channel monitors, which are responsible for updating their on-chain view + * of a channel based on transactions unconfirmed as a result of a chain reorganization. See + * [`ChannelMonitor::transaction_unconfirmed`] for details. + * + * Used instead of [`block_disconnected`] by clients that are notified of transactions rather + * than blocks. May be called before or after [`update_best_block`] for transactions in the + * corresponding block. See [`update_best_block`] for further calling expectations. + * + * [`block_disconnected`]: Self::block_disconnected + * [`update_best_block`]: Self::update_best_block + */ +void ChainMonitor_transaction_unconfirmed(const struct LDKChainMonitor *NONNULL_PTR this_arg, const uint8_t (*txid)[32]); + +/** + * Returns the set of txids that should be monitored for re-organization out of the chain. + */ +MUST_USE_RES struct LDKCVec_TxidZ ChainMonitor_get_relevant_txids(const struct LDKChainMonitor *NONNULL_PTR this_arg); + /** * Creates a new `ChainMonitor` used to watch on-chain activity pertaining to channels. * @@ -10301,7 +10405,7 @@ MUST_USE_RES struct LDKCVec_TransactionZ ChannelMonitor_get_latest_holder_commit * * [`get_outputs_to_watch`]: #method.get_outputs_to_watch */ -MUST_USE_RES struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ ChannelMonitor_block_connected(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height, struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); +MUST_USE_RES struct LDKCVec_TransactionOutputsZ ChannelMonitor_block_connected(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height, struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); /** * Determines if the disconnected block contained any transactions of interest and updates @@ -10309,6 +10413,55 @@ MUST_USE_RES struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32TxOutZZZZ ChannelMonitor */ void ChannelMonitor_block_disconnected(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t height, struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); +/** + * Processes transactions confirmed in a block with the given header and height, returning new + * outputs to watch. See [`block_connected`] for details. + * + * Used instead of [`block_connected`] by clients that are notified of transactions rather than + * blocks. May be called before or after [`update_best_block`] for transactions in the + * corresponding block. See [`update_best_block`] for further calling expectations. + * + * [`block_connected`]: Self::block_connected + * [`update_best_block`]: Self::update_best_block + */ +MUST_USE_RES struct LDKCVec_TransactionOutputsZ ChannelMonitor_transactions_confirmed(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height, struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); + +/** + * Processes a transaction that was reorganized out of the chain. + * + * Used instead of [`block_disconnected`] by clients that are notified of transactions rather + * than blocks. May be called before or after [`update_best_block`] for transactions in the + * corresponding block. See [`update_best_block`] for further calling expectations. + * + * [`block_disconnected`]: Self::block_disconnected + * [`update_best_block`]: Self::update_best_block + */ +void ChannelMonitor_transaction_unconfirmed(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*txid)[32], struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); + +/** + * Updates the monitor with the current best chain tip, returning new outputs to watch. See + * [`block_connected`] for details. + * + * Used instead of [`block_connected`] by clients that are notified of transactions rather than + * blocks. May be called before or after [`transactions_confirmed`] for the corresponding + * block. + * + * Must be called after new blocks become available for the most recent block. Intermediary + * blocks, however, may be safely skipped. In the event of a chain re-organization, this only + * needs to be called for the most recent block assuming `transaction_unconfirmed` is called + * for any affected transactions. + * + * [`block_connected`]: Self::block_connected + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + */ +MUST_USE_RES struct LDKCVec_TransactionOutputsZ ChannelMonitor_update_best_block(const struct LDKChannelMonitor *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t height, struct LDKBroadcasterInterface broadcaster, struct LDKFeeEstimator fee_estimator, struct LDKLogger logger); + +/** + * Returns the set of txids that should be monitored for re-organization out of the chain. + */ +MUST_USE_RES struct LDKCVec_TxidZ ChannelMonitor_get_relevant_txids(const struct LDKChannelMonitor *NONNULL_PTR this_arg); + /** * Calls the free function if one is set */ @@ -10531,6 +10684,11 @@ struct LDKCVec_u8Z SpendableOutputDescriptor_write(const struct LDKSpendableOutp */ struct LDKCResult_SpendableOutputDescriptorDecodeErrorZ SpendableOutputDescriptor_read(struct LDKu8slice ser); +/** + * Calls the free function if one is set + */ +void BaseSign_free(struct LDKBaseSign this_ptr); + /** * Creates a copy of a Sign */ @@ -10682,6 +10840,12 @@ MUST_USE_RES struct LDKCResult_CVec_CVec_u8ZZNoneZ InMemorySigner_sign_counterpa */ MUST_USE_RES struct LDKCResult_CVec_CVec_u8ZZNoneZ InMemorySigner_sign_dynamic_p2wsh_input(const struct LDKInMemorySigner *NONNULL_PTR this_arg, struct LDKTransaction spend_tx, uintptr_t input_idx, const struct LDKDelayedPaymentOutputDescriptor *NONNULL_PTR descriptor); +/** + * Constructs a new BaseSign which calls the relevant methods on this_arg. + * This copies the `inner` pointer in this_arg and thus the returned BaseSign must be freed before this_arg is + */ +struct LDKBaseSign InMemorySigner_as_BaseSign(const struct LDKInMemorySigner *NONNULL_PTR this_arg); + /** * Constructs a new Sign which calls the relevant methods on this_arg. * This copies the `inner` pointer in this_arg and thus the returned Sign must be freed before this_arg is @@ -10777,33 +10941,53 @@ enum LDKNetwork ChainParameters_get_network(const struct LDKChainParameters *NON void ChainParameters_set_network(struct LDKChainParameters *NONNULL_PTR this_ptr, enum LDKNetwork val); /** - * The hash of the latest block successfully connected. + * The hash and height of the latest block successfully connected. + * + * Used to track on-chain channel funding outputs and send payments with reliable timelocks. */ -const uint8_t (*ChainParameters_get_latest_hash(const struct LDKChainParameters *NONNULL_PTR this_ptr))[32]; +struct LDKBestBlock ChainParameters_get_best_block(const struct LDKChainParameters *NONNULL_PTR this_ptr); /** - * The hash of the latest block successfully connected. + * The hash and height of the latest block successfully connected. + * + * Used to track on-chain channel funding outputs and send payments with reliable timelocks. */ -void ChainParameters_set_latest_hash(struct LDKChainParameters *NONNULL_PTR this_ptr, struct LDKThirtyTwoBytes val); +void ChainParameters_set_best_block(struct LDKChainParameters *NONNULL_PTR this_ptr, struct LDKBestBlock val); /** - * The height of the latest block successfully connected. - * - * Used to track on-chain channel funding outputs and send payments with reliable timelocks. + * Constructs a new ChainParameters given each field */ -uintptr_t ChainParameters_get_latest_height(const struct LDKChainParameters *NONNULL_PTR this_ptr); +MUST_USE_RES struct LDKChainParameters ChainParameters_new(enum LDKNetwork network_arg, struct LDKBestBlock best_block_arg); /** - * The height of the latest block successfully connected. - * - * Used to track on-chain channel funding outputs and send payments with reliable timelocks. + * Frees any resources used by the BestBlock, if is_owned is set and inner is non-NULL. */ -void ChainParameters_set_latest_height(struct LDKChainParameters *NONNULL_PTR this_ptr, uintptr_t val); +void BestBlock_free(struct LDKBestBlock this_obj); /** - * Constructs a new ChainParameters given each field + * Creates a copy of the BestBlock */ -MUST_USE_RES struct LDKChainParameters ChainParameters_new(enum LDKNetwork network_arg, struct LDKThirtyTwoBytes latest_hash_arg, uintptr_t latest_height_arg); +struct LDKBestBlock BestBlock_clone(const struct LDKBestBlock *NONNULL_PTR orig); + +/** + * Returns the best block from the genesis of the given network. + */ +MUST_USE_RES struct LDKBestBlock BestBlock_from_genesis(enum LDKNetwork network); + +/** + * Returns the best block as identified by the given block hash and height. + */ +MUST_USE_RES struct LDKBestBlock BestBlock_new(struct LDKThirtyTwoBytes block_hash, uint32_t height); + +/** + * Returns the best block hash. + */ +MUST_USE_RES struct LDKThirtyTwoBytes BestBlock_block_hash(const struct LDKBestBlock *NONNULL_PTR this_arg); + +/** + * Returns the best block height. + */ +MUST_USE_RES uint32_t BestBlock_height(const struct LDKBestBlock *NONNULL_PTR this_arg); /** * Frees any resources used by the ChannelDetails, if is_owned is set and inner is non-NULL. @@ -10959,13 +11143,19 @@ struct LDKPaymentSendFailure PaymentSendFailure_clone(const struct LDKPaymentSen */ MUST_USE_RES struct LDKChannelManager ChannelManager_new(struct LDKFeeEstimator fee_est, struct LDKWatch chain_monitor, struct LDKBroadcasterInterface tx_broadcaster, struct LDKLogger logger, struct LDKKeysInterface keys_manager, struct LDKUserConfig config, struct LDKChainParameters params); +/** + * Gets the current configuration applied to all new channels, as + */ +MUST_USE_RES struct LDKUserConfig ChannelManager_get_current_default_configuration(const struct LDKChannelManager *NONNULL_PTR this_arg); + /** * 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. @@ -11057,15 +11247,24 @@ MUST_USE_RES struct LDKCResult_NonePaymentSendFailureZ ChannelManager_send_payme /** * 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. */ -void ChannelManager_funding_transaction_generated(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*temporary_channel_id)[32], struct LDKOutPoint funding_txo); +MUST_USE_RES struct LDKCResult_NoneAPIErrorZ ChannelManager_funding_transaction_generated(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*temporary_channel_id)[32], struct LDKTransaction funding_transaction); /** * Generates a signed node_announcement from the given arguments and creates a @@ -11101,7 +11300,7 @@ void ChannelManager_process_pending_htlc_forwards(const struct LDKChannelManager * * Note that in some rare cases this may generate a `chain::Watch::update_channel` call. */ -void ChannelManager_timer_chan_freshness_every_min(const struct LDKChannelManager *NONNULL_PTR this_arg); +void ChannelManager_timer_tick_occurred(const struct LDKChannelManager *NONNULL_PTR this_arg); /** * Indicates that the preimage for payment_hash is unknown or the received amount is incorrect @@ -11179,17 +11378,83 @@ struct LDKEventsProvider ChannelManager_as_EventsProvider(const struct LDKChanne struct LDKListen ChannelManager_as_Listen(const struct LDKChannelManager *NONNULL_PTR this_arg); /** - * 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` + */ +void ChannelManager_transactions_confirmed(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t height, struct LDKCVec_C2Tuple_usizeTransactionZZ txdata); + +/** + * 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. + * + * 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. + */ +void ChannelManager_update_best_block(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*header)[80], uint32_t height); + +/** + * Gets the set of txids which should be monitored for their confirmation state. + * + * If you're providing information about reorganizations via [`transaction_unconfirmed`], this + * is the set of transactions which you may need to call [`transaction_unconfirmed`] for. + * + * This may be useful to poll to determine the set of transactions which must be registered + * with an Electrum server or for which an Electrum server needs to be polled to determine + * transaction confirmation state. + * + * This may update after any [`transactions_confirmed`] or [`block_connected`] call. + * + * Note that this is NOT the set of transactions which must be included in calls to + * [`transactions_confirmed`] if they are confirmed, but a small subset of it. + * + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`transaction_unconfirmed`]: Self::transaction_unconfirmed + * [`block_connected`]: chain::Listen::block_connected */ -void ChannelManager_block_connected(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*header)[80], struct LDKCVec_C2Tuple_usizeTransactionZZ txdata, uint32_t height); +MUST_USE_RES struct LDKCVec_TxidZ ChannelManager_get_relevant_txids(const struct LDKChannelManager *NONNULL_PTR this_arg); /** - * Updates channel state based on a disconnected block. + * Marks a transaction as having been reorganized out of the blockchain. + * + * If a transaction is included in [`get_relevant_txids`], and is no longer in the main branch + * of the blockchain, this function should be called to indicate that the transaction should + * be considered reorganized out. + * + * Once this is called, the given transaction will no longer appear on [`get_relevant_txids`], + * though this may be called repeatedly for a given transaction without issue. + * + * Note that if the transaction is confirmed on the main chain in a different block (indicated + * via a call to [`transactions_confirmed`]), it may re-appear in [`get_relevant_txids`], thus + * be very wary of race-conditions wherein the final state of a transaction indicated via + * these APIs is not the same as its state on the blockchain. * - * If necessary, the channel may be force-closed without letting the counterparty participate - * in the shutdown. + * [`transactions_confirmed`]: Self::transactions_confirmed + * [`get_relevant_txids`]: Self::get_relevant_txids */ -void ChannelManager_block_disconnected(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*header)[80]); +void ChannelManager_transaction_unconfirmed(const struct LDKChannelManager *NONNULL_PTR this_arg, const uint8_t (*txid)[32]); /** * Blocks until ChannelManager needs to be persisted or a timeout is reached. It returns a bool