Skip to content

Instantly share code, notes, and snippets.

@rBurgett
Last active December 6, 2022 20:39
Show Gist options
  • Save rBurgett/22605a4880e6f6e1cda15e426d02b299 to your computer and use it in GitHub Desktop.
Save rBurgett/22605a4880e6f6e1cda15e426d02b299 to your computer and use it in GitHub Desktop.
Node Pilot JSON-RPC Documentation

Node Pilot JSON-RPC Server Overview

The Node Pilot JSON-RPC server provides API access to every single Node Pilot operation, from initial registration to creating, staking, and updating nodes.

The RPC server is available both via HTTP and via the command line using the Node Pilot CLI.

Accessing the JSON-RPC server via HTTP

The server can be accessed via port 34417 on the host machine at path /v1 e.g. http://localhost:34417/v1. It follows the JSON-RPC 2.0 Specification. All requests must be POST requests sent with a Content-Type of application/json. The payload must be in the following form:

{
  id: number
  jsonrpc: '2.0'
  method: string
  params?: Object
}

Accessing the JSON-RPC server via the CLI

All server methods are available via the cli with the api command. Any parameters should be entered as --param.[key] [value'. For example, if you need to pass an id as a parameter, you would use --param.id pokt-000. That will set the parameters {id: 'pokt-000'} in the JSON-RPC request.


Available Methods

All methods are namespaced with one of the following:

  • np - These methods have to do with Node Pilot as a whole
  • node - These methods have to do with individual nodes
  • pokt - These methods are specific to Pocket nodes

np_getVersion

Gets the Node Pilot version.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_getVersion"
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_getVersion"}' http://localhost:34417/v1

CLI Example:

./np api np_getVersion

np_register

Registers a new Node Pilot instance.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_configureTLS",
  "params": {
    "email": "my@emailaddress.com"
    "masterPassword": "mypassword"
    "domain": "subdomain.mydomain.com"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_register", "params": {"email": "my@emailaddress.com", "domain": "subdomain.mydomain.com", "masterPassword": "mypassword"}}' http://localhost:34417/v1

CLI Example:

./np api np_register --params.email "my@emailaddress.com" --params.masterPassword "mypassword" --params.domain "subdomain.mydomain.com"

np_configureTLS

Configures and generates TLS certs using Let's Encrypt.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_configureTLS",
  "params": {
    "masterPassword": "mypassword"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_configureTLS", "params": {"masterPassword": "mypassword"}}' http://localhost:34417/v1

CLI Example:

./np api np_configureTLS --params.masterPassword "mypassword"

np_shutdown

Shuts down Node Pilot while leaving all nodes and load balancers running.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_shutdown"
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_shutdown"}' http://localhost:34417/v1

CLI Example:

./np api np_shutdown

np_shutdownAll

Shuts down all of Node Pilot including all nodes and load balancers.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_shutdownAll"
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_shutdownAll"}' http://localhost:34417/v1

CLI Example:

./np api np_shutdownAll

np_getLoadBalancers

Gets all running load balancers available to be used as relay chains in Pocket nodes.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "np_getLoadBalancers"
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "np_getLoadBalancers"}' http://localhost:34417/v1

CLI Example:

./np api np_getLoadBalancers

node_getAll

Gets information on all nodes. (matches the contents of ~/.node-pilot/config/chains.json)

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getAll"
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_getAll"}' http://localhost:34417/v1

CLI Example:

./np api node_getAll

node_get

Gets an individual node's information.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_get",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_get", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_get --params.id "pokt-000"

node_getBlockHeight

Gets a node's current block height.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getBlockHeight",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_getBlockHeight", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_getBlockHeight --params.id "pokt-000"

node_getStatus

Gets a node's current status.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getStatus",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_getStatus", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_getStatus --params.id "pokt-000"

node_start

Starts a stopped node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_start",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_start", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_start --params.id "pokt-000"

node_stop

Stops a running node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_stop",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_stop", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_stop --params.id "pokt-000"

node_restart

Restarts a running or stopped node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_restart",
  "params": {
    "id": "pokt-000"
  }
}

curl Example:

curl -X POST -H 'Content-Type: application/json' --data '{"jsonrpc": "2.0", "id": 1, "method": "node_restart", "params": {"id": "pokt-000"}}' http://localhost:34417/v1

CLI Example:

./np api node_restart --params.id "pokt-000"

node_getValidatorInfo

Gets the validator info of a validator node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getValidatorInfo",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api node_getValidatorInfo --params.id "pokt-000"

node_getContainerInfo

Gets the Docker container info of a node. (equivalent of docker container inspect)

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getContainerInfo",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api node_getContainerInfo --params.id "pokt-000"

node_getContainerStats

Gets the Docker container's hardware stats. (equivalent of docker container stats)

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getContainerStats",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api node_getContainerStats --params.id "pokt-000"

node_getBalance

Gets a node's balance. (this only applies to validator nodes)

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getBalance",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api node_getBalance --params.id "pokt-000"

node_send

Sends coin to another wallet. (this method is only available to validator nodes)

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getBalance",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword",
    "amount": "4.5",
    "to": "156924a37c36e9e6b75e0a34027747032fe22cd2",
    "memo": "some memo"
  }
}

CLI Example:

./np api node_send --params.id "pokt-000" --params.masterPassword "mypassword" --params.amount "4.5" --params.to "156924a37c36e9e6b75e0a34027747032fe22cd2" --params.memo "some memo"

node_getAvailableUpgrades

Gets info on any node upgrades available.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getAvailableUpgrades"
}

CLI Example:

./np api node_getAvailableUpgrades

node_upgrade

Upgrades a node to the latest available version.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_upgrade",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_upgrade --params.id "pokt-000" --params.masterPassword "mypassword"

node_stakeValidator

Stakes a validator node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_stakeValidator",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword",
    "stakeAmount": "15100"
  }
}

CLI Example:

./np api node_stakeValidator --params.id "pokt-000" --params.masterPassword "mypassword" --params.stakeAmount "15100"

node_restakeValidator

Restakes an already-staked validator node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_restakeValidator",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_restakeValidator --params.id "pokt-000" --params.masterPassword "mypassword"

node_unjailValidator

Unjails a validator node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_unjailValidator",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_unjailValidator --params.id "pokt-000" --params.masterPassword "mypassword"

node_unstakeValidator

Unstakes a validator node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_unstakeValidator",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_unstakeValidator --params.id "pokt-000" --params.masterPassword "mypassword"

node_create

Creates a new node. Available properties for creation:

  • masterPassword: string
  • ticker: string "pokt", "eth", "fuse", etc.
  • network?: string "MAINNET"|"TESTNET"|"RINKEBY"
  • peerPort?: number
  • rpcPort?: number
  • dockerCPUs?: number
  • dockerMem?: number
  • password?: string Key password required for validator nodes
  • chainsDir?: string Directory which the node's data directory will be placed into.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_create",
  "params": {
    "masterPassword": "mypassword",
    "ticker": "pokt",
    "network": "MAINNET",
    "password": "mynodepassword"
  }
}

CLI Example:

./np api node_create --params.masterPassword "mypassword" --params.ticker "pokt" --params.network "MAINNET" --params.password "mynodepassword"

node_delete

Deletes a node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_delete",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_delete --params.id "pokt-000" --params.masterPassword "mypassword"

node_clearDataDir

Clears a node's chain data directory.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_clearDataDir",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_clearDataDir --params.id "pokt-000" --params.masterPassword "mypassword"

node_getRawPrivateKey

Gets a validator node's raw private key.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getRawPrivateKey",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_getRawPrivateKey --params.id "pokt-000" --params.masterPassword "mypassword"

node_getKeyPassword

Gets a validator node's key password.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "node_getKeyPassword",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword"
  }
}

CLI Example:

./np api node_getKeyPassword --params.id "pokt-000" --params.masterPassword "mypassword"

pokt_getPrometheusData

Gets a Pocket node's prometheus data.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pokt_getPrometheusData",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api pokt_getPrometheusData --params.id "pokt-000"

pokt_getRelayChains

Gets a Pocket node's relay chains.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pokt_getRelayChains",
  "params": {
    "id": "pokt-000"
  }
}

CLI Example:

./np api pokt_getRelayChains --params.id "pokt-000"

pokt_setRelayChains

Sets a Pocket node's relay chains.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pokt_setRelayChains",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword",
    "chains": [
      {
        "id": "0002",
        "url": "http://localhost:8081",
        "basic_auth": {
          "username": "",
          "password": ""
        }
      },
      {
        "id": "0021",
        "url": "http://eth-mainnet",
        "basic_auth": {
          "username": "",
          "password": ""
        }
      }
    ]
  }
}

CLI Example:

not available via CLI

pokt_addRelayChain

Adds a relay chain to a Pocket node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pokt_addRelayChain",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword",
    "chainId": "0025",
    "chainUrl": "http://eth-rinkeby"
  }
}

CLI Example:

./np api pokt_addRelayChain --params.id "pokt-000" --params.masterPassword "mypassword" --params.chainId "0025" --params.chainUrl "http://eth-rinkeby"

pokt_removeRelayChain

Removes a relay chain from a Pocket node.

Request Body Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "pokt_removeRelayChain",
  "params": {
    "id": "pokt-000",
    "masterPassword": "mypassword",
    "chainId": "0025"
  }
}

CLI Example:

./np api pokt_removeRelayChain --params.id "pokt-000" --params.masterPassword "mypassword" --params.chainId "0025"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment