This proposal defines a standard set of remote procedure call methods that an Ethereum node should 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
#### RFC-2119
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC-2119](https://www.ietf.org/rfc/rfc2119.txt).
#### 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|standard|
The RPC methods below take a default block identifier as a parameter.
-`eth_getBalance`
-`eth_getStorageAt`
-`eth_getTransactionCount`
-`eth_getCode`
-`eth_call`
-`eth_getProof`
Since there is no way to clearly distinguish between a `Data` parameter and a `Quantity` parameter, [EIP-1898](eip-1898.md) provides a format to specify a block either using the block hash or block number. The block identifier is a JSON `object` with the following fields:
|Property|Type|Description|
|-|-|-|
|`[blockNumber]`|{[`Quantity`](#quantity)}|The block in the canonical chain with this number|
|OR `[blockHash]`|{[`Data`](#data)}|The block uniquely identified by this hash. The `blockNumber` and `blockHash` properties are mutually exclusive; exactly one of them must be set.|
|`requireCanonical`|{`boolean`}|(optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the `blockHash` tag. Defaults to `false`.|
If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is `-32001: Resource not found`. If the tag is `blockHash` and `requireCanonical` is `true`, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is `-32000: Invalid input` and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.
- A `Data` value **MUST** be expressed using two hex digits per byte.
Examples `Data` values:
|Value|Valid|Reason|
|-|-|-|
|0x|`valid`|interpreted as empty data|
|0x0|`invalid`|each byte must be represented using two hex digits|
|0x00|`valid`|interpreted as a single zero byte|
|0x41|`true`|interpreted as a data value of 65|
|0x004200|`true`|interpreted as a data value of 16896|
|0xf0f0f|`false`|bytes require two hex digits|
|004200|`false`|values must be prefixed|
##### Proposing changes
New Ethereum RPC methods and changes to existing methods **MUST** be proposed via the traditional EIP process. This allows for community consensus around new method implementations and proposed method modifications. RPC method proposals **MUST** reach "draft" status before being added to this proposal and the official Ethereum RPC specification defined herein.
Executes a new message call immediately without submitting a transaction to the network
#### Parameters
|#|Type|Description|
|-|-|-|
|1|{`object`}|@property {[`Data`](#data)} `[from]` - transaction sender<br/>@property {[`Data`](#data)} `to` - transaction recipient or `null` if deploying a contract<br/>@property {[`Quantity`](#quantity)} `[gas]` - gas provided for transaction execution<br/>@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used<br/>@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction<br/>@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args|
|2|{[`Quantity`](#quantity)\|`string`\|[`Block Identifier`](#block-identifier)}|block number, or one of `"latest"`, `"earliest"` or `"pending"`, or a block identifier as described in [`Block Identifier`](#block-identifier)|
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<br/>@property {[`Data`](#data)} `[to]` - transaction recipient<br/>@property {[`Quantity`](#quantity)} `[gas]` - gas provided for transaction execution<br/>@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used<br/>@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction<br/>@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
|2|{[`Quantity`](#quantity)\|`string`\|[`Block Identifier`](#block-identifier)}|block number, or one of `"latest"`, `"earliest"` or `"pending"`, or a block identifier as described in [`Block Identifier`](#block-identifier)|
|2|{[`Quantity`](#quantity)\|`string`\|[`Block Identifier`](#block-identifier)}|block number, or one of `"latest"`, `"earliest"` or `"pending"`, or a block identifier as described in [`Block Identifier`](#block-identifier)|
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<Log>`} - 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.
{`Array<Log>`} - 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<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_getFilterLogs` when retrieving logs from `eth_newBlockFilter` and `eth_newPendingTransactionFilter` filters will be an array of hashes, not an array of Log objects.
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"`<br/>@property {[`Quantity`](#quantity)\|`string`} `[toBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`<br/>@property {[`Data`](#data)\|[`Data[]`](#data)} `[address]` - contract address or a list of addresses from which logs should originate<br/>@property {[`Data[]`](#data)} `[topics]` - list of order-dependent topics<br/>@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<Log>`} - 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.
|3|{[`Quantity`](#quantity)\|`string`\|[`Block Identifier`](#block-identifier)}|block number, or one of `"latest"`, `"earliest"` or `"pending"`, or a block identifier as described in [`Block Identifier`](#block-identifier)|
|2|{[`Quantity`](#quantity)\|`string`\|[`Block Identifier`](#block-identifier)}|block number, or one of `"latest"`, `"earliest"` or `"pending"`, or a block identifier as described in [`Block Identifier`](#block-identifier)|
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"`<br/>@property {[`Quantity`](#quantity)\|`string`} `[toBlock]` - block number, or one of `"latest"`, `"earliest"` or `"pending"`<br/>@property {[`Data`](#data)\|[`Data[]`](#data)} `[address]` - contract address or a list of addresses from which logs should originate<br/>@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`
Creates, signs, and sends a new transaction to the network
#### Parameters
|#|Type|Description|
|-|-|-|
|1|{`object`}|@property {[`Data`](#data)} `from` - transaction sender<br/>@property {[`Data`](#data)} `[to]` - transaction recipient<br/>@property {[`Quantity`](#quantity)} `[gas="0x15f90"]` - gas provided for transaction execution<br/>@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used<br/>@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction<br/>@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args<br/>@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
Signs a transaction that can be submitted to the network at a later time using with `eth_sendRawTransaction`
#### Parameters
|#|Type|Description|
|-|-|-|
|1|{`object`}|@property {[`Data`](#data)} `from` - transaction sender<br/>@property {[`Data`](#data)} `[to]` - transaction recipient<br/>@property {[`Quantity`](#quantity)} `[gas="0x15f90"]` - gas provided for transaction execution<br/>@property {[`Quantity`](#quantity)} `[gasPrice]` - price in wei of each gas used<br/>@property {[`Quantity`](#quantity)} `[value]` - value in wei sent with this transaction<br/>@property {[`Data`](#data)} `[data]` - contract code or a hashed method call with encoded args<br/>@property {[`Quantity`](#quantity)} `[nonce]` - unique number identifying this transaction|
#### Returns
{[`Data`](#data)} - signature hash of the transaction object
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
**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
```sh
# Request
curl -X POST --data '{
"id": 1337,
"jsonrpc": "2.0",
"method": "eth_uninstallFilter",
"params": ["0xb"]
}' <url>
# Response
{
"id": 1337,
"jsonrpc": "2.0",
"result": true
}
```
---
</details>
## 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:
