Struct OnionMessenger

pub struct OnionMessenger<ES, NS, L, MR, OMH, CMH>
where
    ES: Deref,
    NS: Deref,
    L: Deref,
    MR: Deref,
    OMH: Deref,
    CMH: Deref,
    <ES as Deref>::Target: EntropySource,
    <NS as Deref>::Target: NodeSigner,
    <L as Deref>::Target: Logger,
    <MR as Deref>::Target: MessageRouter,
    <OMH as Deref>::Target: OffersMessageHandler,
    <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, 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 path = OnionMessagePath {
	intermediate_nodes: vec![hop_node_id1, hop_node_id2],
	destination: Destination::Node(destination_node_id),
};
let reply_path = None;
onion_messenger.send_onion_message(path, message, 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 path = OnionMessagePath {
	intermediate_nodes: vec![hop_node_id1, hop_node_id2],
	destination: Destination::BlindedPath(blinded_path),
};
let reply_path = None;
onion_messenger.send_onion_message(path, message, reply_path);

Implementations

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

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

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

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

pub fn send_onion_message<T>( &self, path: OnionMessagePath, contents: T, reply_path: Option<BlindedPath>, ) -> Result<(), SendError>

where T: OnionMessageContents,

Sends an OnionMessage with the given contents for sending to the destination of path.

See OnionMessenger for example usage.

Trait Implementations

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

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