Struct lightning::onion_message::messenger::OnionMessenger

pub struct OnionMessenger<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref>
where
    ES::Target: EntropySource,
    NS::Target: NodeSigner,
    L::Target: Logger,
    MR::Target: MessageRouter,
    OMH::Target: OffersMessageHandler,
    CMH::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, message_router, &offers_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
	}
}
// Send a custom onion message to a node id.
let destination = Destination::Node(destination_node_id);
let reply_path = None;
onion_messenger.send_onion_message(message, destination, reply_path);

// Create a blinded path to yourself, for someone to send an onion message to.
let hops = [hop_node_id3, hop_node_id4, your_node_id];
let blinded_path = BlindedPath::new_for_message(&hops, &keys_manager, &secp_ctx).unwrap();

// Send a custom onion message to a blinded path.
let destination = Destination::BlindedPath(blinded_path);
let reply_path = None;
onion_messenger.send_onion_message(message, destination, reply_path);

Implementations

impl<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref> OnionMessenger<ES, NS, L, MR, OMH, CMH>

where ES::Target: EntropySource, NS::Target: NodeSigner, L::Target: Logger, MR::Target: MessageRouter, OMH::Target: OffersMessageHandler, CMH::Target: CustomOnionMessageHandler,

pub fn new( entropy_source: ES, node_signer: NS, logger: L, message_router: MR, offers_handler: OMH, custom_handler: CMH ) -> Self

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

pub fn send_onion_message<T: OnionMessageContents>( &self, contents: T, destination: Destination, reply_path: Option<BlindedPath> ) -> Result<SendSuccess, SendError>

Sends an OnionMessage with the given contents to destination.

See OnionMessenger for example usage.

Trait Implementations

impl<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref> EventsProvider for OnionMessenger<ES, NS, L, MR, OMH, CMH>

where ES::Target: EntropySource, NS::Target: NodeSigner, L::Target: Logger, MR::Target: MessageRouter, OMH::Target: OffersMessageHandler, CMH::Target: CustomOnionMessageHandler,

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

where H::Target: EventHandler,

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

impl<ES: Deref, NS: Deref, L: Deref, MR: Deref, OMH: Deref, CMH: Deref> OnionMessageHandler for OnionMessenger<ES, NS, L, MR, OMH, CMH>

where ES::Target: EntropySource, NS::Target: NodeSigner, L::Target: Logger, MR::Target: MessageRouter, OMH::Target: OffersMessageHandler, CMH::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) -> NodeFeatures

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) -> InitFeatures

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.