diff --git a/EIPS/eip-rpc.md b/EIPS/eip-rpc.md new file mode 100644 index 00000000000000..abe4b77dee84a3 --- /dev/null +++ b/EIPS/eip-rpc.md @@ -0,0 +1,2670 @@ +--- +eip: +title: Remote procedure call specification +author: Paul Bouchon +discussions-to: +status: Draft +type: Standards Track +category: Interface +created: 2018-10-02 +--- + +## Simple Summary + +This proposal defines a standard set of remote procedure call methods that an Ethereum node must implement. + +## Abstract + +Nodes created by the current generation of Ethereum clients expose inconsistent and incompatible remote procedure call (RPC) methods because no formal Ethereum RPC specification exists. This proposal standardizes such a specification to provide developers with a predictable Ethereum RPC interface regardless of underlying node implementation. + +## Specification + +### Concepts + +#### JSON-RPC + +Communication with Ethereum nodes is accomplished using [JSON-RPC](https://www.jsonrpc.org/specification), a stateless, lightweight [remote procedure call](https://en.wikipedia.org/wiki/Remote_procedure_call) protocol that uses [JSON](http://www.json.org/) as its data format. Ethereum RPC methods MUST be called using [JSON-RPC request objects](https://www.jsonrpc.org/specification#request_object) and MUST respond with [JSON-RPC response objects](https://www.jsonrpc.org/specification#response_object). + +#### Error codes + +If an Ethereum RPC method encounters an error, the `error` member included on the response object MUST be an object containing a `code` member and descriptive `message` member. The following list contains all possible error codes and associated messages: + +|Code|Message|Meaning|Category| +|-|-|-|-| +|-32700|Parse error|Invalid JSON|standard| +|-32600|Invalid request|JSON is not a valid request object|standard| +|-32601|Method not found|Method does not exist or is not available|standard| +|-32602|Invalid params|Invalid method parameters|standard| +|-32603|Internal error|Internal JSON-RPC error|standard| +|-32000|Invalid input|Missing or invalid parameters|non-standard| +|-32001|Resource not found|Requested resource not found|non-standard| +|-32002|Resource unavailable|Requested resource not available|non-standard| +|-32003|Transaction rejected|Transaction creation failed|non-standard| + +Example error response: + +```js +{ + "id": 1337 + "jsonrpc": "2.0", + "error": { + "code": -32003, + "message": "Transaction rejected" + } +} +``` + +#### Value encoding + +Specific types of values passed to and returned from Ethereum RPC methods require special encoding: + +##### `Quantity` + +- A `Quantity` value MUST be hex-encoded. +- A `Quantity` value MUST be "0x"-prefixed. +- A `Quantity` value MUST be expressed using compact notation. +- A `Quantity` value MUST express zero as "0x0". + +##### `Data` + +- A `Data` value MUST be hex-encoded. +- A `Data` value MUST be "0x"-prefixed. +- A `Data` value MUST be expressed using two hex digits per byte. + +### Methods + +
+web3_clientVersion + +#### Description + +Returns the version of the current client + +#### Parameters + +_(none)_ + +#### Returns + +{`string`} - client version + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "web3_clientVersion", + "params": [], +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "Mist/v0.9.3/darwin/go1.4.1" +} +``` +--- +
+ +
+web3_sha3 + +#### Description + +Hashes data using the Keccak-256 algorithm + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|data to hash| + +#### Returns + +{[`Data`](#data)} - Keccak-256 hash of the given data + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "web3_sha3", + "params": ["0x68656c6c6f20776f726c64"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc94770007dda54cF92009BFF0dE90c06F603a09f" +} +``` +--- +
+ +
+net_version + +#### Description + +Returns the chain ID associated with the current network + +#### Parameters + +_(none)_ + +#### Returns + +{`string`} - chain ID associated with the current network + +Common chain IDs: + +- `"1"` - Ethereum mainnet +- `"3"` - Ropsten testnet +- `"4"` - Rinkeby testnet +- `"42"` - Kovan testnet + +**Note:** See EIP-155 for a [complete list](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-155.md#list-of-chain-ids) of possible chain IDs. + +#### Example + +```js +// Request object +{ + "id": 1337 + "jsonrpc": "2.0", + "method": "net_version", + "params": [], +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "3" +} +``` +--- +
+ +
+net_listening + +#### Description + +Determines if this client is listening for new network connections + +#### Parameters + +_(none)_ + +#### Returns + +{`boolean`} - `true` if listening is active or `false` if listening is not active + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "net_listening", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+net_peerCount + +#### Description + +Returns the number of peers currently connected to this client + +#### Parameters + +_(none)_ + +#### Returns + +{[`Quantity`](#quantity)} - number of connected peers + +#### Example +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "net_peerCount", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x2" +} +``` +--- +
+ +
+eth_protocolVersion + +#### Description + +Returns the current Ethereum protocol version + +#### Parameters + +_(none)_ + +#### Returns + +{`string`} - current Ethereum protocol version + +#### Example +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_protocolVersion", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "54" +} +``` +--- +
+ +
+eth_syncing + +#### Description + +Returns information about the status of this client's network synchronization + +#### Parameters + +_(none)_ + +#### Returns + +{`boolean|object`} - `false` if this client is not syncing with the network, otherwise an object with the following members: + +- {[`Quantity`](#quantity)} `currentBlock` - number of the most-recent block synced +- {[`Quantity`](#quantity)} `highestBlock` - number of latest block on the network +- {[`Quantity`](#quantity)} `startingBlock` - block number at which syncing started + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_syncing", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "currentBlock": '0x386', + "highestBlock": '0x454', + "startingBlock": '0x384' + } +} +``` +--- +
+ +
+eth_coinbase + +#### Description + +Returns the coinbase address for this client + +#### Parameters + +_(none)_ + +#### Returns + +{[`Data`](#data)} - coinbase address + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_coinbase", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc94770007dda54cF92009BFF0dE90c06F603a09f" +} +``` +--- +
+ +
+eth_mining + +#### Description + +Determines if this client is mining new blocks + +#### Parameters + +_(none)_ + +#### Returns + +{`boolean`} - `true` if this client is mining or `false` if it is not mining + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_mining", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+eth_hashrate + +#### Description + +Returns the number of hashes-per-second this node is mining at + +#### Parameters + +_(none)_ + +#### Returns + +{[`Quantity`](#quantity)} - number of hashes-per-second + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_hashrate", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x38a" +} +``` +--- +
+ +
+eth_gasPrice + +#### Description + +Returns the current price of gas expressed in wei + +#### Parameters + +_(none)_ + +#### Returns + +{[`Quantity`](#quantity)} - current gas price in wei + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_gasPrice", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x09184e72a000" +} +``` +--- +
+ +
+eth_accounts + +#### Description + +Returns a list of addresses owned by this client + +#### Parameters + +_(none)_ + +#### Returns + +{[`Data[]`](#data)} - array of addresses + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_accounts", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"] +} +``` +--- +
+ +
+eth_blockNumber + +#### Description + +Returns the number of the most recent block seen by this client + +#### Parameters + +_(none)_ + +#### Returns + +{[`Quantity`](#quantity)} - number of the latest block + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_blockNumber", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc94" +} +``` +--- +
+ +
+eth_getBalance + +#### Description + +Returns the balance of an address in wei + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address to query for balance| +|2|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Quantity`](#quantity)} - balance of the provided account in wei + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getBalance", + "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x0234c8a3397aab58" +} +``` +--- +
+ +
+eth_getStorageAt + +#### Description + +Returns the value from a storage position at an address + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address of stored data| +|2|{[`Quantity`](#quantity)}|index into stored data| +|3|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Data`](#data)} - value stored at the given address and data index + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getStorageAt", + "params": ["0x295a70b2de5e3953354a6a8344e616ed314d7251", "0x0", "latest"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x00000000000000000000000000000000000000000000000000000000000004d2" +} +``` +--- +
+ +
+eth_getTransactionCount + +#### Description + +Returns the number of transactions sent from an address + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address to query for sent transactions| +|2|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Quantity`](#quantity)} - number of transactions sent from the specified address + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getTransactionCount", + "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x1" +} +``` +--- +
+ +
+eth_getBlockTransactionCountByHash + +#### Description + +Returns the number of transactions in a block specified by block hash + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a block| + +#### Returns + +{[`Quantity`](#quantity)} - number of transactions in the specified block + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getBlockTransactionCountByHash", + "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc" +} +``` +--- +
+ +
+eth_getBlockTransactionCountByNumber + +#### Description + +Returns the number of transactions in a block specified by block number + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Quantity`](#quantity)} - number of transactions in the specified block + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getBlockTransactionCountByNumber", + "params": ["0xe8"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xa" +} +``` +--- +
+ +
+eth_getUncleCountByBlockHash + +#### Description + +Returns the number of uncles in a block specified by block hash + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a block| + +#### Returns + +{[`Quantity`](#quantity)} - number of uncles in the specified block + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getUncleCountByBlockHash", + "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc" +} +``` +--- +
+ +
+eth_getUncleCountByBlockNumber + +#### Description + +Returns the number of uncles in a block specified by block number + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Quantity`](#quantity)} - number of uncles in the specified block + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getUncleCountByBlockNumber", + "params": ["0xe8"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x1" +} +``` +--- +
+ +
+eth_getCode + +#### Description + +Returns the contract code stored at a given address + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address to query for code| +|2|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Data`](#data)} - code from the specified address + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getCode", + "params": ["0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x2"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056" +} +``` +--- +
+ +
+eth_sign + +#### Description + +Calculates an Ethereum-specific signature in the form of `keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))` + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address to use for signing| +|2|{[`Data`](#data)}|data to sign| + +#### Returns + +{[`Data`](#data)} - signature hash of the provided data + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_sign", + "params": ["0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "0xdeadbeaf"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b" +} +``` +--- +
+ +
+eth_signTypedData + +#### Description + +Calculates an Ethereum-specific signature in the form of `keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))` + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|address to use for signing| +|2|{[`Data`](#data)}|message to sign containing type information, a domain separator, and data| + +**Note:** Client developers should refer to EIP-712 for complete semantics around [encoding and signing data](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md#specification). Dapp developers should refer to EIP-712 for the expected structure of [RPC method input parameters](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-712.md#parameters). + +#### Returns + +{[`Data`](#data)} - signature hash of the provided message + +#### Example + +```js +// Request object +{ + "id": 1337 + "jsonrpc": "2.0", + "method": "eth_signTypedData", + "params": ["0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826", { + "types": { + "EIP712Domain": [{ + "name": "name", + "type": "string" + }, { + "name": "version", + "type": "string" + }, { + "name": "chainId", + "type": "uint256" + }, { + "name": "verifyingContract", + "type": "address" + }], + "Person": [{ + "name": "name", + "type": "string" + }, { + "name": "wallet", + "type": "address" + }], + "Mail": [{ + "name": "from", + "type": "Person" + }, { + "name": "to", + "type": "Person" + }, { + "name": "contents", + "type": "string" + }] + }, + "primaryType": "Mail", + "domain": { + "name": "Ether Mail", + "version": "1", + "chainId": 1, + "verifyingContract": "0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC" + }, + "message": { + "from": { + "name": "Cow", + "wallet": "0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826" + }, + "to": { + "name": "Bob", + "wallet": "0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB" + }, + "contents": "Hello, Bob!" + } + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c" +} +``` +--- +
+ +
+eth_sendTransaction + +#### Description + +Creates, signs, and sends a new transaction to the network + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Data`](#data)} `from` - transaction sender
@property {[`Data`](#data)} `[to]` - transaction recipient
@property {[`Quantity`](#quantity)} `[gas="0x15f90"]` - gas provided for transaction execution
@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used
@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction
@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args
@property {[`Quantity`](#quantity)} `[nonce]` - unique number identifying this transaction| + +#### Returns + +{[`Data`](#data)} - transaction hash, or the zero hash if the transaction is not yet available + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_sendTransaction", + "params": [{ + "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", + "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", + "gas": "0x76c0", + "gasPrice": "0x9184e72a000", + "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "value": "0x9184e72a" + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +} +``` +--- +
+ +
+eth_sendRawTransaction + +#### Description + +Sends and already-signed transaction to the network + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|signed transaction data| + +#### Returns + +{[`Data`](#data)} - transaction hash, or the zero hash if the transaction is not yet available + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_sendRawTransaction", + "params": ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" +} +``` +--- +
+ +
+eth_call + +#### Description + +Executes a new message call immediately without submitting a transaction to the network + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Data`](#data)} `[from]` - transaction sender
@property {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract
@property {[`Quantity`](#quantity)} `[gas]` - gas provided for transaction execution
@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used
@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction
@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args| +|2|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Data`](#data)} - return value of executed contract + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_call", + "params": [{ + "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", + "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", + "gas": "0x76c0", + "gasPrice": "0x9184e72a000", + "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "value": "0x9184e72a" + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x" +} +``` +--- +
+ +
+eth_estimateGas + +#### Description + +Estimates the gas necessary to complete a transaction without submitting it to the network + +**Note:** The resulting gas estimation may be significantly more than the amount of gas actually used by the transaction. This is due to a variety of reasons including EVM mechanics and node performance. + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Data`](#data)} `[from]` - transaction sender
@property {[`Data`](#data)} `[to]` - transaction recipient
@property {[`Quantity`](#quantity)} `[gas]` - gas provided for transaction execution
@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used
@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction
@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args| +|2|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| + +#### Returns + +{[`Quantity`](#quantity)} - amount of gas required by transaction + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_estimateGas", + "params": [{ + "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675", + "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155", + "gas": "0x76c0", + "gasPrice": "0x9184e72a000", + "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567", + "value": "0x9184e72a" + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x5208" +} +``` +--- +
+ +
+eth_getBlockByHash + +#### Description + +Returns information about a block specified by hash + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a block| +|2|{`boolean`}|`true` will pull full transaction objects, `false` will pull transaction hashes| + +#### Returns + +{`null|object`} - `null` if no block is found, otherwise a block object with the following members: + +- {[`Data`](#data)} `extraData` - "extra data" field of this block +- {[`Data`](#data)} `hash` - block hash or `null` if pending +- {[`Data`](#data)} `logsBloom` - logs bloom filter or `null` if pending +- {[`Data`](#data)} `miner` - address that received this block's mining rewards +- {[`Data`](#data)} `nonce` - proof-of-work hash or `null` if pending +- {[`Data`](#data)} `parentHash` - parent block hash +- {[`Data`](#data)} `receiptsRoot` -root of the this block's receipts trie +- {[`Data`](#data)} `sha3Uncles` - SHA3 of the uncles data in this block +- {[`Data`](#data)} `stateRoot` - root of this block's final state trie +- {[`Data`](#data)} `transactionsRoot` - root of this block's transaction trie +- {[`Quantity`](#quantity)} `difficulty` - difficulty for this block +- {[`Quantity`](#quantity)} `gasLimit` - maximum gas allowed in this block +- {[`Quantity`](#quantity)} `gasUsed` - total used gas by all transactions in this block +- {[`Quantity`](#quantity)} `number` - block number or `null` if pending +- {[`Quantity`](#quantity)} `size` - size of this block in bytes +- {[`Quantity`](#quantity)} `timestamp` - unix timestamp of when this block was collated +- {[`Quantity`](#quantity)} `totalDifficulty` - total difficulty of the chain until this block +- {`Array`} `transactions` - list of transaction objects or hashes +- {`Array`} `uncles` - list of uncle hashes + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getBlockByHash", + "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "difficulty": "0x027f07", + "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000", + "gasLimit": "0x9f759", + "gasUsed": "0x9f759", + "hash": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", + "logsBloom": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", + "miner": "0x4e65fda2159562a496f9f3522f89122a3088497a", + "nonce": "0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2", + "number": "0x1b4", + "parentHash": "0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x027f07", + "stateRoot": "0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff", + "timestamp": "0x54e34e8e" + "totalDifficulty": "0x027f07", + "transactions": [] + "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "uncles": ["0x1606e5...", "0xd5145a9..."] + } +} +``` +--- +
+ +
+eth_getBlockByNumber + +#### Description + +Returns information about a block specified by number + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| +|2|{`boolean`}|`true` will pull full transaction objects, `false` will pull transaction hashes| + +#### Returns + +{`null|object`} - `null` if no block is found, otherwise a block object with the following members: + +- {[`Data`](#data)} `extraData` - "extra data" field of this block +- {[`Data`](#data)} `hash` - block hash or `null` if pending +- {[`Data`](#data)} `logsBloom` - logs bloom filter or `null` if pending +- {[`Data`](#data)} `miner` - address that received this block's mining rewards +- {[`Data`](#data)} `nonce` - proof-of-work hash or `null` if pending +- {[`Data`](#data)} `parentHash` - parent block hash +- {[`Data`](#data)} `receiptsRoot` -root of the this block's receipts trie +- {[`Data`](#data)} `sha3Uncles` - SHA3 of the uncles data in this block +- {[`Data`](#data)} `stateRoot` - root of this block's final state trie +- {[`Data`](#data)} `transactionsRoot` - root of this block's transaction trie +- {[`Quantity`](#quantity)} `difficulty` - difficulty for this block +- {[`Quantity`](#quantity)} `gasLimit` - maximum gas allowed in this block +- {[`Quantity`](#quantity)} `gasUsed` - total used gas by all transactions in this block +- {[`Quantity`](#quantity)} `number` - block number or `null` if pending +- {[`Quantity`](#quantity)} `size` - size of this block in bytes +- {[`Quantity`](#quantity)} `timestamp` - unix timestamp of when this block was collated +- {[`Quantity`](#quantity)} `totalDifficulty` - total difficulty of the chain until this block +- {`Array`} `transactions` - list of transaction objects or hashes +- {`Array`} `uncles` - list of uncle hashes + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getBlockByNumber", + "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "difficulty": "0x027f07", + "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000", + "gasLimit": "0x9f759", + "gasUsed": "0x9f759", + "hash": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", + "logsBloom": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", + "miner": "0x4e65fda2159562a496f9f3522f89122a3088497a", + "nonce": "0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2", + "number": "0x1b4", + "parentHash": "0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5", + "sha3Uncles": "0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347", + "size": "0x027f07", + "stateRoot": "0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff", + "timestamp": "0x54e34e8e" + "totalDifficulty": "0x027f07", + "transactions": [] + "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421", + "uncles": ["0x1606e5...", "0xd5145a9..."] + } +} +``` +--- +
+ +
+eth_getTransactionByHash + +#### Description + +Returns information about a transaction specified by hash + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a transaction| + +#### Returns + +{`null|object`} - `null` if no transaction is found, otherwise a transaction object with the following members: + +- {[`Data`](#data)} `r` - ECDSA signature r +- {[`Data`](#data)} `s` - ECDSA signature s +- {[`Data`](#data)} `blockHash` - hash of block containing this transaction or `null` if pending +- {[`Data`](#data)} `from` - transaction sender +- {[`Data`](#data)} `hash` - hash of this transaction +- {[`Data`](#data)} `input` - contract code or a hashed method call +- {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract +- {[`Quantity`](#quantity)} `v` - ECDSA recovery ID +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this transaction or `null` if pending +- {[`Quantity`](#quantity)} `gas` - gas provided for transaction execution +- {[`Quantity`](#quantity)} `gasPrice` - price in wei of each gas used +- {[`Quantity`](#quantity)} `nonce` - unique number identifying this transaction +- {[`Quantity`](#quantity)} `transactionIndex` - index of this transaction in the block or `null` if pending +- {[`Quantity`](#quantity)} `value` - value in wei sent with this transaction + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getTransactionByHash", + "params": ["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2", + "blockNumber": "0x5daf3b", + "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d", + "gas": "0xc350", + "gasPrice": "0x4a817c800", + "hash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b", + "input": "0x68656c6c6f21", + "nonce": "0x15", + "r": "0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea", + "s": "0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c", + "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb", + "transactionIndex": "0x41", + "v": "0x25", + "value": "0xf3dbb76162000" + } +} +``` +--- +
+ +
+eth_getTransactionByBlockHashAndIndex + +#### Description + +Returns information about a transaction specified by block hash and transaction index + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a block| +|2|{[`Quantity`](#quantity)}|index of a transaction in the specified block| + +#### Returns + +{`null|object`} - `null` if no transaction is found, otherwise a transaction object with the following members: + +- {[`Data`](#data)} `r` - ECDSA signature r +- {[`Data`](#data)} `s` - ECDSA signature s +- {[`Data`](#data)} `blockHash` - hash of block containing this transaction or `null` if pending +- {[`Data`](#data)} `from` - transaction sender +- {[`Data`](#data)} `hash` - hash of this transaction +- {[`Data`](#data)} `input` - contract code or a hashed method call +- {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract +- {[`Quantity`](#quantity)} `v` - ECDSA recovery ID +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this transaction or `null` if pending +- {[`Quantity`](#quantity)} `gas` - gas provided for transaction execution +- {[`Quantity`](#quantity)} `gasPrice` - price in wei of each gas used +- {[`Quantity`](#quantity)} `nonce` - unique number identifying this transaction +- {[`Quantity`](#quantity)} `transactionIndex` - index of this transaction in the block or `null` if pending +- {[`Quantity`](#quantity)} `value` - value in wei sent with this transaction + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getTransactionByBlockHashAndIndex", + "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", "0x0"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2", + "blockNumber": "0x5daf3b", + "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d", + "gas": "0xc350", + "gasPrice": "0x4a817c800", + "hash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b", + "input": "0x68656c6c6f21", + "nonce": "0x15", + "r": "0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea", + "s": "0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c", + "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb", + "transactionIndex": "0x41", + "v": "0x25", + "value": "0xf3dbb76162000" + } +} +``` +--- +
+ +
+eth_getTransactionByBlockNumberAndIndex + +#### Description + +Returns information about a transaction specified by block number and transaction index + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| +|2|{[`Quantity`](#quantity)}|index of a transaction in the specified block| + +#### Returns + +{`null|object`} - `null` if no transaction is found, otherwise a transaction object with the following members: + +- {[`Data`](#data)} `r` - ECDSA signature r +- {[`Data`](#data)} `s` - ECDSA signature s +- {[`Data`](#data)} `blockHash` - hash of block containing this transaction or `null` if pending +- {[`Data`](#data)} `from` - transaction sender +- {[`Data`](#data)} `hash` - hash of this transaction +- {[`Data`](#data)} `input` - contract code or a hashed method call +- {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract +- {[`Quantity`](#quantity)} `v` - ECDSA recovery ID +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this transaction or `null` if pending +- {[`Quantity`](#quantity)} `gas` - gas provided for transaction execution +- {[`Quantity`](#quantity)} `gasPrice` - price in wei of each gas used +- {[`Quantity`](#quantity)} `nonce` - unique number identifying this transaction +- {[`Quantity`](#quantity)} `transactionIndex` - index of this transaction in the block or `null` if pending +- {[`Quantity`](#quantity)} `value` - value in wei sent with this transaction + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getTransactionByBlockNumberAndIndex", + "params":["0x29c", "0x0"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": "0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2", + "blockNumber": "0x5daf3b", + "from": "0xa7d9ddbe1f17865597fbd27ec712455208b6b76d", + "gas": "0xc350", + "gasPrice": "0x4a817c800", + "hash": "0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b", + "input": "0x68656c6c6f21", + "nonce": "0x15", + "r": "0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea", + "s": "0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c", + "to": "0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb", + "transactionIndex": "0x41", + "v": "0x25", + "value": "0xf3dbb76162000" + } +} +``` +--- +
+ +
+eth_getTransactionReceipt + +#### Description + +Returns the receipt of a transaction specified by hash + +**Note:** Transaction receipts are unavailable for pending transactions. + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a transaction| + +#### Returns + +{`null|object`} - `null` if no transaction is found, otherwise a transaction receipt object with the following members: + +- {[`Data`](#data)} `blockHash` - hash of block containing this transaction +- {[`Data`](#data)} `contractAddress` - address of new contract or `null` if no contract was created +- {[`Data`](#data)} `from` - transaction sender +- {[`Data`](#data)} `logsBloom` - logs bloom filter +- {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract +- {[`Data`](#data)} `transactionHash` - hash of this transaction +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this transaction +- {[`Quantity`](#quantity)} `cumulativeGasUsed` - gas used by this and all preceding transactions in this block +- {[`Quantity`](#quantity)} `gasUsed` - gas used by this transaction +- {[`Quantity`](#quantity)} `status` - `1` if this transaction was successful or `0` if it failed +- {[`Quantity`](#quantity)} `transactionIndex` - index of this transaction in the block +- {`Array`} `logs` - list of log objects generated by this transaction + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getTransactionReceipt", + "params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b', + "blockNumber": '0xb', + "contractAddress": '0xb60e8dd61c5d32be8058bb8eb970870f07233155', + "cumulativeGasUsed": '0x33bc', + "gasUsed": '0x4dc', + "logs": [], + "logsBloom": "0x00...0", + "status": "0x1", + "transactionHash": '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238', + "transactionIndex": '0x1' + } +} +``` +--- +
+ +
+eth_getUncleByBlockHashAndIndex + +#### Description + +Returns information about an uncle specified by block hash and uncle index position + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash of a block| +|2|{[`Quantity`](#quantity)}|index of uncle| + +#### Returns + +{`null|object`} - `null` if no block or uncle is found, otherwise an uncle object with the following members: + +- {[`Data`](#data)} `extraData` - "extra data" field of this block +- {[`Data`](#data)} `hash` - block hash or `null` if pending +- {[`Data`](#data)} `logsBloom` - logs bloom filter or `null` if pending +- {[`Data`](#data)} `miner` - address that received this block's mining rewards +- {[`Data`](#data)} `nonce` - proof-of-work hash or `null` if pending +- {[`Data`](#data)} `parentHash` - parent block hash +- {[`Data`](#data)} `receiptsRoot` -root of the this block's receipts trie +- {[`Data`](#data)} `sha3Uncles` - SHA3 of the uncles data in this block +- {[`Data`](#data)} `stateRoot` - root of this block's final state trie +- {[`Data`](#data)} `transactionsRoot` - root of this block's transaction trie +- {[`Quantity`](#quantity)} `difficulty` - difficulty for this block +- {[`Quantity`](#quantity)} `gasLimit` - maximum gas allowed in this block +- {[`Quantity`](#quantity)} `gasUsed` - total used gas by all transactions in this block +- {[`Quantity`](#quantity)} `number` - block number or `null` if pending +- {[`Quantity`](#quantity)} `size` - size of this block in bytes +- {[`Quantity`](#quantity)} `timestamp` - unix timestamp of when this block was collated +- {[`Quantity`](#quantity)} `totalDifficulty` - total difficulty of the chain until this block +- {`Array`} `uncles` - list of uncle hashes + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getUncleByBlockHashAndIndex", + "params": ["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "0x0"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b', + "blockNumber": '0xb', + "contractAddress": '0xb60e8dd61c5d32be8058bb8eb970870f07233155', + "cumulativeGasUsed": '0x33bc', + "gasUsed": '0x4dc', + "logs": [], + "logsBloom": "0x00...0", + "status": "0x1", + "transactionHash": '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238', + "transactionIndex": '0x1' + } +} +``` +--- +
+ +
+eth_getUncleByBlockNumberAndIndex + +#### Description + +Returns information about an uncle specified by block number and uncle index position + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)\|`string`}|block number, or one of `"latest"`, `"earliest"` or `"pending"`| +|2|{[`Quantity`](#quantity)}|index of uncle| + +#### Returns + +{`null|object`} - `null` if no block or uncle is found, otherwise an uncle object with the following members: + +- {[`Data`](#data)} `extraData` - "extra data" field of this block +- {[`Data`](#data)} `hash` - block hash or `null` if pending +- {[`Data`](#data)} `logsBloom` - logs bloom filter or `null` if pending +- {[`Data`](#data)} `miner` - address that received this block's mining rewards +- {[`Data`](#data)} `nonce` - proof-of-work hash or `null` if pending +- {[`Data`](#data)} `parentHash` - parent block hash +- {[`Data`](#data)} `receiptsRoot` -root of the this block's receipts trie +- {[`Data`](#data)} `sha3Uncles` - SHA3 of the uncles data in this block +- {[`Data`](#data)} `stateRoot` - root of this block's final state trie +- {[`Data`](#data)} `transactionsRoot` - root of this block's transaction trie +- {[`Quantity`](#quantity)} `difficulty` - difficulty for this block +- {[`Quantity`](#quantity)} `gasLimit` - maximum gas allowed in this block +- {[`Quantity`](#quantity)} `gasUsed` - total used gas by all transactions in this block +- {[`Quantity`](#quantity)} `number` - block number or `null` if pending +- {[`Quantity`](#quantity)} `size` - size of this block in bytes +- {[`Quantity`](#quantity)} `timestamp` - unix timestamp of when this block was collated +- {[`Quantity`](#quantity)} `totalDifficulty` - total difficulty of the chain until this block +- {`Array`} `uncles` - list of uncle hashes + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getUncleByBlockNumberAndIndex", + "params": ["0x29c", "0x0"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": { + "blockHash": '0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b', + "blockNumber": '0xb', + "contractAddress": '0xb60e8dd61c5d32be8058bb8eb970870f07233155', + "cumulativeGasUsed": '0x33bc', + "gasUsed": '0x4dc', + "logs": [], + "logsBloom": "0x00...0", + "status": "0x1", + "transactionHash": '0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238', + "transactionIndex": '0x1' + } +} +``` +--- +
+ +
+eth_newFilter + +#### Description + +Creates a filter to listen for specific state changes that can then be used with `eth_getFilterChanges` + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Quantity`](#quantity)\|`string`} `[fromBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`
@property {[`Quantity`](#quantity)\|`string`} `[toBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`
@property {[`Data`](#data)\|[`Data[]`](#data)} `[address]` - contract address or a list of addresses from which logs should originate
@property {[`Data[]`](#data)} `[topics]` - list of order-dependent topics| + +**Note:** Topics are order-dependent. A transaction with a log with topics `[A, B]` will be matched by the following topic filters: +- `[]` - "anything" +- `[A]` - "A in first position (and anything after)" +- `[null, B]` - "anything in first position AND B in second position (and anything after)" +- `[A, B]` - "A in first position AND B in second position (and anything after)" +- `[[A, B], [A, B]]` - "(A OR B) in first position AND (A OR B) in second position (and anything after)" + +#### Returns + +{[`Quantity`](#quantity)} - ID of the newly-created filter that can be used with `eth_getFilterChanges` + +#### Example + +```js +// Request object +{ + "id": 1337 + "jsonrpc": "2.0", + "method": "eth_newFilter", + "params": [{ + "topics": ["0x0000000000000000000000000000000000000000000000000000000012341234"] + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x1" +} +``` +--- +
+ +
+eth_newBlockFilter + +#### Description + +Creates a filter to listen for new blocks that can be used with `eth_getFilterChanges` + +#### Parameters + +_none_ + +#### Returns + +{[`Quantity`](#quantity)} - ID of the newly-created filter that can be used with `eth_getFilterChanges` + +#### Example + +```js +// Request object +{ + "id": 1337 + "jsonrpc": "2.0", + "method": "eth_newBlockFilter", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x1" +} +``` +--- +
+ +
+eth_newPendingTransactionFilter + +#### Description + +Creates a filter to listen for new pending transactions that can be used with `eth_getFilterChanges` + +#### Parameters + +_none_ + +#### Returns + +{[`Quantity`](#quantity)} - ID of the newly-created filter that can be used with `eth_getFilterChanges` + +#### Example + +```js +// Request object +{ + "id": 1337 + "jsonrpc": "2.0", + "method": "eth_newPendingTransactionFilter", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x1" +} +``` +--- +
+ +
+eth_uninstallFilter + +#### Description + +Destroys a filter based on filter ID + +**Note:** This should only be called if a filter and its notifications are no longer needed. This will also be called automatically on a filter if its notifications are not retrieved using `eth_getFilterChanges` for a period of time. + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter to destroy| + +#### Returns + +{`boolean`} - `true` if the filter is found and successfully destroyed or `false` if it is not + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_uninstallFilter", + "params": ["0xb"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+eth_getFilterChanges + +#### Description + +Returns a list of all logs based on filter ID since the last log retrieval + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter| + +#### Returns + +{`Array`} - array of log objects with the following members: + +- {[`Data`](#data)} `address` - address from which this log originated +- {[`Data`](#data)} `blockHash` - hash of block containing this log or `null` if pending +- {[`Data`](#data)} `data` - contains the non-indexed arguments of the log +- {[`Data`](#data)} `transactionHash` - hash of the transaction that created this log or `null` if pending +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this log or `null` if pending +- {[`Quantity`](#quantity)} `logIndex` - index of this log within its block or `null` if pending +- {[`Quantity`](#quantity)} `transactionIndex` - index of the transaction that created this log or `null` if pending +- {[`Data[]`](#data)} `topics` - list of order-dependent topics +- {`boolean`} `removed` - `true` if this filter has been destroyed and is invalid + +**Note:** The return value of `eth_getFilterChanges` when retrieving logs from `eth_newBlockFilter` and `eth_newPendingTransactionFilter` filters will be an array of hashes, not an array of Log objects. + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getFilterChanges", + "params": ["0x16"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": [{ + "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockNumber":"0x1b4", + "data":"0x0000000000000000000000000000000000000000000000000000000000000000", + "logIndex": "0x1", + "topics": [], + "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", + "transactionIndex": "0x0" + }] +} +``` +--- +
+ +
+eth_getFilterLogs + +#### Description + +Returns a list of all logs based on filter ID + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter| + +#### Returns + +{`Array`} - array of log objects with the following members: + +- {[`Data`](#data)} address - address from which this log originated +- {[`Data`](#data)} blockHash - hash of block containing this log or `null` if pending +- {[`Data`](#data)} data - contains the non-indexed arguments of the log +- {[`Data`](#data)} transactionHash - hash of the transaction that created this log or `null` if pending +- {[`Quantity`](#quantity)} blockNumber - number of block containing this log or `null` if pending +- {[`Quantity`](#quantity)} logIndex - index of this log within its block or `null` if pending +- {[`Quantity`](#quantity)} transactionIndex - index of the transaction that created this log or `null` if pending +- {`Array`} topics - list of order-dependent topics +- {`boolean`} removed - `true` if this filter has been destroyed and is invalid + +**Note:** The return value of `eth_getFilterLogs` when retrieving logs from `eth_newBlockFilter` and `eth_newPendingTransactionFilter` filters will be an array of hashes, not an array of Log objects. + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getFilterLogs", + "params": ["0x16"] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": [{ + "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockNumber":"0x1b4", + "data":"0x0000000000000000000000000000000000000000000000000000000000000000", + "logIndex": "0x1", + "topics": [], + "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", + "transactionIndex": "0x0" + }] +} +``` +--- +
+ +
+eth_getLogs + +#### Description + +Returns a list of all logs based on a filter object + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Quantity`](#quantity)\|`string`} `[fromBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`
@property {[`Quantity`](#quantity)\|`string`} `[toBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`
@property {[`Data`](#data)\|[`Data[]`](#data)} `[address]` - contract address or a list of addresses from which logs should originate
@property {[`Data[]`](#data)} `[topics]` - list of order-dependent topics
@property {[`Data`](#data)} `[blockhash]` - restrict logs to a block by hash| + +**Note:** If `blockhash` is passed, neither `fromBlock` nor `toBlock` are allowed or respected. + +#### Returns + +{`Array`} - array of log objects with the following members: + +- {[`Data`](#data)} `address` - address from which this log originated +- {[`Data`](#data)} `blockHash` - hash of block containing this log or `null` if pending +- {[`Data`](#data)} `data` - contains the non-indexed arguments of the log +- {[`Data`](#data)} `transactionHash` - hash of the transaction that created this log or `null` if pending +- {[`Quantity`](#quantity)} `blockNumber` - number of block containing this log or `null` if pending +- {[`Quantity`](#quantity)} `logIndex` - index of this log within its block or `null` if pending +- {[`Quantity`](#quantity)} `transactionIndex` - index of the transaction that created this log or `null` if pending +- {[`Data`](#data)} `topics` - list of order-dependent topics +- {`boolean`} `removed` - `true` if this filter has been destroyed and is invalid + +**Note:** The return value of `eth_getLogs` when retrieving logs from `eth_newBlockFilter` and `eth_newPendingTransactionFilter` filters will be an array of hashes, not an array of Log objects. + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getLogs", + "params": [{ + "topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": [{ + "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d", + "blockNumber":"0x1b4", + "data":"0x0000000000000000000000000000000000000000000000000000000000000000", + "logIndex": "0x1", + "topics": [], + "transactionHash": "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf", + "transactionIndex": "0x0" + }] +} +``` +--- +
+ +
+eth_getWork + +#### Description + +Returns a list containing relevant information for proof-of-work + +#### Parameters + +_none_ + +#### Returns + +{[`Data[]`](#data)} - array with the following items: + +1. {[`Data`](#data)} - current block header pow-hash +1. {[`Data`](#data)} - seed hash used for the DAG +1. {[`Data`](#data)} - boundary condition ("target"), 2^256 / difficulty + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_getWork", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": [ + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "0x5EED00000000000000000000000000005EED0000000000000000000000000000", + "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000" + ] +} +``` +--- +
+ +
+eth_submitWork + +#### Description + +Submit a proof-of-work solution + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|nonce found| +|2|{[`Data`](#data)}|header's pow-hash| +|3|{[`Data`](#data)}|mix digest| + +#### Returns + +{`boolean`} - `true` if the provided solution is valid, `false` otherwise + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_submitWork", + "params": [ + "0x0000000000000001", + "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", + "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000" + ] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+eth_submitHashrate + +#### Description + +Submit a mining hashrate + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|hash rate| +|2|{[`Data`](#data)}|random ID identifying this node| + +#### Returns + +{`boolean`} - `true` if submitting went through succesfully, `false` otherwise + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "eth_submitHashrate", + "params": [ + "0x0000000000000000000000000000000000000000000000000000000000500000", + "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c" + ] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+shh_version + +#### Description + +Returns the current whisper protocol version + +#### Parameters + +_none_ + +#### Returns + +{`string`} - whisper protocol version + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_version", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "2" +} +``` +--- +
+ +
+shh_post + +#### Description + +Sends a whisper message + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Data`](#data)} `[from]` - sender identity
@property {[`Data`](#data)} `[to]` - recipient identity
@property {[`Data[]`](#data)} `topics` - list of topics to identify messages
@property {[`Data`](#data)} `payload` - message payload
@property {[`Quantity`](#quantity)} `priority` - message priority
@property {[`Quantity`](#quantity)} `ttl` - time to live in seconds| + +#### Returns + +{`boolean`} - `true` if the message is sent successfully, `false` otherwise + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_post", + "params": [{ + "from": "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1", + "to": "0x3e245533f97284d442460f2998cd41858798ddf04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a0d4d661997d3940272b717b1", + "topics": ["0x776869737065722d636861742d636c69656e74", "0x4d5a695276454c39425154466b61693532"], + "payload": "0x7b2274797065223a226d6", + "priority": "0x64", + "ttl": "0x64", + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+shh_newIdentity + +#### Description + +Creates a new whisper identity on this client + +#### Parameters + +_none_ + +#### Returns + +{[`Data`](#data)} - address of the newly-created identity + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_newIdentity", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc931d93e97ab07fe42d923478ba2465f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca9007d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" +} +``` +--- +
+ +
+shh_hasIdentity + +#### Description + +Checks if this client has private keys for a given identity + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|identity address to check| + +#### Returns + +{`boolean`} - `true` if the client holds the private key for that identity, otherwise `false` + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_hasIdentity", + "params": [ + "0x04f96a5e25610293e42a73908e93ccc8c4d4dc0edcfa9fa872f50cb214e08ebf61a03e245533f97284d442460f2998cd41858798ddfd4d661997d3940272b717b1" + ] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+shh_newGroup + +#### Description + +Creates a new whisper group on this client + +#### Parameters + +_none_ + +#### Returns + +{[`Data`](#data)} - address of the newly-created group + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_newGroup", + "params": [] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0xc65f283f440fd6cabea4dd7a2c807108f651b7135d1d6ca90931d93e97ab07fe42d923478ba2407d5b68aa497e4619ac10aa3b27726e1863c1fd9b570d99bbaf" +} +``` +--- +
+ +
+shh_addToGroup + +#### Description + +Adds a whisper identity to the current group + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Data`](#data)}|identity address to add| + +#### Returns + +{`boolean`} - `true` if the identity is successfully added to the group, otherwise `false` + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_addToGroup", + "params": [ + "0x04f96a5e25610293e42a73....." + ] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+shh_newFilter + +#### Description + +Creates a filter to listen for specific whisper messages that can then be used with `shh_getFilterChanges` + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{`object`}|@property {[`Data`](#data)} `[to]` - identity of the receiver
@property {[`Data[]`](#data)} `topics` - list of topics that incoming messages should match| + +**Note:** The following combinations can be used for topics: +- `[A, B] = A && B` +- `[A, [B, C]] = A && (B || C)` +- `[null, A, B] = ANYTHING && A && B` (`null` works as a wildcard) + +#### Returns + +{[`Quantity`](#quantity)} - ID of the newly-created filter that can be used with `shh_getFilterChanges` + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_newFilter", + "params": [{ + "topics": ["0x12341234bf4b564f"], + "to": "0x2341234bf4b2341234bf4b564f..." + }] +} + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": "0x7" +} +``` +--- +
+ +
+shh_uninstallFilter + +#### Description + +Destroys a whisper filter based on filter ID + +**Note:** This should only be called if a filter and its notifications are no longer needed. This will also be called automatically on a filter if its notifications are not retrieved using `shh_getFilterChanges` for a period of time. + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter to destroy| + +#### Returns + +{`boolean`} - `true` if the filter is found and successfully destroyed or `false` if it is not + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_uninstallFilter", + "params": ["0x7"] +} + + +// Response object +{ + "id": 1337, + "jsonrpc": "2.0", + "result": true +} +``` +--- +
+ +
+shh_getFilterChanges + +#### Description + +Returns a list of all whisper messages based on filter ID since the last message retrieval + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter| + +#### Returns + +{`Array`} - array of message objects with the following members: + +- {[`Data[]`](#data)} `topics` - list of topics contained in the message +- {[`Data`](#data)} `from` - message sender +- {[`Data`](#data)} `hash` - message hash +- {[`Data`](#data)} `payload` - message payload +- {[`Data`](#data)} `to` - message recipient +- {[`Quantity`](#quantity)} `expiry` - time in seconds when this message expires +- {[`Quantity`](#quantity)} `sent` - unix timestamp when message was sent +- {[`Quantity`](#quantity)} `ttl` - message time to live in seconds +- {[`Quantity`](#quantity)} `workProved` - work required by this message + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_getFilterChanges", + "params": ["0x16"] +} + +// Response object +{ + "id": 1337, + "jsonrpc":"2.0", + "result": [{ + "expiry": "0x54caa50a", + "from": "0x3ec052fc33..", + "hash": "0x33eb2da77bf3527e28f8bf493650b1879b08c4f2a362beae4ba2f71bafcd91f9", + "payload": "0x7b2274797065223a226d657373616765222c2263686...", + "sent": "0x54ca9ea2", + "to": "0x87gdf76g8d7fgdfg...", + "topics": ["0x6578616d"], + "ttl": "0x64", + "workProved": "0x0" + }] +} +``` +--- +
+ +
+shh_getMessages + +#### Description + +Returns a list of all messages based on filter ID + +#### Parameters + +|#|Type|Description| +|-|-|-| +|1|{[`Quantity`](#quantity)}|ID of the filter| + +#### Returns + +{`Array`} - array of message objects with the following structure: + +- {[`Data[]`](#data)} `topics` - list of topics contained in the message +- {[`Data`](#data)} `from` - message sender +- {[`Data`](#data)} `hash` - message hash +- {[`Data`](#data)} `payload` - message payload +- {[`Data`](#data)} `to` - message recipient +- {[`Quantity`](#quantity)} `expiry` - time in seconds when this message expires +- {[`Quantity`](#quantity)} `sent` - unix timestamp when message was sent +- {[`Quantity`](#quantity)} `ttl` - message time to live in seconds +- {[`Quantity`](#quantity)} `workProved` - work required by this message + +#### Example + +```js +// Request object +{ + "id": 1337, + "jsonrpc": "2.0", + "method": "shh_getMessages", + "params": ["0x16"] +} + +// Response object +{ + "id": 1337, + "jsonrpc":"2.0", + "result": [{ + "expiry": "0x54caa50a", + "from": "0x3ec052fc33..", + "hash": "0x33eb2da77bf3527e28f8bf493650b1879b08c4f2a362beae4ba2f71bafcd91f9", + "payload": "0x7b2274797065223a226d657373616765222c2263686...", + "sent": "0x54ca9ea2", + "to": "0x87gdf76g8d7fgdfg...", + "topics": ["0x6578616d"], + "ttl": "0x64", + "workProved": "0x0" + }] +} +``` +--- +
+ +## Rationale + +Much of Ethereum's effectiveness as an enterprise-grade application platform depends on its ability to provide a reliable and predictable developer experience. Nodes created by the current generation of Ethereum clients expose RPC endpoints with differing method signatures; this forces applications to work around method inconsistencies to maintain compatibility with various Ethereum RPC implementations. + +Both Ethereum client developers and downstream dapp developers lack a formal Ethereum RPC specification. This proposal standardizes such a specification in a way that's versionable and modifiable through the traditional EIP process. + +## Backwards compatibility + +This proposal impacts Ethereum client developers by requiring that any exposed RPC interface adheres to this specification. This proposal impacts dapp developers by requiring that any RPC calls currently used in applications are made according to this specification. + +## Implementation + +The current generation of Ethereum clients includes several implementations that attempt to expose this RPC specification: + +|Client Name|Language|Homepage| +|-|-|-| +|Geth|Go|[geth.ethereum.org](https://geth.ethereum.org)| +|Parity|Rust|[parity.io](https://parity.io/ethereum)| +|Aleth|C++|[cpp-ethereum.org](https://cpp-ethereum.org)| + +## Copyright + +Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/). \ No newline at end of file