LIGHTNING-HOOK-O...SAGE_RECV_SECRET(7)

💖 NAME 💖

Okay bestie, welcome to the LIGHTNING-HOOK-O...SAGE_RECV_SECRET(7) manual page ✨ — this is all about onion_message_recv_secret, the hook for receiving onion messages via blinded paths 🧅🦋.

✨ DESCRIPTION ✨

So the onion_message_recv_secret hook gets called when an onion message arrives via a blinded path that this node literally provided before. No cap.

The presence of pathsecret lets the plugin authenticate that the message used the intended return path. That's the whole vibe check right there 👑

Replies MUST only be sent when the pathsecret matches expectations. Periodt — do not be out here replying when it doesn't line up.

Returning anything other than {"result": "continue"} prevents further hook processing. So yeah, that exact thing is the green light 💚.

🎀 HOOK PAYLOAD 🎀

• onion_message (object):
  • pathsecret (secret): shared secret identifying the blinded path. It's 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. That's it, bestie — "continue" is the only slay here for keeping things moving ✨

---

Cute lil' sign-off: this iconic page is from Core Lightning v26.06.9 — LIGHTNING-HOOK-O...SAGE_RECV_SECRET(7) — mwah 💋, go forth and verify those pathsecrets 🧚💖