X-Git-Url: http://git.bitcoin.ninja/index.cgi?p=ldk-c-bindings;a=blobdiff_plain;f=lightning-c-bindings%2Finclude%2Flightning.h;h=2a5f617dbc4d165414bdf922c3058ecd482d23ec;hp=8fe104873df2a9c011bfef88e18905f7014ecb4b;hb=2f0c348c6fe505a736c3d015df6d6cd30032c912;hpb=e419524cf19c36857bf1f3c79d4b9dd47c7544c8 diff --git a/lightning-c-bindings/include/lightning.h b/lightning-c-bindings/include/lightning.h index 8fe1048..2a5f617 100644 --- a/lightning-c-bindings/include/lightning.h +++ b/lightning-c-bindings/include/lightning.h @@ -8,7 +8,7 @@ #include #include #include -#include +#include "ldk_rust_types.h" /** * An error when accessing the chain via [`Access`]. @@ -210,29 +210,25 @@ typedef enum LDKIOError { */ typedef enum LDKLevel { /** - *Designates logger being silent - */ - LDKLevel_Off, - /** - * Designates very serious errors + * Designates very low priority, often extremely verbose, information */ - LDKLevel_Error, + LDKLevel_Trace, /** - * Designates hazardous situations + * Designates lower priority information */ - LDKLevel_Warn, + LDKLevel_Debug, /** * Designates useful information */ LDKLevel_Info, /** - * Designates lower priority information + * Designates hazardous situations */ - LDKLevel_Debug, + LDKLevel_Warn, /** - * Designates very low priority, often extremely verbose, information + * Designates very serious errors */ - LDKLevel_Trace, + LDKLevel_Error, /** * Must be last for serialization purposes */ @@ -2209,6 +2205,11 @@ typedef enum LDKErrorAction_Tag { * The peer did something harmless that we weren't able to process, just log and ignore */ LDKErrorAction_IgnoreError, + /** + * The peer did something harmless that we weren't able to meaningfully process. + * If the error is logged, log it at the given level. + */ + LDKErrorAction_IgnoreAndLog, /** * The peer did something incorrect. Tell them. */ @@ -2222,6 +2223,8 @@ typedef enum LDKErrorAction_Tag { typedef struct LDKErrorAction_LDKDisconnectPeer_Body { /** * An error message which we should make an effort to send before we disconnect. + * + * Note that this (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKErrorMessage msg; } LDKErrorAction_LDKDisconnectPeer_Body; @@ -2237,6 +2240,9 @@ typedef struct MUST_USE_STRUCT LDKErrorAction { LDKErrorAction_Tag tag; union { LDKErrorAction_LDKDisconnectPeer_Body disconnect_peer; + struct { + enum LDKLevel ignore_and_log; + }; LDKErrorAction_LDKSendErrorMessage_Body send_error_message; }; } LDKErrorAction; @@ -2454,6 +2460,12 @@ typedef enum LDKMessageSendEvent_Tag { * Used to indicate that a channel_update should be broadcast to all peers. */ LDKMessageSendEvent_BroadcastChannelUpdate, + /** + * 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. + */ + LDKMessageSendEvent_SendChannelUpdate, /** * Broadcast an error downstream to be handled */ @@ -2629,6 +2641,17 @@ typedef struct LDKMessageSendEvent_LDKBroadcastChannelUpdate_Body { struct LDKChannelUpdate msg; } LDKMessageSendEvent_LDKBroadcastChannelUpdate_Body; +typedef struct LDKMessageSendEvent_LDKSendChannelUpdate_Body { + /** + * The node_id of the node which should receive this message + */ + struct LDKPublicKey node_id; + /** + * The channel_update which should be sent. + */ + struct LDKChannelUpdate msg; +} LDKMessageSendEvent_LDKSendChannelUpdate_Body; + typedef struct LDKMessageSendEvent_LDKHandleError_Body { /** * The node_id of the node which should receive this message @@ -2697,6 +2720,7 @@ typedef struct MUST_USE_STRUCT LDKMessageSendEvent { LDKMessageSendEvent_LDKBroadcastChannelAnnouncement_Body broadcast_channel_announcement; LDKMessageSendEvent_LDKBroadcastNodeAnnouncement_Body broadcast_node_announcement; LDKMessageSendEvent_LDKBroadcastChannelUpdate_Body broadcast_channel_update; + LDKMessageSendEvent_LDKSendChannelUpdate_Body send_channel_update; LDKMessageSendEvent_LDKHandleError_Body handle_error; LDKMessageSendEvent_LDKPaymentFailureNetworkUpdate_Body payment_failure_network_update; LDKMessageSendEvent_LDKSendChannelRangeQuery_Body send_channel_range_query; @@ -3318,21 +3342,16 @@ typedef struct LDKSign { * 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. + * Called, if set, after this Sign has been cloned into a duplicate object. + * The new Sign is provided, and should be mutated as needed to perform a + * deep copy of the object pointed to by this_arg or avoid any double-freeing. */ - void *(*clone)(const void *this_arg); + void (*cloned)(struct LDKSign *NONNULL_PTR 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. @@ -3667,6 +3686,33 @@ typedef struct LDKCResult_CVec_C2Tuple_BlockHashChannelMonitorZZErrorZ { bool result_ok; } LDKCResult_CVec_C2Tuple_BlockHashChannelMonitorZZErrorZ; +/** + * An enum which can either contain a u16 or not + */ +typedef enum LDKCOption_u16Z_Tag { + /** + * When we're in this state, this COption_u16Z contains a u16 + */ + LDKCOption_u16Z_Some, + /** + * When we're in this state, this COption_u16Z contains nothing + */ + LDKCOption_u16Z_None, + /** + * Must be last for serialization purposes + */ + LDKCOption_u16Z_Sentinel, +} LDKCOption_u16Z_Tag; + +typedef struct LDKCOption_u16Z { + LDKCOption_u16Z_Tag tag; + union { + struct { + uint16_t some; + }; + }; +} LDKCOption_u16Z; + /** * Indicates an error on the client's part (usually some variant of attempting to use too-low or * too-high values) @@ -3910,6 +3956,39 @@ typedef struct LDKCResult_NonePaymentSendFailureZ { bool result_ok; } LDKCResult_NonePaymentSendFailureZ; +/** + * The contents of CResult_PaymentHashPaymentSendFailureZ + */ +typedef union LDKCResult_PaymentHashPaymentSendFailureZPtr { + /** + * A pointer to the contents in the success state. + * Reading from this pointer when `result_ok` is not set is undefined. + */ + struct LDKThirtyTwoBytes *result; + /** + * A pointer to the contents in the error state. + * Reading from this pointer when `result_ok` is set is undefined. + */ + struct LDKPaymentSendFailure *err; +} LDKCResult_PaymentHashPaymentSendFailureZPtr; + +/** + * A CResult_PaymentHashPaymentSendFailureZ represents the result of a fallible operation, + * containing a crate::c_types::ThirtyTwoBytes on success and a crate::lightning::ln::channelmanager::PaymentSendFailure on failure. + * `result_ok` indicates the overall state, and the contents are provided via `contents`. + */ +typedef struct LDKCResult_PaymentHashPaymentSendFailureZ { + /** + * The contents of this CResult_PaymentHashPaymentSendFailureZ, accessible via either + * `err` or `result` depending on the state of `result_ok`. + */ + union LDKCResult_PaymentHashPaymentSendFailureZPtr contents; + /** + * Whether this CResult_PaymentHashPaymentSendFailureZ represents a success state. + */ + bool result_ok; +} LDKCResult_PaymentHashPaymentSendFailureZ; + /** * A 4-byte byte array. */ @@ -5336,6 +5415,74 @@ typedef struct LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32ScriptZZZZ { uintptr_t datalen; } LDKCVec_C2Tuple_TxidCVec_C2Tuple_u32ScriptZZZZ; +/** + * 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. + */ +typedef enum LDKPaymentPurpose_Tag { + /** + * Information for receiving a payment that we generated an invoice for. + */ + LDKPaymentPurpose_InvoicePayment, + /** + * Because this is a spontaneous payment, the payer generated their own preimage rather than us + * (the payee) providing a preimage. + */ + LDKPaymentPurpose_SpontaneousPayment, + /** + * Must be last for serialization purposes + */ + LDKPaymentPurpose_Sentinel, +} LDKPaymentPurpose_Tag; + +typedef struct LDKPaymentPurpose_LDKInvoicePayment_Body { + /** + * 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 + * + * Note that this (or a relevant inner pointer) may be NULL or all-0s to represent None + */ + struct LDKThirtyTwoBytes payment_preimage; + /** + * 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 + */ + struct LDKThirtyTwoBytes payment_secret; + /** + * This is the `user_payment_id` which was provided to + * [`ChannelManager::create_inbound_payment_for_hash`] or + * [`ChannelManager::create_inbound_payment`]. It has no meaning inside of LDK and is + * simply copied here. It may be used to correlate PaymentReceived events with invoice + * metadata stored elsewhere. + * + * [`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 + */ + uint64_t user_payment_id; +} LDKPaymentPurpose_LDKInvoicePayment_Body; + +typedef struct MUST_USE_STRUCT LDKPaymentPurpose { + LDKPaymentPurpose_Tag tag; + union { + LDKPaymentPurpose_LDKInvoicePayment_Body invoice_payment; + struct { + struct LDKThirtyTwoBytes spontaneous_payment; + }; + }; +} LDKPaymentPurpose; + /** * An Event which you should probably take some action in response to. * @@ -5388,6 +5535,11 @@ typedef enum LDKEvent_Tag { * somewhere and spend them when you create on-chain transactions. */ LDKEvent_SpendableOutputs, + /** + * This event is generated when a payment has been successfully forwarded through us and a + * forwarding fee earned. + */ + LDKEvent_PaymentForwarded, /** * Must be last for serialization purposes */ @@ -5419,28 +5571,6 @@ typedef struct LDKEvent_LDKPaymentReceived_Body { * The hash for which the preimage should be handed to the ChannelManager. */ struct LDKThirtyTwoBytes payment_hash; - /** - * 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 - */ - struct LDKThirtyTwoBytes payment_preimage; - /** - * 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 - */ - struct LDKThirtyTwoBytes payment_secret; /** * The value, in thousandths of a satoshi, that this payment is for. Note that you must * compare this to the expected value before accepting the payment (as otherwise you are @@ -5448,16 +5578,10 @@ typedef struct LDKEvent_LDKPaymentReceived_Body { */ uint64_t amt; /** - * This is the `user_payment_id` which was provided to - * [`ChannelManager::create_inbound_payment_for_hash`] or - * [`ChannelManager::create_inbound_payment`]. It has no meaning inside of LDK and is - * simply copied here. It may be used to correlate PaymentReceived events with invoice - * metadata stored elsewhere. - * - * [`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 + * 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. */ - uint64_t user_payment_id; + struct LDKPaymentPurpose purpose; } LDKEvent_LDKPaymentReceived_Body; typedef struct LDKEvent_LDKPaymentSent_Body { @@ -5499,6 +5623,30 @@ typedef struct LDKEvent_LDKSpendableOutputs_Body { struct LDKCVec_SpendableOutputDescriptorZ outputs; } LDKEvent_LDKSpendableOutputs_Body; +typedef struct LDKEvent_LDKPaymentForwarded_Body { + /** + * 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`. + */ + struct LDKCOption_u64Z fee_earned_msat; + /** + * If this is `true`, the forwarded HTLC was claimed by our counterparty via an on-chain + * transaction. + */ + bool claim_from_onchain_tx; +} LDKEvent_LDKPaymentForwarded_Body; + typedef struct MUST_USE_STRUCT LDKEvent { LDKEvent_Tag tag; union { @@ -5508,6 +5656,7 @@ typedef struct MUST_USE_STRUCT LDKEvent { LDKEvent_LDKPaymentFailed_Body payment_failed; LDKEvent_LDKPendingHTLCsForwardable_Body pending_htl_cs_forwardable; LDKEvent_LDKSpendableOutputs_Body spendable_outputs; + LDKEvent_LDKPaymentForwarded_Body payment_forwarded; }; } LDKEvent; @@ -7900,6 +8049,26 @@ typedef struct MUST_USE_STRUCT LDKUserConfig { bool is_owned; } LDKUserConfig; + + +/** + * 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; + /** * The `Access` trait defines behavior for accessing chain data and state, such as blocks and * UTXOs. @@ -8277,22 +8446,23 @@ typedef struct MUST_USE_STRUCT LDKChainParameters { /** - * The best known block as identified by its hash and height. + * Channel parameters which apply to our counterparty. These are split out from [`ChannelDetails`] + * to better separate parameters. */ -typedef struct MUST_USE_STRUCT LDKBestBlock { +typedef struct MUST_USE_STRUCT LDKChannelCounterparty { /** * 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; + LDKnativeChannelCounterparty *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; +} LDKChannelCounterparty; /** * A 3-byte byte array. @@ -8522,6 +8692,8 @@ typedef struct LDKRoutingMessageHandler { * starting at the node *after* the provided publickey and including batch_amount entries * immediately higher (as defined by ::cmp) than starting_point. * If None is provided for starting_point, we start at the first node. + * + * Note that starting_point (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKCVec_NodeAnnouncementZ (*get_next_node_announcements)(const void *this_arg, struct LDKPublicKey starting_point, uint8_t batch_amount); /** @@ -8633,11 +8805,12 @@ typedef struct MUST_USE_STRUCT LDKMessageHandler { * * For efficiency, Clone should be relatively cheap for this type. * - * You probably want to just extend an int and put a file descriptor in a struct and implement - * send_data. Note that if you are using a higher-level net library that may call close() itself, - * be careful to ensure you don't have races whereby you might register a new connection with an - * fd which is the same as a previous one which has yet to be removed via - * PeerManager::socket_disconnected(). + * Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original + * has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it + * having triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no + * further calls to the [`PeerManager`] related to the original socket occur. This allows you to + * use a file descriptor for your SocketDescriptor directly, however for simplicity you may wish + * to simply use another value which is guaranteed to be globally unique instead. */ typedef struct LDKSocketDescriptor { /** @@ -8649,25 +8822,27 @@ typedef struct LDKSocketDescriptor { * Attempts to send some data from the given slice to the peer. * * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected. - * Note that in the disconnected case, socket_disconnected must still fire and further write - * attempts may occur until that time. + * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be + * called and further write attempts may occur until that time. * - * If the returned size is smaller than data.len(), a write_available event must - * trigger the next time more data can be written. Additionally, until the a send_data event - * completes fully, no further read_events should trigger on the same peer! + * If the returned size is smaller than `data.len()`, a + * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be + * written. Additionally, until a `send_data` event completes fully, no further + * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to + * prevent denial-of-service issues, you should not read or buffer any data from the socket + * until then. * - * If a read_event on this descriptor had previously returned true (indicating that read - * events should be paused to prevent DoS in the send buffer), resume_read may be set - * indicating that read events on this descriptor should resume. A resume_read of false does - * *not* imply that further read events should be paused. + * If a [`PeerManager::read_event`] call on this descriptor had previously returned true + * (indicating that read events should be paused to prevent DoS in the send buffer), + * `resume_read` may be set indicating that read events on this descriptor should resume. A + * `resume_read` of false carries no meaning, and should not cause any action. */ uintptr_t (*send_data)(void *this_arg, struct LDKu8slice data, bool resume_read); /** - * Disconnect the socket pointed to by this SocketDescriptor. Once this function returns, no - * more calls to write_buffer_space_avail, read_event or socket_disconnected may be made with - * this descriptor. No socket_disconnected call should be generated as a result of this call, - * though races may occur whereby disconnect_socket is called after a call to - * socket_disconnected but prior to socket_disconnected returning. + * Disconnect the socket pointed to by this SocketDescriptor. + * + * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this + * call (doing so is a noop). */ void (*disconnect_socket)(void *this_arg); /** @@ -8680,11 +8855,11 @@ typedef struct LDKSocketDescriptor { */ uint64_t (*hash)(const void *this_arg); /** - * Creates a copy of the object pointed to by this_arg, for a copy of this SocketDescriptor. - * Note that the ultimate copy of the SocketDescriptor 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 SocketDescriptor. + * Called, if set, after this SocketDescriptor has been cloned into a duplicate object. + * The new SocketDescriptor is provided, and should be mutated as needed to perform a + * deep copy of the object pointed to by this_arg or avoid any double-freeing. */ - void *(*clone)(const void *this_arg); + void (*cloned)(struct LDKSocketDescriptor *NONNULL_PTR new_SocketDescriptor); /** * 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. @@ -8695,14 +8870,25 @@ typedef struct LDKSocketDescriptor { /** - * A PeerManager manages a set of peers, described by their SocketDescriptor and marshalls socket - * events into messages which it passes on to its MessageHandlers. + * A PeerManager manages a set of peers, described by their [`SocketDescriptor`] and marshalls + * socket events into messages which it passes on to its [`MessageHandler`]. + * + * Locks are taken internally, so you must never assume that reentrancy from a + * [`SocketDescriptor`] call back into [`PeerManager`] methods will not deadlock. + * + * Calls to [`read_event`] will decode relevant messages and pass them to the + * [`ChannelMessageHandler`], likely doing message processing in-line. Thus, the primary form of + * parallelism in Rust-Lightning is in calls to [`read_event`]. Note, however, that calls to any + * [`PeerManager`] functions related to the same connection must occur only in serial, making new + * calls only after previous ones have returned. * * Rather than using a plain PeerManager, it is preferable to use either a SimpleArcPeerManager * a SimpleRefPeerManager, for conciseness. See their documentation for more details, but * essentially you should default to using a SimpleRefPeerManager, and use a * SimpleArcPeerManager when you require a PeerManager with a static lifetime, such as when * you're using lightning-net-tokio. + * + * [`read_event`]: PeerManager::read_event */ typedef struct MUST_USE_STRUCT LDKPeerManager { /** @@ -8857,6 +9043,7 @@ typedef struct MUST_USE_STRUCT LDKFilesystemPersister { * then there is a risk of channels force-closing on startup when the manager realizes it's * outdated. However, as long as `ChannelMonitor` backups are sound, no funds besides those used * for unilateral chain closure fees are at risk. + *BackgroundProcessor will immediately stop on drop. It should be stored until shutdown. */ typedef struct MUST_USE_STRUCT LDKBackgroundProcessor { /** @@ -9022,6 +9209,10 @@ extern const uint32_t MIN_FINAL_CLTV_EXPIRY; extern const uintptr_t REVOKEABLE_REDEEMSCRIPT_MAX_LENGTH; +extern const uint64_t DEFAULT_EXPIRY_TIME; + +extern const uint64_t DEFAULT_MIN_FINAL_CLTV_EXPIRY; + extern const uint8_t TAG_PAYMENT_HASH; extern const uint8_t TAG_DESCRIPTION; @@ -9051,6 +9242,11 @@ struct LDKStr _ldk_c_bindings_get_compiled_version(void); */ void Transaction_free(struct LDKTransaction _res); +/** + * Convenience function for constructing a new TxOut + */ +struct LDKTxOut TxOut_new(struct LDKCVec_u8Z script_pubkey, uint64_t value); + /** * Frees the data pointed to by script_pubkey. */ @@ -9913,6 +10109,27 @@ struct LDKCResult_CVec_C2Tuple_BlockHashChannelMonitorZZErrorZ CResult_CVec_C2Tu */ void CResult_CVec_C2Tuple_BlockHashChannelMonitorZZErrorZ_free(struct LDKCResult_CVec_C2Tuple_BlockHashChannelMonitorZZErrorZ _res); +/** + * Constructs a new COption_u16Z containing a u16 + */ +struct LDKCOption_u16Z COption_u16Z_some(uint16_t o); + +/** + * Constructs a new COption_u16Z containing nothing + */ +struct LDKCOption_u16Z COption_u16Z_none(void); + +/** + * Frees any resources associated with the u16, if we are in the Some state + */ +void COption_u16Z_free(struct LDKCOption_u16Z _res); + +/** + * Creates a new COption_u16Z which has the same data as `orig` + * but with all dynamically-allocated buffers duplicated in new buffers. + */ +struct LDKCOption_u16Z COption_u16Z_clone(const struct LDKCOption_u16Z *NONNULL_PTR orig); + /** * Creates a new CResult_NoneAPIErrorZ in the success state. */ @@ -9965,6 +10182,27 @@ void CResult_NonePaymentSendFailureZ_free(struct LDKCResult_NonePaymentSendFailu */ struct LDKCResult_NonePaymentSendFailureZ CResult_NonePaymentSendFailureZ_clone(const struct LDKCResult_NonePaymentSendFailureZ *NONNULL_PTR orig); +/** + * Creates a new CResult_PaymentHashPaymentSendFailureZ in the success state. + */ +struct LDKCResult_PaymentHashPaymentSendFailureZ CResult_PaymentHashPaymentSendFailureZ_ok(struct LDKThirtyTwoBytes o); + +/** + * Creates a new CResult_PaymentHashPaymentSendFailureZ in the error state. + */ +struct LDKCResult_PaymentHashPaymentSendFailureZ CResult_PaymentHashPaymentSendFailureZ_err(struct LDKPaymentSendFailure e); + +/** + * Frees any resources used by the CResult_PaymentHashPaymentSendFailureZ. + */ +void CResult_PaymentHashPaymentSendFailureZ_free(struct LDKCResult_PaymentHashPaymentSendFailureZ _res); + +/** + * Creates a new CResult_PaymentHashPaymentSendFailureZ which has the same data as `orig` + * but with all dynamically-allocated buffers duplicated in new buffers. + */ +struct LDKCResult_PaymentHashPaymentSendFailureZ CResult_PaymentHashPaymentSendFailureZ_clone(const struct LDKCResult_PaymentHashPaymentSendFailureZ *NONNULL_PTR orig); + /** * Frees the buffer pointed to by `data` if `datalen` is non-0. */ @@ -11536,78 +11774,283 @@ void CResult_InvoiceSignOrCreationErrorZ_free(struct LDKCResult_InvoiceSignOrCre struct LDKCResult_InvoiceSignOrCreationErrorZ CResult_InvoiceSignOrCreationErrorZ_clone(const struct LDKCResult_InvoiceSignOrCreationErrorZ *NONNULL_PTR orig); /** - * Frees any resources used by the Event + * Frees any resources used by the PaymentPurpose */ -void Event_free(struct LDKEvent this_ptr); +void PaymentPurpose_free(struct LDKPaymentPurpose this_ptr); /** - * Creates a copy of the Event + * Creates a copy of the PaymentPurpose */ -struct LDKEvent Event_clone(const struct LDKEvent *NONNULL_PTR orig); +struct LDKPaymentPurpose PaymentPurpose_clone(const struct LDKPaymentPurpose *NONNULL_PTR orig); /** - * Serialize the Event object into a byte array which can be read by Event_read + * Utility method to constructs a new InvoicePayment-variant PaymentPurpose */ -struct LDKCVec_u8Z Event_write(const struct LDKEvent *NONNULL_PTR obj); +struct LDKPaymentPurpose PaymentPurpose_invoice_payment(struct LDKThirtyTwoBytes payment_preimage, struct LDKThirtyTwoBytes payment_secret, uint64_t user_payment_id); /** - * Frees any resources used by the MessageSendEvent + * Utility method to constructs a new SpontaneousPayment-variant PaymentPurpose */ -void MessageSendEvent_free(struct LDKMessageSendEvent this_ptr); +struct LDKPaymentPurpose PaymentPurpose_spontaneous_payment(struct LDKThirtyTwoBytes a); /** - * Creates a copy of the MessageSendEvent + * Frees any resources used by the Event */ -struct LDKMessageSendEvent MessageSendEvent_clone(const struct LDKMessageSendEvent *NONNULL_PTR orig); +void Event_free(struct LDKEvent this_ptr); /** - * Calls the free function if one is set + * Creates a copy of the Event */ -void MessageSendEventsProvider_free(struct LDKMessageSendEventsProvider this_ptr); +struct LDKEvent Event_clone(const struct LDKEvent *NONNULL_PTR orig); /** - * Calls the free function if one is set + * Utility method to constructs a new FundingGenerationReady-variant Event */ -void EventsProvider_free(struct LDKEventsProvider this_ptr); +struct LDKEvent Event_funding_generation_ready(struct LDKThirtyTwoBytes temporary_channel_id, uint64_t channel_value_satoshis, struct LDKCVec_u8Z output_script, uint64_t user_channel_id); /** - * Calls the free function if one is set + * Utility method to constructs a new PaymentReceived-variant Event */ -void EventHandler_free(struct LDKEventHandler this_ptr); +struct LDKEvent Event_payment_received(struct LDKThirtyTwoBytes payment_hash, uint64_t amt, struct LDKPaymentPurpose purpose); /** - * Frees any resources used by the APIError + * Utility method to constructs a new PaymentSent-variant Event */ -void APIError_free(struct LDKAPIError this_ptr); +struct LDKEvent Event_payment_sent(struct LDKThirtyTwoBytes payment_preimage); /** - * Creates a copy of the APIError + * Utility method to constructs a new PaymentFailed-variant Event */ -struct LDKAPIError APIError_clone(const struct LDKAPIError *NONNULL_PTR orig); +struct LDKEvent Event_payment_failed(struct LDKThirtyTwoBytes payment_hash, bool rejected_by_dest); /** - * Creates a digital signature of a message given a SecretKey, like the node's secret. - * A receiver knowing the PublicKey (e.g. the node's id) and the message can be sure that the signature was generated by the caller. - * Signatures are EC recoverable, meaning that given the message and the signature the PublicKey of the signer can be extracted. + * Utility method to constructs a new PendingHTLCsForwardable-variant Event */ -struct LDKCResult_StringErrorZ sign(struct LDKu8slice msg, struct LDKSecretKey sk); +struct LDKEvent Event_pending_htlcs_forwardable(uint64_t time_forwardable); /** - * Recovers the PublicKey of the signer of the message given the message and the signature. + * Utility method to constructs a new SpendableOutputs-variant Event */ -struct LDKCResult_PublicKeyErrorZ recover_pk(struct LDKu8slice msg, struct LDKStr sig); +struct LDKEvent Event_spendable_outputs(struct LDKCVec_SpendableOutputDescriptorZ outputs); /** - * Verifies a message was signed by a PrivateKey that derives to a given PublicKey, given a message, a signature, - * and the PublicKey. + * Utility method to constructs a new PaymentForwarded-variant Event */ -bool verify(struct LDKu8slice msg, struct LDKStr sig, struct LDKPublicKey pk); +struct LDKEvent Event_payment_forwarded(struct LDKCOption_u64Z fee_earned_msat, bool claim_from_onchain_tx); + +/** + * Serialize the Event object into a byte array which can be read by Event_read + */ +struct LDKCVec_u8Z Event_write(const struct LDKEvent *NONNULL_PTR obj); + +/** + * Frees any resources used by the MessageSendEvent + */ +void MessageSendEvent_free(struct LDKMessageSendEvent this_ptr); + +/** + * Creates a copy of the MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_clone(const struct LDKMessageSendEvent *NONNULL_PTR orig); + +/** + * Utility method to constructs a new SendAcceptChannel-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_accept_channel(struct LDKPublicKey node_id, struct LDKAcceptChannel msg); + +/** + * Utility method to constructs a new SendOpenChannel-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_open_channel(struct LDKPublicKey node_id, struct LDKOpenChannel msg); + +/** + * Utility method to constructs a new SendFundingCreated-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_funding_created(struct LDKPublicKey node_id, struct LDKFundingCreated msg); + +/** + * Utility method to constructs a new SendFundingSigned-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_funding_signed(struct LDKPublicKey node_id, struct LDKFundingSigned msg); + +/** + * Utility method to constructs a new SendFundingLocked-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_funding_locked(struct LDKPublicKey node_id, struct LDKFundingLocked msg); + +/** + * Utility method to constructs a new SendAnnouncementSignatures-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_announcement_signatures(struct LDKPublicKey node_id, struct LDKAnnouncementSignatures msg); + +/** + * Utility method to constructs a new UpdateHTLCs-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_update_htlcs(struct LDKPublicKey node_id, struct LDKCommitmentUpdate updates); + +/** + * Utility method to constructs a new SendRevokeAndACK-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_revoke_and_ack(struct LDKPublicKey node_id, struct LDKRevokeAndACK msg); + +/** + * Utility method to constructs a new SendClosingSigned-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_closing_signed(struct LDKPublicKey node_id, struct LDKClosingSigned msg); + +/** + * Utility method to constructs a new SendShutdown-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_shutdown(struct LDKPublicKey node_id, struct LDKShutdown msg); + +/** + * Utility method to constructs a new SendChannelReestablish-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_channel_reestablish(struct LDKPublicKey node_id, struct LDKChannelReestablish msg); + +/** + * Utility method to constructs a new BroadcastChannelAnnouncement-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_broadcast_channel_announcement(struct LDKChannelAnnouncement msg, struct LDKChannelUpdate update_msg); + +/** + * Utility method to constructs a new BroadcastNodeAnnouncement-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_broadcast_node_announcement(struct LDKNodeAnnouncement msg); + +/** + * Utility method to constructs a new BroadcastChannelUpdate-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_broadcast_channel_update(struct LDKChannelUpdate msg); + +/** + * Utility method to constructs a new SendChannelUpdate-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_channel_update(struct LDKPublicKey node_id, struct LDKChannelUpdate msg); + +/** + * Utility method to constructs a new HandleError-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_handle_error(struct LDKPublicKey node_id, struct LDKErrorAction action); + +/** + * Utility method to constructs a new PaymentFailureNetworkUpdate-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_payment_failure_network_update(struct LDKHTLCFailChannelUpdate update); + +/** + * Utility method to constructs a new SendChannelRangeQuery-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_channel_range_query(struct LDKPublicKey node_id, struct LDKQueryChannelRange msg); + +/** + * Utility method to constructs a new SendShortIdsQuery-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_short_ids_query(struct LDKPublicKey node_id, struct LDKQueryShortChannelIds msg); + +/** + * Utility method to constructs a new SendReplyChannelRange-variant MessageSendEvent + */ +struct LDKMessageSendEvent MessageSendEvent_send_reply_channel_range(struct LDKPublicKey node_id, struct LDKReplyChannelRange msg); + +/** + * Calls the free function if one is set + */ +void MessageSendEventsProvider_free(struct LDKMessageSendEventsProvider this_ptr); + +/** + * Calls the free function if one is set + */ +void EventsProvider_free(struct LDKEventsProvider this_ptr); + +/** + * Calls the free function if one is set + */ +void EventHandler_free(struct LDKEventHandler this_ptr); + +/** + * Frees any resources used by the APIError + */ +void APIError_free(struct LDKAPIError this_ptr); + +/** + * Creates a copy of the APIError + */ +struct LDKAPIError APIError_clone(const struct LDKAPIError *NONNULL_PTR orig); + +/** + * Utility method to constructs a new APIMisuseError-variant APIError + */ +struct LDKAPIError APIError_apimisuse_error(struct LDKStr err); + +/** + * Utility method to constructs a new FeeRateTooHigh-variant APIError + */ +struct LDKAPIError APIError_fee_rate_too_high(struct LDKStr err, uint32_t feerate); + +/** + * Utility method to constructs a new RouteError-variant APIError + */ +struct LDKAPIError APIError_route_error(struct LDKStr err); + +/** + * Utility method to constructs a new ChannelUnavailable-variant APIError + */ +struct LDKAPIError APIError_channel_unavailable(struct LDKStr err); + +/** + * Utility method to constructs a new MonitorUpdateFailed-variant APIError + */ +struct LDKAPIError APIError_monitor_update_failed(void); + +/** + * Creates a digital signature of a message given a SecretKey, like the node's secret. + * A receiver knowing the PublicKey (e.g. the node's id) and the message can be sure that the signature was generated by the caller. + * Signatures are EC recoverable, meaning that given the message and the signature the PublicKey of the signer can be extracted. + */ +struct LDKCResult_StringErrorZ sign(struct LDKu8slice msg, const uint8_t (*sk)[32]); + +/** + * Recovers the PublicKey of the signer of the message given the message and the signature. + */ +struct LDKCResult_PublicKeyErrorZ recover_pk(struct LDKu8slice msg, struct LDKStr sig); + +/** + * Verifies a message was signed by a PrivateKey that derives to a given PublicKey, given a message, a signature, + * and the PublicKey. + */ +bool verify(struct LDKu8slice msg, struct LDKStr sig, struct LDKPublicKey pk); /** * Creates a copy of the Level */ enum LDKLevel Level_clone(const enum LDKLevel *NONNULL_PTR orig); +/** + * Utility method to constructs a new Trace-variant Level + */ +enum LDKLevel Level_trace(void); + +/** + * Utility method to constructs a new Debug-variant Level + */ +enum LDKLevel Level_debug(void); + +/** + * Utility method to constructs a new Info-variant Level + */ +enum LDKLevel Level_info(void); + +/** + * Utility method to constructs a new Warn-variant Level + */ +enum LDKLevel Level_warn(void); + +/** + * Utility method to constructs a new Error-variant Level + */ +enum LDKLevel Level_error(void); + /** * Checks if two Levels contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -11835,20 +12278,26 @@ uint32_t ChannelHandshakeLimits_get_max_minimum_depth(const struct LDKChannelHan void ChannelHandshakeLimits_set_max_minimum_depth(struct LDKChannelHandshakeLimits *NONNULL_PTR this_ptr, uint32_t val); /** - * Set to force the incoming channel to match our announced channel preference in - * ChannelConfig. + * Set to force an incoming channel to match our announced channel preference in + * [`ChannelConfig::announced_channel`]. + * + * For a node which is not online reliably, this should be set to true and + * [`ChannelConfig::announced_channel`] set to false, ensuring that no announced (aka public) + * channels will ever be opened. * - * Default value: true, to make the default that no announced channels are possible (which is - * appropriate for any nodes which are not online very reliably). + * Default value: true. */ bool ChannelHandshakeLimits_get_force_announced_channel_preference(const struct LDKChannelHandshakeLimits *NONNULL_PTR this_ptr); /** - * Set to force the incoming channel to match our announced channel preference in - * ChannelConfig. + * Set to force an incoming channel to match our announced channel preference in + * [`ChannelConfig::announced_channel`]. + * + * For a node which is not online reliably, this should be set to true and + * [`ChannelConfig::announced_channel`] set to false, ensuring that no announced (aka public) + * channels will ever be opened. * - * Default value: true, to make the default that no announced channels are possible (which is - * appropriate for any nodes which are not online very reliably). + * Default value: true. */ void ChannelHandshakeLimits_set_force_announced_channel_preference(struct LDKChannelHandshakeLimits *NONNULL_PTR this_ptr, bool val); @@ -11895,22 +12344,56 @@ MUST_USE_RES struct LDKChannelHandshakeLimits ChannelHandshakeLimits_default(voi void ChannelConfig_free(struct LDKChannelConfig this_obj); /** - * Amount (in millionths of a satoshi) the channel will charge per transferred satoshi. + * Amount (in millionths of a satoshi) charged per satoshi for payments forwarded outbound + * over the channel. * This may be allowed to change at runtime in a later update, however doing so must result in * update messages sent to notify all nodes of our updated relay fee. * * Default value: 0. */ -uint32_t ChannelConfig_get_fee_proportional_millionths(const struct LDKChannelConfig *NONNULL_PTR this_ptr); +uint32_t ChannelConfig_get_forwarding_fee_proportional_millionths(const struct LDKChannelConfig *NONNULL_PTR this_ptr); /** - * Amount (in millionths of a satoshi) the channel will charge per transferred satoshi. + * Amount (in millionths of a satoshi) charged per satoshi for payments forwarded outbound + * over the channel. * This may be allowed to change at runtime in a later update, however doing so must result in * update messages sent to notify all nodes of our updated relay fee. * * Default value: 0. */ -void ChannelConfig_set_fee_proportional_millionths(struct LDKChannelConfig *NONNULL_PTR this_ptr, uint32_t val); +void ChannelConfig_set_forwarding_fee_proportional_millionths(struct LDKChannelConfig *NONNULL_PTR this_ptr, uint32_t val); + +/** + * Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in + * excess of [`forwarding_fee_proportional_millionths`]. + * This may be allowed to change at runtime in a later update, however doing so must result in + * update messages sent to notify all nodes of our updated relay fee. + * + * The default value of a single satoshi roughly matches the market rate on many routing nodes + * as of July 2021. Adjusting it upwards or downwards may change whether nodes route through + * this node. + * + * Default value: 1000. + * + * [`forwarding_fee_proportional_millionths`]: ChannelConfig::forwarding_fee_proportional_millionths + */ +uint32_t ChannelConfig_get_forwarding_fee_base_msat(const struct LDKChannelConfig *NONNULL_PTR this_ptr); + +/** + * Amount (in milli-satoshi) charged for payments forwarded outbound over the channel, in + * excess of [`forwarding_fee_proportional_millionths`]. + * This may be allowed to change at runtime in a later update, however doing so must result in + * update messages sent to notify all nodes of our updated relay fee. + * + * The default value of a single satoshi roughly matches the market rate on many routing nodes + * as of July 2021. Adjusting it upwards or downwards may change whether nodes route through + * this node. + * + * Default value: 1000. + * + * [`forwarding_fee_proportional_millionths`]: ChannelConfig::forwarding_fee_proportional_millionths + */ +void ChannelConfig_set_forwarding_fee_base_msat(struct LDKChannelConfig *NONNULL_PTR this_ptr, uint32_t val); /** * The difference in the CLTV value between incoming HTLCs and an outbound HTLC forwarded over @@ -11965,7 +12448,7 @@ void ChannelConfig_set_cltv_expiry_delta(struct LDKChannelConfig *NONNULL_PTR th * This should only be set to true for nodes which expect to be online reliably. * * As the node which funds a channel picks this value this will only apply for new outbound - * channels unless ChannelHandshakeLimits::force_announced_channel_preferences is set. + * channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. * * This cannot be changed after the initial channel handshake. * @@ -11980,7 +12463,7 @@ bool ChannelConfig_get_announced_channel(const struct LDKChannelConfig *NONNULL_ * This should only be set to true for nodes which expect to be online reliably. * * As the node which funds a channel picks this value this will only apply for new outbound - * channels unless ChannelHandshakeLimits::force_announced_channel_preferences is set. + * channels unless [`ChannelHandshakeLimits::force_announced_channel_preference`] is set. * * This cannot be changed after the initial channel handshake. * @@ -12021,7 +12504,7 @@ void ChannelConfig_set_commit_upfront_shutdown_pubkey(struct LDKChannelConfig *N /** * Constructs a new ChannelConfig given each field */ -MUST_USE_RES struct LDKChannelConfig ChannelConfig_new(uint32_t fee_proportional_millionths_arg, uint16_t cltv_expiry_delta_arg, bool announced_channel_arg, bool commit_upfront_shutdown_pubkey_arg); +MUST_USE_RES struct LDKChannelConfig ChannelConfig_new(uint32_t forwarding_fee_proportional_millionths_arg, uint32_t forwarding_fee_base_msat_arg, uint16_t cltv_expiry_delta_arg, bool announced_channel_arg, bool commit_upfront_shutdown_pubkey_arg); /** * Creates a copy of the ChannelConfig @@ -12078,10 +12561,50 @@ struct LDKChannelConfig UserConfig_get_channel_options(const struct LDKUserConfi */ void UserConfig_set_channel_options(struct LDKUserConfig *NONNULL_PTR this_ptr, struct LDKChannelConfig val); +/** + * If this is set to false, we will reject any HTLCs which were to be forwarded over private + * channels. This prevents us from taking on HTLC-forwarding risk when we intend to run as a + * node which is not online reliably. + * + * For nodes which are not online reliably, you should set all channels to *not* be announced + * (using [`ChannelConfig::announced_channel`] and + * [`ChannelHandshakeLimits::force_announced_channel_preference`]) and set this to false to + * ensure you are not exposed to any forwarding risk. + * + * Note that because you cannot change a channel's announced state after creation, there is no + * way to disable forwarding on public channels retroactively. Thus, in order to change a node + * from a publicly-announced forwarding node to a private non-forwarding node you must close + * all your channels and open new ones. For privacy, you should also change your node_id + * (swapping all private and public key material for new ones) at that time. + * + * Default value: false. + */ +bool UserConfig_get_accept_forwards_to_priv_channels(const struct LDKUserConfig *NONNULL_PTR this_ptr); + +/** + * If this is set to false, we will reject any HTLCs which were to be forwarded over private + * channels. This prevents us from taking on HTLC-forwarding risk when we intend to run as a + * node which is not online reliably. + * + * For nodes which are not online reliably, you should set all channels to *not* be announced + * (using [`ChannelConfig::announced_channel`] and + * [`ChannelHandshakeLimits::force_announced_channel_preference`]) and set this to false to + * ensure you are not exposed to any forwarding risk. + * + * Note that because you cannot change a channel's announced state after creation, there is no + * way to disable forwarding on public channels retroactively. Thus, in order to change a node + * from a publicly-announced forwarding node to a private non-forwarding node you must close + * all your channels and open new ones. For privacy, you should also change your node_id + * (swapping all private and public key material for new ones) at that time. + * + * Default value: false. + */ +void UserConfig_set_accept_forwards_to_priv_channels(struct LDKUserConfig *NONNULL_PTR this_ptr, bool val); + /** * Constructs a new UserConfig given each field */ -MUST_USE_RES struct LDKUserConfig UserConfig_new(struct LDKChannelHandshakeConfig own_channel_config_arg, struct LDKChannelHandshakeLimits peer_channel_config_limits_arg, struct LDKChannelConfig channel_options_arg); +MUST_USE_RES struct LDKUserConfig UserConfig_new(struct LDKChannelHandshakeConfig own_channel_config_arg, struct LDKChannelHandshakeLimits peer_channel_config_limits_arg, struct LDKChannelConfig channel_options_arg, bool accept_forwards_to_priv_channels_arg); /** * Creates a copy of the UserConfig @@ -12093,11 +12616,52 @@ struct LDKUserConfig UserConfig_clone(const struct LDKUserConfig *NONNULL_PTR or */ MUST_USE_RES struct LDKUserConfig UserConfig_default(void); +/** + * Frees any resources used by the BestBlock, if is_owned is set and inner is non-NULL. + */ +void BestBlock_free(struct LDKBestBlock this_obj); + +/** + * Creates a copy of the BestBlock + */ +struct LDKBestBlock BestBlock_clone(const struct LDKBestBlock *NONNULL_PTR orig); + +/** + * Constructs a `BestBlock` that represents the genesis block at height 0 of the given + * network. + */ +MUST_USE_RES struct LDKBestBlock BestBlock_from_genesis(enum LDKNetwork network); + +/** + * Returns a `BestBlock` 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); + /** * Creates a copy of the AccessError */ enum LDKAccessError AccessError_clone(const enum LDKAccessError *NONNULL_PTR orig); +/** + * Utility method to constructs a new UnknownChain-variant AccessError + */ +enum LDKAccessError AccessError_unknown_chain(void); + +/** + * Utility method to constructs a new UnknownTx-variant AccessError + */ +enum LDKAccessError AccessError_unknown_tx(void); + /** * Calls the free function if one is set */ @@ -12130,11 +12694,15 @@ void WatchedOutput_free(struct LDKWatchedOutput this_obj); /** * First block where the transaction output may have been spent. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKThirtyTwoBytes WatchedOutput_get_block_hash(const struct LDKWatchedOutput *NONNULL_PTR this_ptr); /** * First block where the transaction output may have been spent. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void WatchedOutput_set_block_hash(struct LDKWatchedOutput *NONNULL_PTR this_ptr, struct LDKThirtyTwoBytes val); @@ -12183,6 +12751,21 @@ void BroadcasterInterface_free(struct LDKBroadcasterInterface this_ptr); */ enum LDKConfirmationTarget ConfirmationTarget_clone(const enum LDKConfirmationTarget *NONNULL_PTR orig); +/** + * Utility method to constructs a new Background-variant ConfirmationTarget + */ +enum LDKConfirmationTarget ConfirmationTarget_background(void); + +/** + * Utility method to constructs a new Normal-variant ConfirmationTarget + */ +enum LDKConfirmationTarget ConfirmationTarget_normal(void); + +/** + * Utility method to constructs a new HighPriority-variant ConfirmationTarget + */ +enum LDKConfirmationTarget ConfirmationTarget_high_priority(void); + /** * Calls the free function if one is set */ @@ -12201,6 +12784,8 @@ void ChainMonitor_free(struct LDKChainMonitor this_obj); * pre-filter blocks or only fetch blocks matching a compact filter. Otherwise, clients may * always need to fetch full blocks absent another means for determining which blocks contain * transactions relevant to the watched channels. + * + * Note that chain_source (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKChainMonitor ChainMonitor_new(struct LDKFilter *chain_source, struct LDKBroadcasterInterface broadcaster, struct LDKLogger logger, struct LDKFeeEstimator feeest, struct LDKPersist persister); @@ -12283,6 +12868,16 @@ struct LDKCResult_ChannelMonitorUpdateDecodeErrorZ ChannelMonitorUpdate_read(str */ enum LDKChannelMonitorUpdateErr ChannelMonitorUpdateErr_clone(const enum LDKChannelMonitorUpdateErr *NONNULL_PTR orig); +/** + * Utility method to constructs a new TemporaryFailure-variant ChannelMonitorUpdateErr + */ +enum LDKChannelMonitorUpdateErr ChannelMonitorUpdateErr_temporary_failure(void); + +/** + * Utility method to constructs a new PermanentFailure-variant ChannelMonitorUpdateErr + */ +enum LDKChannelMonitorUpdateErr ChannelMonitorUpdateErr_permanent_failure(void); + /** * Frees any resources used by the MonitorUpdateError, if is_owned is set and inner is non-NULL. */ @@ -12303,6 +12898,16 @@ void MonitorEvent_free(struct LDKMonitorEvent this_ptr); */ struct LDKMonitorEvent MonitorEvent_clone(const struct LDKMonitorEvent *NONNULL_PTR orig); +/** + * Utility method to constructs a new HTLCEvent-variant MonitorEvent + */ +struct LDKMonitorEvent MonitorEvent_htlcevent(struct LDKHTLCUpdate a); + +/** + * Utility method to constructs a new CommitmentTxBroadcasted-variant MonitorEvent + */ +struct LDKMonitorEvent MonitorEvent_commitment_tx_broadcasted(struct LDKOutPoint a); + /** * Frees any resources used by the HTLCUpdate, if is_owned is set and inner is non-NULL. */ @@ -12452,6 +13057,12 @@ MUST_USE_RES struct LDKCVec_TransactionOutputsZ ChannelMonitor_best_block_update */ MUST_USE_RES struct LDKCVec_TxidZ ChannelMonitor_get_relevant_txids(const struct LDKChannelMonitor *NONNULL_PTR this_arg); +/** + * Gets the latest best block which was connected either via the [`chain::Listen`] or + * [`chain::Confirm`] interfaces. + */ +MUST_USE_RES struct LDKBestBlock ChannelMonitor_current_best_block(const struct LDKChannelMonitor *NONNULL_PTR this_arg); + /** * Calls the free function if one is set */ @@ -12696,6 +13307,21 @@ void SpendableOutputDescriptor_free(struct LDKSpendableOutputDescriptor this_ptr */ struct LDKSpendableOutputDescriptor SpendableOutputDescriptor_clone(const struct LDKSpendableOutputDescriptor *NONNULL_PTR orig); +/** + * Utility method to constructs a new StaticOutput-variant SpendableOutputDescriptor + */ +struct LDKSpendableOutputDescriptor SpendableOutputDescriptor_static_output(struct LDKOutPoint outpoint, struct LDKTxOut output); + +/** + * Utility method to constructs a new DelayedPaymentOutput-variant SpendableOutputDescriptor + */ +struct LDKSpendableOutputDescriptor SpendableOutputDescriptor_delayed_payment_output(struct LDKDelayedPaymentOutputDescriptor a); + +/** + * Utility method to constructs a new StaticPaymentOutput-variant SpendableOutputDescriptor + */ +struct LDKSpendableOutputDescriptor SpendableOutputDescriptor_static_payment_output(struct LDKStaticPaymentOutputDescriptor a); + /** * Serialize the SpendableOutputDescriptor object into a byte array which can be read by SpendableOutputDescriptor_read */ @@ -12987,34 +13613,60 @@ MUST_USE_RES struct LDKChainParameters ChainParameters_new(enum LDKNetwork netwo struct LDKChainParameters ChainParameters_clone(const struct LDKChainParameters *NONNULL_PTR orig); /** - * Frees any resources used by the BestBlock, if is_owned is set and inner is non-NULL. + * Frees any resources used by the ChannelCounterparty, if is_owned is set and inner is non-NULL. */ -void BestBlock_free(struct LDKBestBlock this_obj); +void ChannelCounterparty_free(struct LDKChannelCounterparty this_obj); /** - * Creates a copy of the BestBlock + * The node_id of our counterparty */ -struct LDKBestBlock BestBlock_clone(const struct LDKBestBlock *NONNULL_PTR orig); +struct LDKPublicKey ChannelCounterparty_get_node_id(const struct LDKChannelCounterparty *NONNULL_PTR this_ptr); /** - * Returns the best block from the genesis of the given network. + * The node_id of our counterparty */ -MUST_USE_RES struct LDKBestBlock BestBlock_from_genesis(enum LDKNetwork network); +void ChannelCounterparty_set_node_id(struct LDKChannelCounterparty *NONNULL_PTR this_ptr, struct LDKPublicKey val); /** - * Returns the best block as identified by the given block hash and height. + * The Features the channel counterparty provided upon last connection. + * Useful for routing as it is the most up-to-date copy of the counterparty's features and + * many routing-relevant features are present in the init context. */ -MUST_USE_RES struct LDKBestBlock BestBlock_new(struct LDKThirtyTwoBytes block_hash, uint32_t height); +struct LDKInitFeatures ChannelCounterparty_get_features(const struct LDKChannelCounterparty *NONNULL_PTR this_ptr); /** - * Returns the best block hash. + * The Features the channel counterparty provided upon last connection. + * Useful for routing as it is the most up-to-date copy of the counterparty's features and + * many routing-relevant features are present in the init context. */ -MUST_USE_RES struct LDKThirtyTwoBytes BestBlock_block_hash(const struct LDKBestBlock *NONNULL_PTR this_arg); +void ChannelCounterparty_set_features(struct LDKChannelCounterparty *NONNULL_PTR this_ptr, struct LDKInitFeatures val); /** - * Returns the best block height. + * The value, in satoshis, that must always be held in the channel for our counterparty. This + * value ensures that if our counterparty broadcasts a revoked state, we can punish them by + * claiming at least this value on chain. + * + * This value is not included in [`inbound_capacity_msat`] as it can never be spent. + * + * [`inbound_capacity_msat`]: ChannelDetails::inbound_capacity_msat */ -MUST_USE_RES uint32_t BestBlock_height(const struct LDKBestBlock *NONNULL_PTR this_arg); +uint64_t ChannelCounterparty_get_unspendable_punishment_reserve(const struct LDKChannelCounterparty *NONNULL_PTR this_ptr); + +/** + * The value, in satoshis, that must always be held in the channel for our counterparty. This + * value ensures that if our counterparty broadcasts a revoked state, we can punish them by + * claiming at least this value on chain. + * + * This value is not included in [`inbound_capacity_msat`] as it can never be spent. + * + * [`inbound_capacity_msat`]: ChannelDetails::inbound_capacity_msat + */ +void ChannelCounterparty_set_unspendable_punishment_reserve(struct LDKChannelCounterparty *NONNULL_PTR this_ptr, uint64_t val); + +/** + * Creates a copy of the ChannelCounterparty + */ +struct LDKChannelCounterparty ChannelCounterparty_clone(const struct LDKChannelCounterparty *NONNULL_PTR orig); /** * Frees any resources used by the ChannelDetails, if is_owned is set and inner is non-NULL. @@ -13037,12 +13689,24 @@ const uint8_t (*ChannelDetails_get_channel_id(const struct LDKChannelDetails *NO */ void ChannelDetails_set_channel_id(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKThirtyTwoBytes val); +/** + * Parameters which apply to our counterparty. See individual fields for more information. + */ +struct LDKChannelCounterparty ChannelDetails_get_counterparty(const struct LDKChannelDetails *NONNULL_PTR this_ptr); + +/** + * Parameters which apply to our counterparty. See individual fields for more information. + */ +void ChannelDetails_set_counterparty(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKChannelCounterparty val); + /** * The Channel's funding transaction output, if we've negotiated the funding transaction with * our counterparty already. * * Note that, if this has been set, `channel_id` will be equivalent to * `funding_txo.unwrap().to_channel_id()`. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKOutPoint ChannelDetails_get_funding_txo(const struct LDKChannelDetails *NONNULL_PTR this_ptr); @@ -13052,6 +13716,8 @@ struct LDKOutPoint ChannelDetails_get_funding_txo(const struct LDKChannelDetails * * Note that, if this has been set, `channel_id` will be equivalent to * `funding_txo.unwrap().to_channel_id()`. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelDetails_set_funding_txo(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKOutPoint val); @@ -13068,38 +13734,40 @@ struct LDKCOption_u64Z ChannelDetails_get_short_channel_id(const struct LDKChann void ChannelDetails_set_short_channel_id(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKCOption_u64Z val); /** - * The node_id of our counterparty - */ -struct LDKPublicKey ChannelDetails_get_remote_network_id(const struct LDKChannelDetails *NONNULL_PTR this_ptr); - -/** - * The node_id of our counterparty - */ -void ChannelDetails_set_remote_network_id(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKPublicKey val); - -/** - * The Features the channel counterparty provided upon last connection. - * Useful for routing as it is the most up-to-date copy of the counterparty's features and - * many routing-relevant features are present in the init context. + * The value, in satoshis, of this channel as appears in the funding output */ -struct LDKInitFeatures ChannelDetails_get_counterparty_features(const struct LDKChannelDetails *NONNULL_PTR this_ptr); +uint64_t ChannelDetails_get_channel_value_satoshis(const struct LDKChannelDetails *NONNULL_PTR this_ptr); /** - * The Features the channel counterparty provided upon last connection. - * Useful for routing as it is the most up-to-date copy of the counterparty's features and - * many routing-relevant features are present in the init context. + * The value, in satoshis, of this channel as appears in the funding output */ -void ChannelDetails_set_counterparty_features(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKInitFeatures val); +void ChannelDetails_set_channel_value_satoshis(struct LDKChannelDetails *NONNULL_PTR this_ptr, uint64_t val); /** - * The value, in satoshis, of this channel as appears in the funding output + * The value, in satoshis, that must always be held in the channel for us. This value ensures + * that if we broadcast a revoked state, our counterparty can punish us by claiming at least + * this value on chain. + * + * This value is not included in [`outbound_capacity_msat`] as it can never be spent. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + * + * [`outbound_capacity_msat`]: ChannelDetails::outbound_capacity_msat */ -uint64_t ChannelDetails_get_channel_value_satoshis(const struct LDKChannelDetails *NONNULL_PTR this_ptr); +struct LDKCOption_u64Z ChannelDetails_get_unspendable_punishment_reserve(const struct LDKChannelDetails *NONNULL_PTR this_ptr); /** - * The value, in satoshis, of this channel as appears in the funding output + * The value, in satoshis, that must always be held in the channel for us. This value ensures + * that if we broadcast a revoked state, our counterparty can punish us by claiming at least + * this value on chain. + * + * This value is not included in [`outbound_capacity_msat`] as it can never be spent. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + * + * [`outbound_capacity_msat`]: ChannelDetails::outbound_capacity_msat */ -void ChannelDetails_set_channel_value_satoshis(struct LDKChannelDetails *NONNULL_PTR this_ptr, uint64_t val); +void ChannelDetails_set_unspendable_punishment_reserve(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKCOption_u64Z val); /** * The user_id passed in to create_channel, or 0 if the channel was inbound. @@ -13116,6 +13784,10 @@ void ChannelDetails_set_user_id(struct LDKChannelDetails *NONNULL_PTR this_ptr, * any pending HTLCs which are not yet fully resolved (and, thus, who's balance is not * available for inclusion in new outbound HTLCs). This further does not include any pending * outgoing HTLCs which are awaiting some other resolution to be sent. + * + * This value is not exact. Due to various in-flight changes, feerate changes, and our + * conflict-avoidance policy, exactly this amount is not likely to be spendable. However, we + * should be able to spend nearly this amount. */ uint64_t ChannelDetails_get_outbound_capacity_msat(const struct LDKChannelDetails *NONNULL_PTR this_ptr); @@ -13124,6 +13796,10 @@ uint64_t ChannelDetails_get_outbound_capacity_msat(const struct LDKChannelDetail * any pending HTLCs which are not yet fully resolved (and, thus, who's balance is not * available for inclusion in new outbound HTLCs). This further does not include any pending * outgoing HTLCs which are awaiting some other resolution to be sent. + * + * This value is not exact. Due to various in-flight changes, feerate changes, and our + * conflict-avoidance policy, exactly this amount is not likely to be spendable. However, we + * should be able to spend nearly this amount. */ void ChannelDetails_set_outbound_capacity_msat(struct LDKChannelDetails *NONNULL_PTR this_ptr, uint64_t val); @@ -13133,6 +13809,10 @@ void ChannelDetails_set_outbound_capacity_msat(struct LDKChannelDetails *NONNULL * available for inclusion in new inbound HTLCs). * Note that there are some corner cases not fully handled here, so the actual available * inbound capacity may be slightly higher than this. + * + * This value is not exact. Due to various in-flight changes, feerate changes, and our + * counterparty's conflict-avoidance policy, exactly this amount is not likely to be spendable. + * However, our counterparty should be able to spend nearly this amount. */ uint64_t ChannelDetails_get_inbound_capacity_msat(const struct LDKChannelDetails *NONNULL_PTR this_ptr); @@ -13142,9 +13822,65 @@ uint64_t ChannelDetails_get_inbound_capacity_msat(const struct LDKChannelDetails * available for inclusion in new inbound HTLCs). * Note that there are some corner cases not fully handled here, so the actual available * inbound capacity may be slightly higher than this. + * + * This value is not exact. Due to various in-flight changes, feerate changes, and our + * counterparty's conflict-avoidance policy, exactly this amount is not likely to be spendable. + * However, our counterparty should be able to spend nearly this amount. */ void ChannelDetails_set_inbound_capacity_msat(struct LDKChannelDetails *NONNULL_PTR this_ptr, uint64_t val); +/** + * The number of required confirmations on the funding transaction before the funding will be + * considered \"locked\". This number is selected by the channel fundee (i.e. us if + * [`is_outbound`] is *not* set), and can be selected for inbound channels with + * [`ChannelHandshakeConfig::minimum_depth`] or limited for outbound channels with + * [`ChannelHandshakeLimits::max_minimum_depth`]. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + * + * [`is_outbound`]: ChannelDetails::is_outbound + * [`ChannelHandshakeConfig::minimum_depth`]: crate::util::config::ChannelHandshakeConfig::minimum_depth + * [`ChannelHandshakeLimits::max_minimum_depth`]: crate::util::config::ChannelHandshakeLimits::max_minimum_depth + */ +struct LDKCOption_u32Z ChannelDetails_get_confirmations_required(const struct LDKChannelDetails *NONNULL_PTR this_ptr); + +/** + * The number of required confirmations on the funding transaction before the funding will be + * considered \"locked\". This number is selected by the channel fundee (i.e. us if + * [`is_outbound`] is *not* set), and can be selected for inbound channels with + * [`ChannelHandshakeConfig::minimum_depth`] or limited for outbound channels with + * [`ChannelHandshakeLimits::max_minimum_depth`]. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + * + * [`is_outbound`]: ChannelDetails::is_outbound + * [`ChannelHandshakeConfig::minimum_depth`]: crate::util::config::ChannelHandshakeConfig::minimum_depth + * [`ChannelHandshakeLimits::max_minimum_depth`]: crate::util::config::ChannelHandshakeLimits::max_minimum_depth + */ +void ChannelDetails_set_confirmations_required(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKCOption_u32Z val); + +/** + * The number of blocks (after our commitment transaction confirms) that we will need to wait + * until we can claim our funds after we force-close the channel. During this time our + * counterparty is allowed to punish us if we broadcasted a stale state. If our counterparty + * force-closes the channel and broadcasts a commitment transaction we do not have to wait any + * time to claim our non-HTLC-encumbered funds. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + */ +struct LDKCOption_u16Z ChannelDetails_get_force_close_spend_delay(const struct LDKChannelDetails *NONNULL_PTR this_ptr); + +/** + * The number of blocks (after our commitment transaction confirms) that we will need to wait + * until we can claim our funds after we force-close the channel. During this time our + * counterparty is allowed to punish us if we broadcasted a stale state. If our counterparty + * force-closes the channel and broadcasts a commitment transaction we do not have to wait any + * time to claim our non-HTLC-encumbered funds. + * + * This value will be `None` for outbound channels until the counterparty accepts the channel. + */ +void ChannelDetails_set_force_close_spend_delay(struct LDKChannelDetails *NONNULL_PTR this_ptr, struct LDKCOption_u16Z val); + /** * True if the channel was initiated (and thus funded) by us. */ @@ -13159,7 +13895,10 @@ void ChannelDetails_set_is_outbound(struct LDKChannelDetails *NONNULL_PTR this_p * True if the channel is confirmed, funding_locked messages have been exchanged, and the * channel is not currently being shut down. `funding_locked` message exchange implies the * required confirmation count has been reached (and we were connected to the peer at some - * point after the funding transaction received enough confirmations). + * point after the funding transaction received enough confirmations). The required + * confirmation count is provided in [`confirmations_required`]. + * + * [`confirmations_required`]: ChannelDetails::confirmations_required */ bool ChannelDetails_get_is_funding_locked(const struct LDKChannelDetails *NONNULL_PTR this_ptr); @@ -13167,14 +13906,16 @@ bool ChannelDetails_get_is_funding_locked(const struct LDKChannelDetails *NONNUL * True if the channel is confirmed, funding_locked messages have been exchanged, and the * channel is not currently being shut down. `funding_locked` message exchange implies the * required confirmation count has been reached (and we were connected to the peer at some - * point after the funding transaction received enough confirmations). + * point after the funding transaction received enough confirmations). The required + * confirmation count is provided in [`confirmations_required`]. + * + * [`confirmations_required`]: ChannelDetails::confirmations_required */ void ChannelDetails_set_is_funding_locked(struct LDKChannelDetails *NONNULL_PTR this_ptr, bool val); /** * True if the channel is (a) confirmed and funding_locked messages have been exchanged, (b) - * the peer is connected, (c) no monitor update failure is pending resolution, and (d) the - * channel is not currently negotiating a shutdown. + * the peer is connected, and (c) the channel is not currently negotiating a shutdown. * * This is a strict superset of `is_funding_locked`. */ @@ -13182,8 +13923,7 @@ bool ChannelDetails_get_is_usable(const struct LDKChannelDetails *NONNULL_PTR th /** * True if the channel is (a) confirmed and funding_locked messages have been exchanged, (b) - * the peer is connected, (c) no monitor update failure is pending resolution, and (d) the - * channel is not currently negotiating a shutdown. + * the peer is connected, and (c) the channel is not currently negotiating a shutdown. * * This is a strict superset of `is_funding_locked`. */ @@ -13199,6 +13939,11 @@ bool ChannelDetails_get_is_public(const struct LDKChannelDetails *NONNULL_PTR th */ void ChannelDetails_set_is_public(struct LDKChannelDetails *NONNULL_PTR this_ptr, bool val); +/** + * Constructs a new ChannelDetails given each field + */ +MUST_USE_RES struct LDKChannelDetails ChannelDetails_new(struct LDKThirtyTwoBytes channel_id_arg, struct LDKChannelCounterparty counterparty_arg, struct LDKOutPoint funding_txo_arg, struct LDKCOption_u64Z short_channel_id_arg, uint64_t channel_value_satoshis_arg, struct LDKCOption_u64Z unspendable_punishment_reserve_arg, uint64_t user_id_arg, uint64_t outbound_capacity_msat_arg, uint64_t inbound_capacity_msat_arg, struct LDKCOption_u32Z confirmations_required_arg, struct LDKCOption_u16Z force_close_spend_delay_arg, bool is_outbound_arg, bool is_funding_locked_arg, bool is_usable_arg, bool is_public_arg); + /** * Creates a copy of the ChannelDetails */ @@ -13214,6 +13959,26 @@ void PaymentSendFailure_free(struct LDKPaymentSendFailure this_ptr); */ struct LDKPaymentSendFailure PaymentSendFailure_clone(const struct LDKPaymentSendFailure *NONNULL_PTR orig); +/** + * Utility method to constructs a new ParameterError-variant PaymentSendFailure + */ +struct LDKPaymentSendFailure PaymentSendFailure_parameter_error(struct LDKAPIError a); + +/** + * Utility method to constructs a new PathParameterError-variant PaymentSendFailure + */ +struct LDKPaymentSendFailure PaymentSendFailure_path_parameter_error(struct LDKCVec_CResult_NoneAPIErrorZZ a); + +/** + * Utility method to constructs a new AllFailedRetrySafe-variant PaymentSendFailure + */ +struct LDKPaymentSendFailure PaymentSendFailure_all_failed_retry_safe(struct LDKCVec_APIErrorZ a); + +/** + * Utility method to constructs a new PartialFailure-variant PaymentSendFailure + */ +struct LDKPaymentSendFailure PaymentSendFailure_partial_failure(struct LDKCVec_CResult_NoneAPIErrorZZ a); + /** * Constructs a new ChannelManager to hold several channels and route between them. * @@ -13249,6 +14014,12 @@ MUST_USE_RES struct LDKUserConfig ChannelManager_get_current_default_configurati * * Raises APIError::APIMisuseError when channel_value_satoshis > 2**24 or push_msat is * greater than channel_value_satoshis * 1k or channel_value_satoshis is < 1000. + * + * Note that we do not check if you are currently connected to the given peer. If no + * connection is available, the outbound `open_channel` message may fail to send, resulting in + * the channel eventually being silently forgotten. + * + * Note that override_config (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKCResult_NoneAPIErrorZ ChannelManager_create_channel(const struct LDKChannelManager *NONNULL_PTR this_arg, struct LDKPublicKey their_network_key, uint64_t channel_value_satoshis, uint64_t push_msat, uint64_t user_id, struct LDKUserConfig override_config); @@ -13329,9 +14100,27 @@ void ChannelManager_force_close_all_channels(const struct LDKChannelManager *NON * If a payment_secret *is* provided, we assume that the invoice had the payment_secret feature * bit set (either as required or as available). If multiple paths are present in the Route, * we assume the invoice had the basic_mpp feature set. + * + * Note that payment_secret (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKCResult_NonePaymentSendFailureZ ChannelManager_send_payment(const struct LDKChannelManager *NONNULL_PTR this_arg, const struct LDKRoute *NONNULL_PTR route, struct LDKThirtyTwoBytes payment_hash, struct LDKThirtyTwoBytes payment_secret); +/** + * Send a spontaneous payment, which is a payment that does not require the recipient to have + * generated an invoice. Optionally, you may specify the preimage. If you do choose to specify + * the preimage, it must be a cryptographically secure random value that no intermediate node + * would be able to guess -- otherwise, an intermediate node may claim the payment and it will + * never reach the recipient. + * + * Similar to regular payments, you MUST NOT reuse a `payment_preimage` value. See + * [`send_payment`] for more information about the risks of duplicate preimage usage. + * + * [`send_payment`]: Self::send_payment + * + * Note that payment_preimage (or a relevant inner pointer) may be NULL or all-0s to represent None + */ +MUST_USE_RES struct LDKCResult_PaymentHashPaymentSendFailureZ ChannelManager_send_spontaneous_payment(const struct LDKChannelManager *NONNULL_PTR this_arg, const struct LDKRoute *NONNULL_PTR route, struct LDKThirtyTwoBytes payment_preimage); + /** * Call this upon creation of a funding transaction for the given channel. * @@ -13483,7 +14272,7 @@ MUST_USE_RES struct LDKC2Tuple_PaymentHashPaymentSecretZ ChannelManager_create_i * The [`PaymentHash`] (and corresponding [`PaymentPreimage`]) must be globally unique. This * method may return an Err if another payment with the same payment_hash is still pending. * - * `user_payment_id` will be provided back in [`PaymentReceived::user_payment_id`] events to + * `user_payment_id` will be provided back in [`PaymentPurpose::InvoicePayment::user_payment_id`] events to * allow tracking of which events correspond with which calls to this and * [`create_inbound_payment`]. `user_payment_id` has no meaning inside of LDK, it is simply * copied to events and otherwise ignored. It may be used to correlate PaymentReceived events @@ -13517,7 +14306,7 @@ MUST_USE_RES struct LDKC2Tuple_PaymentHashPaymentSecretZ ChannelManager_create_i * * [`create_inbound_payment`]: Self::create_inbound_payment * [`PaymentReceived`]: events::Event::PaymentReceived - * [`PaymentReceived::user_payment_id`]: events::Event::PaymentReceived::user_payment_id + * [`PaymentPurpose::InvoicePayment::user_payment_id`]: events::PaymentPurpose::InvoicePayment::user_payment_id */ MUST_USE_RES struct LDKCResult_PaymentSecretAPIErrorZ ChannelManager_create_inbound_payment_for_hash(const struct LDKChannelManager *NONNULL_PTR this_arg, struct LDKThirtyTwoBytes payment_hash, struct LDKCOption_u64Z min_value_msat, uint32_t invoice_expiry_delta_secs, uint64_t user_payment_id); @@ -13561,6 +14350,12 @@ MUST_USE_RES bool ChannelManager_await_persistable_update_timeout(const struct L */ void ChannelManager_await_persistable_update(const struct LDKChannelManager *NONNULL_PTR this_arg); +/** + * Gets the latest best block which was connected either via the [`chain::Listen`] or + * [`chain::Confirm`] interfaces. + */ +MUST_USE_RES struct LDKBestBlock ChannelManager_current_best_block(const struct LDKChannelManager *NONNULL_PTR this_arg); + /** * 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 @@ -14797,6 +15592,26 @@ void NetAddress_free(struct LDKNetAddress this_ptr); */ struct LDKNetAddress NetAddress_clone(const struct LDKNetAddress *NONNULL_PTR orig); +/** + * Utility method to constructs a new IPv4-variant NetAddress + */ +struct LDKNetAddress NetAddress_ipv4(struct LDKFourBytes addr, uint16_t port); + +/** + * Utility method to constructs a new IPv6-variant NetAddress + */ +struct LDKNetAddress NetAddress_ipv6(struct LDKSixteenBytes addr, uint16_t port); + +/** + * Utility method to constructs a new OnionV2-variant NetAddress + */ +struct LDKNetAddress NetAddress_onion_v2(struct LDKTenBytes addr, uint16_t port); + +/** + * Utility method to constructs a new OnionV3-variant NetAddress + */ +struct LDKNetAddress NetAddress_onion_v3(struct LDKThirtyTwoBytes ed25519_pubkey, uint16_t checksum, uint8_t version, uint16_t port); + /** * Serialize the NetAddress object into a byte array which can be read by NetAddress_read */ @@ -15427,6 +16242,26 @@ void ErrorAction_free(struct LDKErrorAction this_ptr); */ struct LDKErrorAction ErrorAction_clone(const struct LDKErrorAction *NONNULL_PTR orig); +/** + * Utility method to constructs a new DisconnectPeer-variant ErrorAction + */ +struct LDKErrorAction ErrorAction_disconnect_peer(struct LDKErrorMessage msg); + +/** + * Utility method to constructs a new IgnoreError-variant ErrorAction + */ +struct LDKErrorAction ErrorAction_ignore_error(void); + +/** + * Utility method to constructs a new IgnoreAndLog-variant ErrorAction + */ +struct LDKErrorAction ErrorAction_ignore_and_log(enum LDKLevel a); + +/** + * Utility method to constructs a new SendErrorMessage-variant ErrorAction + */ +struct LDKErrorAction ErrorAction_send_error_message(struct LDKErrorMessage msg); + /** * Frees any resources used by the LightningError, if is_owned is set and inner is non-NULL. */ @@ -15489,11 +16324,15 @@ void CommitmentUpdate_set_update_fail_malformed_htlcs(struct LDKCommitmentUpdate /** * An update_fee message which should be sent + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKUpdateFee CommitmentUpdate_get_update_fee(const struct LDKCommitmentUpdate *NONNULL_PTR this_ptr); /** * An update_fee message which should be sent + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void CommitmentUpdate_set_update_fee(struct LDKCommitmentUpdate *NONNULL_PTR this_ptr, struct LDKUpdateFee val); @@ -15527,6 +16366,21 @@ void HTLCFailChannelUpdate_free(struct LDKHTLCFailChannelUpdate this_ptr); */ struct LDKHTLCFailChannelUpdate HTLCFailChannelUpdate_clone(const struct LDKHTLCFailChannelUpdate *NONNULL_PTR orig); +/** + * Utility method to constructs a new ChannelUpdateMessage-variant HTLCFailChannelUpdate + */ +struct LDKHTLCFailChannelUpdate HTLCFailChannelUpdate_channel_update_message(struct LDKChannelUpdate msg); + +/** + * Utility method to constructs a new ChannelClosed-variant HTLCFailChannelUpdate + */ +struct LDKHTLCFailChannelUpdate HTLCFailChannelUpdate_channel_closed(uint64_t short_channel_id, bool is_permanent); + +/** + * Utility method to constructs a new NodeFailure-variant HTLCFailChannelUpdate + */ +struct LDKHTLCFailChannelUpdate HTLCFailChannelUpdate_node_failure(struct LDKPublicKey node_id, bool is_permanent); + /** * Calls the free function if one is set */ @@ -15903,25 +16757,35 @@ void MessageHandler_free(struct LDKMessageHandler this_obj); /** * A message handler which handles messages specific to channels. Usually this is just a - * ChannelManager object or a ErroringMessageHandler. + * [`ChannelManager`] object or an [`ErroringMessageHandler`]. + * + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager */ const struct LDKChannelMessageHandler *MessageHandler_get_chan_handler(const struct LDKMessageHandler *NONNULL_PTR this_ptr); /** * A message handler which handles messages specific to channels. Usually this is just a - * ChannelManager object or a ErroringMessageHandler. + * [`ChannelManager`] object or an [`ErroringMessageHandler`]. + * + * [`ChannelManager`]: crate::ln::channelmanager::ChannelManager */ void MessageHandler_set_chan_handler(struct LDKMessageHandler *NONNULL_PTR this_ptr, struct LDKChannelMessageHandler val); /** * A message handler which handles messages updating our knowledge of the network channel - * graph. Usually this is just a NetGraphMsgHandlerMonitor object or an IgnoringMessageHandler. + * graph. Usually this is just a [`NetGraphMsgHandler`] object or an + * [`IgnoringMessageHandler`]. + * + * [`NetGraphMsgHandler`]: crate::routing::network_graph::NetGraphMsgHandler */ const struct LDKRoutingMessageHandler *MessageHandler_get_route_handler(const struct LDKMessageHandler *NONNULL_PTR this_ptr); /** * A message handler which handles messages updating our knowledge of the network channel - * graph. Usually this is just a NetGraphMsgHandlerMonitor object or an IgnoringMessageHandler. + * graph. Usually this is just a [`NetGraphMsgHandler`] object or an + * [`IgnoringMessageHandler`]. + * + * [`NetGraphMsgHandler`]: crate::routing::network_graph::NetGraphMsgHandler */ void MessageHandler_set_route_handler(struct LDKMessageHandler *NONNULL_PTR this_ptr, struct LDKRoutingMessageHandler val); @@ -15995,8 +16859,10 @@ MUST_USE_RES struct LDKCVec_PublicKeyZ PeerManager_get_peer_node_ids(const struc * * Returns a small number of bytes to send to the remote node (currently always 50). * - * Panics if descriptor is duplicative with some other descriptor which has not yet had a - * socket_disconnected(). + * Panics if descriptor is duplicative with some other descriptor which has not yet been + * [`socket_disconnected()`]. + * + * [`socket_disconnected()`]: PeerManager::socket_disconnected */ MUST_USE_RES struct LDKCResult_CVec_u8ZPeerHandleErrorZ PeerManager_new_outbound_connection(const struct LDKPeerManager *NONNULL_PTR this_arg, struct LDKPublicKey their_node_id, struct LDKSocketDescriptor descriptor); @@ -16008,8 +16874,10 @@ MUST_USE_RES struct LDKCResult_CVec_u8ZPeerHandleErrorZ PeerManager_new_outbound * call socket_disconnected for the new descriptor but must disconnect the connection * immediately. * - * Panics if descriptor is duplicative with some other descriptor which has not yet had - * socket_disconnected called. + * Panics if descriptor is duplicative with some other descriptor which has not yet been + * [`socket_disconnected()`]. + * + * [`socket_disconnected()`]: PeerManager::socket_disconnected */ MUST_USE_RES struct LDKCResult_NonePeerHandleErrorZ PeerManager_new_inbound_connection(const struct LDKPeerManager *NONNULL_PTR this_arg, struct LDKSocketDescriptor descriptor); @@ -16018,12 +16886,14 @@ MUST_USE_RES struct LDKCResult_NonePeerHandleErrorZ PeerManager_new_inbound_conn * * May return an Err to indicate that the connection should be closed. * - * Will most likely call send_data on the descriptor passed in (or the descriptor handed into - * new_*\\_connection) before returning. Thus, be very careful with reentrancy issues! The - * invariants around calling write_buffer_space_avail in case a write did not fully complete - * must still hold - be ready to call write_buffer_space_avail again if a write call generated - * here isn't sufficient! Panics if the descriptor was not previously registered in a - * new_\\*_connection event. + * May call [`send_data`] on the descriptor passed in (or an equal descriptor) before + * returning. Thus, be very careful with reentrancy issues! The invariants around calling + * [`write_buffer_space_avail`] in case a write did not fully complete must still hold - be + * ready to call `[write_buffer_space_avail`] again if a write call generated here isn't + * sufficient! + * + * [`send_data`]: SocketDescriptor::send_data + * [`write_buffer_space_avail`]: PeerManager::write_buffer_space_avail */ MUST_USE_RES struct LDKCResult_NonePeerHandleErrorZ PeerManager_write_buffer_space_avail(const struct LDKPeerManager *NONNULL_PTR this_arg, struct LDKSocketDescriptor *NONNULL_PTR descriptor); @@ -16032,51 +16902,60 @@ MUST_USE_RES struct LDKCResult_NonePeerHandleErrorZ PeerManager_write_buffer_spa * * May return an Err to indicate that the connection should be closed. * - * Will *not* call back into send_data on any descriptors to avoid reentrancy complexity. - * Thus, however, you almost certainly want to call process_events() after any read_event to - * generate send_data calls to handle responses. + * Will *not* call back into [`send_data`] on any descriptors to avoid reentrancy complexity. + * Thus, however, you should call [`process_events`] after any `read_event` to generate + * [`send_data`] calls to handle responses. * - * If Ok(true) is returned, further read_events should not be triggered until a send_data call - * on this file descriptor has resume_read set (preventing DoS issues in the send buffer). + * If `Ok(true)` is returned, further read_events should not be triggered until a + * [`send_data`] call on this descriptor has `resume_read` set (preventing DoS issues in the + * send buffer). * - * Panics if the descriptor was not previously registered in a new_*_connection event. + * [`send_data`]: SocketDescriptor::send_data + * [`process_events`]: PeerManager::process_events */ MUST_USE_RES struct LDKCResult_boolPeerHandleErrorZ PeerManager_read_event(const struct LDKPeerManager *NONNULL_PTR this_arg, struct LDKSocketDescriptor *NONNULL_PTR peer_descriptor, struct LDKu8slice data); /** * Checks for any events generated by our handlers and processes them. Includes sending most * response messages as well as messages generated by calls to handler functions directly (eg - * functions like ChannelManager::process_pending_htlc_forward or send_payment). + * functions like [`ChannelManager::process_pending_htlc_forwards`] or [`send_payment`]). + * + * May call [`send_data`] on [`SocketDescriptor`]s. Thus, be very careful with reentrancy + * issues! + * + * [`send_payment`]: crate::ln::channelmanager::ChannelManager::send_payment + * [`ChannelManager::process_pending_htlc_forwards`]: crate::ln::channelmanager::ChannelManager::process_pending_htlc_forwards + * [`send_data`]: SocketDescriptor::send_data */ void PeerManager_process_events(const struct LDKPeerManager *NONNULL_PTR this_arg); /** * Indicates that the given socket descriptor's connection is now closed. - * - * This must only be called if the socket has been disconnected by the peer or your own - * decision to disconnect it and must NOT be called in any case where other parts of this - * library (eg PeerHandleError, explicit disconnect_socket calls) instruct you to disconnect - * the peer. - * - * Panics if the descriptor was not previously registered in a successful new_*_connection event. */ void PeerManager_socket_disconnected(const struct LDKPeerManager *NONNULL_PTR this_arg, const struct LDKSocketDescriptor *NONNULL_PTR descriptor); /** * Disconnect a peer given its node id. * - * Set no_connection_possible to true to prevent any further connection with this peer, + * Set `no_connection_possible` to true to prevent any further connection with this peer, * force-closing any channels we have with it. * - * If a peer is connected, this will call `disconnect_socket` on the descriptor for the peer, - * so be careful about reentrancy issues. + * If a peer is connected, this will call [`disconnect_socket`] on the descriptor for the + * peer. Thus, be very careful about reentrancy issues. + * + * [`disconnect_socket`]: SocketDescriptor::disconnect_socket */ void PeerManager_disconnect_by_node_id(const struct LDKPeerManager *NONNULL_PTR this_arg, struct LDKPublicKey node_id, bool no_connection_possible); /** * This function should be called roughly once every 30 seconds. - * It will send pings to each peer and disconnect those which did not respond to the last round of pings. - * Will most likely call send_data on all of the registered descriptors, thus, be very careful with reentrancy issues! + * It will send pings to each peer and disconnect those which did not respond to the last + * round of pings. + * + * May call [`send_data`] on all [`SocketDescriptor`]s. Thus, be very careful with reentrancy + * issues! + * + * [`send_data`]: SocketDescriptor::send_data */ void PeerManager_timer_tick_occurred(const struct LDKPeerManager *NONNULL_PTR this_arg); @@ -16473,22 +17352,30 @@ void ChannelTransactionParameters_set_is_outbound_from_holder(struct LDKChannelT /** * The late-bound counterparty channel transaction parameters. * These parameters are populated at the point in the protocol where the counterparty provides them. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKCounterpartyChannelTransactionParameters ChannelTransactionParameters_get_counterparty_parameters(const struct LDKChannelTransactionParameters *NONNULL_PTR this_ptr); /** * The late-bound counterparty channel transaction parameters. * These parameters are populated at the point in the protocol where the counterparty provides them. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelTransactionParameters_set_counterparty_parameters(struct LDKChannelTransactionParameters *NONNULL_PTR this_ptr, struct LDKCounterpartyChannelTransactionParameters val); /** * The late-bound funding outpoint + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKOutPoint ChannelTransactionParameters_get_funding_outpoint(const struct LDKChannelTransactionParameters *NONNULL_PTR this_ptr); /** * The late-bound funding outpoint + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelTransactionParameters_set_funding_outpoint(struct LDKChannelTransactionParameters *NONNULL_PTR this_ptr, struct LDKOutPoint val); @@ -17207,6 +18094,15 @@ bool RouteHintHop_eq(const struct LDKRouteHintHop *NONNULL_PTR a, const struct L */ struct LDKRouteHintHop RouteHintHop_clone(const struct LDKRouteHintHop *NONNULL_PTR orig); +/** + * Gets a keysend route from us (payer) to the given target node (payee). This is needed because + * keysend payments do not have an invoice from which to pull the payee's supported features, which + * makes it tricky to otherwise supply the `payee_features` parameter of `get_route`. + * + * Note that first_hops (or a relevant inner pointer) may be NULL or all-0s to represent None + */ +struct LDKCResult_RouteLightningErrorZ get_keysend_route(struct LDKPublicKey our_node_id, const struct LDKNetworkGraph *NONNULL_PTR network, struct LDKPublicKey payee, struct LDKCVec_ChannelDetailsZ *first_hops, struct LDKCVec_RouteHintZ last_hops, uint64_t final_value_msat, uint32_t final_cltv, struct LDKLogger logger); + /** * Gets a route from us (payer) to the given target node (payee). * @@ -17227,6 +18123,9 @@ struct LDKRouteHintHop RouteHintHop_clone(const struct LDKRouteHintHop *NONNULL_ * The fees on channels from us to next-hops are ignored (as they are assumed to all be * equal), however the enabled/disabled bit on such channels as well as the * htlc_minimum_msat/htlc_maximum_msat *are* checked as they may change based on the receiving node. + * + * Note that payee_features (or a relevant inner pointer) may be NULL or all-0s to represent None + * Note that first_hops (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKCResult_RouteLightningErrorZ get_route(struct LDKPublicKey our_node_id, const struct LDKNetworkGraph *NONNULL_PTR network, struct LDKPublicKey payee, struct LDKInvoiceFeatures payee_features, struct LDKCVec_ChannelDetailsZ *first_hops, struct LDKCVec_RouteHintZ last_hops, uint64_t final_value_msat, uint32_t final_cltv, struct LDKLogger logger); @@ -17256,12 +18155,16 @@ void NetGraphMsgHandler_free(struct LDKNetGraphMsgHandler this_obj); * Chain monitor is used to make sure announced channels exist on-chain, * channel data is correct, and that the announcement is signed with * channel owners' keys. + * + * Note that chain_access (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKNetGraphMsgHandler NetGraphMsgHandler_new(struct LDKThirtyTwoBytes genesis_hash, struct LDKAccess *chain_access, struct LDKLogger logger); /** * Creates a new tracker of the actual state of the network of channels and nodes, * assuming an existing Network Graph. + * + * Note that chain_access (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKNetGraphMsgHandler NetGraphMsgHandler_from_net_graph(struct LDKAccess *chain_access, struct LDKLogger logger, struct LDKNetworkGraph network_graph); @@ -17269,6 +18172,8 @@ MUST_USE_RES struct LDKNetGraphMsgHandler NetGraphMsgHandler_from_net_graph(stru * Adds a provider used to check new announcements. Does not affect * existing announcements unless they are updated. * Add, update or remove the provider would replace the current one. + * + * Note that chain_access (or a relevant inner pointer) may be NULL or all-0s to represent None */ void NetGraphMsgHandler_add_chain_access(struct LDKNetGraphMsgHandler *NONNULL_PTR this_arg, struct LDKAccess *chain_access); @@ -17369,6 +18274,8 @@ void DirectionalChannelInfo_set_fees(struct LDKDirectionalChannelInfo *NONNULL_P * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKChannelUpdate DirectionalChannelInfo_get_last_update_message(const struct LDKDirectionalChannelInfo *NONNULL_PTR this_ptr); @@ -17377,6 +18284,8 @@ struct LDKChannelUpdate DirectionalChannelInfo_get_last_update_message(const str * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void DirectionalChannelInfo_set_last_update_message(struct LDKDirectionalChannelInfo *NONNULL_PTR this_ptr, struct LDKChannelUpdate val); @@ -17427,11 +18336,15 @@ void ChannelInfo_set_node_one(struct LDKChannelInfo *NONNULL_PTR this_ptr, struc /** * Details about the first direction of a channel + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKDirectionalChannelInfo ChannelInfo_get_one_to_two(const struct LDKChannelInfo *NONNULL_PTR this_ptr); /** * Details about the first direction of a channel + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelInfo_set_one_to_two(struct LDKChannelInfo *NONNULL_PTR this_ptr, struct LDKDirectionalChannelInfo val); @@ -17447,11 +18360,15 @@ void ChannelInfo_set_node_two(struct LDKChannelInfo *NONNULL_PTR this_ptr, struc /** * Details about the second direction of a channel + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKDirectionalChannelInfo ChannelInfo_get_two_to_one(const struct LDKChannelInfo *NONNULL_PTR this_ptr); /** * Details about the second direction of a channel + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelInfo_set_two_to_one(struct LDKChannelInfo *NONNULL_PTR this_ptr, struct LDKDirectionalChannelInfo val); @@ -17470,6 +18387,8 @@ void ChannelInfo_set_capacity_sats(struct LDKChannelInfo *NONNULL_PTR this_ptr, * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKChannelAnnouncement ChannelInfo_get_announcement_message(const struct LDKChannelInfo *NONNULL_PTR this_ptr); @@ -17478,6 +18397,8 @@ struct LDKChannelAnnouncement ChannelInfo_get_announcement_message(const struct * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void ChannelInfo_set_announcement_message(struct LDKChannelInfo *NONNULL_PTR this_ptr, struct LDKChannelAnnouncement val); @@ -17616,6 +18537,8 @@ void NodeAnnouncementInfo_set_addresses(struct LDKNodeAnnouncementInfo *NONNULL_ * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKNodeAnnouncement NodeAnnouncementInfo_get_announcement_message(const struct LDKNodeAnnouncementInfo *NONNULL_PTR this_ptr); @@ -17624,6 +18547,8 @@ struct LDKNodeAnnouncement NodeAnnouncementInfo_get_announcement_message(const s * Mostly redundant with the data we store in fields explicitly. * Everything else is useful only for sending out for initial routing sync. * Not stored if contains excess data to prevent DoS. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void NodeAnnouncementInfo_set_announcement_message(struct LDKNodeAnnouncementInfo *NONNULL_PTR this_ptr, struct LDKNodeAnnouncement val); @@ -17661,6 +18586,8 @@ void NodeInfo_set_channels(struct LDKNodeInfo *NONNULL_PTR this_ptr, struct LDKC * Lowest fees enabling routing via any of the enabled, known channels to a node. * The two fields (flat and proportional fee) are independent, * meaning they don't have to refer to the same channel. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKRoutingFees NodeInfo_get_lowest_inbound_channel_fees(const struct LDKNodeInfo *NONNULL_PTR this_ptr); @@ -17668,6 +18595,8 @@ struct LDKRoutingFees NodeInfo_get_lowest_inbound_channel_fees(const struct LDKN * Lowest fees enabling routing via any of the enabled, known channels to a node. * The two fields (flat and proportional fee) are independent, * meaning they don't have to refer to the same channel. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void NodeInfo_set_lowest_inbound_channel_fees(struct LDKNodeInfo *NONNULL_PTR this_ptr, struct LDKRoutingFees val); @@ -17675,6 +18604,8 @@ void NodeInfo_set_lowest_inbound_channel_fees(struct LDKNodeInfo *NONNULL_PTR th * More information about a node from node_announcement. * Optional because we store a Node entry after learning about it from * a channel announcement, but before receiving a node announcement. + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ struct LDKNodeAnnouncementInfo NodeInfo_get_announcement_info(const struct LDKNodeInfo *NONNULL_PTR this_ptr); @@ -17682,6 +18613,8 @@ struct LDKNodeAnnouncementInfo NodeInfo_get_announcement_info(const struct LDKNo * More information about a node from node_announcement. * Optional because we store a Node entry after learning about it from * a channel announcement, but before receiving a node announcement. + * + * Note that val (or a relevant inner pointer) may be NULL or all-0s to represent None */ void NodeInfo_set_announcement_info(struct LDKNodeInfo *NONNULL_PTR this_ptr, struct LDKNodeAnnouncementInfo val); @@ -17747,6 +18680,8 @@ MUST_USE_RES struct LDKCResult_NoneLightningErrorZ NetworkGraph_update_node_from * * If a `chain::Access` object is provided via `chain_access`, it will be called to verify * the corresponding UTXO exists on chain and is correctly-formatted. + * + * Note that chain_access (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKCResult_NoneLightningErrorZ NetworkGraph_update_channel_from_announcement(struct LDKNetworkGraph *NONNULL_PTR this_arg, const struct LDKChannelAnnouncement *NONNULL_PTR msg, struct LDKAccess *chain_access); @@ -17757,6 +18692,8 @@ MUST_USE_RES struct LDKCResult_NoneLightningErrorZ NetworkGraph_update_channel_f * * If a `chain::Access` object is provided via `chain_access`, it will be called to verify * the corresponding UTXO exists on chain and is correctly-formatted. + * + * Note that chain_access (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKCResult_NoneLightningErrorZ NetworkGraph_update_channel_from_unsigned_announcement(struct LDKNetworkGraph *NONNULL_PTR this_arg, const struct LDKUnsignedChannelAnnouncement *NONNULL_PTR msg, struct LDKAccess *chain_access); @@ -17829,21 +18766,25 @@ void BackgroundProcessor_free(struct LDKBackgroundProcessor this_obj); void ChannelManagerPersister_free(struct LDKChannelManagerPersister this_ptr); /** - * Start a background thread that takes care of responsibilities enumerated in the top-level - * documentation. + * Start a background thread that takes care of responsibilities enumerated in the [top-level + * documentation]. + * + * The thread runs indefinitely unless the object is dropped, [`stop`] is called, or + * `persist_manager` returns an error. In case of an error, the error is retrieved by calling + * either [`join`] or [`stop`]. * - * If `persist_manager` returns an error, then this thread will return said error (and - * `start()` will need to be called again to restart the `BackgroundProcessor`). Users should - * wait on [`thread_handle`]'s `join()` method to be able to tell if and when an error is - * returned, or implement `persist_manager` such that an error is never returned to the - * `BackgroundProcessor` + * Typically, users should either implement [`ChannelManagerPersister`] to never return an + * error or call [`join`] and handle any error that may arise. For the latter case, the + * `BackgroundProcessor` must be restarted by calling `start` again after handling the error. * * `persist_manager` is responsible for writing out the [`ChannelManager`] to disk, and/or * uploading to one or more backup services. See [`ChannelManager::write`] for writing out a * [`ChannelManager`]. See [`FilesystemPersister::persist_manager`] for Rust-Lightning's * provided implementation. * - * [`thread_handle`]: BackgroundProcessor::thread_handle + * [top-level documentation]: Self + * [`join`]: Self::join + * [`stop`]: Self::stop * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager * [`ChannelManager::write`]: lightning::ln::channelmanager::ChannelManager#impl-Writeable * [`FilesystemPersister::persist_manager`]: lightning_persister::FilesystemPersister::persist_manager @@ -17851,7 +18792,28 @@ void ChannelManagerPersister_free(struct LDKChannelManagerPersister this_ptr); MUST_USE_RES struct LDKBackgroundProcessor BackgroundProcessor_start(struct LDKChannelManagerPersister persister, struct LDKEventHandler event_handler, const struct LDKChainMonitor *NONNULL_PTR chain_monitor, const struct LDKChannelManager *NONNULL_PTR channel_manager, const struct LDKPeerManager *NONNULL_PTR peer_manager, struct LDKLogger logger); /** - * Stop `BackgroundProcessor`'s thread. + * Join `BackgroundProcessor`'s thread, returning any error that occurred while persisting + * [`ChannelManager`]. + * + * # Panics + * + * This function panics if the background thread has panicked such as while persisting or + * handling events. + * + * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager + */ +MUST_USE_RES struct LDKCResult_NoneErrorZ BackgroundProcessor_join(struct LDKBackgroundProcessor this_arg); + +/** + * Stop `BackgroundProcessor`'s thread, returning any error that occurred while persisting + * [`ChannelManager`]. + * + * # Panics + * + * This function panics if the background thread has panicked such as while persisting or + * handling events. + * + * [`ChannelManager`]: lightning::ln::channelmanager::ChannelManager */ MUST_USE_RES struct LDKCResult_NoneErrorZ BackgroundProcessor_stop(struct LDKBackgroundProcessor this_arg); @@ -17982,6 +18944,26 @@ struct LDKPositiveTimestamp PositiveTimestamp_clone(const struct LDKPositiveTime */ enum LDKSiPrefix SiPrefix_clone(const enum LDKSiPrefix *NONNULL_PTR orig); +/** + * Utility method to constructs a new Milli-variant SiPrefix + */ +enum LDKSiPrefix SiPrefix_milli(void); + +/** + * Utility method to constructs a new Micro-variant SiPrefix + */ +enum LDKSiPrefix SiPrefix_micro(void); + +/** + * Utility method to constructs a new Nano-variant SiPrefix + */ +enum LDKSiPrefix SiPrefix_nano(void); + +/** + * Utility method to constructs a new Pico-variant SiPrefix + */ +enum LDKSiPrefix SiPrefix_pico(void); + /** * Checks if two SiPrefixs contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -17999,6 +18981,31 @@ MUST_USE_RES uint64_t SiPrefix_multiplier(const enum LDKSiPrefix *NONNULL_PTR th */ enum LDKCurrency Currency_clone(const enum LDKCurrency *NONNULL_PTR orig); +/** + * Utility method to constructs a new Bitcoin-variant Currency + */ +enum LDKCurrency Currency_bitcoin(void); + +/** + * Utility method to constructs a new BitcoinTestnet-variant Currency + */ +enum LDKCurrency Currency_bitcoin_testnet(void); + +/** + * Utility method to constructs a new Regtest-variant Currency + */ +enum LDKCurrency Currency_regtest(void); + +/** + * Utility method to constructs a new Simnet-variant Currency + */ +enum LDKCurrency Currency_simnet(void); + +/** + * Utility method to constructs a new Signet-variant Currency + */ +enum LDKCurrency Currency_signet(void); + /** * Checks if two Currencys contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -18100,6 +19107,21 @@ void Fallback_free(struct LDKFallback this_ptr); */ struct LDKFallback Fallback_clone(const struct LDKFallback *NONNULL_PTR orig); +/** + * Utility method to constructs a new SegWitProgram-variant Fallback + */ +struct LDKFallback Fallback_seg_wit_program(struct LDKu5 version, struct LDKCVec_u8Z program); + +/** + * Utility method to constructs a new PubKeyHash-variant Fallback + */ +struct LDKFallback Fallback_pub_key_hash(struct LDKTwentyBytes a); + +/** + * Utility method to constructs a new ScriptHash-variant Fallback + */ +struct LDKFallback Fallback_script_hash(struct LDKTwentyBytes a); + /** * Checks if two Fallbacks contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -18179,20 +19201,52 @@ MUST_USE_RES bool SignedRawInvoice_check_signature(const struct LDKSignedRawInvo */ MUST_USE_RES struct LDKThirtyTwoBytes RawInvoice_hash(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKSha256 RawInvoice_payment_hash(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKDescription RawInvoice_description(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKPayeePubKey RawInvoice_payee_pub_key(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKSha256 RawInvoice_description_hash(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKExpiryTime RawInvoice_expiry_time(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKMinFinalCltvExpiry RawInvoice_min_final_cltv_expiry(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKThirtyTwoBytes RawInvoice_payment_secret(const struct LDKRawInvoice *NONNULL_PTR this_arg); +/** + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None + */ MUST_USE_RES struct LDKInvoiceFeatures RawInvoice_features(const struct LDKRawInvoice *NONNULL_PTR this_arg); MUST_USE_RES struct LDKCVec_PrivateRouteZ RawInvoice_private_routes(const struct LDKRawInvoice *NONNULL_PTR this_arg); @@ -18264,16 +19318,22 @@ MUST_USE_RES const uint8_t (*Invoice_payment_hash(const struct LDKInvoice *NONNU /** * Get the payee's public key if one was included in the invoice + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKPublicKey Invoice_payee_pub_key(const struct LDKInvoice *NONNULL_PTR this_arg); /** * Get the payment secret if one was included in the invoice + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKThirtyTwoBytes Invoice_payment_secret(const struct LDKInvoice *NONNULL_PTR this_arg); /** * Get the invoice features if they were included in the invoice + * + * Note that the return value (or a relevant inner pointer) may be NULL or all-0s to represent None */ MUST_USE_RES struct LDKInvoiceFeatures Invoice_features(const struct LDKInvoice *NONNULL_PTR this_arg); @@ -18365,6 +19425,26 @@ MUST_USE_RES struct LDKRouteHint PrivateRoute_into_inner(struct LDKPrivateRoute */ enum LDKCreationError CreationError_clone(const enum LDKCreationError *NONNULL_PTR orig); +/** + * Utility method to constructs a new DescriptionTooLong-variant CreationError + */ +enum LDKCreationError CreationError_description_too_long(void); + +/** + * Utility method to constructs a new RouteTooLong-variant CreationError + */ +enum LDKCreationError CreationError_route_too_long(void); + +/** + * Utility method to constructs a new TimestampOutOfBounds-variant CreationError + */ +enum LDKCreationError CreationError_timestamp_out_of_bounds(void); + +/** + * Utility method to constructs a new ExpiryTimeOutOfBounds-variant CreationError + */ +enum LDKCreationError CreationError_expiry_time_out_of_bounds(void); + /** * Checks if two CreationErrors contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -18381,6 +19461,46 @@ struct LDKStr CreationError_to_str(const enum LDKCreationError *NONNULL_PTR o); */ enum LDKSemanticError SemanticError_clone(const enum LDKSemanticError *NONNULL_PTR orig); +/** + * Utility method to constructs a new NoPaymentHash-variant SemanticError + */ +enum LDKSemanticError SemanticError_no_payment_hash(void); + +/** + * Utility method to constructs a new MultiplePaymentHashes-variant SemanticError + */ +enum LDKSemanticError SemanticError_multiple_payment_hashes(void); + +/** + * Utility method to constructs a new NoDescription-variant SemanticError + */ +enum LDKSemanticError SemanticError_no_description(void); + +/** + * Utility method to constructs a new MultipleDescriptions-variant SemanticError + */ +enum LDKSemanticError SemanticError_multiple_descriptions(void); + +/** + * Utility method to constructs a new MultiplePaymentSecrets-variant SemanticError + */ +enum LDKSemanticError SemanticError_multiple_payment_secrets(void); + +/** + * Utility method to constructs a new InvalidFeatures-variant SemanticError + */ +enum LDKSemanticError SemanticError_invalid_features(void); + +/** + * Utility method to constructs a new InvalidRecoveryId-variant SemanticError + */ +enum LDKSemanticError SemanticError_invalid_recovery_id(void); + +/** + * Utility method to constructs a new InvalidSignature-variant SemanticError + */ +enum LDKSemanticError SemanticError_invalid_signature(void); + /** * Checks if two SemanticErrors contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -18402,6 +19522,16 @@ void SignOrCreationError_free(struct LDKSignOrCreationError this_ptr); */ struct LDKSignOrCreationError SignOrCreationError_clone(const struct LDKSignOrCreationError *NONNULL_PTR orig); +/** + * Utility method to constructs a new SignError-variant SignOrCreationError + */ +struct LDKSignOrCreationError SignOrCreationError_sign_error(void); + +/** + * Utility method to constructs a new CreationError-variant SignOrCreationError + */ +struct LDKSignOrCreationError SignOrCreationError_creation_error(enum LDKCreationError a); + /** * Checks if two SignOrCreationErrors contain equal inner contents. * This ignores pointers and is_owned flags and looks at the values in fields. @@ -18459,4 +19589,4 @@ struct LDKStr SiPrefix_to_str(const enum LDKSiPrefix *NONNULL_PTR o); #endif /* LDK_C_BINDINGS_H */ -#include +#include "ldk_ver.h"