onion_message_recv -- Hook for receiving unsolicited onion messages
DESCRIPTION
The onion_message_recv hook is used for unsolicited onion messages (where the source knows that it is sending to this node).
Replies MUST be ignored unless they use the correct path (see onion_message_recv_secret).
Returning anything other than {"result": "continue"} prevents further hook processing.
HOOK PAYLOAD
- onion_message (object):
- reply_blindedpath (object, optional): A blinded return path provided by the sender.
This allows replying without revealing the recipient's identity or network position.
If present, plugins must use this path if they construct a reply onion message.:
- first_node_id (pubkey, optional): The introduction node of the blinded path.
This is the first hop to which the reply should be sent.
Only one of first_node_id or the pair first_scid and first_scid_dir is present.
- first_scid (short_channel_id, optional): Alternative to first_node_id: identifies the introduction point via a channel.
Only one of first_node_id or the pair first_scid and first_scid_dir is present.
- first_scid_dir (u32, optional): Direction of the short_channel_id (0 or 1).
Only one of first_node_id or the pair first_scid and first_scid_dir is present.
- first_path_key (pubkey, optional): Initial public key used to derive shared secrets with the first hop.
This key allows each hop to derive per-hop encryption keys and blinding factors. (added v24.11)
- hops (array of objects, optional): Sequence of blinded hops forming the path.
Each hop contains a blinded node identifier and encrypted routing instructions.:
- blinded_node_id (pubkey): Blinded public key representing the hop.
The actual node identity is hidden using a blinding factor.
- encrypted_recipient_data (hex): Encrypted TLV payload for this hop.
Contains instructions (e.g., next hop) encrypted with a shared secret derived from the path key.
- invoice_request (hex, optional): BOLT #12
invoice_requestpayload. - invoice (hex, optional): BOLT #12
invoicepayload. - invoice_error (hex, optional): BOLT #12
invoice_errorpayload. - unknown_fields (array of objects, optional): Unknown or unparsed TLV fields from the onion message.
Plugins may inspect these for experimental or custom extensions.:
- number (u64): TLV type number.
- value (hex): Raw TLV value.
HOOK RETURN
- result (string): Return "continue" to pass the message to the next plugin.
Returning any other value stops further hook processing.