diff --git a/doc/Makefile b/doc/Makefile index 288d26c1e..173b3b03f 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -54,6 +54,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-reserveinputs.7 \ doc/lightning-sendinvoice.7 \ doc/lightning-sendonion.7 \ + doc/lightning-sendonionmessage.7 \ doc/lightning-sendpay.7 \ doc/lightning-setchannelfee.7 \ doc/lightning-signmessage.7 \ diff --git a/doc/index.rst b/doc/index.rst index 3fe53324d..d7f81712c 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -84,6 +84,7 @@ c-lightning Documentation lightning-reserveinputs lightning-sendinvoice lightning-sendonion + lightning-sendonionmessage lightning-sendpay lightning-sendpsbt lightning-setchannelfee diff --git a/doc/lightning-sendonionmessage.7 b/doc/lightning-sendonionmessage.7 new file mode 100644 index 000000000..089eab827 --- /dev/null +++ b/doc/lightning-sendonionmessage.7 @@ -0,0 +1,45 @@ +.TH "LIGHTNING-SENDONIONMESSAGE" "7" "" "" "lightning-sendonionmessage" +.SH NAME +lightning-sendonionmessage - low-level command to send an onion message +.SH SYNOPSIS + +\fB(WARNING: experimental-onion-messages only)\fR + + +\fBsendonionmessage\fR \fIhops\fR [\fIreply_path\fR] + +.SH DESCRIPTION + +The \fBsendonionmessage\fR RPC command can be used to send a message via +the lightning network\. These are currently used by \fIoffers\fR to request +and receive invoices\. + + +\fIhops\fR is an array of json objects: \fIid\fR as a public key of the node, +and either \fIrawtlv\fR containing a hexidecimal TLV to include, or any of +the fields \fIshort_channel_id\fR, \fIblinding\fR, \fIenctlv\fR, \fIinvoice\fR, +\fIinvoice_request\fR and \fIinvoice_error\fR to construct the onionmessage +TLV with\. + + +\fIreply_path\fR is a json object, containing a pubkey \fIblinding\fR, and an +array \fIpath\fR of objects containing \fIid\fR (a pubkey) and \fIenctlv\fR (a hex +value, optional for final element)\. + +.SH RETURN VALUE + +On success, an empty JSON object is returned\. + +.SH AUTHOR + +Rusty Russell \fI is mainly responsible\. + +.SH SEE ALSO + +\fBlightning-fetchinvoice\fR(7), \fBlightning-offer\fR(7)\. + +.SH RESOURCES + +Main web site: \fIhttps://github.com/ElementsProject/lightning\fR + +\" SHA256STAMP:680e0897d06c217e868bbc5b3985dec975d1af37dfd9fd0b91f5e1d9c651b687 diff --git a/doc/lightning-sendonionmessage.7.md b/doc/lightning-sendonionmessage.7.md new file mode 100644 index 000000000..7fa4b8785 --- /dev/null +++ b/doc/lightning-sendonionmessage.7.md @@ -0,0 +1,49 @@ +lightning-sendonionmessage -- low-level command to send an onion message +================================================================ + +SYNOPSIS +-------- + +**(WARNING: experimental-onion-messages only)** + +**sendonionmessage** *hops* \[*reply_path*\] + +DESCRIPTION +----------- + +The **sendonionmessage** RPC command can be used to send a message via +the lightning network. These are currently used by *offers* to request +and receive invoices. + +*hops* is an array of json objects: *id* as a public key of the node, +and either *rawtlv* containing a hexidecimal TLV to include, or any of +the fields *short_channel_id*, *blinding*, *enctlv*, *invoice*, +*invoice_request* and *invoice_error* to construct the onionmessage +TLV with. + +*reply_path* is a json object, containing a pubkey *blinding*, and an +array *path* of objects containing *id* (a pubkey) and *enctlv* (a hex +value, optional for final element). + +RETURN VALUE +------------ + +On success, an empty JSON object is returned. + +AUTHOR +------ + +Rusty Russell <> is mainly responsible. + +SEE ALSO +-------- + +lightning-fetchinvoice(7), lightning-offer(7). + +RESOURCES +--------- + +Main web site: + +[bolt04]: https://github.com/lightningnetwork/lightning-rfc/blob/master/04-onion-routing.md + diff --git a/doc/lightningd-config.5 b/doc/lightningd-config.5 index 61708660d..641d1c1b4 100644 --- a/doc/lightningd-config.5 +++ b/doc/lightningd-config.5 @@ -559,6 +559,29 @@ if C-lightning terminates\. Built-in plugins, which are installed with \fBlightningd\fR(8), are automatically considered important\. +.SH Experimental Options + +Experimental options are subject to breakage between releases: they +are made available for advanced users who want to test proposed +features\. If lightningd is built configured with +\fB--enable-experimental-features\fR these are on by default\. + + + \fBexperimental-onion-messages\fR + + +Specifying this enables sending, forwarding and receiving onion messages, +which are in draft status in the BOLT specifications\. + + + \fBexperimental-offers\fR + + +Specifying this enables the \fBoffers\fR and \fBfetchinvoice\fR plugins and +corresponding functionality, which are in draft status as BOLT12\. +This usually requires \fBexperimental-onion-messages\fR as well\. See +\fBlightning-offer\fR(7) and \fBlightning-fetchinvoice\fR(7)\. + .SH BUGS You should report bugs on our github issues page, and maybe submit a fix @@ -584,4 +607,4 @@ Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Note: the modules in the ccan/ directory have their own licenses, but the rest of the code is covered by the BSD-style MIT license\. -\" SHA256STAMP:c927bd3afb61288bb67d941d113cdeefe1363b0c7a28936ef30d43af3ce66098 +\" SHA256STAMP:e9f294f15d8873a2332b5748179be09c1496c9e81576dc0e4546c047474289fd diff --git a/doc/lightningd-config.5.md b/doc/lightningd-config.5.md index 8bd4fc591..edd2c4e59 100644 --- a/doc/lightningd-config.5.md +++ b/doc/lightningd-config.5.md @@ -463,6 +463,25 @@ if C-lightning terminates. Built-in plugins, which are installed with lightningd(8), are automatically considered important. +### Experimental Options + +Experimental options are subject to breakage between releases: they +are made available for advanced users who want to test proposed +features. If lightningd is built configured with +`--enable-experimental-features` these are on by default. + + **experimental-onion-messages** + +Specifying this enables sending, forwarding and receiving onion messages, +which are in draft status in the BOLT specifications. + + **experimental-offers** + +Specifying this enables the `offers` and `fetchinvoice` plugins and +corresponding functionality, which are in draft status as BOLT12. +This usually requires **experimental-onion-messages** as well. See +lightning-offer(7) and lightning-fetchinvoice(7). + BUGS ----