LIGHTNING-LISTPEERS(7)

📦
version 26.06.9 · 2 versions
, in nixpkgs unstable

💜 LIGHTNING-LISTPEERS(7) — okay bestie, let's talk about listpeers

So this is the manual page for lightning-listpeers, and honestly? It's the "who's in my contacts rn" of Core Lightning. Let's get into it 🫶

✨ NAME ✨

listpeers — the command that hands you all the data on your connected lightning nodes. It's giving main character energy for peer info, fr fr.

🌸 SYNOPSIS 🌸

listpeers [id] [level]

🦋 DESCRIPTION 🦋

okay so the listpeers RPC command returns data on nodes that are connected or not connected but still have open channels with this node. Both categories, bestie. It's inclusive 💅

Once a connection to another lightning node has been established — using the connect command — you can get the data on that node back with listpeers, passing the same id you used with connect. Matchy matchy ✨

If you don't supply an id, then you get data on all the lightning nodes that are connected, or not connected but have open channels with this node. The whole group chat 😭

Now here's the part where you need to pay attention 👑 — if a channel is open with a node and the connection has been lost, that node still shows up in the output of the command, and the value of its connected attribute will be "false". It's not ghosting you, it's just... disconnected.

The channel stays open for a set blocktime, and after that, if the connection hasn't been re-established, the channel closes and the node no longer appears in the command output. So like, enjoy it while it lasts 💀

  • id (pubkey, optional): if you supply it, it limits the result to just the peer with that given ID — assuming it exists, which, fair.
  • level (string, optional) (one of "io", "trace", "debug", "info", "unusual"): supplying level shows you log entries related to that peer at the given log level. Very "let me check the receipts" of you 🎀

💖 RETURN VALUE 💖

On success, you get an object containing peers. It's an array of objects, where each object contains:

  • id (pubkey): the unique id of the peer. Their little name tag 🏷️
  • 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. Here's how those break down:
    • 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. Yeah, that one's on you bestie 😭

👑 AUTHOR 👑

Michael Hawkins michael.hawkins@protonmail.com. We stan 💜

🌈 SEE ALSO 🌈

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

🧚 RESOURCES 🧚

🍓 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"
    }
  ]
}

that's the whole page, bestie — go forth and peer at your peers 💅✨

Core Lightning v26.06.9 🌸 LIGHTNING-LISTPEERS(7) — mwah, hope this helped, ily 🫶💖

📦 where this page comes from