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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "additionalProperties": false,
  "rpc": "listnodes",
  "title": "Command to get the list of nodes in the known network.",
  "description": [
    "The **listnodes** command returns nodes the node has learned about via gossip messages, or a single one if the node *id* was specified."
  ],
  "categories": [
    "readonly"
  ],
  "request": {
    "required": [],
    "properties": {
      "id": {
        "type": "pubkey",
        "description": [
          "The public key of the node to list."
        ]
      }
    }
  },
  "response": {
    "required": [
      "nodes"
    ],
    "properties": {
      "nodes": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": true,
          "required": [
            "nodeid"
          ],
          "properties": {
            "nodeid": {
              "type": "pubkey",
              "description": [
                "The public key of the node."
              ]
            },
            "last_timestamp": {
              "type": "u32",
              "description": [
                "A node_announcement has been received for this node (UNIX timestamp)."
              ]
            }
          },
          "allOf": [
            {
              "if": {
                "required": [
                  "last_timestamp"
                ]
              },
              "then": {
                "additionalProperties": false,
                "required": [
                  "nodeid",
                  "last_timestamp",
                  "alias",
                  "color",
                  "features",
                  "addresses"
                ],
                "properties": {
                  "nodeid": {},
                  "last_timestamp": {},
                  "option_will_fund": {},
                  "alias": {
                    "type": "string",
                    "description": [
                      "The fun alias this node advertized."
                    ],
                    "maxLength": 32
                  },
                  "color": {
                    "type": "hex",
                    "description": [
                      "The favorite RGB color this node advertized."
                    ],
                    "minLength": 6,
                    "maxLength": 6
                  },
                  "features": {
                    "type": "hex",
                    "description": [
                      "BOLT #9 features bitmap this node advertized."
                    ]
                  },
                  "addresses": {
                    "type": "array",
                    "description": [
                      "The addresses this node advertized."
                    ],
                    "items": {
                      "type": "object",
                      "required": [
                        "type",
                        "port"
                      ],
                      "additionalProperties": true,
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "dns",
                            "ipv4",
                            "ipv6",
                            "torv2",
                            "torv3"
                          ],
                          "description": [
                            "Type of connection (until 23.08, `websocket` was also allowed)."
                          ]
                        },
                        "port": {
                          "type": "u16",
                          "description": [
                            "Port number."
                          ]
                        }
                      },
                      "if": {
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": [
                              "dns",
                              "ipv4",
                              "ipv6",
                              "torv2",
                              "torv3"
                            ]
                          }
                        }
                      },
                      "then": {
                        "required": [
                          "type",
                          "address",
                          "port"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "type": {},
                          "port": {},
                          "address": {
                            "type": "string",
                            "description": [
                              "Address in expected format for **type**."
                            ]
                          }
                        }
                      },
                      "else": {
                        "required": [
                          "type",
                          "port"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "type": {},
                          "port": {}
                        }
                      }
                    }
                  }
                }
              },
              "else": {
                "additionalProperties": false,
                "properties": {
                  "nodeid": {}
                }
              }
            },
            {
              "if": {
                "required": [
                  "option_will_fund"
                ]
              },
              "then": {
                "additionalProperties": true,
                "required": [
                  "option_will_fund"
                ],
                "properties": {
                  "option_will_fund": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "lease_fee_base_msat",
                      "lease_fee_basis",
                      "funding_weight",
                      "channel_fee_max_base_msat",
                      "channel_fee_max_proportional_thousandths",
                      "compact_lease"
                    ],
                    "properties": {
                      "lease_fee_base_msat": {
                        "type": "msat",
                        "description": [
                          "The fixed fee for a lease (whole number of satoshis)."
                        ]
                      },
                      "lease_fee_basis": {
                        "type": "u32",
                        "description": [
                          "The proportional fee in basis points (parts per 10,000) for a lease."
                        ]
                      },
                      "funding_weight": {
                        "type": "u32",
                        "description": [
                          "The onchain weight you'll have to pay for a lease."
                        ]
                      },
                      "channel_fee_max_base_msat": {
                        "type": "msat",
                        "description": [
                          "The maximum base routing fee this node will charge during the lease."
                        ]
                      },
                      "channel_fee_max_proportional_thousandths": {
                        "type": "u32",
                        "description": [
                          "The maximum proportional routing fee this node will charge during the lease (in thousandths, not millionths like channel_update)."
                        ]
                      },
                      "compact_lease": {
                        "type": "hex",
                        "description": [
                          "The lease as represented in the node_announcement."
                        ]
                      }
                    }
                  }
                }
              }
            }
          ]
        }
      }
    }
  },
  "errors": [
    "On failure, one of the following error codes may be returned:",
    "",
    "- -32602: Error in given parameters."
  ],
  "author": [
    "Vincenzo Palazzo <<vincenzo.palazzo@protonmail.com>> wrote the initial version of this man page,",
    "but many others did the hard work of actually implementing this rpc command."
  ],
  "see_also": [
    "lightning-listchannels(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:listnodes#1",
        "method": "listnodes",
        "params": {
          "id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d"
        }
      },
      "response": {
        "nodes": [
          {
            "nodeid": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
            "alias": "HOPPINGFIRE--190-g5fd2f9c-modded",
            "color": "035d2b",
            "last_timestamp": 1722303669,
            "features": "88a0802a8a59a1",
            "addresses": []
          }
        ]
      }
    },
    {
      "request": {
        "id": "example:listnodes#2",
        "method": "listnodes",
        "params": {}
      },
      "response": {
        "nodes": [
          {
            "nodeid": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
            "alias": "SILENTARTIST-190-g5fd2f9c-modded",
            "color": "022d22",
            "last_timestamp": 1722303662,
            "features": "88a0802a8a59a1",
            "addresses": []
          },
          {
            "nodeid": "0266e4598d1d3c415f572a8488830b60f7e744ed9235eb0b1ba93283b315c03518",
            "alias": "JUNIORBEAM-5-190-g5fd2f9c-modded",
            "color": "0266e4",
            "last_timestamp": 1722303662,
            "features": "88a0802a8a59a1",
            "addresses": []
          },
          {
            "nodeid": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
            "alias": "HOPPINGFIRE--190-g5fd2f9c-modded",
            "color": "035d2b",
            "last_timestamp": 1722303669,
            "features": "88a0802a8a59a1",
            "addresses": []
          },
          {
            "nodeid": "0382ce59ebf18be7d84677c2e35f23294b9992ceca95491fcf8a56c6cb2d9de199",
            "alias": "JUNIORFELONY-190-g5fd2f9c-modded",
            "color": "0382ce",
            "last_timestamp": 1722303669,
            "features": "88a0802a8a59a1",
            "addresses": []
          }
        ]
      }
    }
  ]
}