Skip to content

Commit 22921f1

Browse files
hawkmaukrustyrussell
hawkmauk
authored and
rustyrussell
committed
Manpage for lightning-listchannels created
1 parent 55e8634 commit 22921f1

File tree

3 files changed

+331
-0
lines changed

3 files changed

+331
-0
lines changed

‎doc/Makefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ MANPAGES := doc/lightning-cli.1 \
1717
doc/lightning-fundchannel.7 \
1818
doc/lightning-getroute.7 \
1919
doc/lightning-invoice.7 \
20+
doc/lightning-listchannels.7 \
2021
doc/lightning-listfunds.7 \
2122
doc/lightning-listinvoices.7 \
2223
doc/lightning-listpayments.7 \

‎doc/lightning-listchannels.7‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
'\" t
2+
.\" Title: lightning-listchannels
3+
.\" Author: [see the "AUTHOR" section]
4+
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
5+
.\" Date: 01/08/2019
6+
.\" Manual: \ \&
7+
.\" Source: \ \&
8+
.\" Language: English
9+
.\"
10+
.TH "LIGHTNING\-LISTCHANN" "7" "01/08/2019" "\ \&" "\ \&"
11+
.\" -----------------------------------------------------------------
12+
.\" * Define some portability stuff
13+
.\" -----------------------------------------------------------------
14+
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15+
.\" http://bugs.debian.org/507673
16+
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17+
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18+
.ie \n(.g .ds Aq \(aq
19+
.el .ds Aq '
20+
.\" -----------------------------------------------------------------
21+
.\" * set default formatting
22+
.\" -----------------------------------------------------------------
23+
.\" disable hyphenation
24+
.nh
25+
.\" disable justification (adjust text to left margin only)
26+
.ad l
27+
.\" -----------------------------------------------------------------
28+
.\" * MAIN CONTENT STARTS HERE *
29+
.\" -----------------------------------------------------------------
30+
.SH "NAME"
31+
lightning-listchannels \- Command to query active lightning channels in the entire network\&.
32+
.SH "SYNOPSIS"
33+
.sp
34+
\fBlistchannels\fR [\fIshort_channel_id\fR]
35+
.SH "DESCRIPTION"
36+
.sp
37+
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)\&.
38+
.sp
39+
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\&.
40+
.sp
41+
Supplying \fIshort_channel_id\fR will filter the results to only return data for known channels with a matching \fIshort_channel_id\fR\&.
42+
.SH "RETURN VALUE"
43+
.sp
44+
On success, an object with a "channels" key is returned containing a list of 0 or more objects\&.
45+
.sp
46+
Each object in the list contains the following data:
47+
.sp
48+
.RS 4
49+
.ie n \{\
50+
\h'-04'\(bu\h'+03'\c
51+
.\}
52+
.el \{\
53+
.sp -1
54+
.IP \(bu 2.3
55+
.\}
56+
\fIsource\fR
57+
: The node providing entry to the channel, specifying the fees charged for using the channel in that direction\&.
58+
.RE
59+
.sp
60+
.RS 4
61+
.ie n \{\
62+
\h'-04'\(bu\h'+03'\c
63+
.\}
64+
.el \{\
65+
.sp -1
66+
.IP \(bu 2.3
67+
.\}
68+
\fIdestination\fR
69+
: The node providing the exit point for the channel\&.
70+
.RE
71+
.sp
72+
.RS 4
73+
.ie n \{\
74+
\h'-04'\(bu\h'+03'\c
75+
.\}
76+
.el \{\
77+
.sp -1
78+
.IP \(bu 2.3
79+
.\}
80+
\fIshort_channel_id\fR
81+
: The channel identifier\&.
82+
.RE
83+
.sp
84+
.RS 4
85+
.ie n \{\
86+
\h'-04'\(bu\h'+03'\c
87+
.\}
88+
.el \{\
89+
.sp -1
90+
.IP \(bu 2.3
91+
.\}
92+
\fIpublic\fR
93+
: 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\&.
94+
.RE
95+
.sp
96+
.RS 4
97+
.ie n \{\
98+
\h'-04'\(bu\h'+03'\c
99+
.\}
100+
.el \{\
101+
.sp -1
102+
.IP \(bu 2.3
103+
.\}
104+
\fIsatoshis\fR
105+
: Funds available in the channel\&.
106+
.RE
107+
.sp
108+
.RS 4
109+
.ie n \{\
110+
\h'-04'\(bu\h'+03'\c
111+
.\}
112+
.el \{\
113+
.sp -1
114+
.IP \(bu 2.3
115+
.\}
116+
\fImessage_flags\fR
117+
: Bitfield showing the presence of optional fields in the
118+
\fIchannel_update\fR
119+
message (BOLT #7)\&.
120+
.RE
121+
.sp
122+
.RS 4
123+
.ie n \{\
124+
\h'-04'\(bu\h'+03'\c
125+
.\}
126+
.el \{\
127+
.sp -1
128+
.IP \(bu 2.3
129+
.\}
130+
\fIchannel_flags\fR
131+
: Bitfields indicating the direction of the channel and signaling various options concerning the channel\&. (BOLT #7)\&.
132+
.RE
133+
.sp
134+
.RS 4
135+
.ie n \{\
136+
\h'-04'\(bu\h'+03'\c
137+
.\}
138+
.el \{\
139+
.sp -1
140+
.IP \(bu 2.3
141+
.\}
142+
\fIactive\fR
143+
: 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\&.
144+
.RE
145+
.sp
146+
.RS 4
147+
.ie n \{\
148+
\h'-04'\(bu\h'+03'\c
149+
.\}
150+
.el \{\
151+
.sp -1
152+
.IP \(bu 2.3
153+
.\}
154+
\fIlast_update\fR
155+
: Unix timestamp (seconds) showing when the last channel_update message was received\&.
156+
.RE
157+
.sp
158+
.RS 4
159+
.ie n \{\
160+
\h'-04'\(bu\h'+03'\c
161+
.\}
162+
.el \{\
163+
.sp -1
164+
.IP \(bu 2.3
165+
.\}
166+
\fIbase_fee_millisatoshi\fR
167+
: The base fee (in millisatoshi) charged for the HTLC (BOLT #2)\&.
168+
.RE
169+
.sp
170+
.RS 4
171+
.ie n \{\
172+
\h'-04'\(bu\h'+03'\c
173+
.\}
174+
.el \{\
175+
.sp -1
176+
.IP \(bu 2.3
177+
.\}
178+
\fIfee_per_millionth\fR
179+
: The amount (in millionths of a satoshi) charged per transferred satoshi (BOLT #2)\&.
180+
.RE
181+
.sp
182+
.RS 4
183+
.ie n \{\
184+
\h'-04'\(bu\h'+03'\c
185+
.\}
186+
.el \{\
187+
.sp -1
188+
.IP \(bu 2.3
189+
.\}
190+
\fIdelay\fR
191+
: The number of blocks delay required to wait for on\-chain settlement when unilaterally closing the channel (BOLT #2)\&.
192+
.RE
193+
.sp
194+
If \fIshort_channel_id\fR is supplied and no matching channels are found, a "channels" object with an empty list is returned\&.
195+
.SH "ERRORS"
196+
.sp
197+
If \fIshort_channel_id\fR is not a valid short_channel_id, an error message will be returned:
198+
.sp
199+
.if n \{\
200+
.RS 4
201+
.\}
202+
.nf
203+
{ "code" : \-32602,
204+
"message" : "\*(Aqshort_channel_id\*(Aq should be a short channel id, not \*(Aq\&.\&.\&.\*(Aq" }
205+
.fi
206+
.if n \{\
207+
.RE
208+
.\}
209+
.SH "AUTHOR"
210+
.sp
211+
Michael Hawkins <michael\&.hawkins@protonmail\&.com>\&.
212+
.SH "SEE ALSO"
213+
.sp
214+
lightning\-fundchannel(7)
215+
.SH "RESOURCES"
216+
.sp
217+
Main web site: https://github\&.com/ElementsProject/lightning
218+
.sp
219+
Lightning RFC site
220+
.sp
221+
.RS 4
222+
.ie n \{\
223+
\h'-04'\(bu\h'+03'\c
224+
.\}
225+
.el \{\
226+
.sp -1
227+
.IP \(bu 2.3
228+
.\}
229+
BOLT #2:
230+
https://github\&.com/lightningnetwork/lightning\-rfc/blob/master/02\-peer\-protocol\&.md
231+
.RE
232+
.sp
233+
.RS 4
234+
.ie n \{\
235+
\h'-04'\(bu\h'+03'\c
236+
.\}
237+
.el \{\
238+
.sp -1
239+
.IP \(bu 2.3
240+
.\}
241+
BOLT #7:
242+
https://github\&.com/lightningnetwork/lightning\-rfc/blob/master/07\-routing\-gossip\&.md
243+
.RE

‎doc/lightning-listchannels.7.txt‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
LIGHTNING-LISTCHANNELS(7)
2+
=======================
3+
:doctype: manpage
4+
5+
NAME
6+
----
7+
lightning-listchannels - Command to query active lightning channels in the entire network.
8+
9+
SYNOPSIS
10+
--------
11+
*listchannels* ['short_channel_id']
12+
13+
DESCRIPTION
14+
-----------
15+
The *listchannels* RPC command returns data on channels that are known to the
16+
node. Because channels may be bidirectional, up to 2 objects will be returned
17+
for each channel (one for each direction).
18+
19+
If no 'short_channel_id' is supplied, then data on all lightning channels known
20+
to this node, are returned. These can be local channels or public channels
21+
broadcast on the gossip network.
22+
23+
Supplying 'short_channel_id' will filter the results to only return data for
24+
known channels with a matching 'short_channel_id'.
25+
26+
RETURN VALUE
27+
------------
28+
On success, an object with a "channels" key is returned containing a list of 0
29+
or more objects.
30+
31+
Each object in the list contains the following data:
32+
33+
- 'source' : The node providing entry to the channel, specifying the fees
34+
charged for using the channel in that direction.
35+
- 'destination' : The node providing the exit point for the channel.
36+
- 'short_channel_id' : The channel identifier.
37+
- 'public' : Boolean value, is publicly available. Non-local channels will only
38+
ever have this value set to true. Local channels are side-loaded by this node,
39+
rather than obtained through the gossip network, and so may have this value set
40+
to false.
41+
- 'satoshis' : Funds available in the channel.
42+
- 'message_flags' : Bitfield showing the presence of optional fields in the
43+
'channel_update' message (BOLT #7).
44+
- 'channel_flags' : Bitfields indicating the direction of the channel and
45+
signaling various options concerning the channel. (BOLT #7).
46+
- 'active' : Boolean value, is available for routing. This is linked to the
47+
channel flags data, where if the second bit is set, signals a channels
48+
temporary unavailability (due to loss of connectivity) OR permanent
49+
unavailability where the channel has been closed but not settlement on-chain.
50+
- 'last_update' : Unix timestamp (seconds) showing when the last channel_update
51+
message was received.
52+
- 'base_fee_millisatoshi' : The base fee (in millisatoshi) charged for the
53+
HTLC (BOLT #2).
54+
- 'fee_per_millionth' : The amount (in millionths of a satoshi) charged per
55+
transferred satoshi (BOLT #2).
56+
- 'delay' : The number of blocks delay required to wait for on-chain settlement
57+
when unilaterally closing the channel (BOLT #2).
58+
59+
If 'short_channel_id' is supplied and no matching channels are found, a
60+
"channels" object with an empty list is returned.
61+
62+
ERRORS
63+
------
64+
If 'short_channel_id' is not a valid short_channel_id, an error message will be
65+
returned:
66+
67+
----
68+
{ "code" : -32602,
69+
"message" : "'short_channel_id' should be a short channel id, not '...'" }
70+
----
71+
72+
AUTHOR
73+
------
74+
Michael Hawkins <[email protected]>.
75+
76+
SEE ALSO
77+
--------
78+
lightning-fundchannel(7)
79+
80+
RESOURCES
81+
---------
82+
Main web site: https://github.com/ElementsProject/lightning
83+
84+
Lightning RFC site
85+
86+
- BOLT #2: https://github.com/lightningnetwork/lightning-rfc/blob/master/02-peer-protocol.md
87+
- BOLT #7: https://github.com/lightningnetwork/lightning-rfc/blob/master/07-routing-gossip.md

0 commit comments

Comments
 (0)