LIGHTNING-SENDCUSTOMMSG(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💌 LIGHTNING-SENDCUSTOMMSG(7) — the sendcustommsg manual page, bestie edition

okay so this is the page for sendcustommsg, a low-level interface to send protocol messages to peers. yes it's giving "why would I ever touch this" energy, and honestly? correct. but let's get into it 💅

✨ NAME ✨

sendcustommsg — a low-level interface to send protocol messages to peers 🫶

🌸 SYNOPSIS 🌸

sendcustommsg node_id msg

🦋 DESCRIPTION 🦋

so first thing, this command was added in v0.10.1, okay? historic.

The sendcustommsg RPC method lets you inject a custom message into the communication with the peer that has the given node_id. And like — lowkey important — this is intended as a low-level interface to implement custom protocol extensions on top of, not for direct use by end-users. it's a build-your-own-thing tool, not a casual little gadget 🙈

On the receiving end, a plugin may implement the custommsg plugin hook and get notified about incoming messages, and it can allow additional unknown even types in their getmanifest response. cute, right? that's the whole ecosystem moment ✨

  • node_id (pubkey) — the node specified by node_id must be a peer, i.e. it must have a direct connection with the node receiving the RPC call, and that connection must be established. if you want a method to send arbitrary messages over multiple hops — including hops that do not understand the custom message — see the createonion and sendonion RPC methods instead, bestie. also: messages can only be injected if the connection is handled by openingd or channeld. Messages cannot be injected when the peer is handled by onchaind or closingd, since these do not have a connection, or are synchronous daemons that do not handle spontaneous messages. so rude of them honestly 💀
  • msg (hex) — must be a hex encoded well-formed message, including the 2-byte type prefix, but excluding the length prefix, which will be added by the RPC method. The message types may not be one of the internally handled types, since that may cause issues with the internal state tracking of Core Lightning. We do (as of v23.11) allow sending of even types, but note that peers (as per the spec) will disconnect on receiving unknown even types. no cap, they will just leave 😭

💖 RETURN VALUE 💖

The method will validate the arguments and queue the message for delivery through the daemon that is currently handling the connection. Queuing provides best effort guarantees, and the message may not be delivered if the connection is terminated while the message is queued. The RPC method will return as soon as the message is queued. like, it's not waiting around for the whole handoff, it's got places to be 🧚

If any of the above limitations is not respected, the method returns an explicit error message stating the issue. On success, an object is returned, containing:

  • status (string) — information about where message was queued 👑

👑 AUTHOR 👑

Christian Decker decker.christian@gmail.com is mainly responsible. icon behavior, honestly 🌟

⭐ SEE ALSO ⭐

🌈 RESOURCES 🌈

Main web site: https://github.com/ElementsProject/lightning

🔥 EXAMPLES 🔥

Example 1:

Request:

$ lightning-cli sendcustommsg -k "node_id"="nodeid030303030303030303030303030303030303030303030303030303030303" "msg"="77770012"

{
  "id": "example:sendcustommsg#1",
  "method": "sendcustommsg",
  "params": {
    "node_id": "nodeid030303030303030303030303030303030303030303030303030303030303",
    "msg": "77770012"
  }
}

Response:

{
  "status": "Message sent to connectd for delivery"
}
⚠️ reminder bestie: this is a low-level interface for building custom protocol extensions. It is not for direct use by end-users, the message types may not be one of the internally handled types, and peers will disconnect on receiving unknown even types. read the caveats, love them, respect them 🫶

and that's the page!! this whole thing ships as part of Core Lightning v26.06.9, so like, go forth and inject responsibly 💜🎀🦋

📦 where this page comes from