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 connected, or not connected but have open channels with this node, are returned.

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 actual 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 array.:
  • (string, optional): Address, e.g. 1.2.3.4:1234.
• features (hex): Bitmap of BOLT #9 features from peer's INIT message.
• remote_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 <[email protected]>.

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": "08a8882a8a59a1"
    }
  ]
}

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": "08a8882a8a59a1"
    },
    {
      "id": "nodeid030303030303030303030303030303030303030303030303030303030303",
      "connected": true,
      "num_channels": 1,
      "netaddr": [
        "127.0.0.1:19736"
      ],
      "features": "08a8882a8a59a1"
    },
    {
      "id": "nodeid040404040404040404040404040404040404040404040404040404040404",
      "connected": false,
      "num_channels": 1,
      "features": "08a8882a8a59a1"
    }
  ]
}