|
|
|
|
.TH "LIGHTNING-LISTPEERS" "7" "" "" "lightning-listpeers"
|
|
|
|
|
.SH NAME
|
|
|
|
|
lightning-listpeers - Command returning data on connected lightning nodes
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
|
|
|
|
|
\fBlistpeers\fR [\fIid\fR] [\fIlevel\fR]
|
|
|
|
|
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
|
|
|
|
|
The \fBlistpeers\fR RPC command returns data on nodes that are connected
|
|
|
|
|
or are not connected but have open channels with this node\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Once a connection to another lightning node has been established, using
|
|
|
|
|
the \fBconnect\fR command, data on the node can be returned using
|
|
|
|
|
\fBlistpeers\fR and the \fIid\fR that was used with the \fBconnect\fR command\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If no \fIid\fR is supplied, then data on all lightning nodes that are
|
|
|
|
|
connected, or not connected but have open channels with this node, are
|
|
|
|
|
returned\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Supplying \fIid\fR will filter the results to only return data on a node
|
|
|
|
|
with a matching \fIid\fR, if one exists\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Supplying \fIlevel\fR will show log entries related to that peer at the
|
|
|
|
|
given log level\. Valid log levels are "io", "debug", "info", and
|
|
|
|
|
"unusual"\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If a channel is open with a node and the connection has been lost, then
|
|
|
|
|
the node will still appear in the output of the command and the value of
|
|
|
|
|
the \fIconnected\fR attribute of the node will be "false"\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The channel will remain open for a set blocktime, after which if the
|
|
|
|
|
connection has not been re-established, the channel will close and the
|
|
|
|
|
node will no longer appear in the command output\.
|
|
|
|
|
|
|
|
|
|
.SH RETURN VALUE
|
|
|
|
|
|
|
|
|
|
On success, an object with a "peers" key is returned containing a list
|
|
|
|
|
of 0 or more objects\.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Each object in the list contains the following data:
|
|
|
|
|
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIid\fR : The unique id of the peer
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIconnected\fR : A boolean value showing the connection status
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fInetaddr\fR : A list of network addresses the node is listening on
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIglobalfeatures\fR : Bit flags showing supported global features (BOLT #9)
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIlocalfeatures\fR : Bit flags showing supported local features (BOLT #9)
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIchannels\fR : An list of channel id’s open on the peer
|
|
|
|
|
.IP \[bu]
|
|
|
|
|
\fIlog\fR : Only present if \fIlevel\fR is set\. List logs related to the
|
|
|
|
|
peer at the specified \fIlevel\fR
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If \fIid\fR is supplied and no matching nodes are found, a "peers" object
|
|
|
|
|
with an empty list is returned\.
|
|
|
|
|
|
|
|
|
|
.SH ERRORS
|
|
|
|
|
|
|
|
|
|
If \fIid\fR is not a valid public key, an error message will be returned:
|
|
|
|
|
|
|
|
|
|
.nf
|
|
|
|
|
.RS
|
|
|
|
|
{ "code" : -32602, "message" : "'id' should be a pubkey, not '...'" }
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.fi
|
|
|
|
|
|
|
|
|
|
If \fIlevel\fR is not a valid log level, an error message will be returned:
|
|
|
|
|
|
|
|
|
|
.nf
|
|
|
|
|
.RS
|
|
|
|
|
{ "code" : -32602, "message" "'level' should be 'io', 'debug', 'info', or 'unusual', not '...'" }
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.RE
|
|
|
|
|
|
|
|
|
|
.fi
|
|
|
|
|
.SH AUTHOR
|
|
|
|
|
|
|
|
|
|
Michael Hawkins \fI<michael.hawkins@protonmail.com\fR>\.
|
|
|
|
|
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
|
|
|
|
|
\fBlightning-connect\fR(7)
|
|
|
|
|
|
|
|
|
|
.SH RESOURCES
|
|
|
|
|
|
|
|
|
|
Main web site: \fIhttps://github.com/ElementsProject/lightning\fR Lightning
|
|
|
|
|
RFC site (BOLT #9):
|
|
|
|
|
\fIhttps://github.com/lightningnetwork/lightning-rfc/blob/master/09-features.md\fR
|
|
|
|
|
|
