Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
LIGHTNING-LISTPEERS(7)					LIGHTNING-LISTPEERS(7)

NAME
       listpeers -- Command returning data on connected	lightning nodes

SYNOPSIS
       listpeers [id] [level]

DESCRIPTION
       The  listpeers  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 connect command, data on the	node can be returned  using  listpeers
       and the id that was used	with the connect command.

       If  no  id  is supplied,	then data on all lightning nodes that are con-
       nected, or not connected	but have open channels with this node, are re-
       turned.

       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 connected	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.

       •  id  (pubkey,	optional):  If supplied, limits	the result to just the
	  peer with the	given ID, if it	exists.
       •  level	(string, optional) (one	of  "io",  "trace",  "debug",  "info",
	  "unusual"):  Supplying  level	 will show log entries related to that
	  peer at the given log	level.

RETURN VALUE
       On success, an object containing	peers is returned. It is an  array  of
       objects,	where each object contains:

       •  id (pubkey): The unique id of	the peer.
       •  connected (boolean): Value showing the connection status.
       •  num_channels	(u32):	The  number of channels	the peer has with this
	  node.	(added v23.02)
       •  log (array of	objects, optional): If level is	 specified,  logs  for
	  this peer.:

	  •  type  (string)  (one  of  "SKIPPED", "BROKEN", "UNUSUAL", "INFO",
	     "DEBUG", "TRACE", "IO_IN",	"IO_OUT")

	  If type is "SKIPPED":	- num_skipped (u32): Number of deleted/omitted
	  entries.

	  If type is "BROKEN", "UNUSUAL", "INFO", "DEBUG" or "TRACE":  -  time
	  (string):  UNIX timestamp with 9 decimal places.  - source (string):
	  The particular logbook this was found	in.  - log (string):  The  ac-
	  tual	log  message.  - node_id (pubkey): The peer this is associated
	  with.

	  If type is "IO_IN" or	"IO_OUT": - time (string): UNIX	timestamp with
	  9 decimal places.  - source (string):	The  particular	 logbook  this
	  was  found  in.   - log (string): The	actual log message.  - node_id
	  (pubkey): The	peer this is associated	with.  - data  (hex):  The  IO
	  which	occurred.

       If  connected is	true: -	netaddr	(array of strings): A single entry ar-
       ray.: - (string,	optional): Address,  e.g.  1.2.3.4:1234.   -  features
       (hex):  Bitmap  of  BOLT	 #9  features from peer's INIT message.	 - re-
       mote_addr (string, optional): The public	IPv4/6 address the  peer  sees
       us from,	e.g. 1.2.3.4:1234.

ERRORS
       On  error the returned object will contain code and message properties,
       with code being one of the following:

       •  -32602: If the given parameters are wrong.

AUTHOR
       Michael Hawkins <<michael.hawkins@protonmail.com>>.

SEE ALSO
       lightning-connect(7),	lightning-fundchannel_start(7),	    lightning-
       setchannel(7)

RESOURCES
       Main web	site: <https://github.com/ElementsProject/lightning> Lightning
       RFC		     site		   (BOLT		  #9):
       <https://github.com/lightning/bolts/blob/master/09-features.md>

EXAMPLES
       Example 1:

       Request:

       $ lightning-cli listpeers -k "id"="nodeid030303030303030303030303030303030303030303030303030303030303"

       {
	 "id": "example:listpeers#1",
	 "method": "listpeers",
	 "params": {
	   "id": "nodeid030303030303030303030303030303030303030303030303030303030303"
	 }
       }

       Response:

       {
	 "peers": [
	   {
	     "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	     "connected": true,
	     "num_channels": 1,
	     "netaddr":	[
	       "127.0.0.1:19736"
	     ],
	     "features": "0898882a8a59a1"
	   }
	 ]
       }

       Example 2:

       Request:

       $ lightning-cli listpeers

       {
	 "id": "example:listpeers#2",
	 "method": "listpeers",
	 "params": {}
       }

       Response:

       {
	 "peers": [
	   {
	     "id": "nodeid010101010101010101010101010101010101010101010101010101010101",
	     "connected": true,
	     "num_channels": 1,
	     "netaddr":	[
	       "127.0.0.1:19734"
	     ],
	     "features": "0898882a8a59a1"
	   },
	   {
	     "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
	     "connected": true,
	     "num_channels": 1,
	     "netaddr":	[
	       "127.0.0.1:19736"
	     ],
	     "features": "0898882a8a59a1"
	   },
	   {
	     "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
	     "connected": false,
	     "num_channels": 1,
	     "features": "0898882a8a59a1"
	   }
	 ]
       }

Core Lightning v25.09					LIGHTNING-LISTPEERS(7)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=lightning-listpeers&sektion=7&manpath=FreeBSD+Ports+15.0>

home | help