diff --git a/doc/Makefile b/doc/Makefile index 284c50c10..78449841e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -17,6 +17,7 @@ MANPAGES := doc/lightning-cli.1 \ doc/lightning-fundchannel.7 \ doc/lightning-getroute.7 \ doc/lightning-invoice.7 \ + doc/lightning-listchannels.7 \ doc/lightning-listfunds.7 \ doc/lightning-listinvoices.7 \ doc/lightning-listpayments.7 \ diff --git a/doc/lightning-listchannels.7 b/doc/lightning-listchannels.7 new file mode 100644 index 000000000..976dad333 --- /dev/null +++ b/doc/lightning-listchannels.7 @@ -0,0 +1,243 @@ +'\" t +.\" Title: lightning-listchannels +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.79.1 +.\" Date: 01/08/2019 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "LIGHTNING\-LISTCHANN" "7" "01/08/2019" "\ \&" "\ \&" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" +lightning-listchannels \- Command to query active lightning channels in the entire network\&. +.SH "SYNOPSIS" +.sp +\fBlistchannels\fR [\fIshort_channel_id\fR] +.SH "DESCRIPTION" +.sp +The \fBlistchannels\fR RPC command returns data on channels that are known to the node\&. Because channels may be bidirectional, up to 2 objects will be returned for each channel (one for each direction)\&. +.sp +If no \fIshort_channel_id\fR is supplied, then data on all lightning channels known to this node, are returned\&. These can be local channels or public channels broadcast on the gossip network\&. +.sp +Supplying \fIshort_channel_id\fR will filter the results to only return data for known channels with a matching \fIshort_channel_id\fR\&. +.SH "RETURN VALUE" +.sp +On success, an object with a "channels" key is returned containing a list of 0 or more objects\&. +.sp +Each object in the list contains the following data: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsource\fR +: The node providing entry to the channel, specifying the fees charged for using the channel in that direction\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdestination\fR +: The node providing the exit point for the channel\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIshort_channel_id\fR +: The channel identifier\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIpublic\fR +: Boolean value, is publicly available\&. Non\-local channels will only ever have this value set to true\&. Local channels are side\-loaded by this node, rather than obtained through the gossip network, and so may have this value set to false\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIsatoshis\fR +: Funds available in the channel\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fImessage_flags\fR +: Bitfield showing the presence of optional fields in the +\fIchannel_update\fR +message (BOLT #7)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIchannel_flags\fR +: Bitfields indicating the direction of the channel and signaling various options concerning the channel\&. (BOLT #7)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIactive\fR +: Boolean value, is available for routing\&. This is linked to the channel flags data, where if the second bit is set, signals a channels temporary unavailability (due to loss of connectivity) OR permanent unavailability where the channel has been closed but not settlement on\-chain\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIlast_update\fR +: Unix timestamp (seconds) showing when the last channel_update message was received\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIbase_fee_millisatoshi\fR +: The base fee (in millisatoshi) charged for the HTLC (BOLT #2)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIfee_per_millionth\fR +: The amount (in millionths of a satoshi) charged per transferred satoshi (BOLT #2)\&. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +\fIdelay\fR +: The number of blocks delay required to wait for on\-chain settlement when unilaterally closing the channel (BOLT #2)\&. +.RE +.sp +If \fIshort_channel_id\fR is supplied and no matching channels are found, a "channels" object with an empty list is returned\&. +.SH "ERRORS" +.sp +If \fIshort_channel_id\fR is not a valid short_channel_id, an error message will be returned: +.sp +.if n \{\ +.RS 4 +.\} +.nf +{ "code" : \-32602, + "message" : "\*(Aqshort_channel_id\*(Aq should be a short channel id, not \*(Aq\&.\&.\&.\*(Aq" } +.fi +.if n \{\ +.RE +.\} +.SH "AUTHOR" +.sp +Michael Hawkins \&. +.SH "SEE ALSO" +.sp +lightning\-fundchannel(7) +.SH "RESOURCES" +.sp +Main web site: https://github\&.com/ElementsProject/lightning +.sp +Lightning RFC site +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +BOLT #2: +https://github\&.com/lightningnetwork/lightning\-rfc/blob/master/02\-peer\-protocol\&.md +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +BOLT #7: +https://github\&.com/lightningnetwork/lightning\-rfc/blob/master/07\-routing\-gossip\&.md +.RE diff --git a/doc/lightning-listchannels.7.txt b/doc/lightning-listchannels.7.txt new file mode 100644 index 000000000..95cf6eea0 --- /dev/null +++ b/doc/lightning-listchannels.7.txt @@ -0,0 +1,87 @@ +LIGHTNING-LISTCHANNELS(7) +======================= +:doctype: manpage + +NAME +---- +lightning-listchannels - Command to query active lightning channels in the entire network. + +SYNOPSIS +-------- +*listchannels* ['short_channel_id'] + +DESCRIPTION +----------- +The *listchannels* RPC command returns data on channels that are known to the +node. Because channels may be bidirectional, up to 2 objects will be returned +for each channel (one for each direction). + +If no 'short_channel_id' is supplied, then data on all lightning channels known +to this node, are returned. These can be local channels or public channels +broadcast on the gossip network. + +Supplying 'short_channel_id' will filter the results to only return data for +known channels with a matching 'short_channel_id'. + +RETURN VALUE +------------ +On success, an object with a "channels" key is returned containing a list of 0 +or more objects. + +Each object in the list contains the following data: + +- 'source' : The node providing entry to the channel, specifying the fees +charged for using the channel in that direction. +- 'destination' : The node providing the exit point for the channel. +- 'short_channel_id' : The channel identifier. +- 'public' : Boolean value, is publicly available. Non-local channels will only +ever have this value set to true. Local channels are side-loaded by this node, +rather than obtained through the gossip network, and so may have this value set +to false. +- 'satoshis' : Funds available in the channel. +- 'message_flags' : Bitfield showing the presence of optional fields in the +'channel_update' message (BOLT #7). +- 'channel_flags' : Bitfields indicating the direction of the channel and +signaling various options concerning the channel. (BOLT #7). +- 'active' : Boolean value, is available for routing. This is linked to the +channel flags data, where if the second bit is set, signals a channels +temporary unavailability (due to loss of connectivity) OR permanent +unavailability where the channel has been closed but not settlement on-chain. +- 'last_update' : Unix timestamp (seconds) showing when the last channel_update +message was received. +- 'base_fee_millisatoshi' : The base fee (in millisatoshi) charged for the +HTLC (BOLT #2). +- 'fee_per_millionth' : The amount (in millionths of a satoshi) charged per +transferred satoshi (BOLT #2). +- 'delay' : The number of blocks delay required to wait for on-chain settlement +when unilaterally closing the channel (BOLT #2). + +If 'short_channel_id' is supplied and no matching channels are found, a +"channels" object with an empty list is returned. + +ERRORS +------ +If 'short_channel_id' is not a valid short_channel_id, an error message will be +returned: + +---- +{ "code" : -32602, + "message" : "'short_channel_id' should be a short channel id, not '...'" } +---- + +AUTHOR +------ +Michael Hawkins . + +SEE ALSO +-------- +lightning-fundchannel(7) + +RESOURCES +--------- +Main web site: https://github.com/ElementsProject/lightning + +Lightning RFC site + +- BOLT #2: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md +- BOLT #7: https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md