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

{
  "$schema": "../rpc-schema-draft.json",
  "type": "object",
  "rpc": "connect",
  "title": "Command for connecting to another lightning node",
  "description": [
    "The **connect** RPC command establishes a new connection with another node in the Lightning Network.",
    "",
    "Connecting to a node is just the first step in opening a channel with another node. Once the peer is connected a channel can be opened with lightning-fundchannel(7).",
    "",
    "If there are active channels with the peer, **connect** returns once all the subdaemons are in place to handle the channels, not just once it's connected."
  ],
  "request": {
    "required": [
      "id"
    ],
    "additionalProperties": false,
    "properties": {
      "id": {
        "type": "string",
        "description": [
          "The target node's public key. As a convenience, *id* may be of the form *id@host* or *id@host:port*. In this case, the *host* and *port* parameters must be omitted. This can fail if your C-lightning node is a fresh install that has not connected to any peers yet (your node has no gossip yet), or if the target *id* is a fresh install that has no channels yet (nobody will gossip about a node until it has one published channel)."
        ]
      },
      "host": {
        "type": "string",
        "description": [
          "The peer's hostname or IP address. If *host* is not specified (or doesn't work), the connection will be attempted to an IP belonging to *id* obtained through gossip with other already connected peers. If *host* begins with a `/` it is interpreted as a local path and the connection will be made to that local socket (see **bind-addr** in lightningd-config(5))."
        ]
      },
      "port": {
        "type": "u16",
        "description": [
          "The peer's port number. If not specified, the *port* depends on the current network:",
          "    * bitcoin **mainnet**: 9735.",
          "    * bitcoin **testnet**: 19735.",
          "    * bitcoin **signet**: 39735.",
          "    * bitcoin **regtest**: 19846."
        ]
      }
    }
  },
  "response": {
    "required": [
      "id",
      "features",
      "direction",
      "address"
    ],
    "additionalProperties": false,
    "properties": {
      "id": {
        "type": "pubkey",
        "description": [
          "The peer we connected to."
        ]
      },
      "features": {
        "type": "hex",
        "description": [
          "BOLT 9 features bitmap offered by peer."
        ]
      },
      "direction": {
        "type": "string",
        "enum": [
          "in",
          "out"
        ],
        "description": [
          "Whether they initiated connection or we did."
        ]
      },
      "address": {
        "type": "object",
        "description": [
          "Address information (mainly useful if **direction** is *out*)."
        ],
        "additionalProperties": true,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "local socket",
              "ipv4",
              "ipv6",
              "torv2",
              "torv3"
            ],
            "description": [
              "Type of connection (*torv2*/*torv3* only if **direction** is *out*)."
            ]
          }
        },
        "allOf": [
          {
            "if": {
              "additionalProperties": true,
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "local socket"
                  ]
                }
              }
            },
            "then": {
              "additionalProperties": false,
              "required": [
                "socket"
              ],
              "properties": {
                "type": {},
                "socket": {
                  "type": "string",
                  "description": [
                    "Socket filename."
                  ]
                }
              }
            }
          },
          {
            "if": {
              "additionalProperties": true,
              "properties": {
                "type": {
                  "type": "string",
                  "enum": [
                    "ipv4",
                    "ipv6",
                    "torv2",
                    "torv3"
                  ]
                }
              }
            },
            "then": {
              "additionalProperties": false,
              "required": [
                "address",
                "port"
              ],
              "properties": {
                "type": {},
                "address": {
                  "type": "string",
                  "description": [
                    "Address in expected format for **type**."
                  ]
                },
                "port": {
                  "type": "u16",
                  "description": [
                    "Port number."
                  ]
                }
              }
            }
          }
        ]
      }
    }
  },
  "errors": [
    "On failure, one of the following errors will be returned:",
    "",
    "- 400: Unable to connect, no address known for peer",
    "- 401: If some addresses are known but connecting to all of them failed, the message will contain details about the failures",
    "- 402: If the peer disconnected while we were connecting",
    "- -32602: If the given parameters are wrong"
  ],
  "author": [
    "Rusty Russell <<rusty@rustcorp.com.au>> is mainly responsible. Felix <<fixone@gmail.com>> is the original author of this manpage."
  ],
  "see_also": [
    "lightning-fundchannel(7)",
    "lightning-listpeers(7)",
    "lightning-listchannels(7)",
    "lightning-disconnect(7)"
  ],
  "resources": [
    "Main web site: <https://github.com/ElementsProject/lightning>"
  ],
  "examples": [
    {
      "request": {
        "id": "example:connect#1",
        "method": "connect",
        "params": {
          "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
          "host": "localhost",
          "port": 41219
        }
      },
      "response": {
        "id": "022d223620a359a47ff7f7ac447c85c46c923da53389221a0054c11c1e3ca31d59",
        "features": "08a0802a8a59a1",
        "direction": "out",
        "address": {
          "type": "ipv4",
          "address": "127.0.0.1",
          "port": 41219
        }
      }
    },
    {
      "request": {
        "id": "example:connect#2",
        "method": "connect",
        "params": {
          "id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
          "host": "localhost",
          "port": 34785
        }
      },
      "response": {
        "id": "035d2b1192dfba134e10e540875d366ebc8bc353d5aa766b80c090b39c3a5d885d",
        "features": "08a0802a8a59a1",
        "direction": "out",
        "address": {
          "type": "ipv4",
          "address": "127.0.0.1",
          "port": 34785
        }
      }
    }
  ]
}