RPC Methods
RPC methods required by retesteth
The test API gives you access to several non-standard RPC methods, which will allow you to run ethereum client consensus tests with retesteth agains your client.
The setChainParams test method is the main method which would tell the client to init a test chain with the given state of accounts and genesis block config. A genesis block is a block and should have the block fields. A state is a list of accounts with it's storage and balances, nonce and code. No precompiled contracts are explicitly defined in the genesis state *(1 to be discussed).
The params section tells the client which mining method to use. "ProofOfWork" is a regular mining that accepts new block according to the hash calculation rules. The "ForkRules" sets which fork changes should be enabled to use on this chain. *(2 fork names to be discussed). The fork names are (Frontier, Homestead, ... Byzantium).
"sealEngine" : "NoProof" - Do not check `nonce` and `mixhash` field in blockHeaders
"sealEngine" : "NoReward" - NoProof + Do not check mining reward (block + uncle headers)
The method accepts a single argument which is a genesis.json contents. Similar to genesis config files. But the format is yet to be designed and greed to be universal.
Discussion EIP: https://github.com/ethereum/EIPs/issues/1085
Specification: https://github.com/ethereum/retesteth/issues/4
Schemas: https://github.com/ethereum/tests/pull/469
| Client | Method invocation |
|---|---|
| RPC | {"method": "test_setChainParams", "params": [genesisconfig]} |
Request:
{"jsonrpc":"2.0","method":"test_setChainParams","params":[{
"sealEngine" : "NoProof",
"params" : {
"homesteadForkBlock" : "0x00"
},
"genesis" : {
"author" : "0x2adc25665018aa1fe0e6bc666dac8fc2697ff9ba",
"difficulty" : "0x20000",
"gasLimit" : "0x0f4240",
"nonce" : "0x00",
"extraData" : "0x00",
"timestamp" : "0x00",
"mixHash" : "0x00"
},
"accounts" : {
"0x095e7baea6a6c7c4c2dfeb977efac326af552d87" : {
"balance" : "0x0de0b6b3a7640000",
"code" : "0x6001600101600055",
"nonce" : "0x00",
"storage" : {
}
},
"0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b" : {
"balance" : "0x0de0b6b3a7640000",
"code" : "0x",
"nonce" : "0x00",
"storage" : {
}
}
}
}],"id":51}
Response:
{"id":51,"jsonrpc":"2.0","result":true}
The mineBlocks test method is actually has nothing to do with mining. It just tells the client to create a _number of new blocks on top of the existing one, sealing all valid pending transactions into it.
_number > 0 and must be reasonably not high. (*max value to discuss)
The method of generating a new block is configured in genesis configuration with test_setChainParams. A sealEngine field tells the client how to generate new blocks. (with or without mining or by custom mining rules)
The timestamp distance between blocks is not fixed and is for a client to decide.
Specification Discussion: https://github.com/ethereum/retesteth/issues/8
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"test_mineBlocks","params":[1],"id":5} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"test_mineBlocks","params":[1],"id":5}
Response:
{"id":5,"jsonrpc":"2.0","result":true}
The getLogHash test method is optional and it is possible to run all the tests without implementing this.
The argument here is a transaction hash.It returns pre-calculated log hash of the given _txHash. Hash of emptyRLPList is returned if transaction not found.
Specification Discussion: https://github.com/ethereum/retesteth/issues/7
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"test_getLogHash","params":["0x5363f287fccaad86a0ce8d2c5b15b4b917afe6ebac6a87e61884bf18fc7af58a"],"id":9} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"test_getLogHash","params":["0x5363f287fccaad86a0ce8d2c5b15b4b917afe6ebac6a87e61884bf18fc7af58a"],"id":9}
Response:
{"id":9,"jsonrpc":"2.0","result":"0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347"}
The rewindToBlock test method should revert the state of the blockchain to a specific block number.
Basically cancelling the blocks so there would be no need to reset the chain genesis if we want to apply different transactions on top of the same genesis block.
Specification Discussion: https://github.com/ethereum/retesteth/issues/9
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"test_rewindToBlock","params":[0],"id":50} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"test_rewindToBlock","params":[0],"id":50}
Response:
{"id":50,"jsonrpc":"2.0","result":true}
As some transactions execute TIMESTAMP opcode it is needed to set the timestamp of the current block that is being mined with that transaction so that a transaction could calculate the desired TIMESTAMP value; Or for the difficulty formula calculation the timestamp difference between the blocks should be controllable for tests.
The RPC call sequence is following:
session.test_modifyTimestamp(a.convert_to<size_t>());
session.test_addTransaction(tr.transaction.getData().asJson());
session.test_mineBlocks(1);
First set the timestamp of the current block. Then calculate some transaction with that timestamp. Then finish and calculate the post state hash of a new block.
*This is basically needed to check that TIMESTAMP/DIFFICULTY related tests that has a determined results. But might be not a good solution so far. A disscussion is welcome.
Specification Discussion: https://github.com/ethereum/retesteth/issues/10
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"test_modifyTimestamp","params":[1000],"id":52} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"test_modifyTimestamp","params":[1000],"id":52}
Response:
{"id":52,"jsonrpc":"2.0","result":true}
Try importing a block from the given RLP. RLP data might be intentionally corrupted. The response contains the hash of a block by which it is registered by the client.
Specification Discussion: https://github.com/ethereum/retesteth/issues/19
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"test_importRawBlock","params":["0xBlockrlp"],"id":237} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"test_importRawBlock","params":["0xf9032bf901fda0f7666415a06fe86f39a614be3e707683426ca0cec5a92ccce6664bebbe2ba55ca01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347942adc25665018aa1fe0e6bc666dac8fc2697ff9baa0899fa95a9a2abb5e3893a9a6503b7d5695e9ae011a06927da4132faa6206b627a0ee43fc418be6b43209e9692e06c96b18ce47ed4e0be964cc1b2128567debc2dda0c5e103d2a515a3597320f128d46051e535f2d17f780ca5467647a1708cfec7a2b90100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008302000001887fffffffffffffff83022f9c8203e880a04a9492e8dfefd952b71295549e0113706fc11d149bba15edc227061da9f3521788fb6e2e65e95e1e6df90127f8608001830249f094100000000000000000000000000000000000000001801ba0a8d69db5cc7b988975447a2e77fa471a04e8738915df60767b3104a95bf95c1aa030d6d7f9cd259c5937c46412312a382eabaf62794a7f6d6183891f864057feecf8608001830f424094100000000000000000000000000000000000000101801ba03e25058b9043ef9130f5423b04831a80989f086dacf5ff8468da47b0790086d7a04115beb874eee5f516fd60c91471249bde75186e260632ebf3567b7f05b3ea40f8618001840ee6b28094100000000000000000000000000000000000000201801ca0b4d82d934cb8d0b959b87a51e42cd51d560d24a71047b2127e78830404837662a00e7c42d2e4ce666564a232a4705cf6e43a2bcf29ecbd7db39a21484d01383e75c0"],"id":237}
Response:
{"id":237,"jsonrpc":"2.0","result":"0xee1a10722d2cb6a7a36c90ec1935ecfd2515cfeca81916c08ed009c31d6410f7"}
Response:
{"id":8,"jsonrpc":"2.0","error":{"code":-1,"message":"block validation failed!"}}}
debug_accountRange(string _blockHashOrNumber, int _txIndex, string _addressHash, int _maxResults)
Get the list of accounts of size _maxResults in the given _blockHashOrNumber after given _txIndex. In response AddressMap contains addressHash - > address starting from given _addressHash. nexKey field is the next addressHash (if any addresses left in the state).
The return is like
{
"addressMap" : {
"036014....109616b" : "a94f5374fce5edbc8e2a8697c15331677e6ebf0b",
"0fbc62.....ba962a6" : "095e7baea6a6c7c4c2dfeb977efac326af552d87"
},
"nextKey" : "0000000000000000000000000000000000000000000000000000000000000000"
}
Specification Discussion: https://github.com/ethereum/retesteth/issues/18
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"debug_accountRange","params":["0", 0, "0", 1000],"id":240} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"debug_accountRange","params":["0", 0, "0", 1000],"id":240}
Response:
{"id":240,"jsonrpc":"2.0","result":{"addressMap":{"03601462093b5945d1676df093446790fd31b20e7b12a2e8e5e09d068109616b":"a94f5374fce5edbc8e2a8697c15331677e6ebf0b","14bc834c8d6eafd0088989ab65ab3beea660a9b9744cc3925047b9bea7a9dff6":"118797674cc60c07ad39a824cecc53c29d803feb","3ed02be1e351ddbcc2bf3ffafc25fb42a533df024b33c85f9805e17b60f7230c":"1000000000000000000000000000000000000001","ee51ea7e15b3ec83d9e87eac953fcb2444be7f09e9b1e6e02a47fe32c5a9163a":"1000000000000000000000000000000000000000","f98fb194b034d67d7b8f43f8fd20dd4527b394e6adca7727fc6aa551de072ea3":"840c2083a4726e89c45df3387770b8fb55677229"},"nextKey":"0000000000000000000000000000000000000000000000000000000000000000"}}
debug_storageRangeAt(string _blockHashOrNumber, int _txIndex, string _address, string _begin, int _maxResults)
Get the list of storage values starting from _begin and up to _begin + _maxResults at account _address after transaction _txIndex is executed in the block _blockHashOrNumber.
The return is like
{
"complete" : true,
"storage" : {
"0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563" : {
"key" : "0x00",
"value" : "0x02"
}
}
}
0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563 is trie hash of the state entrie.
Specification Discussion: ???
| Client | Method invocation |
|---|---|
| RPC | {"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["1", 1, "095e7baea6a6c7c4c2dfeb977efac326af552d87", "0", 1000],"id":133} |
(the "id" is just json rpc identificator and could take various values)
Request:
{"jsonrpc":"2.0","method":"debug_storageRangeAt","params":["1", 1, "095e7baea6a6c7c4c2dfeb977efac326af552d87", "0", 1000],"id":133}
Response:
{"id":133,"jsonrpc":"2.0","result":{"complete":true,"storage":{"0x290decd9548b62a8d60345a988386fc84ba6bc95484008f6362f93160ef3e563":{"key":"0x00","value":"0x02"}}}}
Output vm steps trace of transaction execution
https://github.com/ethereum/go-ethereum/wiki/Management-APIs#debug_tracetransaction
Creates new message call transaction or a contract creation for signed transactions.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_sendrawtransaction
Returns information about a block by block number.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getblockbynumber
Returns information about a block by block hash.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getblockbyhash
Returns the number of most recent block.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_blocknumber
Returns the balance of the account of given address.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getbalance
Returns code at a given address.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getcode
Returns the number of transactions sent from an address.
https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_gettransactioncount
Returns the current client version.
https://github.com/ethereum/wiki/wiki/JSON-RPC#web3_clientversion