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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_version", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_status", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_start", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "node_stop", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_status", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_start", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_stop", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_invoke", "params": ["0xf0cd9d2e1f93028f89e9ff92a2b"], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_invoke_rbl", "params": ["(+ 1 2)"], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_metrics_start", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "vm_metrics_stop", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_status", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_start", "params": [], "id": 123}' |
Code Block |
---|
|
{
"jsonrpc": "2.0",
"id": 123,
"result": true
} |
comm_stop
Parameters
None
Returns
Boolean — true
if comms succesfully stopped, false
otherwise
Example
Code Block |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_stop", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_peers", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_network", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_metrics_start", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "comm_metrics_stop", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_status", "params": [], "id": 123}' |
Code Block |
---|
|
{
"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 |
---|
|
curl -X POST --data '{"jsonrpc": "2.0", "method": "storage_get", "params": { "key": "foo"}, "id": 123}' |
Code Block |
---|
|
{
"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...