JSON API (RPC and Websocket)

Owned by Chris Kirkwood-Watts
Last updated: Mar 22, 2018 by Medha Parlikar (Unlicensed)


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.


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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_version", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_status", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_start", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_stop", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_status", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_start", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_stop", "params": [], "id": 123}'
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).

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_invoke", "params": ["0xf0cd9d2e1f93028f89e9ff92a2b"], "id": 123}'
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).

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

vm_metrics_start

Parameters

None

Returns

Boolean — true if metrics were started succesfully, false othewise

Example

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

vm_metrics_stop

Parameters

None

Returns

Boolean — true if metrics were stopped succesfully, false othewise

Example

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_metrics_stop", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_status", "params": [], "id": 123}'
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

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

comm_stop

Parameters

None

Returns

Boolean — true if comms succesfully stopped, false otherwise

Example

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_stop", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_peers", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_network", "params": [], "id": 123}'
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

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

comm_metrics_stop

Parameters

None

Returns

Boolean — true if metrics were stopped succesfully, false othewise

Example

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_metrics_stop", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_status", "params": [], "id": 123}'
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

Request
curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_get", "params": { "key": "foo"}, "id": 123}'
Response
{
  "jsonrpc": "2.0",
  "id": 123,
  "result": {
    "value": "0x2098ab9e9"
  }
}

storage_put

Parameters

foo

Returns

bar

Example

baz

storage_metrics_start

Parameters

foo

Returns

bar

Example

baz

storage_metrics_stop

Parameters

foo

Returns

bar

Example

baz


Websocket Facilities

Logging

VM logging...

Comms logging...

Storage logging...