EdgeV2 RPC
The Edge V2 protocol uses Ethereums Recursive Length Prefix encoding (RLP) over secure TLS1.3 channels. Each message in the protocol prefixed with two bytes, a 16-bit length field of the RLP payload. Number encodings is always big-endian. Requests in the protocol look like this:
For each request the corresponding response will have the same <Request ID>
value and its first value will be the string "response"
:
For example, if we want to get block header of block nr 100, the RPC command could be [1, ["getblockheader", 100]]
encoded into RLP. The RLP byte sequence will be of 19 bytes length. And thus the message is prefixed with the two byte (16-bit) encoding of 19 <<0, 19>>
.
Here a transcript of encoding the sample message on an Elixir console:
iex(0)> payload = [1, ["getblockheader", 100]][1, ["getblockheader", 100]]
iex(1)> rlp = Rlp.encode!(payload)<<210, 1, 208, 142, 103, 101, 116, 98, 108, 111, 99, 107, 104, 101, 97, 100,
101, 114, 100>>
iex(2)> size = byte_size(rlp)19
iex(3)> message = <<size :: unsigned-size(16), rlp::binary>><<0, 19, 210, 1, 208, 142, 103, 101, 116, 98, 108, 111, 99, 107, 104, 101, 97,
100, 101, 114, 100>>
Client Implementation
The reference implementation used in the prenet is the open source Diode GO Client.
Data types
Integer
Integers are big-endian encoded.
Binary
Binaries are stored natively in RLP.
Data Objects
All data objects follow the general structure:
Where signature is a signature on the Bert encoded list [, , ...,]
Location object
RPC: ["location", <s>, <peak_block>, <device_signature>, <server_signature>]
- server_id: binary - server address
- peak_block: binary - block hash
- device_signature: binary - Bert encoded list:
[<server_id>, <peak_block>]
- server_signature: binary - Bert encoded list:
[<server_id>, <peak_block>, <device_signature>]
Server Object v1
RPC: ["server", <host>, <edge_port>, <server_port>, <signature>]
- host: binary - name or ip address of the host
- edge_port: integer - port for IoT devices to connect
- server_port: integer - port for other cloud software to connect
- signature: binary - Signature of the bert encoded list:
[<host>, <edge_port>, <server_port>]
Server Object v2
RPC: ["server", <host>, <edge_port>, <server_port>, <version>, <extra>, <signature>]
- host: binary - name or ip address of the host
- edge_port: integer - port for IoT devices to connect
- server_port: integer - port for other cloud software to connect
- version: binary - string represnting a server version identification
- extra: list -
[[<key>, <value>]]
key value list with key being a binary string and value being an integer - signature: binary - Signature of the bert encoded list:
[<host>, <edge_port>, <server_port>, <version>, <extra>]
Edge RPC API Reference
getblockpeak()
Returns the current block number.
RPC call: ["getblockpeak"]
Parameters:
- none
Response:
["response", blockNumber]
- blockNumber: integer - the highest valid block number
Example:
<< ["getblockpeak"]
>> ["response", 100]
getblockheader(int)
Returns block header information about a block by block index (block number).
RPC call: ["getblockheader", index]
Parameters:
- index: integer - block number
Response
["response", block_header]
block_header:
- previous_block: binary - previous block hash
- miner: binary - miner publickey
- miner_signature: binary - miner signature of this block
- block_hash: binary - block hash
- state_hash: binary - state hash
- transaction_hash: binary - transaction hash
- timestamp: integer - timestamp
Example:
<< ["getblockheader", 189462]
>> ["response", [
["transaction_hash", 0x4309bcba566dde47811c47fa17eda8251761909a39934d3ae48cb5fb2f90cb14]
["timestamp", 0x5d5392b4,
["state_hash", 0xc579e39541eb2907677384b995017c28fe3dc105ae0c3bf8476bb4bbccad7def,
["previous_block", 0x00005e0fbc09d917905c47a41fddfd695278b823eddf2490cf4abe8f87be2071,["miner_signature", 0x00764f10ff4365db2165a8cf4aa9dce8be67fb1f2cff43ae51cf288e6311eb9f0d3ec9a75406f9060805ed36b17720736f278300fe84fcfb9cebda78676df4d477],
["miner", ""],
["block_hash", 0x00003335f640c174ac2a04e0b8537e1adc3a9e035f5f8f4bbc6937578289c43e],]]
getblock(int)
Returns block information about a block by block index (block number).
RPC call: ["getblock", index]
Parameters
- index: integer - block number
Response:
["response", block]
block:
- transactions: array of transaction
- receipts: array of transaction receipt
- header: block_header (see above)
Example:
<< ["getblock", 189462]
>> ["response", [
["transactions", []],
["receipts", []],
["header": [
["transaction_hash", 0x4309bcba566dde47811c47fa17eda8251761909a39934d3ae48cb5fb2f90cb14],
["timestamp", 0x5d53c51d],
["state_hash", 0xc579e39541eb2907677384b995017c28fe3dc105ae0c3bf8476bb4bbccad7def],
["previous_block", 0x00004f6ca36a5d67135707b32355665976f9bdb0b57b2a8962c616f949d39363],
["miner_signature", 0x01e2c1afc76ea799feaf8fa3daa5317cbe9d578f27417d893358d61e64f9ec62720362894a48508fcf9a4ed9a999dadeed4ef4254e8b8fde604902436cf0c05cb0,
["miner", ""]
["block_hash", 0x00002ac3dc9997f624fa9b8c90e4375ca2be4ad8a558bc393ca9127a0915a8bd]]]]
getstateroots(int)
Returns the 16 sub-merkle roots of the state (accounts) storage. The hash of all roots together should return then block_header.state_root hash value.
RPC call, ["getstateroots", index]
Parameters:
- index: integer - block index
Response:
["response", state_roots]
state_roots:
- 16 x binary - 16 state hashes
Example
<< ["getstateroots", 189462]
>> ["response", [
0xc5d026438f345b413fb7a9afe09a909fffe12adbc15d755e65872be43be5d27e,
0xad4dc2937cba7f0380017522bf87af148eaa19787bef6a7640c64d55939f79b6,
0x75fef175fe530fdcebfda15a85d5b5d7680758963fb986151155868c3c126845,
0x26d8a38694a7725ef001a8f5acd292b3edbf8346a3710d44cbf4c5e56928174b,
0x6ecacecd9f80d20087077225eb0cf313584d24eb72c5e72e09e44364638db45a,
0x86dfae6acc66a2de136c47e6f3e93c5d1c8ca696f5e129c472a4394bfafb65e9,
0x7f8b60aa695ba2cae9e4e421493c4ed610fd2cf56d9f173706f7439e86742147,
0xff1a24e061a3a4d5ea9b78bd9a22aa96288d92bf9838e798c08041cb5962127c,
0x34568925599c25225f36571daaecf73c9975d4489e95741b3ed66d0ca1e8913d,
0xd31405fbc0dd7f202d89aa5886f9a84cea7ee64ccf93675740766d88b5cea34d,
0xf467cf2207b25529e4e99c6d86bf1278e0a239c5a9262bae40b829d62fbe951b,
0xbd095f49b588be346c93ff7204eed0a2591347e09b8be2e4c70152ce57ab82b9,
0xe73817f797acfba37691287d15915064991b7d92daf198affc0ba1338e4476b7,
0xb141df7a1857cf056d61732524e868eddc6995dd6d4e60d8dcad13b23020c56c,
0x5009d2b4e4e2833df471f7d636b5ecee9345ce8212a09fcb81a25289cc2eae5b,
0xec1e267dd2579ada733e8732ff164e88b20a36d82c181b2551c28279783d37ef]]
getaccount(block_index, account)
Return account and the merkle proof of account in the given index.
RPC call: ["getaccount", index, account]
Parameters:
- index: integer - block index
- account: hex string- the account id
Response:
["response", account, proof]
account:
- nonce: integer - the current account nonce, starting at 1
- balance: integer - the balance of the account
- storageRoot: binary - the merkle root of the account storage
- code: binary - the hash of the account code
proof:
<proof>
:=[<prefix>, <modulo>, <values>] | {<proof>, <proof>} | <hash>
<hash>
:= binary<prefix>
:= binary[0-32] - the prefix of the HASH(account)<modulo>
:= integer 0-15 - modulo 16 of the last byte of HASH(account)<values>
:=[ account, <accountHash>, …]
<accountHash>
:= HASH(RLP([nonce, balance, storageRoot, code]
))
Example:
<< ["getaccount", 189462, 0xdeea0d008e4d966191fc1fd6c67272956208cf9f]
>> ["response", [
["storageRoot", 0x438a90405daa876539082cd0baf6cddaa3bf880f1c8af0c0381f0042db93088a],
["nonce", 2],
["code", 0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855],
["balance", 0x0de04867d0e8d000]], [
"",
[0x0c],[
0x3aea1b343ab62ee8b5251e71f68aaee0a951cb03,
0xda43b2f3f9e9ef399546d08cb0fd6b8943d71a9d73e9b530ab533aec0b2be69b
],[
0xdeea0d008e4d966191fc1fd6c67272956208cf9f,
0x8812c6fbc7e39c8efe0a7e9957fb651f9b37d0cc5bc1b58a86c9633d854d5ae3
]]]
getaccountroots(block_nr, account)
Returns the 16 sub-merkle roots of the specified account storage. The hash of all roots together should return the account.storageRoot hash value.
RPC call: ["getaccountroots", index, account]
Parameters:
- index: integer - block index
- account: binary - account address
Response:
["response", account_roots]
account_roots:
- 16 x binary - 16 account hash
Example:
<< ["getaccountroots", 189462, 0xdeea0d008e4d966191fc1fd6c67272956208cf9f]
>> ["response", [
0xc5d026438f345b413fb7a9afe09a909fffe12adbc15d755e65872be43be5d27e,
0xad4dc2937cba7f0380017522bf87af148eaa19787bef6a7640c64d55939f79b6,
0x9af297d4b76e52fef84c9e148f60861c47bf545a2c2aee37e8cab6f470818f2c,
0x26d8a38694a7725ef001a8f5acd292b3edbf8346a3710d44cbf4c5e56928174b,
0x6ecacecd9f80d20087077225eb0cf313584d24eb72c5e72e09e44364638db45a,
0xef56405dbbf82ede8346049094f3b4478339e6bc2ee3cd61b0bcee9104b6c6e0,
0x6a041c23a8111b58863fb5ce6df220d99d2a849f5236442791f8d74603eb49d5,
0xff1a24e061a3a4d5ea9b78bd9a22aa96288d92bf9838e798c08041cb5962127c,
0x6e62238f4dd5fa16e25f9a52e02aaf538f7238371eeea3de67b6d9d05454cdb2,
0xd31405fbc0dd7f202d89aa5886f9a84cea7ee64ccf93675740766d88b5cea34d,
0xf467cf2207b25529e4e99c6d86bf1278e0a239c5a9262bae40b829d62fbe951b,
0x0105d4c20f91bb426cf43eef8bc6b69fad00d279dd97c5d78f960f381105d8cc,
0x5580868f156ec53c7abb35d2aa7a9fbd67db2b4cde3bfa1c8859cce2b11fcaad,
0xb141df7a1857cf056d61732524e868eddc6995dd6d4e60d8dcad13b23020c56c,
0xc21848713073e2d3df4b4d6109d91f8ac252c670eea1d7c3815ae16f1ac4c435,
0xec1e267dd2579ada733e8732ff164e88b20a36d82c181b2551c28279783d37ef]]
getaccountvalue(block_index, account, key)
Returns account (contract) storage data by account (contract) id and storage key and block index.
RPC call: ["getaccountvalue", index, account, key]
Parameters:
- index: integer - block index
- account: binary - account address
- key: binary OR integer - the key that should be retrieved, if an integer is specified it is first converted to a hex string
Response:
["response", proof]
proof:
<proof>
:=[<prefix>, <modulo>, <values>] | {<proof>, <proof>} | <hash>
<hash>
:= binary<prefix>
:= binary[0-32] - the prefix of the HASH(account)<modulo>
:= integer 0-15 - modulo 16 of the last byte of HASH(account)<values>
:=[ account, <accountHash>, …]
<accountHash>
:= HASH(RLP([nonce, balance, storageRoot, code]
))
Example:
<< ["getaccountvalue", 189462, 0xdeea0d008e4d966191fc1fd6c67272956208cf9f,0x0000000000000000000000000000000000000000000000000000000000000000]
>> ["response", [
"",0x05]]
getnode(key)
Retrieves the object of the server from the kademlia network.
RPC call: ["getnode", key]
Parameters:
- key: binary - address of the node that shall be retrieved
Response
["response", <server_object>]
Example:
<< ["getnode", 0x36c1031e7b38593bbd48943fe8c82f557017fac5]
>> ["response", [
"server",
"ipv4 address",
0xa053,
0xc76d,
0x013edfd174175cc1b127deedcf5837415a4a9a4cacae7642b8671ec1286b797391541d2a6721c64889d7b9c9e132ac59d3003abc940a03ecbe735a01862919843a]]
getobject(key)
Retrieves an object of device from the kademlia network.
RPC call: ["getobject", key | device_id]
Parameters:
- key: binary - address of the object that should be fetched
Response
["response", <location_object>]
Example:
<< ["getobject", 0x0808db74162847051c30084f316ef482954ec224]
>> ["response", [
"location",
0x36c1031e7b38593bbd48943fe8c82f557017fac5,
0x00000a78cea0d1c7730ed747436c28ea450ed34cd4cc4b47104c25d243d661d4,
0x0121e822492399ff06fa8855b249747c306e38b7d81205a8c1d223bb29f03697c064315b69af7c836fdf3875e1d389d04c63b871fdbb5cdde11bd62bda7cd3b1df,
0x0017f28e0e4a881fea9c29da99a62f5d29f8b0919dad75bf09a94b44cad4f27f74560a37a4ec3badb3c09efd7c508e2fdc430225c93cf6ab1c20447fb587e640f6]]
sendtransaction(tx)
Submit a transaction to the network.
RPC call: ["sendtransaction", tx]
Parameters:
- tx: binary - RLP encoded signed transactions that is to be submitted
Response
["response", "ok"]
Example:
<< ["sendtransaction", 0x0808db74162847051c30084f316ef482954ec224]
>> ["response", "ok"]
portopen(device, port, flags = “rw”)
Requests to open a port on the target device. Ports can only be opened on nodes holding the actual device connection.
RPC call: ["portopen", device_id, port, (flags)]
Parameters:
- device_id: binary - public key of a target device
- port: integer - port number
- flags: binary[1-3] - defaults to “rw” can be any one of:
- “r” -> read only port
- “w” -> write only port
- “rw” -> read/write port
- “rs” -> shared read only port
- “ws” -> shared write only port
- “rws” -> shared read/write port
Response:
["response", "error", reason]
- Reason: string - Description of the error
["response", "ok", ref]
- ref: binary - Unique identifier of the creating port connection
Example:
<< ["portopen", 0x0808db74162847051c30084f316ef482954ec224, 80, "rw"]
>> ["response", "ok", 0x86f0]
portsend(ref, data)
Sends a chunk of data to the destination.
RPC call: ["portsend", ref, data]
Parameters:
- ref: binary - unique identifier of the creating port connection
- data: binary - the payload
Response:
["response", "ok"]
["response", "error", reason]
- reason: string - description of the error
Example:
<< ["portsend", 34544, "hexdata"]
>> ["response", "ok"]
portclose(ref)
Closes an open port.
RPC call: [“portclose”, ref]
Parameters:
- ref: binary - unique identifier of the creating port connection
Response:
[“response”, “ok”]
Example:
<< ["portclose",34544]
>> ["response", "ok"]
DEVICE RPC
These are calls that can be made from the server down to the edge.
« portopen(port, ref, access_id)
Requests to open a port on the given port number using the unique identifier
RPC Call: [“portopen”, port, ref, access_id]
Parameters:
- port - integer the target port
- ref: binary - unique identifier of the creating port connection
Response:
- Success:
[“response”, ref, “ok”]
- ref: binary - the same unique identifier of the port connection
- Error:
[“response”, ref, “error”, reason]
- ref: binary - the same unique identifier of the port connection
- reason: string - description of the error
« portsend(ref, data)
Sends a chunk of data to the destination.
RPC Call: [“portsend”, ref, data]
Parameters:
- ref: binary - unique identifier of the creating port connection
- data: binary - the payload
Response:
- Success:
[“response”, “ok”]
- Error:
[“response”, “error”, reason]
- reason: string - Description of the error
« portclose(ref)
Closes an open port.
RPC Call: [“portclose”, ref]
Parameters:
- ref: binary - unique identifier of the creating port connection
Response: [“response”, “ok”]
« goodbye(reason, …)
Server disconnect. This is the only command that does not expect a response, since the connection is closed immediately after it.
RPC Call: [“goodbye”,reasons…]
Parameters:
- reasons: array of binary - reason why server disconnect to device
Example:
[“goodbye”,”ticket expected”,”you might get blacklisted”]