Skip to content

JSON-RPC

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

For more details, see the JSON-RPC 2.0 Specification.

Server

By default, a JSON-RPC server is started at 127.0.0.1:21338. It can be disabled in the configuration file.

Protocol

A message must be a valid utf8 string finished with a newline (\n).

The parser will start processing the request when it finds the first newline.

Therefore, the JSON string cannot contain any newlines expect for the final one.

NewLineCodec

Subscriptions

The Witnet node provides a pub/sub API, see here for more info.

Methods

See json_rpc_methods.rs for the implementation details.

inventory

Make the node process, validate and potentially broadcast a new inventory item.

@params: InventoryItem

/// Inventory element: block, transaction, etc
#[derive(Debug, Eq, PartialEq, Clone, Serialize, Deserialize)]
pub enum InventoryItem {
    /// Error
    #[serde(rename = "error")]
    Error,
    /// Transaction
    #[serde(rename = "transaction")]
    Transaction(Transaction),
    /// Block
    #[serde(rename = "block")]
    Block(Block),
}

@returns: boolean indicating success, or parse error

Example:

{"jsonrpc": "2.0", "method": "inventory", "params": {"block":{"block_header":{"version":1,"beacon":{"checkpoint":2,"hash_prev_block":{"SHA256":[4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4,4]}},"hash_merkle_root":{"SHA256":[3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3]}},"proof":{"block_sig":null,"influence":99999},"txns":[null]}}, "id": 1}

Response:

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

getBlockChain

Get the list of all the known block hashes.

Returns a list of (epoch, block_hash) pairs.

These parameters can be used to limit to some epoch range. There are two optional parameters: epoch and limit. For example, to get the blocks for epochs 100-104, use "epoch" 100 and "limit": 5:

"params": {
    "epoch": 100,
    "limit": 5,
}

If a negative epoch is supplied, it is interpreted as "the last N epochs". For instance, to get the block for the last epoch:

"params": {
    "epoch": -1,
}

Example:

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

Response:

{"jsonrpc":"2.0","result":[[0,"ed28899af8c3148a4162736af942bc68c4466da93c5124dabfaa7c582af49e30"],[1,"9c9038cfb31a7050796920f91b17f4a68c7e9a795ee8962916b35d39fc1efefc"]],"id":1}

getBlock

Get the block with the provided hash.

Returns a Block.

Example:

{"jsonrpc":"2.0","id":1,"method":"getBlock","params":["c0002c6b25615c0f71069f159dffddf8a0b3e529efb054402f0649e969715bdb"]}

Response:

{"jsonrpc":"2.0","result":{"block_header":{"beacon":{"checkpoint":279256,"hash_prev_block":{"SHA256":[255,198,135,145,253,40,66,175,226,220,119,243,233,210,25,119,171,217,215,188,185,190,93,116,164,234,217,67,30,102,205,46]}},"hash_merkle_root":{"SHA256":[213,120,146,54,165,218,119,82,142,198,232,156,45,174,34,203,107,87,171,204,108,233,223,198,186,218,93,102,190,186,216,27]},"version":0},"proof":{"block_sig":{"Secp256k1":{"r":[112,102,21,231,95,88,196,37,189,190,121,79,13,61,106,45,53,191,114,223,172,133,64,85,96,96,61,17,125,86,4,149],"s":[112,102,21,231,95,88,196,37,189,190,121,79,13,61,106,45,53,191,114,223,172,133,64,85,96,96,61,17,125,86,4,149],"v":0}},"influence":0},"txns":[{"inputs":[],"outputs":[{"ValueTransfer":{"pkh":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"value":50000000000}}],"signatures":[],"version":0}]},"id":1}

getOutput

Get the outputPointer that matches with the input provided.

Returns an OutputPointer.

Example:

{"jsonrpc": "2.0","method": "getOutput", "params": {"transaction_id":{"SHA256":[17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17,17]},"output_index":1}, "id": "1"}

Response:

{"jsonrpc":"2.0","result":{"DataRequest":{"backup_witnesses":0,"commit_fee":0,"data_request":{"aggregate":{"script":[0]},"consensus":{"script":[0]},"deliver":[{"kind":"HTTP-GET","url":"https://hooks.zapier.com/hooks/catch/3860543/l2awcd/"}],"not_before":0,"retrieve":[{"kind":"HTTP-GET","script":[0],"url":"https://openweathermap.org/data/2.5/weather?id=2950159&appid=b6907d289e10d714a6e88b30761fae22"}]},"pkh":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],"reveal_fee":0,"tally_fee":0,"time_lock":0,"value":0,"witnesses":0}},"id":"1"}