_ Git - ldk-java/blob - src/main/java/org/ldk/structs/OnionMessenger.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10
  11 /**
  12  * A sender, receiver and forwarder of [`OnionMessage`]s.
  13  *
  14  * # Handling Messages
  15  *
  16  * `OnionMessenger` implements [`OnionMessageHandler`], making it responsible for either forwarding
  17  * messages to peers or delegating to the appropriate handler for the message type. Currently, the
  18  * available handlers are:
  19  * [`OffersMessageHandler`], for responding to [`InvoiceRequest`]s and paying [`Bolt12Invoice`]s
  20  * [`CustomOnionMessageHandler`], for handling user-defined message types
  21  *
  22  * # Sending Messages
  23  *
  24  * [`OnionMessage`]s are sent initially using [`OnionMessenger::send_onion_message`]. When handling
  25  * a message, the matched handler may return a response message which `OnionMessenger` will send
  26  * on its behalf.
  27  *
  28  * # Example
  29  *
  30  * ```
  31  * # extern crate bitcoin;
  32  * # use bitcoin::hashes::_export::_core::time::Duration;
  33  * # use bitcoin::hashes::hex::FromHex;
  34  * # use bitcoin::secp256k1::{PublicKey, Secp256k1, SecretKey, self};
  35  * # use lightning::blinded_path::BlindedPath;
  36  * # use lightning::sign::{EntropySource, KeysManager};
  37  * # use lightning::ln::peer_handler::IgnoringMessageHandler;
  38  * # use lightning::onion_message::messenger::{Destination, MessageRouter, OnionMessagePath, OnionMessenger};
  39  * # use lightning::onion_message::packet::OnionMessageContents;
  40  * # use lightning::util::logger::{Logger, Record};
  41  * # use lightning::util::ser::{Writeable, Writer};
  42  * # use lightning::io;
  43  * # use std::sync::Arc;
  44  * # struct FakeLogger;
  45  * # impl Logger for FakeLogger {
  46  * #     fn log(&self, record: Record) { println!(\"{:?}\" , record); }
  47  * # }
  48  * # struct FakeMessageRouter {}
  49  * # impl MessageRouter for FakeMessageRouter {
  50  * #     fn find_path(&self, sender: PublicKey, peers: Vec<PublicKey>, destination: Destination) -> Result<OnionMessagePath, ()> {
  51  * #         let secp_ctx = Secp256k1::new();
  52  * #         let node_secret = SecretKey::from_slice(&<Vec<u8>>::from_hex(\"0101010101010101010101010101010101010101010101010101010101010101\").unwrap()[..]).unwrap();
  53  * #         let hop_node_id1 = PublicKey::from_secret_key(&secp_ctx, &node_secret);
  54  * #         let hop_node_id2 = hop_node_id1;
  55  * #         Ok(OnionMessagePath {
  56  * #             intermediate_nodes: vec![hop_node_id1, hop_node_id2],
  57  * #             destination,
  58  * #             first_node_addresses: None,
  59  * #         })
  60  * #     }
  61  * #     fn create_blinded_paths<T: secp256k1::Signing + secp256k1::Verification>(
  62  * #         &self, _recipient: PublicKey, _peers: Vec<PublicKey>, _secp_ctx: &Secp256k1<T>
  63  * #     ) -> Result<Vec<BlindedPath>, ()> {
  64  * #         unreachable!()
  65  * #     }
  66  * # }
  67  * # let seed = [42u8; 32];
  68  * # let time = Duration::from_secs(123456);
  69  * # let keys_manager = KeysManager::new(&seed, time.as_secs(), time.subsec_nanos());
  70  * # let logger = Arc::new(FakeLogger {});
  71  * # let node_secret = SecretKey::from_slice(&<Vec<u8>>::from_hex(\"0101010101010101010101010101010101010101010101010101010101010101\").unwrap()[..]).unwrap();
  72  * # let secp_ctx = Secp256k1::new();
  73  * # let hop_node_id1 = PublicKey::from_secret_key(&secp_ctx, &node_secret);
  74  * # let (hop_node_id3, hop_node_id4) = (hop_node_id1, hop_node_id1);
  75  * # let destination_node_id = hop_node_id1;
  76  * # let message_router = Arc::new(FakeMessageRouter {});
  77  * # let custom_message_handler = IgnoringMessageHandler {};
  78  * # let offers_message_handler = IgnoringMessageHandler {};
  79  * Create the onion messenger. This must use the same `keys_manager` as is passed to your
  80  * ChannelManager.
  81  * let onion_messenger = OnionMessenger::new(
  82  * &keys_manager, &keys_manager, logger, message_router, &offers_message_handler,
  83  * &custom_message_handler
  84  * );
  85  *
  86  * # #[derive(Debug, Clone)]
  87  * # struct YourCustomMessage {}
  88  * impl Writeable for YourCustomMessage {
  89  * \tfn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
  90  * \t\t# Ok(())
  91  * \t\t// Write your custom onion message to `w`
  92  * \t}
  93  * }
  94  * impl OnionMessageContents for YourCustomMessage {
  95  * \tfn tlv_type(&self) -> u64 {
  96  * \t\t# let your_custom_message_type = 42;
  97  * \t\tyour_custom_message_type
  98  * \t}
  99  * }
 100  * Send a custom onion message to a node id.
 101  * let destination = Destination::Node(destination_node_id);
 102  * let reply_path = None;
 103  * # let message = YourCustomMessage {};
 104  * onion_messenger.send_onion_message(message, destination, reply_path);
 105  *
 106  * Create a blinded path to yourself, for someone to send an onion message to.
 107  * # let your_node_id = hop_node_id1;
 108  * let hops = [hop_node_id3, hop_node_id4, your_node_id];
 109  * let blinded_path = BlindedPath::new_for_message(&hops, &keys_manager, &secp_ctx).unwrap();
 110  *
 111  * Send a custom onion message to a blinded path.
 112  * let destination = Destination::BlindedPath(blinded_path);
 113  * let reply_path = None;
 114  * # let message = YourCustomMessage {};
 115  * onion_messenger.send_onion_message(message, destination, reply_path);
 116  * ```
 117  *
 118  * [`InvoiceRequest`]: crate::offers::invoice_request::InvoiceRequest
 119  * [`Bolt12Invoice`]: crate::offers::invoice::Bolt12Invoice
 120  */
 121 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
 122 public class OnionMessenger extends CommonBase {
 123         OnionMessenger(Object _dummy, long ptr) { super(ptr); }
 124         @Override @SuppressWarnings("deprecation")
 125         protected void finalize() throws Throwable {
 126                 super.finalize();
 127                 if (ptr != 0) { bindings.OnionMessenger_free(ptr); }
 128         }
 129
 130         /**
 131          * Constructs a new `OnionMessenger` to send, forward, and delegate received onion messages to
 132          * their respective handlers.
 133          */
 134         public static OnionMessenger of(org.ldk.structs.EntropySource entropy_source, org.ldk.structs.NodeSigner node_signer, org.ldk.structs.Logger logger, org.ldk.structs.MessageRouter message_router, org.ldk.structs.OffersMessageHandler offers_handler, org.ldk.structs.CustomOnionMessageHandler custom_handler) {
 135                 long ret = bindings.OnionMessenger_new(entropy_source.ptr, node_signer.ptr, logger.ptr, message_router.ptr, offers_handler.ptr, custom_handler.ptr);
 136                 Reference.reachabilityFence(entropy_source);
 137                 Reference.reachabilityFence(node_signer);
 138                 Reference.reachabilityFence(logger);
 139                 Reference.reachabilityFence(message_router);
 140                 Reference.reachabilityFence(offers_handler);
 141                 Reference.reachabilityFence(custom_handler);
 142                 if (ret >= 0 && ret <= 4096) { return null; }
 143                 org.ldk.structs.OnionMessenger ret_hu_conv = null; if (ret < 0 || ret > 4096) { ret_hu_conv = new org.ldk.structs.OnionMessenger(null, ret); }
 144                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(ret_hu_conv); };
 145                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(entropy_source); };
 146                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(node_signer); };
 147                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(logger); };
 148                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(message_router); };
 149                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(offers_handler); };
 150                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(custom_handler); };
 151                 return ret_hu_conv;
 152         }
 153
 154         /**
 155          * Sends an [`OnionMessage`] with the given `contents` to `destination`.
 156          *
 157          * See [`OnionMessenger`] for example usage.
 158          *
 159          * Note that reply_path (or a relevant inner pointer) may be NULL or all-0s to represent None
 160          */
 161         public Result_SendSuccessSendErrorZ send_onion_message(org.ldk.structs.OnionMessageContents contents, org.ldk.structs.Destination destination, @Nullable org.ldk.structs.BlindedPath reply_path) {
 162                 long ret = bindings.OnionMessenger_send_onion_message(this.ptr, contents.ptr, destination.ptr, reply_path == null ? 0 : reply_path.ptr);
 163                 Reference.reachabilityFence(this);
 164                 Reference.reachabilityFence(contents);
 165                 Reference.reachabilityFence(destination);
 166                 Reference.reachabilityFence(reply_path);
 167                 if (ret >= 0 && ret <= 4096) { return null; }
 168                 Result_SendSuccessSendErrorZ ret_hu_conv = Result_SendSuccessSendErrorZ.constr_from_ptr(ret);
 169                 if (this != null) { this.ptrs_to.add(contents); };
 170                 if (this != null) { this.ptrs_to.add(destination); };
 171                 if (this != null) { this.ptrs_to.add(reply_path); };
 172                 return ret_hu_conv;
 173         }
 174
 175         /**
 176          * Constructs a new OnionMessageHandler which calls the relevant methods on this_arg.
 177          * This copies the `inner` pointer in this_arg and thus the returned OnionMessageHandler must be freed before this_arg is
 178          */
 179         public OnionMessageHandler as_OnionMessageHandler() {
 180                 long ret = bindings.OnionMessenger_as_OnionMessageHandler(this.ptr);
 181                 Reference.reachabilityFence(this);
 182                 if (ret >= 0 && ret <= 4096) { return null; }
 183                 OnionMessageHandler ret_hu_conv = new OnionMessageHandler(null, ret);
 184                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 185                 return ret_hu_conv;
 186         }
 187
 188 }