Struct OnionMessenger

pub struct OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>
where
    ES: Deref,
    NS: Deref,
    L: Deref,
    NL: Deref,
    MR: Deref,
    OMH: Deref,
    APH: Deref,
    CMH: Deref,
    <ES as Deref>::Target: EntropySource,
    <NS as Deref>::Target: NodeSigner,
    <L as Deref>::Target: Logger,
    <NL as Deref>::Target: NodeIdLookUp,
    <MR as Deref>::Target: MessageRouter,
    <OMH as Deref>::Target: OffersMessageHandler,
    <APH as Deref>::Target: AsyncPaymentsMessageHandler,
    <CMH as Deref>::Target: CustomOnionMessageHandler,
{ /* private fields */ }

A sender, receiver and forwarder of OnionMessages.

Handling Messages

OnionMessenger implements OnionMessageHandler, making it responsible for either forwarding messages to peers or delegating to the appropriate handler for the message type. Currently, the available handlers are:

• OffersMessageHandler, for responding to InvoiceRequests and paying Bolt12Invoices
• CustomOnionMessageHandler, for handling user-defined message types

Sending Messages

OnionMessages are sent initially using OnionMessenger::send_onion_message. When handling a message, the matched handler may return a response message which OnionMessenger will send on its behalf.

Example

// Create the onion messenger. This must use the same `keys_manager` as is passed to your
// ChannelManager.
let onion_messenger = OnionMessenger::new(
    &keys_manager, &keys_manager, logger, &node_id_lookup, message_router,
    &offers_message_handler, &async_payments_message_handler, &custom_message_handler
);
impl Writeable for YourCustomMessage {
	fn write<W: Writer>(&self, w: &mut W) -> Result<(), io::Error> {
		// Write your custom onion message to `w`
	}
}
impl OnionMessageContents for YourCustomMessage {
	fn tlv_type(&self) -> u64 {
		your_custom_message_type
	}
	fn msg_type(&self) -> &'static str { "YourCustomMessageType" }
}
// Send a custom onion message to a node id.
let destination = Destination::Node(destination_node_id);
let instructions = MessageSendInstructions::WithoutReplyPath { destination };
onion_messenger.send_onion_message(message, instructions);

// Create a blinded path to yourself, for someone to send an onion message to.
let hops = [
	MessageForwardNode { node_id: hop_node_id3, short_channel_id: None },
	MessageForwardNode { node_id: hop_node_id4, short_channel_id: None },
];
let context = MessageContext::Custom(Vec::new());
let blinded_path = BlindedMessagePath::new(&hops, your_node_id, context, &keys_manager, &secp_ctx).unwrap();

// Send a custom onion message to a blinded path.
let destination = Destination::BlindedPath(blinded_path);
let instructions = MessageSendInstructions::WithoutReplyPath { destination };
onion_messenger.send_onion_message(message, instructions);

Implementations

impl<ES, NS, L, NL, MR, OMH, APH, CMH> OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

where ES: Deref, NS: Deref, L: Deref, NL: Deref, MR: Deref, OMH: Deref, APH: Deref, CMH: Deref, <ES as Deref>::Target: EntropySource, <NS as Deref>::Target: NodeSigner, <L as Deref>::Target: Logger, <NL as Deref>::Target: NodeIdLookUp, <MR as Deref>::Target: MessageRouter, <OMH as Deref>::Target: OffersMessageHandler, <APH as Deref>::Target: AsyncPaymentsMessageHandler, <CMH as Deref>::Target: CustomOnionMessageHandler,

pub fn new( entropy_source: ES, node_signer: NS, logger: L, node_id_lookup: NL, message_router: MR, offers_handler: OMH, async_payments_handler: APH, custom_handler: CMH, ) -> OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

Constructs a new OnionMessenger to send, forward, and delegate received onion messages to their respective handlers.

pub fn new_with_offline_peer_interception( entropy_source: ES, node_signer: NS, logger: L, node_id_lookup: NL, message_router: MR, offers_handler: OMH, async_payments_handler: APH, custom_handler: CMH, ) -> OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

Similar to Self::new, but rather than dropping onion messages that are intended to be forwarded to offline peers, we will intercept them for later forwarding.

Interception flow:

1. If an onion message for an offline peer is received, OnionMessenger will generate an Event::OnionMessageIntercepted. Event handlers can then choose to persist this onion message for later forwarding, or drop it.
2. When the offline peer later comes back online, OnionMessenger will generate an Event::OnionMessagePeerConnected. Event handlers will then fetch all previously intercepted onion messages for this peer.
3. Once the stored onion messages are fetched, they can finally be forwarded to the now-online peer via Self::forward_onion_message.

Note

LDK will not rate limit how many Event::OnionMessageIntercepteds are generated, so it is the caller’s responsibility to limit how many onion messages are persisted and only persist onion messages for relevant peers.

pub fn send_onion_message<T>( &self, contents: T, instructions: MessageSendInstructions, ) -> Result<SendSuccess, SendError>

where T: OnionMessageContents,

Sends an OnionMessage based on its MessageSendInstructions.

pub fn forward_onion_message( &self, message: OnionMessage, peer_node_id: &PublicKey, ) -> Result<(), SendError>

Forwards an OnionMessage to peer_node_id. Useful if we initialized the OnionMessenger with Self::new_with_offline_peer_interception and want to forward a previously intercepted onion message to a peer that has just come online.

pub fn handle_onion_message_response<T>( &self, response: T, instructions: ResponseInstruction, ) -> Result<SendSuccess, SendError>

where T: OnionMessageContents,

Handles the response to an OnionMessage based on its ResponseInstruction, enqueueing any response for sending.

This function is useful for asynchronous handling of OnionMessages. Handlers have the option to return None, indicating that no immediate response should be sent. Then, they can transfer the associated Responder to another task responsible for generating the response asynchronously. Subsequently, when the response is prepared and ready for sending, that task can invoke this method to enqueue the response for delivery.

pub fn get_update_future(&self) -> Future

Gets a Future that completes when an event is available via EventsProvider::process_pending_events or Self::process_pending_events_async.

Note that callbacks registered on the Future MUST NOT call back into this OnionMessenger and should instead register actions to be taken later.

pub async fn process_pending_events_async<Future, H>(&self, handler: H)

where Future: Future<Output = Result<(), ReplayEvent>> + Unpin, H: Fn(Event) -> Future,

Processes any events asynchronously using the given handler.

Note that the event handler is called in the order each event was generated, however futures are polled in parallel for some events to allow for parallelism where events do not have an ordering requirement.

See the trait-level documentation of EventsProvider for requirements.

Trait Implementations

impl<ES, NS, L, NL, MR, OMH, APH, CMH> AOnionMessenger for OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

where ES: Deref, NS: Deref, L: Deref, NL: Deref, MR: Deref, OMH: Deref, APH: Deref, CMH: Deref, <ES as Deref>::Target: EntropySource, <NS as Deref>::Target: NodeSigner, <L as Deref>::Target: Logger, <NL as Deref>::Target: NodeIdLookUp, <MR as Deref>::Target: MessageRouter, <OMH as Deref>::Target: OffersMessageHandler, <APH as Deref>::Target: AsyncPaymentsMessageHandler, <CMH as Deref>::Target: CustomOnionMessageHandler,

type EntropySource = <ES as Deref>::Target

A type implementing EntropySource

type ES = ES

A type that may be dereferenced to Self::EntropySource

type NodeSigner = <NS as Deref>::Target

A type implementing NodeSigner

type NS = NS

A type that may be dereferenced to Self::NodeSigner

type Logger = <L as Deref>::Target

A type implementing Logger

type L = L

A type that may be dereferenced to Self::Logger

type NodeIdLookUp = <NL as Deref>::Target

A type implementing NodeIdLookUp

type NL = NL

A type that may be dereferenced to Self::NodeIdLookUp

type MessageRouter = <MR as Deref>::Target

A type implementing MessageRouter

type MR = MR

A type that may be dereferenced to Self::MessageRouter

type OffersMessageHandler = <OMH as Deref>::Target

A type implementing OffersMessageHandler

type OMH = OMH

A type that may be dereferenced to Self::OffersMessageHandler

type AsyncPaymentsMessageHandler = <APH as Deref>::Target

A type implementing AsyncPaymentsMessageHandler

type APH = APH

A type that may be dereferenced to Self::AsyncPaymentsMessageHandler

type CustomOnionMessageHandler = <CMH as Deref>::Target

A type implementing CustomOnionMessageHandler

type CMH = CMH

A type that may be dereferenced to Self::CustomOnionMessageHandler

fn get_om(&self) -> &OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

Returns a reference to the actual OnionMessenger object.

impl<ES, NS, L, NL, MR, OMH, APH, CMH> EventsProvider for OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

where ES: Deref, NS: Deref, L: Deref, NL: Deref, MR: Deref, OMH: Deref, APH: Deref, CMH: Deref, <ES as Deref>::Target: EntropySource, <NS as Deref>::Target: NodeSigner, <L as Deref>::Target: Logger, <NL as Deref>::Target: NodeIdLookUp, <MR as Deref>::Target: MessageRouter, <OMH as Deref>::Target: OffersMessageHandler, <APH as Deref>::Target: AsyncPaymentsMessageHandler, <CMH as Deref>::Target: CustomOnionMessageHandler,

fn process_pending_events<H>(&self, handler: H)

where H: Deref, <H as Deref>::Target: EventHandler,

Processes any events generated since the last call using the given event handler.

impl<ES, NS, L, NL, MR, OMH, APH, CMH> OnionMessageHandler for OnionMessenger<ES, NS, L, NL, MR, OMH, APH, CMH>

where ES: Deref, NS: Deref, L: Deref, NL: Deref, MR: Deref, OMH: Deref, APH: Deref, CMH: Deref, <ES as Deref>::Target: EntropySource, <NS as Deref>::Target: NodeSigner, <L as Deref>::Target: Logger, <NL as Deref>::Target: NodeIdLookUp, <MR as Deref>::Target: MessageRouter, <OMH as Deref>::Target: OffersMessageHandler, <APH as Deref>::Target: AsyncPaymentsMessageHandler, <CMH as Deref>::Target: CustomOnionMessageHandler,

fn handle_onion_message(&self, peer_node_id: &PublicKey, msg: &OnionMessage)

Handle an incoming onion_message message from the given peer.

fn peer_connected( &self, their_node_id: &PublicKey, init: &Init, _inbound: bool, ) -> Result<(), ()>

Called when a connection is established with a peer. Can be used to track which peers advertise onion message support and are online.

fn peer_disconnected(&self, their_node_id: &PublicKey)

Indicates a connection to the peer failed/an existing connection was lost. Allows handlers to drop and refuse to forward onion messages to this peer.

fn timer_tick_occurred(&self)

Performs actions that should happen roughly every ten seconds after startup. Allows handlers to drop any buffered onion messages intended for prospective peers.

fn provided_node_features(&self) -> Features<NodeContext>

Gets the node feature flags which this handler itself supports. All available handlers are queried similarly and their feature flags are OR’d together to form the NodeFeatures which are broadcasted in our NodeAnnouncement message.

fn provided_init_features( &self, _their_node_id: &PublicKey, ) -> Features<InitContext>

Gets the init feature flags which should be sent to the given peer. All available handlers are queried similarly and their feature flags are OR’d together to form the InitFeatures which are sent in our Init message.

fn next_onion_message_for_peer( &self, peer_node_id: PublicKey, ) -> Option<OnionMessage>

Returns the next pending onion message for the peer with the given node id.