JSON Command and Control API

The following API functions give access to a running nodes via a few commands. Both the node itself as well as some of its constituent parts may be controlled or queried. this is currently modeled after the relatively successful web3 interface of Ethereum. Although there are a few similarities to that API, this list does not yet cover interacting with contracts or wallets or the blockchain itself.

JSON-RPC

We augment the built-in JSON types in JSON-RPC with a HexString type. This is a String with only hex digits in it, a textual representation of an array of bytes.

The JSON-RPC specification (q.v.) requires several parameters be present in every call. These are

jsonrpc: String, required — must be "2.0"
method: String, required — the name of the API method being called
params: Object, required — key-value pairs representing input (actual) parameters to the method
id: String|Number|NULL, optional — a reference number for the request; used to correlate responses and requests

Note that if id is NULL, then no response data will be returned.

Similarly, the response object is also required to contain jsonrpc and id. It may contain either a result field, an value representing the result of the method call, or an error field, in the case of an error. Result structures are described with the accompanying methods below. An error field contains an Object with the following members according to the JSON-RPC specification:

code: Number, required — an integer indicating the type of error
message: String, required –- a friendly description of the error
data: Anything, optional — values that give detailed information about the error, form specified by the server

There are some canonical error codes with their messages listed in the specification.

Finally, JSON-RPC calls may be batched by simply gathering several requests into an Array. Results come back in a matching Array of responses. See the specification for details.

Table of Contents

maxLevel	3

Page Properties

hidden	true

Author	Chris Kirkwood-Watts
Updated	25 Jan 2018

The API functions are here split into several groups, roughly corresponding to the components of an RChain node.

Node

General node-related functions.

node_version

Returns the current version of the node software as well as the current version of the JSON-RPC subsystem.

Parameters

None.

Returns

Object

node_version: String — Node version
api_version: String — JSON-RPC API version

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "node_version", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "node_version": "0.1-RC3",
    "api_version": "1.2"
  }
}

node_status

Request high-level information about this node's current state.

Parameters

None.

Returns

Object

status: String –- One of "running" or "stopped"
timestamp: String — Timestamp in UTC that node was started or stopped

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "node_status", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "status": "running",
    "timestamp": "2018-01-24T01:49:41"
  }
}

node_start

Request that the node start (or restart) participating in the RChain network. This call has no effect (and returns true) if the node is already running.

Parameters

None.

Returns

Boolean — true if node was successfully started, false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "node_start", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

node_stop

Request that the node stop participating in the RChain network but remain available for restarting. This call has no effect (and returns true) if the node is already stopped.

Parameters

None

Returns

Boolean — true if node was successfully stopped, false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "node_stop", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

Virtual Machine

vm_status

Returns some high-level information about a virtual machine.

Parameters

None

Returns

Object

status: String — one of "running" or "stopped"
timestamp: String — timestamp in UTC that vm was started or stopped
strand_count: Number — number of strands in that vm
object_count: Number — number of roscala objects in in that vm
bytecode_count: Number — number of bytecodes executed since start
mem_size: Number — size of current state in bytes

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_status", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "status": "running",
    "timestamp": "2018-01-24T01:49:41",
    "strand_count": 312,
    "object_count": 1234,
    "bytecode_count": 12345,
    "mem_size": 392489
  }
}

vm_start

Starts a stopped virtual machine.

Parameters

foo

Returns

Boolean — true if this vm was successfully start (or was not stopped), false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_start", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

vm_stop

Parameters

None

Returns

Boolean — true if this vm was successfully stopped (or was already stopped), false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_stop", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

vm_invoke

Invoke a serialized continuation and return the result.

Parameters

HexString — bytes of the serialized continuation

Returns

Object — varies depending on the result

Example

Completely fabricated example continuation whose invocation produces the tuple ["Hello, world!", 3] (a String and a Number).

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_invoke", "params": ["0xf0cd9d2e1f93028f89e9ff92a2b"], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": [
    "Hello, world!",
    3
  ]
}

vm_invoke_rbl

Invoke RBL and return the result.

Parameters

String — RBL code

Returns

Object — varies depending on the result

Example

Invoke "(+ 1 2)" whose invocation produces 3 (a Number).

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_invoke_rbl", "params": ["(+ 1 2)"], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": 3
}

vm_metrics_start

Parameters

None

Returns

Boolean — true if metrics were started succesfully, false othewise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_metrics_start", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

vm_metrics_stop

Parameters

None

Returns

Boolean — true if metrics were stopped succesfully, false othewise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_metrics_stop", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

Communications

comm_status

Parameters

None

Returns

Object

status: String — One of "running" or "stopped"
send_count: Number — Number of messages sent
recv_count: Number — Number of messages received
peer_count: Number — Number of peers currently "connected"
metrics: Boolean — true if metrics are currently being emitted, false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_status", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "status": "running",
    "send_count": 23452,
    "recv_count": 99328,
    "peer_count": 131,
    "metrics": false
  }
}

comm_start

Parameters

None

Returns

Boolean — true if comms succesfully started, false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_start", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

comm_stop

Parameters

None

Returns

Boolean — true if comms succesfully stopped, false otherwise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_stop", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

comm_peers

Request a full list of connected peers

Parameters

None

Returns

Object Array of

address: String — string representation of peer's rnode address
ip: String — peer's observed internet address as a dotted quad
port: Number — peer's UDP port
last_seen: String — Timestamp in UTC of last contact from peer

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_peers", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": [
    {
      "address": "0f365f1016a54747b384b386b8e85352",
      "ip": "216.83.154.106",
      "port": 30012,
      "last_seen": "2018-01-24T06:04:59"
    },
    {
      "address": "384b386b8e853520f365f1016a54747b",
      "ip": "83.143.12.23",
      "port": 30305,
      "last_seen": "2018-01-24T06:04:58"
    },
    ...
  ]
}

comm_network

This is an extremely heavyweight call which queries peers for their peers, and peers of peers for their peers, and so on, until it has mapped the whole network. Not sure it's feasible, yet.

Parameters

None

Returns

Object Array of

address: String — string representation of peer's rnode address
ip: String — peer's observed internet address as a dotted quad
connections: Number Array — representing indexes into outer array of peers to which this peer is connected

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_network", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": [
    {
      "address": "0f365f1016a54747b384b386b8e85352",
      "ip": "216.83.154.106",
      "connections": [1,2,5,9,...]
    },
    {
      "address": "384b386b8e853520f365f1016a54747b",
      "ip": "83.143.12.23",
      "connections": [1,3,4,15,10...]
    },
    ...
  ]
}

comm_metrics_start

Parameters

None

Returns

Boolean — true if metrics were started succesfully, false othewise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_metrics_start", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

comm_metrics_stop

Parameters

None

Returns

Boolean — true if metrics were stopped succesfully, false othewise

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_metrics_stop", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": true
}

Storage

storage_status

Parameters

None

Returns

Object

key_count: Number — total number of keys present
value_count: Number — total number of values present
size: Number — total size (in bytes) of storage
. . . various other bits of information . . .

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_status", "params": [], "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "key_count": 392103,
    "value_count": 451887,
    "size": 9328348,
    ...
  }
}

storage_get

Get the data stored at key.

Parameters

Object

key: String — key to fetch

Returns

Object

value: HexString — hex string representing bytes of the value

Example

Code Block

language	bash
title	Request

curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_get", "params": { "key": "foo"}, "id": 123}'

Code Block

language	js
title	Response

{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "value": "0x2098ab9e9"
  }
}

Page Comparison

Versions Compared

Old Version 13

New Version Current

Key

JSON Command and Control API

JSON-RPC

Node

node_version

Parameters

Returns

Example

node_status

Parameters

Returns

Example

node_start

Parameters

Returns

Example

node_stop

Parameters

Returns

Example

Virtual Machine

vm_status

Parameters

Returns

Example

vm_start

Parameters

Returns

Example

vm_stop

Parameters

Returns

Example

vm_invoke

Parameters

Returns

Example

vm_invoke_rbl

Parameters

Returns

Example

vm_metrics_start

Parameters

Returns

Example

vm_metrics_stop

Parameters

Returns

Example

Communications

comm_status

Parameters

Returns

Example

comm_start

Parameters

Returns

Example

comm_stop

Parameters

Returns

Example

comm_peers

Parameters

Returns

Example

comm_network

Parameters

Returns

Example

comm_metrics_start

Parameters

Returns

Example

comm_metrics_stop

Parameters