From a3ddf9be9bb635e7b6ff14b5385f31c59812f933 Mon Sep 17 00:00:00 2001 From: Christian Decker Date: Mon, 9 Dec 2019 16:32:49 +0100 Subject: [PATCH] docs: Add manpage for dev-sendcustommsg It's a dev-* command for now, but better document it so people can use it rather than having them guess how it's supposed to work. --- doc/Makefile | 1 + doc/index.rst | 1 + doc/lightning-dev-sendcustommsg.7 | 0 doc/lightning-dev-sendcustommsg.7.md | 63 ++++++++++++++++++++++++++++ 4 files changed, 65 insertions(+) create mode 100644 doc/lightning-dev-sendcustommsg.7 create mode 100644 doc/lightning-dev-sendcustommsg.7.md diff --git a/doc/Makefile b/doc/Makefile index db2b30029..dc5738e59 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -16,6 +16,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-decodepay.7 \ doc/lightning-delexpiredinvoice.7 \ doc/lightning-delinvoice.7 \ + doc/lightning-dev-sendcustommsg.7 \ doc/lightning-disconnect.7 \ doc/lightning-fundchannel.7 \ doc/lightning-fundchannel_start.7 \ diff --git a/doc/index.rst b/doc/index.rst index e6380274f..325a02607 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -39,6 +39,7 @@ c-lightning Documentation lightning-decodepay lightning-delexpiredinvoice lightning-delinvoice + lightning-dev-sendcustommsg lightning-disconnect lightning-fundchannel lightning-fundchannel_cancel diff --git a/doc/lightning-dev-sendcustommsg.7 b/doc/lightning-dev-sendcustommsg.7 new file mode 100644 index 000000000..e69de29bb diff --git a/doc/lightning-dev-sendcustommsg.7.md b/doc/lightning-dev-sendcustommsg.7.md new file mode 100644 index 000000000..dfcbc17b5 --- /dev/null +++ b/doc/lightning-dev-sendcustommsg.7.md @@ -0,0 +1,63 @@ +lightning-dev-sendcustommsg -- Low-level interface to send protocol messages to peers +===================================================================================== + +SYNOPSIS +-------- + +**dev-sendcustommsg** *node_id* *msg* + +DESCRIPTION +----------- + +The `dev-sendcustommsg` RPC method allows the user to inject a custom message +into the communication with the peer with the given `node_id`. This is +intended as a low-level interface to implement custom protocol extensions on +top, not for direct use by end-users. + +The message 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 messages must not use even-numbered types, since these may require +synchronous handling on the receiving side, and can cause the connection to be +dropped. The message types may also not use one of the internally handled +types, since that may cause issues with the internal state tracking of +c-lightning. + +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 messages over multiple hops, +including hops that do not understand the custom 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 daemons that do not handle +spontaneous messages. + +On the reveiving end a plugin may implement the `custommsg` plugin hook and +get notified about incoming messages. + +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. + +If any of the above limitations is not respected the method returns an +explicit error message stating the issue. + +AUTHOR +------ + +Christian Decker <> is mainly responsible. + +SEE ALSO +-------- + +lightning-createonion(7), lightning-sendonion(7) + +RESOURCES +--------- + +Main web site: