Manpage for lightning-listchannels created

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 \

doc/lightning-listchannels.7

@@ -0,0 +1,243 @@
+'\" t
+.\"     Title: lightning-listchannels
+.\"    Author: [see the "AUTHOR" section]
+.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
+.\"      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 <michael\&.hawkins@protonmail\&.com>\&.
+.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

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 <[email protected]>.
+
+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