core-lightning/doc/schemas/lightning-listpeers.json

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "rpc": "listpeers",
  "title": "Command returning data on connected lightning nodes",
  "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."
  ],
  "request": {
    "required": [],
    "properties": {
      "id": {
        "type": "pubkey",
        "description": [
          "If supplied, limits the result to just the peer with the given ID, if it exists."
        ]
      },
      "level": {
        "type": "string",
        "description": [
          "Supplying level will show log entries related to that peer at the given log level."
        ],
        "enum": [
          "io",
          "trace",
          "debug",
          "info",
          "unusual"
        ]
      }
    }
  },
  "response": {
    "required": [
      "peers"
    ],
    "properties": {
      "peers": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true,
          "required": [
            "id",
            "connected",
            "num_channels"
          ],
          "properties": {
            "id": {
              "type": "pubkey",
              "description": [
                "The unique id of the peer."
              ]
            },
            "connected": {
              "type": "boolean",
              "description": [
                "Value showing the connection status."
              ]
            },
            "num_channels": {
              "type": "u32",
              "description": [
                "The number of channels the peer has with this node."
              ],
              "added": "v23.02"
            },
            "log": {
              "type": "array",
              "description": [
                "If *level* is specified, logs for this peer."
              ],
              "items": {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "type"
                ],
                "properties": {
                  "type": {
                    "type": "string",
                    "enum": [
                      "SKIPPED",
                      "BROKEN",
                      "UNUSUAL",
                      "INFO",
                      "DEBUG",
                      "TRACE",
                      "IO_IN",
                      "IO_OUT"
                    ]
                  }
                },
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "type": {
                          "enum": [
                            "SKIPPED"
                          ]
                        }
                      }
                    },
                    "then": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "num_skipped"
                      ],
                      "properties": {
                        "type": {},
                        "num_skipped": {
                          "type": "u32",
                          "description": [
                            "Number of deleted/omitted entries."
                          ]
                        }
                      }
                    }
                  },
                  {
                    "if": {
                      "properties": {
                        "type": {
                          "enum": [
                            "BROKEN",
                            "UNUSUAL",
                            "INFO",
                            "DEBUG",
                            "TRACE"
                          ]
                        }
                      }
                    },
                    "then": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "time",
                        "source",
                        "log",
                        "node_id"
                      ],
                      "properties": {
                        "type": {},
                        "time": {
                          "type": "string",
                          "description": [
                            "UNIX timestamp with 9 decimal places."
                          ]
                        },
                        "source": {
                          "type": "string",
                          "description": [
                            "The particular logbook this was found in."
                          ]
                        },
                        "log": {
                          "type": "string",
                          "description": [
                            "The actual log message."
                          ]
                        },
                        "node_id": {
                          "type": "pubkey",
                          "description": [
                            "The peer this is associated with."
                          ]
                        }
                      }
                    }
                  },
                  {
                    "if": {
                      "properties": {
                        "type": {
                          "enum": [
                            "IO_IN",
                            "IO_OUT"
                          ]
                        }
                      }
                    },
                    "then": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "time",
                        "source",
                        "log",
                        "node_id",
                        "data"
                      ],
                      "properties": {
                        "type": {},
                        "time": {
                          "type": "string",
                          "description": [
                            "UNIX timestamp with 9 decimal places."
                          ]
                        },
                        "source": {
                          "type": "string",
                          "description": [
                            "The particular logbook this was found in."
                          ]
                        },
                        "log": {
                          "type": "string",
                          "description": [
                            "The actual log message."
                          ]
                        },
                        "node_id": {
                          "type": "pubkey",
                          "description": [
                            "The peer this is associated with."
                          ]
                        },
                        "data": {
                          "type": "hex",
                          "description": [
                            "The IO which occurred."
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            }
          },
          "allOf": [
            {
              "if": {
                "additionalProperties": true,
                "properties": {
                  "connected": {
                    "enum": [
                      true
                    ]
                  }
                }
              },
              "then": {
                "additionalProperties": false,
                "required": [
                  "netaddr",
                  "features"
                ],
                "properties": {
                  "id": {},
                  "channels": {},
                  "connected": {},
                  "num_channels": {},
                  "htlcs": {},
                  "log": {},
                  "netaddr": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 1,
                    "description": [
                      "A single entry array."
                    ],
                    "items": {
                      "type": "string",
                      "description": [
                        "Address, e.g. 1.2.3.4:1234."
                      ]
                    }
                  },
                  "remote_addr": {
                    "type": "string",
                    "description": [
                      "The public IPv4/6 address the peer sees us from, e.g. 1.2.3.4:1234."
                    ]
                  },
                  "features": {
                    "type": "hex",
                    "description": [
                      "Bitmap of BOLT #9 features from peer's INIT message."
                    ]
                  }
                }
              }
            }
          ]
        }
      }
    }
  },
  "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": [
    {
      "request": {
        "id": "example:listpeers#1",
        "method": "listpeers",
        "params": {
          "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59"
        }
      },
      "response": {
        "peers": [
          {
            "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
            "connected": true,
            "num_channels": 1,
            "netaddr": [
              "127.0.0.1:44619"
            ],
            "features": "08a0000a0a69a2"
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:listpeers#2",
        "method": "listpeers",
        "params": {}
      },
      "response": {
        "peers": [
          {
            "id": "0266e4598d1d3c415f572a8488830b60f7e744ed9235eb0b1ba93283b315c03518",
            "connected": true,
            "num_channels": 1,
            "netaddr": [
              "127.0.0.1:48862"
            ],
            "features": "08a0000a0a69a2"
          }
        ]
      }
    }
  ]
}