home | help 
LIGHTNING-SENDCUSTOMMSG(7)			      LIGHTNING-SENDCUSTOMMSG(7)

NAME
     sendcustommsg -- Low-level interface to send protocol messages to peers

SYNOPSIS
     sendcustommsg node_id msg

DESCRIPTION
     Command added in v0.10.1.

     The  sendcustommsg  RPC  method  allows the user to inject a custom message
     into the communication with the peer with the given node_id.  This  is  in-
     tended  as a low-level interface to implement custom protocol extensions on
     top, not for direct use by end-users.

     On the receiving end a plugin may implement the custommsg plugin  hook  and
     get  notified  about  incoming  messages, and allow additional unknown even
     types in their getmanifest response.

     *	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
	the  connection must be established. For a method to send arbitrary mes-
	sages over multiple hops, including hops that do not understand the cus-
	tom message, see the createonion and sendonion RPC methods. 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  dae-
	mons that do not handle spontaneous messages.
     *	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  receiv-
	ing unknown even types.

RETURN VALUE
     The  method  will validate the arguments and queue the message for delivery
     through the daemon that is currently handling the connection. Queuing  pro-
     vides  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.

     If  any of the above limitations is not respected the method returns an ex-
     plicit 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.

SEE ALSO
     lightning-createonion(7), lightning-sendonion(7)

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"
     }

Core Lightning v26.06.1 			      LIGHTNING-SENDCUSTOMMSG(7)
home | help