X-Git-Url: http://git.bitcoin.ninja/index.cgi?a=blobdiff_plain;f=lightning-c-bindings%2Finclude%2Flightning.h;h=191544007465a1fbc189b7b5a97315d2ac11f7ea;hb=4eb8bb460e025c3d79a47b25cfff6baf068679bb;hp=55957788957f941d51f015cc93ab7242eb3a6d83;hpb=2c56d2b4709d39d5e96ec84e4ecb07f9ebed0387;p=ldk-c-bindings

diff --git a/lightning-c-bindings/include/lightning.h b/lightning-c-bindings/include/lightning.h
index 5595778..1915440 100644
--- a/lightning-c-bindings/include/lightning.h
+++ b/lightning-c-bindings/include/lightning.h
@@ -8,7 +8,7 @@
 #include <stdarg.h>
 #include <stdbool.h>
 #include <stdint.h>
-#include <ldk_rust_types.h>
+#include "ldk_rust_types.h"
 
 /**
  * An error when accessing the chain via [`Access`].
@@ -3340,21 +3340,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.
@@ -3959,6 +3954,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.
  */
@@ -5385,6 +5413,72 @@ 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
+    */
+   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.
  *
@@ -5468,28 +5562,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
@@ -5497,16 +5569,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 {
@@ -8753,11 +8819,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.
@@ -10074,6 +10140,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.
  */
@@ -11644,6 +11731,16 @@ 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 PaymentPurpose
+ */
+void PaymentPurpose_free(struct LDKPaymentPurpose this_ptr);
+
+/**
+ * Creates a copy of the PaymentPurpose
+ */
+struct LDKPaymentPurpose PaymentPurpose_clone(const struct LDKPaymentPurpose *NONNULL_PTR orig);
+
 /**
  * Frees any resources used by the Event
  */
@@ -13677,6 +13774,20 @@ void ChannelManager_force_close_all_channels(const struct LDKChannelManager *NON
  */
 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
+ */
+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.
  *
@@ -13828,7 +13939,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
@@ -13862,7 +13973,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);
 
@@ -17583,6 +17694,13 @@ 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`.
+ */
+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).
  *
@@ -18835,4 +18953,4 @@ struct LDKStr SiPrefix_to_str(const enum LDKSiPrefix *NONNULL_PTR o);
 
 #endif /* LDK_C_BINDINGS_H */
 
-#include <ldk_ver.h>
+#include "ldk_ver.h"