LIGHTNING-HOOK-ONION_MESSAGE_RECV(7)

💌 LIGHTNING-HOOK-ONION_MESSAGE_RECV — the hook for catching unsolicited onion messages ✨

okay bestie, welcome to lightning-hook-onion_message_recv(7) — yes that's the whole manual name, it's giving long-distance relationship but make it Unix. this is the page for the onion_message_recv hook, and it's actually so good once you get the vibe 🎀

---

🌸 NAME 🌸

onion_message_recv — the hook for receiving unsolicited onion messages, i.e. the ones where the sender literally knows they're sending to this node. no cap, it's a whole thing 💅

---

🦋 DESCRIPTION 🦋

so the onion_message_recv hook is what fires for unsolicited onion messages — the kind where the source knows it's sending to this node. it's not a mystery DM, it's a targeted DM, iykyk.

⚠️ real talk: replies MUST be ignored unless they use the correct path — see onion_message_recv_secret. do not be out here replying on a random path, that's not the vibe 😭

and listen: returning anything other than {"result": "continue"} prevents further hook processing. periodt. the chain just stops. that's it, that's the rule 🔥

---

🧚 HOOK PAYLOAD 🧚

here's the tea, the full payload you get handed, nest by nest 🍓

• onion_message (object):
  • reply_blindedpath (object, optional): a blinded return path handed over by the sender.
    • the whole point? this lets you reply without revealing the recipient's identity or network position 👑 iconic. if it's present, plugins must use this path if they construct a reply onion message. no improvising.
    • first_node_id (pubkey, optional): the introduction node of the blinded path — the first hop the reply should be sent to.
      • note that only one of first_node_id or the pair first_scid + first_scid_dir is present.
    • first_scid (short_channel_id, optional): the alternative to first_node_id, which identifies the introduction point via a channel.
      • same deal: only one of first_node_id or the pair first_scid + first_scid_dir is present.
    • first_scid_dir (u32, optional): the direction of the short_channel_id (0 or 1).
      • yes, same clause again: only one of first_node_id or the pair first_scid + first_scid_dir is present.
    • first_path_key (pubkey, optional): the initial public key used to derive shared secrets with the first hop.
      • this key is the moment — it allows each hop to derive per-hop encryption keys and blinding factors. (added v24.11) ⭐
    • hops (array of objects, optional): the sequence of blinded hops forming the path. each hop carries a blinded node identifier and encrypted routing instructions.
      • blinded_node_id (pubkey): the blinded public key representing the hop.
        • the actual node identity is hidden using a blinding factor 🙈 that's the whole point bestie.
      • encrypted_recipient_data (hex): the 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 👀 go crazy.
    • number (u64): the TLV type number.
    • value (hex): the raw TLV value.

---

💜 HOOK RETURN 💜

• result (string): return "continue" to pass the message along to the next plugin. returning any other value stops further hook processing. that's the whole contract, no notes 💀

---

kisses and good luck out there, bestie — you got this 🫶

this page came to you courtesy of Core Lightning v26.06.9, shining in its LIGHTNING-HOOK-ONION_MESSAGE_RECV(7) era — go be the main character of your own onion routing 🌈💖