onion_message_recv_secret -- Hook for receiving onion messages via blinded paths

DESCRIPTION

The onion_message_recv_secret hook is used when an onion message is received via a blinded path previously provided by this node.

The presence of pathsecret allows the plugin to authenticate that the message used the intended return path.

Replies MUST only be sent when the pathsecret matches expectations.

Returning anything other than {"result": "continue"} prevents further hook processing.

HOOK PAYLOAD

onion_message (object):
- pathsecret (secret): Shared secret identifying the blinded path.

Used to verify that the sender used a path previously provided by this node.
This prevents probing attacks and unauthorized replies.

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_request payload.
invoice (hex, optional): BOLT #12 invoice payload.
invoice_error (hex, optional): BOLT #12 invoice_error payload.
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.