Skip to content

Solidity API contract design information for utilizing RPC/RESTful Node Interaction and GraphQL

Notifications You must be signed in to change notification settings

sambacha/ethereum-api

Repository files navigation

API-first Smart Contract Design

Table of Contents

Run JSON RPC in Postman

button

View the JSON RPC API

3 Main Ways of Designing an API for Contract Interaction

  • Direct RPC / IPC (e.g. direct polling to a client such as Geth)

  • 3rd Party Provider (e.g. Infura/Alchemey/Quicknode) also The Graph.

  • Middleware Client (e.g. Kafka Broker or some other MQ)

Service Providers

Schemas

Use these to help design how to best interact with a node

  • Truffle Contract Object

  • Chain State

  • Sample Postman API’s

  • Besu RPC Postman Deff.

Connectivity to Ethereum Mainnet

Cloudflare JSON-RPC Gateway

Setup DNS

Go to your DNS settings for your domain. If your website is on Cloudflare, the DNS settings are accessible from your dashboard. If your website is not on Cloudflare, and you need help finding the DNS records, see here.

Create CNAME Record Pointing to https://cloudflare-eth.com/

Add a CNAME record from your domain (e.g. www.example.com) to cloudflare-eth.com Note: if your website is on Cloudflare, the little cloud next to this record will automatically turn gray. Because you’ve CNAME’d to our gateway, you’ll automatically receive Cloudflare’s enterprise-level performance and security enhancements, but you won’t be able to control those settings yourself.

Once you have added those records: - Type your domain name (e.g. www.example.com) into the text box below and click "Submit".

This will generate an SSL certificate, which will allow traffic from your domain to be served securely over HTTPS. Be prepared to wait up to 90 seconds. You will receive a confirmation message when the certificate has been successfully issued. When this has been issued, then any Ethereum RPC query to your website will automatically resolve to https://cloudflare-eth.com/ and the response will be served from the Ethereum network.

Note: Ensure you have configured any CAA Policies to enable Cloudflare to issue a certificate

API Design Overview

  • JSON RPC

  • RESTful API

  • GraphQL

Transaction mining causes smart contracts to emit events and write logs to the blockchain.

The smart contract address is the link to the logs and the blockchain includes the logs, but contracts cannot access logs. Log storage is cheaper than contract storage (that is, it costs less gas) so storing and accessing the required data in logs reduces the cost. For example, use logs to display all transfers made using a specific contract, but not the current state of the contract.

A Dapp front end can either access logs using the JSON-RPC API filter methods or subscribe to logs using the RPC Pub/Sub API.

Use admin_generateLogBloomCache to improve log retrieval performance.

Events in Solidity

Solidity provides two types of events, anonymous and non-anonymous. The default is non-anonymous, and most developers will not need to worry about anonymous events.

For non-anonymous events, up to 3 topics may be indexed (instead of 4), since the first topic is reserved to specify the event signature. This allows non-anonymous events to always be filtered by their event signature.

This topic hash is always in the first slot of the indexed data, and is computed by normalizing the Event signature and taking the keccak256 hash of it.

For anonymous events, up to 4 topics may be indexed, and there is no signature topic hash, so the events cannot be filtered by the event signature.

Each additional indexed property is processed depending on whether its length is fixed or dynamic.

For fixed length types (e.g. uint, bytes5), all of which are internally exactly 32 bytes (shorter types are padded with zeros; numeric values are padded on the left, data values padded on the right), these are included directly by their actual value, 32 bytes of data.

For dynamic types (e.g. string, uint256[]) , the value is hashed using keccak256 and this hash is used.

Because dynamic types are hashed, there are important consequences in parsing events that should be kept in mind. Mainly that the original value is lost in the event. So, it is possible to tell is a topic is equal to a given string, but if they do not match, there is no way to determine what the value was.

If a developer requires that a string value is required to be both able to be filtered and also able to be read, the value must be included in the signature twice, once indexed and once non-indexed (e.g. someEvent(string indexed searchBy, string clearText)).

For a more detailed description, please refer to the https://docs.soliditylang.org/en/v0.8.1/abi-spec.html#events Solidity Event Documentation

Example of Event Indexing

// Short example of manually creating filters for an ERC-20
// Transfer event.
//
// Most users should generally use the Contract API to
// compute filters, as it is much simpler, but this is
// provided as an illustration for those curious. See
// below for examples of the equivalent Contract API.

// ERC-20:
//   Transfer(address indexed src, address indexed dst, uint val
//
// -------------------^
// ----------------------------------------^
//
// Notice that only *src* and *dst* are *indexed*, so ONLY they
// qualify for filtering.
//
// Also, note that in Solidity an Event uses the first topic to
// identify the Event name; for Transfer this will be:
//   id("Transfer(address,address,uint256)")
//
// Other Notes:
//  - A topic must be 32 bytes; so shorter types must be padded

// List all token transfers  *from*  myAddress
filter = {
    address: tokenAddress,
    topics: [
        id("Transfer(address,address,uint256)"),
        hexZeroPad(myAddress, 32)
    ]
}

// List all token transfers  *to*  myAddress:
filter = {
    address: tokenAddress,
    topics: [
        id("Transfer(address,address,uint256)"),
        null,
        hexZeroPad(myAddress, 32)
    ]
}

// List all token transfers  *to*  myAddress or myOtherAddress:
filter = {
    address: tokenAddress,
    topics: [
        id("Transfer(address,address,uint256)"),
        null,
        [
            hexZeroPad(myAddress, 32),
            hexZeroPad(myOtherAddress, 32),
        ]
    ]
}

DotEnv Configuration

These settings directly affect query/response time for Hyperledger Besu

BLOCKS_PER_BLOOM_CACHE=
export BESU_OPTS="--add-opens java.base/sun.security.provider=ALL-UNNAMED"
set BESU_OPTS="--add-opens java.base/sun.security.provider=ALL-UNNAMED"
BLOCKS_PER_BLOOM_CACHE
BESU_AUTO_LOG_BLOOM_CACHING_ENABLED=false
BESU_KEY_VALUE_STORAGE=rocksdb
BESU_LOGGING=DEBUG

Topics

Log entries contain up to four topics. The first topic is the event signature hash and up to three topics are the indexed event parameters.

Example 1

A log entry for an event with one indexed parameter:

{
  "logIndex": "0x0",
  "removed": false,
  "blockNumber": "0x84",
  "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336",
  "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a",
  "transactionIndex": "0x0",
  "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
  "data": "0x",
  "topics": [
    "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3",
    "0x0000000000000000000000000000000000000000000000000000000000000001"
  ]
}

Event parameters

Up to three event parameters can have the indexed attribute. Logs store these indexed parameters as topics. Indexed parameters are searchable and filterable.

Topics are 32 bytes. If an indexed argument is an array (including string and byte datatypes), the log stores the keccak-256 hash of the paramater as a topic.

Log data includes non-indexed parameters but is difficult to search or filter.

Example 2

A Solidity contract storing one indexed and one non-indexed parameter and has an event emitting the value of each parameter:

  • Storage.sol:

    pragma solidity ^0.5.1;
    contract Storage {
      uint256 public valueIndexed;
      uint256 public valueNotIndexed;
    
      event Event1(uint256 indexed valueIndexed, uint256 valueNotIndexed);
    
      function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public {
        valueIndexed = _valueIndexed;
        valueNotIndexed = _valueNotIndexed;
        emit Event1(_valueIndexed, _valueNotIndexed);
      }
    }

Example 3

A log entry created by invoking the contract in the previous example with valueIndexed set to 5 and valueNotIndexed set to 7:

 {
   "logIndex": "0x0",
   "removed": false,
   "blockNumber": "0x4d6",
   "blockHash": "0x7d0ac7c12ac9f622d346d444c7e0fa4dda8d4ed90de80d6a28814613a4884a67",
   "transactionHash": "0xe994022ada94371ace00c4e1e20663a01437846ced02f18b3f3afec827002781",
   "transactionIndex": "0x0",
   "address": "0x43d1f9096674b5722d359b6402381816d5b22f28",
   "data": "0x0000000000000000000000000000000000000000000000000000000000000007",
   "topics": [
    "0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8",
    "0x0000000000000000000000000000000000000000000000000000000000000005"
   ]
 }

Event signature hash

The first topic in a log entry is always the event signature hash. The event signature hash is a keccak-256 hash of the event name and input argument types, with argument names ignored. For example, the event Hello(uint256 worldId) has the signature hash keccak('Hello(uint256)'). The signature identifies to which event log topics belong.

Example 4

A Solidity contract with two different events:

  • Storage.sol:

    pragma solidity ^0.5.1;
    
    contract Storage {
    
    uint256 public valueA;
    uint256 public valueB;
    
         event Event1(uint256 indexed valueA);
         event Event2(uint256 indexed valueB);
    
         function setValue(uint256 _valueA) public {
           valueA = _valueA;
           emit Event1(_valueA);
         }
    
         function setValueAgain(uint256 _valueB) public {
           valueB = _valueB;
           emit Event2(_valueB);
         }
       }

The event signature hash for event 1 is keccak('Event1(uint256)') and the event signature hash for event 2 is keccak('Event2(uint256)'). The hashes are:

  • 04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3 for event 1

  • 06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e for event 2.

Informative

You can use a library keccak (sha3) hash function, such as provided in
[Web3.js](https://web3js.readthedocs.io/en/v1.2.11/web3-utils.html?highlight=sha3#sha3), or an online tool,
such as link:https://emn178.github.io/online-tools/keccak_256.html, to generate event signature
hashes.

Example 5

Log entries from invoking the Solidity contract in the previous example:

[
  {
    "logIndex": "0x0",
    "removed": false,
    "blockNumber": "0x84",
    "blockHash": "0x5fc573d76ec48ec80cbc43f299ebc306a8168112e3a4485c23e84e9a40f5d336",
    "transactionHash": "0xcb52f02342c2498df82c49ac26b2e91e182155c8b2a2add5b6dc4c249511f85a",
    "transactionIndex": "0x0",
    "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
    "data": "0x",
    "topics": [
      "0x04474795f5b996ff80cb47c148d4c5ccdbe09ef27551820caa9c2f8ed149cce3",
      "0x0000000000000000000000000000000000000000000000000000000000000001"
    ]
  },
  {
    "logIndex": "0x0",
    "removed": false,
    "blockNumber": "0x87",
    "blockHash": "0x6643a1e58ad857f727552e4572b837a85b3ca64c4799d085170c707e4dad5255",
    "transactionHash": "0xa95295fcea7df3b9e47ab95d2dadeb868145719ed9cc0e6c757c8a174e1fcb11",
    "transactionIndex": "0x0",
    "address": "0x42699a7612a82f1d9c36148af9c77354759b210b",
    "data": "0x",
    "topics": [
      "0x06df6fb2d6d0b17a870decb858cc46bf7b69142ab7b9318f7603ed3fd4ad240e",
      "0x0000000000000000000000000000000000000000000000000000000000000002"
    ]
  }
]

Topic filters

Filter options objects have a topics key to filter logs by topics.

Topics are order-dependent. A transaction with a log containing topics [A, B] matches with the following topic filters:

  • [] - Match any topic

  • [A] - Match A in first position

  • [[null], [B]] - Match any topic in first position AND B in second position

  • [[A],[B]] - Match A in first position AND B in second position

  • - Match (A OR C) in first position AND (B OR D) in second position.

Example 6

The following filter option object returns log entries for the [Event Parameters example contract](#event-parameters) with valueIndexed set to 5 or 9:

{
  "fromBlock":"earliest",
  "toBlock":"latest",
  "address":"0x43d1f9096674b5722d359b6402381816d5b22f28",
  "topics":[
   ["0xd3610b1c54575b7f4f0dc03d210b8ac55624ae007679b7a928a4f25a709331a8"],
   ["0x0000000000000000000000000000000000000000000000000000000000000005", "0x0000000000000000000000000000000000000000000000000000000000000009"]
  ]
}

Hyperledger Besu EVM API Objects

The following objects are parameters for or returned by Besu API methods.

Block object

Key Type Value

number

Quantity, Integer

Block number. null when block is pending.

hash

Data, 32 bytes

Hash of the block. null when block is pending.

parentHash

Data, 32 bytes

Hash of the parent block.

nonce

Data, 8 bytes

Hash of the generated proof of work. null when block is pending.

sha3Uncles

Data, 32 bytes

SHA3 of the uncle’s data in the block.

logsBloom

Data, 256 bytes

Bloom filter for the block logs. null when block is pending.

transactionsRoot

Data, 32 bytes

Root of the transaction trie for the block.

stateRoot

Data, 32 bytes

Root of the final state trie for the block.

receiptsRoot

Data, 32 bytes

Root of the receipts trie for the block.

miner

Data, 20 bytes

Address to pay mining rewards to.

difficulty

Quantity, Integer

Difficulty for this block.

totalDifficulty

Quantity, Integer

Total difficulty of the chain until this block.

extraData

Data

Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with Clique and IBFT.

size

Quantity, Integer

Size of block in bytes.

gasLimit

Quantity

Maximum gas allowed in this block.

gasUsed

Quantity

Total gas used by all transactions in this block.

timestamp

Quantity

Unix timestamp for block assembly.

transactions

Array

Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.

uncles

Array

Array of uncle hashes.

Filter options object

Parameter for eth_newFilter, eth_getLogs, and priv_getLogs. Used to filter logs.

Key Type Required/Optional Value

fromBlock

Quantity

Tag

Optional

Integer block number or latest, pending, earliest. See Block Parameter. Default is latest.

toBlock

Quantity

Tag

Optional

Integer block number or latest, pending, earliest. See Block Parameter. Default is latest.

address

Data

Array

Optional

Contract address or array of addresses from which logs originate.

topics

Array of Data, 32 bytes each

Optional

Array of topics by which to filter logs.

eth_getLogs and priv_getLogs have an extra key.

Key Type Required/Optional Value

blockhash

Data, 32 bytes

Optional.

Hash of block for which to return logs. If you specify blockhash, you cannot specify fromBlock and toBlock.

Log object

Returned by eth_getFilterChanges and priv_getLogs. Transaction receipt objects can contain an array of log objects.

Key Type Value

removed

Tag

true if log removed because of a chain reorganization. false if a valid log.

logIndex

Quantity, Integer

Log index position in the block. null when log is pending.

transactionIndex

Quantity, Integer

Index position of the starting transaction for the log. null when log is pending.

transactionHash

Data, 32 bytes

Hash of the starting transaction for the log. null when log is pending.

blockHash

Data, 32 bytes

Hash of the block that includes the log. null when log is pending.

blockNumber

Quantity

Number of block that includes the log. null when log is pending.

address

Data, 20 bytes

Address the log originated from.

data

Data

Non-indexed arguments of the log.

topics

Array of Data, 32 bytes each

Event signature hash and 0 to 3 indexed log arguments.

Pending transaction object

Key Type Value

from

Data, 20 bytes

Address of the sender.

gas

Quantity

Gas provided by the sender.

gasPrice

Quantity

Gas price, in wei, provided by the sender.

hash

Data, 32 bytes

Hash of the transaction.

input

Data

Data sent with the transaction to create or invoke a contract.

nonce

Quantity

Number of transactions made by the sender before this one.

to

Data, 20 bytes

Address of the receiver. null if a contract creation transaction.

value

Quantity

Value transferred, in wei.

v

Quantity

ECDSA Recovery ID.

r

Data, 32 bytes

ECDSA signature r.

s

Data, 32 bytes

ECDSA signature s.

Private transaction object

Key Type Value

from

Data, 20 bytes

Address of the sender.

gas

Quantity

Gas provided by the sender.

gasPrice

Quantity

Gas price, in Wei, provided by the sender.

hash

Data, 32 bytes

Hash of the transaction.

input

Data

The data to create or invoke a contract.

nonce

Quantity

Number of transactions made by the sender to the privacy group before this one.

to

Data, 20 bytes

null if a contract creation transaction, otherwise, the contract address.

value

Quantity

null because private transactions cannot transfer Ether.

v

Quantity

ECDSA Recovery ID.

r

Data, 32 bytes

ECDSA signature r.

s

Data, 32 bytes

ECDSA signature s.

privateFrom

Data, 32 bytes

Orion public key of the sender.

privateFor

Array of Data, 32 bytes each

Orion public keys of recipients. Not returned if using privacyGroupId to send the transaction.

privacyGroupId

Data, 32 bytes

Orion privacy group ID of recipients. Not returned if using privateFor to send the transaction.

restriction

String

Must be restricted.

Range object

Returned by debug_storageRangeAt.

Key Type Value

storage

Object

Key hash and value. Preimage key is null if it falls outside the cache.

nextKey

Hash

Hash of next key if further storage in range. Otherwise, not included.

Structured log object

Log information returned as part of the Trace object.

Key Type Value

pc

Integer

Current program counter.

op

String

Current OpCode.

gas

Integer

Gas remaining.

gasCost

Integer

Cost in wei of each gas unit.

depth

Integer

Execution depth.

exceptionalHaltReasons

Array

One or more strings representing an error condition causing the EVM execution to terminate. These strings suggest that EVM execution terminated for reasons such as running out of gas or attempting to execute an unknown instruction. Generally a single exceptional halt reason returns but it’s possible for more than one to occur at once.

stack

Array of 32 byte arrays

EVM execution stack before executing current operation.

memory

Array of 32 byte arrays

Memory space of the contract before executing current operation.

storage

Object

Storage entries changed by the current transaction.

Trace object

Key Type Value

gas

Integer

Gas used by the transaction.

failed

Boolean

True if transaction failed, otherwise, false.

returnValue

String

Bytes returned from transaction execution (without a 0x prefix).

structLogs

Array

Array of structured log objects.

Transaction object

Key Type Value

blockHash

Data, 32 bytes

Hash of the block containing this transaction. null when transaction is pending.

blockNumber

Quantity

Block number of the block containing this transaction. null when transaction is pending.

from

Data, 20 bytes

Address of the sender.

gas

Quantity

Gas provided by the sender.

gasPrice

Quantity

Gas price, in wei, provided by the sender.

hash

Data, 32 bytes

Hash of the transaction.

input

Data

Data sent with the transaction to create or invoke a contract. For private transactions, it’s a pointer to the transaction location in Orion.

nonce

Quantity

Number of transactions made by the sender before this one.

to

Data, 20 bytes

Address of the receiver. null if a contract creation transaction.

transactionIndex

Quantity, Integer

Index position of the transaction in the block. null when transaction is pending.

value

Quantity

Value transferred, in wei.

v

Quantity

ECDSA Recovery ID.

r

Data, 32 bytes

ECDSA signature r.

s

Data, 32 bytes

ECDSA signature s.

Transaction call object

Parameter for eth_call and eth_estimateGas.

!!!note

All parameters are optional for [`eth_estimateGas`](API-Methods.md#eth_estimategas).
Key Type Required/Optional Value

from

Data, 20 bytes

Optional

Address of the transaction sender.

to

Data, 20 bytes

Required

Address of the transaction receiver.

gas

Quantity, Integer

Optional

Gas provided for the transaction execution. eth_call consumes zero gas, but other executions might need this parameter. eth_estimateGas ignores this value.

gasPrice

Quantity, Integer

Optional

Price used for each paid gas.

value

Quantity, Integer

Optional

Value sent with this transaction.

data

Data

Optional

Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI.

Transaction receipt object

Key Type Value

blockHash

Data, 32 bytes

Hash of block containing this transaction.

blockNumber

Quantity

Block number of block containing this transaction.

contractAddress

Data, 20 bytes

Contract address created, if contract creation transaction, otherwise, null.

cumulativeGasUsed

Quantity

Total amount of gas used by previous transactions in the block and this transaction.

from

Data, 20 bytes

Address of the sender.

gasUsed

Quantity

Amount of gas used by this specific transaction.

logs

Array

Array of log objects generated by this transaction.

logsBloom

Data, 256 bytes

Bloom filter for light clients to quickly retrieve related logs.

status

Quantity

Either 0x1 (success) or 0x0 (failure)

to

Data, 20 bytes

Address of the receiver, if sending ether, otherwise, null.

transactionHash

Data, 32 bytes

Hash of the transaction.

transactionIndex

Quantity, Integer

Index position of transaction in the block.

revertReason

String

ABI-encoded string that displays the reason for reverting the transaction. Only available if revert reason is enabled.

!!!note

For pre-Byzantium transactions, the transaction receipt object includes the following instead
of `status`:
Key Type Value

root

Data, 32 bytes

Post-transaction stateroot

Transaction trace object

Key Type Value

output

Boolean

Transaction result. 1 for success and 0 for failure.

stateDiff

Object

State changes in the requested block.

trace

Array

Ordered list of calls to other contracts.

vmTrace

Object

Ordered list of EVM actions.

transactionHash

Data, 32 bytes

Hash of the replayed transaction.

Private transaction receipt object

Key Type Value

contractAddress

Data, 20 bytes

Contract address created if a contract creation transaction, otherwise, null.

from

Data, 20 bytes

Address of the sender.

output

Data

RLP-encoded return value of a contract call if a value returns, otherwise, null.

commitmentHash

Data, 32 bytes

Hash of the privacy marker transaction.

transactionHash

Data, 32 bytes

Hash of the private transaction.

privateFrom

Data, 32 bytes

Orion public key of the sender.

privateFor or privacyGroupId

Array or Data, 32 bytes

Orion public keys or privacy group ID of the recipients.

status

Quantity

Either 0x1 (success) or 0x0 (failure).

logs

Array

Array of log objects generated by this private transaction.

Data Model

This section serves to describe the relationships between the various components in an . It seeks to present an explicit set of named resource types and how they relate to one another.

This data model seeks to identify explicitly any implicit relationships and to add semantic color to these. It is a work in progress and likely to be incomplete and/or wrong.

Projects and Named Resources

Certain resources are named, meaning that these entities may be referenced by user-defined semantic identifiers. Since Truffle targets the full development lifecycle, this means names refer to different things at different times.

and , for example, both use names. These resources represent entities that change over time. Contracts are written, rewritten, and/or updated many times between a project’s start and past its production deployment. Development networks reset, and public networks fork.

To represent these entities across the entire project lifecycle, Truffle DB models names as a linked list of references to immutable entities.

Each Named resource contains the non-nullable string attribute name, used to index by type.

NameRecord can be considered generically to represent a linked list of current and past resource name references for a given resource type T. Each NameRecord has the same name, plus the following: - type to represent the underlying named resource type - resource to point to the underlying resource - previous to point to the previous name

In order to track the current NameRecords for a given type, the Project resource serves as the aggregation point for the heads of these linked lists.

!define SHOW_PROJECT !define SHOW_NAME_RECORD !define SHOW_NAME_RECORD_INTERNAL

!include uml/macros.iuml

Data Model Resources

Contracts, Constructors, and Instances

scale 0.75

!define SHOW_CONTRACT !define SHOW_INSTANCE !define SHOW_CONSTRUCTOR !define SHOW_INTERFACE

!define SHOW_COMPILATION !define EXTERN_COMPILATION !define SHOW_SOURCE_MAP

!define SHOW_BYTECODE !define EXTERN_BYTECODE

!define SHOW_NETWORK !define EXTERN_NETWORK

!include uml/macros.iuml

Sources, Bytecodes, and Compilations

scale 0.75

!define SHOW_CONTRACT !define EXTERN_CONTRACT

!define SHOW_BYTECODE !define SHOW_SOURCE !define SHOW_COMPILATION !define SHOW_COMPILER !define SHOW_SOURCE_MAP

!include uml/macros.iuml

Contract Interfaces

Contract Interfaces have not been implemented in the first version of Truffle DB, but will be added in a future iteration.

scale 0.75

!define SHOW_INTERFACE !define SHOW_INTERFACE_INTERNAL

!include uml/macros.iuml

Network

scale 0.75

!define SHOW_NETWORK !define SHOW_NETWORK_INTERNAL

!include uml/macros.iuml

A network resource comprises a friendly name, a network ID, and a known historic block.

Combined Data Model

scale 0.75

!define SHOW_PROJECT !define SHOW_NAME_RECORD !define SHOW_NETWORK !define SHOW_NETWORK_INTERNAL

!define SHOW_BYTECODE

!define SHOW_COMPILATION !define SHOW_COMPILER

!define SHOW_SOURCE

!define SHOW_CONTRACT !define SHOW_INTERFACE !define SHOW_INSTANCE !define SHOW_ABI !define SHOW_AST !define SHOW_INSTRUCTION !define SHOW_SOURCE_MAP !define SHOW_SOURCE_RANGE !define SHOW_CONSTRUCTOR

!include uml/macros.iuml

JSON RPC

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

eip: 1474 title: Remote procedure call specification author: Paul Bouchon [email protected], Erik Marks (@rekmarks) discussions-to: https://ethereum-magicians.org/t/eip-remote-procedure-call-specification/1537 status: Draft type: Standards Track category: Interface created: 2018-10-02

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.

JSON-RPC

Communication with Ethereum nodes is accomplished using JSON-RPC, a stateless, lightweight remote procedure call protocol that uses JSON as its data format. Ethereum RPC methods MUST be called using JSON-RPC request objects and MUST respond with JSON-RPC response objects.

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

-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

-32004

Method not supported

Method is not implemented

non-standard

-32005

Limit exceeded

Request exceeds defined limit

non-standard

-32006

JSON-RPC version not supported

Version of JSON-RPC protocol is not supported

non-standard

Example error response:

{
    "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 the fewest possible hex digits per byte.

  • A Quantity value MUST express zero as "0x0".

Examples Quantity values:

Value Valid Reason

0x

invalid

empty not a valid quantity

0x0

valid

interpreted as a quantity of zero

0x00

invalid

leading zeroes not allowed

0x41

valid

interpreted as a quantity of 65

0x400

valid

interpreted as a quantity of 1024

0x0400

invalid

leading zeroes not allowed

ff

invalid

values must be prefixed

Block Identifier

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 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}

The block in the canonical chain with this number

OR [blockHash]

\{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.

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.

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.

Methods

web3_clientVersion

Description

Returns the version of the current client

Parameters

(none)

Returns

\{string} - client version

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "web3_clientVersion",
    "params": [],
}' <url>

# Response
{
    "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 to hash

Returns

\{Data} - Keccak-256 hash of the given data

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "web3_sha3",
    "params": ["0x68656c6c6f20776f726c64"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xc94770007dda54cF92009BFF0dE90c06F603a09f"
}

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
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "net_listening",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": true
}

net_peerCount

Description

Returns the number of peers currently connected to this client

Parameters

(none)

Returns

\{Quantity} - number of connected peers

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "net_peerCount",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x2"
}

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 of possible chain IDs.

Example
# Request
curl -X POST --data '{
    "id": 1337
    "jsonrpc": "2.0",
    "method": "net_version",
    "params": [],
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "3"
}

eth_accounts

Description

Returns a list of addresses owned by this client

Parameters

(none)

Returns

\{Data[]} - array of addresses

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_accounts",
    "params": []
}' <url>

# Response
{
    "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} - number of the latest block

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_blockNumber",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xc94"
}

eth_call

Description

Executes a new message call immediately without submitting a transaction to the network

Parameters
# Type Description

1

\{object}

@property \{Data} [from] - transaction sender@property \{Data} to - transaction recipient or null if deploying a contract@property \{Quantity} [gas] - gas provided for transaction execution@property \{Quantity} [gasPrice] - price in wei of each gas used@property \{Quantity} [value] - value in wei sent with this transaction@property \{Data} [data] - contract code or a hashed method call with encoded args

2

\{Quantity

string

Returns

\{Data} - return value of executed contract

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_call",
    "params": [{
        "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
        "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
        "gas": "0x76c0",
        "gasPrice": "0x9184e72a000",
        "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        "value": "0x9184e72a"
    }]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x"
}

eth_coinbase

Description

Returns the coinbase address for this client

Parameters

(none)

Returns

\{Data} - coinbase address

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_coinbase",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xc94770007dda54cF92009BFF0dE90c06F603a09f"
}

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} [from] - transaction sender@property \{Data} [to] - transaction recipient@property \{Quantity} [gas] - gas provided for transaction execution@property \{Quantity} [gasPrice] - price in wei of each gas used@property \{Quantity} [value] - value in wei sent with this transaction@property \{Data} [data] - contract code or a hashed method call with encoded args

2

\{Quantity

string}

Returns

\{Quantity} - amount of gas required by transaction

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_estimateGas",
    "params": [{
        "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
        "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
        "gas": "0x76c0",
        "gasPrice": "0x9184e72a000",
        "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        "value": "0x9184e72a"
    }]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x5208"
}

eth_gasPrice

Description

Returns the current price of gas expressed in wei

Parameters

(none)

Returns

\{Quantity} - current gas price in wei

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_gasPrice",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x09184e72a000"
}

eth_getBalance

Description

Returns the balance of an address in wei

Parameters
# Type Description

1

\{Data}

address to query for balance

2

\{Quantity

string

Returns

\{Quantity} - balance of the provided account in wei

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x0234c8a3397aab58"
}

eth_getBlockByHash

Description

Returns information about a block specified by hash

Parameters
# Type Description

1

\{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} extraData - "extra data" field of this block

  • \{Data} hash - block hash or null if pending

  • \{Data} logsBloom - logs bloom filter or null if pending

  • \{Data} miner - address that received this block’s mining rewards

  • \{Data} nonce - proof-of-work hash or null if pending

  • \{Data} parentHash - parent block hash

  • \{Data} receiptsRoot -root of the this block’s receipts trie

  • \{Data} sha3Uncles - SHA3 of the uncles data in this block

  • \{Data} stateRoot - root of this block’s final state trie

  • \{Data} transactionsRoot - root of this block’s transaction trie

  • \{Quantity} difficulty - difficulty for this block

  • \{Quantity} gasLimit - maximum gas allowed in this block

  • \{Quantity} gasUsed - total used gas by all transactions in this block

  • \{Quantity} number - block number or null if pending

  • \{Quantity} size - size of this block in bytes

  • \{Quantity} timestamp - unix timestamp of when this block was collated

  • \{Quantity} totalDifficulty - total difficulty of the chain until this block

  • \{Array<Transaction>} transactions - list of transaction objects or hashes

  • \{Array<Transaction>} uncles - list of uncle hashes

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getBlockByHash",
    "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true]
}' <url>

# Response
{
    "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

string}

block number, or one of "latest", "earliest" or "pending"

2

\{boolean}

Returns

\{null|object} - null if no block is found, otherwise a block object with the following members:

  • \{Data} extraData - "extra data" field of this block

  • \{Data} hash - block hash or null if pending

  • \{Data} logsBloom - logs bloom filter or null if pending

  • \{Data} miner - address that received this block’s mining rewards

  • \{Data} nonce - proof-of-work hash or null if pending

  • \{Data} parentHash - parent block hash

  • \{Data} receiptsRoot -root of the this block’s receipts trie

  • \{Data} sha3Uncles - SHA3 of the uncles data in this block

  • \{Data} stateRoot - root of this block’s final state trie

  • \{Data} transactionsRoot - root of this block’s transaction trie

  • \{Quantity} difficulty - difficulty for this block

  • \{Quantity} gasLimit - maximum gas allowed in this block

  • \{Quantity} gasUsed - total used gas by all transactions in this block

  • \{Quantity} number - block number or null if pending

  • \{Quantity} size - size of this block in bytes

  • \{Quantity} timestamp - unix timestamp of when this block was collated

  • \{Quantity} totalDifficulty - total difficulty of the chain until this block

  • \{Array<Transaction>} transactions - list of transaction objects or hashes

  • \{Array<Transaction>} uncles - list of uncle hashes

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getBlockByNumber",
    "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true]
}' <url>

# Response
{
    "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_getBlockTransactionCountByHash

Description

Returns the number of transactions in a block specified by block hash

Parameters
# Type Description

1

\{Data}

hash of a block

Returns

\{Quantity} - number of transactions in the specified block

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByHash",
    "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"]
}' <url>

# Response
{
    "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

string}

Returns

\{Quantity} - number of transactions in the specified block

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getBlockTransactionCountByNumber",
    "params": ["0xe8"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xa"
}

eth_getCode

Description

Returns the contract code stored at a given address

Parameters
# Type Description

1

\{Data}

address to query for code

2

\{Quantity

string

Returns

\{Data} - code from the specified address

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getCode",
    "params": ["0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b", "0x2"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056"
}

eth_getFilterChanges

Description

Returns a list of all logs based on filter ID since the last log retrieval

Parameters
# Type Description

1

\{Quantity}

ID of the filter

Returns

\{Array<Log>} - array of log objects with the following members:

  • \{Data} address - address from which this log originated

  • \{Data} blockHash - hash of block containing this log or null if pending

  • \{Data} data - contains the non-indexed arguments of the log

  • \{Data} transactionHash - hash of the transaction that created this log or null if pending

  • \{Quantity} blockNumber - number of block containing this log or null if pending

  • \{Quantity} logIndex - index of this log within its block or null if pending

  • \{Quantity} transactionIndex - index of the transaction that created this log or null if pending

  • \{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
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getFilterChanges",
    "params": ["0x16"]
}' <url>

# Response
{
   "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}

ID of the filter

Returns

\{Array<Log>} - array of log objects with the following members:

  • \{Data} address - address from which this log originated

  • \{Data} blockHash - hash of block containing this log or null if pending

  • \{Data} data - contains the non-indexed arguments of the log

  • \{Data} transactionHash - hash of the transaction that created this log or null if pending

  • \{Quantity} blockNumber - number of block containing this log or null if pending

  • \{Quantity} logIndex - index of this log within its block or null if pending

  • \{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.

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getFilterLogs",
    "params": ["0x16"]
}' <url>

# Response
{
   "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

string} [fromBlock] - block number, or one of "latest", "earliest" or "pending"@property \{Quantity

string} [toBlock] - block number, or one of "latest", "earliest" or "pending"@property \{Data

Data[]} [address] - contract address or a list of addresses from which logs should originate@property \{Data[]} [topics] - list of order-dependent topics@property \{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} address - address from which this log originated

  • \{Data} blockHash - hash of block containing this log or null if pending

  • \{Data} data - contains the non-indexed arguments of the log

  • \{Data} transactionHash - hash of the transaction that created this log or null if pending

  • \{Quantity} blockNumber - number of block containing this log or null if pending

  • \{Quantity} logIndex - index of this log within its block or null if pending

  • \{Quantity} transactionIndex - index of the transaction that created this log or null if pending

  • \{Data} topics - list of order-dependent topics

  • \{boolean} removed - true if this filter has been destroyed and is invalid

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getLogs",
    "params": [{
        "topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"]
    }]
}' <url>

# Response
{
   "id": 1337,
   "jsonrpc": "2.0",
    "result": [{
        "address": "0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d",
        "blockHash": "0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d",
        "blockNumber":"0x1b4",
        "data":"0x0000000000000000000000000000000000000000000000000000000000000000",
        "logIndex": "0x1",
        "topics": [],
        "transactionHash":  "0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf",
        "transactionIndex": "0x0"
   }]
}

eth_getStorageAt

Description

Returns the value from a storage position at an address

Parameters
# Type Description

1

\{Data}

address of stored data

2

\{Quantity}

index into stored data

3

\{Quantity

string

Returns

\{Data} - value stored at the given address and data index

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getStorageAt",
    "params": ["0x295a70b2de5e3953354a6a8344e616ed314d7251", "0x0", "latest"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x00000000000000000000000000000000000000000000000000000000000004d2"
}

eth_getTransactionByBlockHashAndIndex

Description

Returns information about a transaction specified by block hash and transaction index

Parameters
# Type Description

1

\{Data}

hash of a block

2

\{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} r - ECDSA signature r

  • \{Data} s - ECDSA signature s

  • \{Data} blockHash - hash of block containing this transaction or null if pending

  • \{Data} from - transaction sender

  • \{Data} hash - hash of this transaction

  • \{Data} input - contract code or a hashed method call

  • \{Data} to - transaction recipient or null if deploying a contract

  • \{Quantity} v - ECDSA recovery ID

  • \{Quantity} blockNumber - number of block containing this transaction or null if pending

  • \{Quantity} gas - gas provided for transaction execution

  • \{Quantity} gasPrice - price in wei of each gas used

  • \{Quantity} nonce - unique number identifying this transaction

  • \{Quantity} transactionIndex - index of this transaction in the block or null if pending

  • \{Quantity} value - value in wei sent with this transaction

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByBlockHashAndIndex",
    "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", "0x0"]
}' <url>

# Response
{
    "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

string}

block number, or one of "latest", "earliest" or "pending"

2

\{Quantity}

Returns

\{null|object} - null if no transaction is found, otherwise a transaction object with the following members:

  • \{Data} r - ECDSA signature r

  • \{Data} s - ECDSA signature s

  • \{Data} blockHash - hash of block containing this transaction or null if pending

  • \{Data} from - transaction sender

  • \{Data} hash - hash of this transaction

  • \{Data} input - contract code or a hashed method call

  • \{Data} to - transaction recipient or null if deploying a contract

  • \{Quantity} v - ECDSA recovery ID

  • \{Quantity} blockNumber - number of block containing this transaction or null if pending

  • \{Quantity} gas - gas provided for transaction execution

  • \{Quantity} gasPrice - price in wei of each gas used

  • \{Quantity} nonce - unique number identifying this transaction

  • \{Quantity} transactionIndex - index of this transaction in the block or null if pending

  • \{Quantity} value - value in wei sent with this transaction

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByBlockNumberAndIndex",
    "params":["0x29c", "0x0"]
}' <url>

# Response
{
    "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_getTransactionByHash

Description

Returns information about a transaction specified by hash

Parameters
# Type Description

1

\{Data}

hash of a transaction

Returns

\{null|object} - null if no transaction is found, otherwise a transaction object with the following members:

  • \{Data} r - ECDSA signature r

  • \{Data} s - ECDSA signature s

  • \{Data} blockHash - hash of block containing this transaction or null if pending

  • \{Data} from - transaction sender

  • \{Data} hash - hash of this transaction

  • \{Data} input - contract code or a hashed method call

  • \{Data} to - transaction recipient or null if deploying a contract

  • \{Quantity} v - ECDSA recovery ID

  • \{Quantity} blockNumber - number of block containing this transaction or null if pending

  • \{Quantity} gas - gas provided for transaction execution

  • \{Quantity} gasPrice - price in wei of each gas used

  • \{Quantity} nonce - unique number identifying this transaction

  • \{Quantity} transactionIndex - index of this transaction in the block or null if pending

  • \{Quantity} value - value in wei sent with this transaction

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getTransactionByHash",
    "params": ["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"]
}' <url>

# Response
{
    "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_getTransactionCount

Description

Returns the number of transactions sent from an address

Parameters
# Type Description

1

\{Data}

address to query for sent transactions

2

\{Quantity

string

Returns

\{Quantity} - number of transactions sent from the specified address

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getTransactionCount",
    "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x1"
}

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}

hash of a transaction

Returns

\{null|object} - null if no transaction is found, otherwise a transaction receipt object with the following members:

  • \{Data} blockHash - hash of block containing this transaction

  • \{Data} contractAddress - address of new contract or null if no contract was created

  • \{Data} from - transaction sender

  • \{Data} logsBloom - logs bloom filter

  • \{Data} to - transaction recipient or null if deploying a contract

  • \{Data} transactionHash - hash of this transaction

  • \{Quantity} blockNumber - number of block containing this transaction

  • \{Quantity} cumulativeGasUsed - gas used by this and all preceding transactions in this block

  • \{Quantity} gasUsed - gas used by this transaction

  • \{Quantity} status - 1 if this transaction was successful or 0 if it failed

  • \{Quantity} transactionIndex - index of this transaction in the block

  • \{Array<Log>} logs - list of log objects generated by this transaction

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getTransactionReceipt",
    "params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"]
}' <url>

# Response
{
    "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}

hash of a block

2

\{Quantity}

index of uncle

Returns

\{null|object} - null if no block or uncle is found, otherwise an uncle object with the following members:

  • \{Data} extraData - "extra data" field of this block

  • \{Data} hash - block hash or null if pending

  • \{Data} logsBloom - logs bloom filter or null if pending

  • \{Data} miner - address that received this block’s mining rewards

  • \{Data} nonce - proof-of-work hash or null if pending

  • \{Data} parentHash - parent block hash

  • \{Data} receiptsRoot -root of the this block’s receipts trie

  • \{Data} sha3Uncles - SHA3 of the uncles data in this block

  • \{Data} stateRoot - root of this block’s final state trie

  • \{Data} transactionsRoot - root of this block’s transaction trie

  • \{Quantity} difficulty - difficulty for this block

  • \{Quantity} gasLimit - maximum gas allowed in this block

  • \{Quantity} gasUsed - total used gas by all transactions in this block

  • \{Quantity} number - block number or null if pending

  • \{Quantity} size - size of this block in bytes

  • \{Quantity} timestamp - unix timestamp of when this block was collated

  • \{Quantity} totalDifficulty - total difficulty of the chain until this block

  • \{Array<Transaction>} uncles - list of uncle hashes

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getUncleByBlockHashAndIndex",
    "params": ["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "0x0"]
}' <url>

# Response
{
    "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",
        "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
        "uncles": []
    }
}

eth_getUncleByBlockNumberAndIndex

Description

Returns information about an uncle specified by block number and uncle index position

Parameters
# Type Description

1

\{Quantity

string}

block number, or one of "latest", "earliest" or "pending"

2

\{Quantity}

Returns

\{null|object} - null if no block or uncle is found, otherwise an uncle object with the following members:

  • \{Data} extraData - "extra data" field of this block

  • \{Data} hash - block hash or null if pending

  • \{Data} logsBloom - logs bloom filter or null if pending

  • \{Data} miner - address that received this block’s mining rewards

  • \{Data} nonce - proof-of-work hash or null if pending

  • \{Data} parentHash - parent block hash

  • \{Data} receiptsRoot -root of the this block’s receipts trie

  • \{Data} sha3Uncles - SHA3 of the uncles data in this block

  • \{Data} stateRoot - root of this block’s final state trie

  • \{Data} transactionsRoot - root of this block’s transaction trie

  • \{Quantity} difficulty - difficulty for this block

  • \{Quantity} gasLimit - maximum gas allowed in this block

  • \{Quantity} gasUsed - total used gas by all transactions in this block

  • \{Quantity} number - block number or null if pending

  • \{Quantity} size - size of this block in bytes

  • \{Quantity} timestamp - unix timestamp of when this block was collated

  • \{Quantity} totalDifficulty - total difficulty of the chain until this block

  • \{Array<Transaction>} uncles - list of uncle hashes

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getUncleByBlockNumberAndIndex",
    "params": ["0x29c", "0x0"]
}' <url>

# Response
{
    "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",
        "transactionsRoot": "0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421",
        "uncles": []
    }
}

eth_getUncleCountByBlockHash

Description

Returns the number of uncles in a block specified by block hash

Parameters
# Type Description

1

\{Data}

hash of a block

Returns

\{Quantity} - number of uncles in the specified block

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getUncleCountByBlockHash",
    "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"]
}' <url>

# Response
{
    "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

string}

Returns

\{Quantity} - number of uncles in the specified block

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getUncleCountByBlockNumber",
    "params": ["0xe8"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x1"
}

eth_getWork

Description

Returns a list containing relevant information for proof-of-work

Parameters

none

Returns

\{Data[]} - array with the following items:

  1. \{Data} - current block header pow-hash

  2. \{Data} - seed hash used for the DAG

  3. \{Data} - boundary condition ("target"), 2^256 / difficulty

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_getWork",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": [
        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "0x5EED00000000000000000000000000005EED0000000000000000000000000000",
        "0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000"
    ]
}

eth_hashrate

Description

Returns the number of hashes-per-second this node is mining at

Parameters

(none)

Returns

\{Quantity} - number of hashes-per-second

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_hashrate",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x38a"
}

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
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_mining",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": true
}

eth_newBlockFilter

Description

Creates a filter to listen for new blocks that can be used with eth_getFilterChanges

Parameters

none

Returns

\{Quantity} - ID of the newly-created filter that can be used with eth_getFilterChanges

Example
# Request
curl -X POST --data '{
    "id": 1337
    "jsonrpc": "2.0",
    "method": "eth_newBlockFilter",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "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

string} [fromBlock] - block number, or one of "latest", "earliest" or "pending"@property \{Quantity

string} [toBlock] - block number, or one of "latest", "earliest" or "pending"@property \{Data

Data[]} [address] - contract address or a list of addresses from which logs should originate@property \{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 OR B) in first position AND (A OR B) in second position (and anything after)"

Returns

\{Quantity} - ID of the newly-created filter that can be used with eth_getFilterChanges

Example
# Request
curl -X POST --data '{
    "id": 1337
    "jsonrpc": "2.0",
    "method": "eth_newFilter",
    "params": [{
        "topics": ["0x0000000000000000000000000000000000000000000000000000000012341234"]
    }]
}' <url>

# Response
{
    "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} - ID of the newly-created filter that can be used with eth_getFilterChanges

Example
# Request
curl -X POST --data '{
    "id": 1337
    "jsonrpc": "2.0",
    "method": "eth_newPendingTransactionFilter",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x1"
}

eth_protocolVersion

Description

Returns the current Ethereum protocol version

Parameters

(none)

Returns

\{string} - current Ethereum protocol version

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_protocolVersion",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "54"
}

eth_sendRawTransaction

Description

Sends and already-signed transaction to the network

Parameters
# Type Description

1

\{Data}

signed transaction data

Returns

\{Data} - transaction hash, or the zero hash if the transaction is not yet available

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_sendRawTransaction",
    "params": ["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

eth_sendTransaction

Description

Creates, signs, and sends a new transaction to the network

Parameters
# Type Description

1

\{object}

@property \{Data} from - transaction sender@property \{Data} [to] - transaction recipient@property \{Quantity} [gas="0x15f90"] - gas provided for transaction execution@property \{Quantity} [gasPrice] - price in wei of each gas used@property \{Quantity} [value] - value in wei sent with this transaction@property \{Data} [data] - contract code or a hashed method call with encoded args@property \{Quantity} [nonce] - unique number identifying this transaction

Returns

\{Data} - transaction hash, or the zero hash if the transaction is not yet available

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_sendTransaction",
    "params": [{
        "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
        "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
        "gas": "0x76c0",
        "gasPrice": "0x9184e72a000",
        "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        "value": "0x9184e72a"
    }]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

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}

address to use for signing

2

\{Data}

data to sign

Returns

\{Data} - signature hash of the provided data

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_sign",
    "params": ["0x9b2055d370f73ec7d8a03e965129118dc8f5bf83", "0xdeadbeaf"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b"
}

eth_signTransaction

Description

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} from - transaction sender@property \{Data} [to] - transaction recipient@property \{Quantity} [gas="0x15f90"] - gas provided for transaction execution@property \{Quantity} [gasPrice] - price in wei of each gas used@property \{Quantity} [value] - value in wei sent with this transaction@property \{Data} [data] - contract code or a hashed method call with encoded args@property \{Quantity} [nonce] - unique number identifying this transaction

Returns

\{Data} - signature hash of the transaction object

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_signTransaction",
    "params": [{
        "data": "0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675",
        "from": "0xb60e8dd61c5d32be8058bb8eb970870f07233155",
        "gas": "0x76c0",
        "gasPrice": "0x9184e72a000",
        "to": "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
        "value": "0x9184e72a"
    }]
}' <url>

# Response
{
    "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}

address to use for signing

2

\{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. Dapp developers should refer to EIP-712 for the expected structure of RPC method input parameters.

Returns

\{Data} - signature hash of the provided message

Example
# Request
curl -X POST --data '{
    "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!"
        }
    }]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": "0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c"
}

eth_submitHashrate

Description

Submit a mining hashrate

Parameters
# Type Description

1

\{Data}

hash rate

2

\{Data}

random ID identifying this node

Returns

\{boolean} - true if submitting went through successfully, false otherwise

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_submitHashrate",
    "params": [
        "0x0000000000000000000000000000000000000000000000000000000000500000",
        "0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c"
    ]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": true
}

eth_submitWork

Description

Submit a proof-of-work solution

Parameters
# Type Description

1

\{Data}

nonce found

2

\{Data}

header’s pow-hash

3

\{Data}

mix digest

Returns

\{boolean} - true if the provided solution is valid, false otherwise

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_submitWork",
    "params": [
        "0x0000000000000001",
        "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000"
    ]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": true
}

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} currentBlock - number of the most-recent block synced

  • \{Quantity} highestBlock - number of latest block on the network

  • \{Quantity} startingBlock - block number at which syncing started

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_syncing",
    "params": []
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": {
        "currentBlock": '0x386',
        "highestBlock": '0x454',
        "startingBlock": '0x384'
    }
}

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}

ID of the filter to destroy

Returns

\{boolean} - true if the filter is found and successfully destroyed or false if it is not

Example
# Request
curl -X POST --data '{
    "id": 1337,
    "jsonrpc": "2.0",
    "method": "eth_uninstallFilter",
    "params": ["0xb"]
}' <url>

# Response
{
    "id": 1337,
    "jsonrpc": "2.0",
    "result": true
}

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

Parity

Rust

parity.io/ethereum

Aleth

C++

cpp-ethereum.org


eip: 1767 title: GraphQL interface to Ethereum node data author: Nick Johnson (@arachnid), Raúl Kripalani (@raulk), Kris Shinn (@kshinn) discussions-to: https://ethereum-magicians.org/t/graphql-interface-to-ethereum-node-data/2710 status: Draft type: Standards Track category: Interface created: 2019-02-14

GraphQL

This EIP specifies a GraphQL schema for accessing data stored on an Ethereum node. It aims to provide a complete replacement to the read-only information exposed via the present JSON-RPC interface, while improving on usability, consistency, efficiency, and future-proofing.

Motivation

The current JSON-RPC interface for Ethereum nodes has a number of shortcomings. It’s informally and incompletely specified in areas, which has led to incompatibilities around issues such as representation of empty byte strings ("" vs "0x" vs "0x0"), and it has to make educated guesses about the data a user will request, which often leads to unnecessary work.

For example, the totalDifficulty field is stored separately from the block header in common Ethereum node implementations, and many callers do not require this field. However, every call to eth_getBlock still retrieves this field, requiring a separate disk read, because the RPC server has no way of knowing if the user requires this field or not.

Similarly, transaction receipts in go-ethereum are stored on disk as a single binary blob for each block. Fetching a receipt for a single transaction requires fetching and deserializing this blob, then finding the relevant entry and returning it; this is accomplished by the eth_getTransactionReceipt API call. A common task for API consumers is to fetch all the receipts in a block; as a result, node implementations end up fetching and deserializing the same data repeatedly, leading to O(n^2) effort to fetch all transaction receipts from a block instead of O(n).

Some of these issues could be fixed with changes to the existing JSON-RPC interface, at the cost of complicating the interface somewhat. Instead, we propose adopting a standard query language, GraphQL, which facilitates more efficient API implementations, while also increasing flexibility.

Prior Art

Nick Johnson and EthQL independently developed a GraphQL schema for node data. Once the parties were made aware of the shared effort, they made efforts to bring their schemas into alignment. The current schema proposed in this EIP is derived primarily from the EthQL schema.

Specification

Node API

Compatible nodes MUST provide a GraphQL endpoint available over HTTP. This SHOULD be offered on port 8547 by default. The path to the GraphQL endpoint SHOULD be '/graphql'.

Compatible nodes MAY offer a GraphiQL interactive query explorer on the root path ('/').

Schema

The GraphQL schema for this service is defined as follows:

# Bytes32 is a 32 byte binary string, represented as 0x-prefixed hexadecimal.
scalar Bytes32
# Address is a 20 byte Ethereum address, represented as 0x-prefixed hexadecimal.
scalar Address
# Bytes is an arbitrary length binary string, represented as 0x-prefixed hexadecimal.
# An empty byte string is represented as '0x'. Byte strings must have an even number of hexadecimal nybbles.
scalar Bytes
# BigInt is a large integer. Input is accepted as either a JSON number or as a string.
# Strings may be either decimal or 0x-prefixed hexadecimal. Output values are all
# 0x-prefixed hexadecimal.
scalar BigInt
# Long is a 64 bit unsigned integer.
scalar Long

schema {
    query: Query
    mutation: Mutation
}

# Account is an Ethereum account at a particular block.
type Account {
    # Address is the address owning the account.
    address: Address!
    # Balance is the balance of the account, in wei.
    balance: BigInt!
    # TransactionCount is the number of transactions sent from this account,
    # or in the case of a contract, the number of contracts created. Otherwise
    # known as the nonce.
    transactionCount: Long!
    # Code contains the smart contract code for this account, if the account
    # is a (non-self-destructed) contract.
    code: Bytes!
    # Storage provides access to the storage of a contract account, indexed
    # by its 32 byte slot identifier.
    storage(slot: Bytes32!): Bytes32!
}

# Log is an Ethereum event log.
type Log {
    # Index is the index of this log in the block.
    index: Int!
    # Account is the account which generated this log - this will always
    # be a contract account.
    account(block: Long): Account!
    # Topics is a list of 0-4 indexed topics for the log.
    topics: [Bytes32!]!
    # Data is unindexed data for this log.
    data: Bytes!
    # Transaction is the transaction that generated this log entry.
    transaction: Transaction!
}

# Transaction is an Ethereum transaction.
type Transaction {
    # Hash is the hash of this transaction.
    hash: Bytes32!
    # Nonce is the nonce of the account this transaction was generated with.
    nonce: Long!
    # Index is the index of this transaction in the parent block. This will
    # be null if the transaction has not yet been mined.
    index: Int
    # From is the account that sent this transaction - this will always be
    # an externally owned account.
    from(block: Long): Account!
    # To is the account the transaction was sent to. This is null for
    # contract-creating transactions.
    to(block: Long): Account
    # Value is the value, in wei, sent along with this transaction.
    value: BigInt!
    # GasPrice is the price offered to miners for gas, in wei per unit.
    gasPrice: BigInt!
    # Gas is the maximum amount of gas this transaction can consume.
    gas: Long!
    # InputData is the data supplied to the target of the transaction.
    inputData: Bytes!
    # Block is the block this transaction was mined in. This will be null if
    # the transaction has not yet been mined.
    block: Block

    # Status is the return status of the transaction. This will be 1 if the
    # transaction succeeded, or 0 if it failed (due to a revert, or due to
    # running out of gas). If the transaction has not yet been mined, this
    # field will be null.
    status: Long
    # GasUsed is the amount of gas that was used processing this transaction.
    # If the transaction has not yet been mined, this field will be null.
    gasUsed: Long
    # CumulativeGasUsed is the total gas used in the block up to and including
    # this transaction. If the transaction has not yet been mined, this field
    # will be null.
    cumulativeGasUsed: Long
    # CreatedContract is the account that was created by a contract creation
    # transaction. If the transaction was not a contract creation transaction,
    # or it has not yet been mined, this field will be null.
    createdContract(block: Long): Account
    # Logs is a list of log entries emitted by this transaction. If the
    # transaction has not yet been mined, this field will be null.
    logs: [Log!]
}

# BlockFilterCriteria encapsulates log filter criteria for a filter applied
# to a single block.
input BlockFilterCriteria {
    # Addresses is list of addresses that are of interest. If this list is
    # empty, results will not be filtered by address.
    addresses: [Address!]
    # Topics list restricts matches to particular event topics. Each event has a list
  # of topics. Topics matches a prefix of that list. An empty element array matches any
  # topic. Non-empty elements represent an alternative that matches any of the
  # contained topics.
  #
  # Examples:
  #  - [] or nil          matches any topic list
  #  - [[A]]              matches topic A in first position
  #  - [[], [B]]          matches any topic in first position, B in second position
  #  - [[A], [B]]         matches topic A in first position, B in second position
  #  - [[A, B]], [C, D]]  matches topic (A OR B) in first position, (C OR D) in second position
    topics: [[Bytes32!]!]
}

# Block is an Ethereum block.
type Block {
    # Number is the number of this block, starting at 0 for the genesis block.
    number: Long!
    # Hash is the block hash of this block.
    hash: Bytes32!
    # Parent is the parent block of this block.
    parent: Block
    # Nonce is the block nonce, an 8 byte sequence determined by the miner.
    nonce: Bytes!
    # TransactionsRoot is the keccak256 hash of the root of the trie of transactions in this block.
    transactionsRoot: Bytes32!
    # TransactionCount is the number of transactions in this block. if
    # transactions are not available for this block, this field will be null.
    transactionCount: Int
    # StateRoot is the keccak256 hash of the state trie after this block was processed.
    stateRoot: Bytes32!
    # ReceiptsRoot is the keccak256 hash of the trie of transaction receipts in this block.
    receiptsRoot: Bytes32!
    # Miner is the account that mined this block.
    miner(block: Long): Account!
    # ExtraData is an arbitrary data field supplied by the miner.
    extraData: Bytes!
    # GasLimit is the maximum amount of gas that was available to transactions in this block.
    gasLimit: Long!
    # GasUsed is the amount of gas that was used executing transactions in this block.
    gasUsed: Long!
    # Timestamp is the unix timestamp at which this block was mined.
    timestamp: BigInt!
    # LogsBloom is a bloom filter that can be used to check if a block may
    # contain log entries matching a filter.
    logsBloom: Bytes!
    # MixHash is the hash that was used as an input to the PoW process.
    mixHash: Bytes32!
    # Difficulty is a measure of the difficulty of mining this block.
    difficulty: BigInt!
    # TotalDifficulty is the sum of all difficulty values up to and including
    # this block.
    totalDifficulty: BigInt!
    # OmmerCount is the number of ommers (AKA uncles) associated with this
    # block. If ommers are unavailable, this field will be null.
    ommerCount: Int
    # Ommers is a list of ommer (AKA uncle) blocks associated with this block.
    # If ommers are unavailable, this field will be null. Depending on your
    # node, the transactions, transactionAt, transactionCount, ommers,
    # ommerCount and ommerAt fields may not be available on any ommer blocks.
    ommers: [Block]
    # OmmerAt returns the ommer (AKA uncle) at the specified index. If ommers
    # are unavailable, or the index is out of bounds, this field will be null.
    ommerAt(index: Int!): Block
    # OmmerHash is the keccak256 hash of all the ommers (AKA uncles)
    # associated with this block.
    ommerHash: Bytes32!
    # Transactions is a list of transactions associated with this block. If
    # transactions are unavailable for this block, this field will be null.
    transactions: [Transaction!]
    # TransactionAt returns the transaction at the specified index. If
    # transactions are unavailable for this block, or if the index is out of
    # bounds, this field will be null.
    transactionAt(index: Int!): Transaction
    # Logs returns a filtered set of logs from this block.
    logs(filter: BlockFilterCriteria!): [Log!]!
    # Account fetches an Ethereum account at the current block's state.
    account(address: Address!): Account
    # Call executes a local call operation at the current block's state.
    call(data: CallData!): CallResult
    # EstimateGas estimates the amount of gas that will be required for
    # successful execution of a transaction at the current block's state.
    estimateGas(data: CallData!): Long!
}

# CallData represents the data associated with a local contract call.
# All fields are optional.
input CallData {
    # From is the address making the call.
    from: Address
    # To is the address the call is sent to.
    to: Address
    # Gas is the amount of gas sent with the call.
    gas: Long
    # GasPrice is the price, in wei, offered for each unit of gas.
    gasPrice: BigInt
    # Value is the value, in wei, sent along with the call.
    value: BigInt
    # Data is the data sent to the callee.
    data: Bytes
}

# CallResult is the result of a local call operation.
type CallResult {
    # Data is the return data of the called contract.
    data: Bytes!
    # GasUsed is the amount of gas used by the call, after any refunds.
    gasUsed: Long!
    # Status is the result of the call - 1 for success or 0 for failure.
    status: Long!
}

# FilterCriteria encapsulates log filter criteria for searching log entries.
input FilterCriteria {
    # FromBlock is the block at which to start searching, inclusive. Defaults
    # to the latest block if not supplied.
    fromBlock: Long
    # ToBlock is the block at which to stop searching, inclusive. Defaults
    # to the latest block if not supplied.
    toBlock: Long
    # Addresses is a list of addresses that are of interest. If this list is
    # empty, results will not be filtered by address.
    addresses: [Address!]
    # Topics list restricts matches to particular event topics. Each event has a list
  # of topics. Topics matches a prefix of that list. An empty element array matches any
  # topic. Non-empty elements represent an alternative that matches any of the
  # contained topics.
  #
  # Examples:
  #  - [] or nil          matches any topic list
  #  - [[A]]              matches topic A in first position
  #  - [[], [B]]          matches any topic in first position, B in second position
  #  - [[A], [B]]         matches topic A in first position, B in second position
  #  - [[A, B]], [C, D]]  matches topic (A OR B) in first position, (C OR D) in second position
    topics: [[Bytes32!]!]
}

# SyncState contains the current synchronisation state of the client.
type SyncState{
    # StartingBlock is the block number at which synchronisation started.
    startingBlock: Long!
    # CurrentBlock is the point at which synchronisation has presently reached.
    currentBlock: Long!
    # HighestBlock is the latest known block number.
    highestBlock: Long!
    # PulledStates is the number of state entries fetched so far, or null
    # if this is not known or not relevant.
    pulledStates: Long
    # KnownStates is the number of states the node knows of so far, or null
    # if this is not known or not relevant.
    knownStates: Long
}

# Pending represents the current pending state.
type Pending {
  # TransactionCount is the number of transactions in the pending state.
  transactionCount: Int!
  # Transactions is a list of transactions in the current pending state.
  transactions: [Transaction!]
  # Account fetches an Ethereum account for the pending state.
  account(address: Address!): Account
  # Call executes a local call operation for the pending state.
  call(data: CallData!): CallResult
  # EstimateGas estimates the amount of gas that will be required for
  # successful execution of a transaction for the pending state.
  estimateGas(data: CallData!): Long!
}

type Query {
    # Block fetches an Ethereum block by number or by hash. If neither is
    # supplied, the most recent known block is returned.
    block(number: Long, hash: Bytes32): Block
    # Blocks returns all the blocks between two numbers, inclusive. If
    # to is not supplied, it defaults to the most recent known block.
    blocks(from: Long!, to: Long): [Block!]!
    # Pending returns the current pending state.
    pending: Pending!
    # Transaction returns a transaction specified by its hash.
    transaction(hash: Bytes32!): Transaction
    # Logs returns log entries matching the provided filter.
    logs(filter: FilterCriteria!): [Log!]!
    # GasPrice returns the node's estimate of a gas price sufficient to
    # ensure a transaction is mined in a timely fashion.
    gasPrice: BigInt!
    # ProtocolVersion returns the current wire protocol version number.
    protocolVersion: Int!
    # Syncing returns information on the current synchronisation state.
    syncing: SyncState
}

type Mutation {
    # SendRawTransaction sends an RLP-encoded transaction to the network.
    sendRawTransaction(data: Bytes!): Bytes32!
}

Nodes MAY offer a superset of this schema, by adding new fields or types. Experimental or client-specific fields MUST be prefixed with 'client' (eg, 'geth' or 'parity'). Unprefixed fields MUST be specified in a new EIP that extends this one.

Rationale

Ethereum nodes have been moving away from providing read-write functionality such as transaction and message signing, and from other services such as code compilation, in favor of a more 'unix-like' approach where each task is performed by a dedicated process. We have thus specified a core set of types and fields that reflects this trend, leaving out functionality that is presently, or intended to be, deprecated:

  • eth_compile* calls are deprecated, and hence not provided here.

  • eth_accounts, eth_sign, and eth_sendTransaction are considered by many to be deprecated, and are not provided here; callers should use local accounts or a separate signing daemon instead.

Further, two areas of the current API interface have been omitted for simplicity in this initial standard, with the intention that they will be defined in a later EIP:

  • Filters will require use of GraphQL subscriptions, and require careful consideration around the desire for nodes without local per-caller state.

  • Mining functionality is less-used and benefits less from reimplementation in GraphQL, and should be specified in a separate EIP.

Backwards Compatibility

This schema implements the bulk of the current read-only functionality provided by the JSON-RPC node interface. Existing RPC calls can be mapped to GraphQL queries as follows:

RPC Status Description

eth_blockNumber

IMPLEMENTED

{ block { number } }

eth_call

IMPLEMENTED

{ call(data: { to: "0x…​", data: "0x…​" }) { data status gasUsed } }

eth_estimateGas

IMPLEMENTED

{ estimateGas(data: { to: "0x…​", data: "0x…​" }) }

eth_gasPrice

IMPLEMENTED

{ gasPrice }

eth_getBalance

IMPLEMENTED

{ account(address: "0x…​") { balance } }

eth_getBlockByHash

IMPLEMENTED

{ block(hash: "0x…​") { …​ } }

eth_getBlockByNumber

IMPLEMENTED

{ block(number: 123) { …​ } }

eth_getBlockTransactionCountByHash

IMPLEMENTED

{ block(hash: "0x…​") { transactionCount } }

eth_getBlockTransactionCountByNumber

IMPLEMENTED

{ block(number: x) { transactionCounnt } }

eth_getCode

IMPLEMENTED

{ account(address: "0x…​") { code } }

eth_getLogs

IMPLEMENTED

{ logs(filter: { …​ }) { …​ } } or { block(…​) { logs(filter: { …​ }) { …​ } } }

eth_getStorageAt

IMPLEMENTED

{ account(address: "0x…​") { storage(slot: "0x…​") } }

eth_getTransactionByBlockHashAndIndex

IMPLEMENTED

{ block(hash: "0x…​") { transactionAt(index: x) { …​ } } }

eth_getTransactionByBlockNumberAndIndex

IMPLEMENTED

{ block(number: n) { transactionAt(index: x) { …​ } } }

eth_getTransactionByHash

IMPLEMENTED

{ transaction(hash: "0x…​") { …​ } }

eth_getTransactionCount

IMPLEMENTED

{ account(address: "0x…​") { transactionCount } }

eth_getTransactionReceipt

IMPLEMENTED

{ transaction(hash: "0x…​") { …​ } }

eth_getUncleByBlockHashAndIndex

IMPLEMENTED

{ block(hash: "0x…​") { ommerAt(index: x) { …​ } } }

eth_getUncleByBlockNumberAndIndex

IMPLEMENTED

{ block(number: n) { ommerAt(index: x) { …​ } } }

eth_getUncleCountByBlockHash

IMPLEMENTED

{ block(hash: "0x…​") { ommerCount } }

eth_getUncleCountByBlockNumber

IMPLEMENTED

{ block(number: x) { ommerCount } }

eth_protocolVersion

IMPLEMENTED

{ protocolVersion }

eth_sendRawTransaction

IMPLEMENTED

mutation { sendRawTransaction(data: data) }

eth_syncing

IMPLEMENTED

{ syncing { …​ } }

eth_getCompilers

NOT IMPLEMENTED

Compiler functionality is deprecated in JSON-RPC.

eth_compileLLL

NOT IMPLEMENTED

Compiler functionality is deprecated in JSON-RPC.

eth_compileSolidity

NOT IMPLEMENTED

Compiler functionality is deprecated in JSON-RPC.

eth_compileSerpent

NOT IMPLEMENTED

Compiler functionality is deprecated in JSON-RPC.

eth_newFilter

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_newBlockFilter

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_newPendingTransactionFilter

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_uninstallFilter

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_getFilterChanges

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_getFilterLogs

NOT IMPLEMENTED

Filter functionality may be specified in a future EIP.

eth_accounts

NOT IMPLEMENTED

Accounts functionality is not part of the core node API.

eth_sign

NOT IMPLEMENTED

Accounts functionality is not part of the core node API.

eth_sendTransaction

NOT IMPLEMENTED

Accounts functionality is not part of the core node API.

eth_coinbase

NOT IMPLEMENTED

Mining functionality to be defined separately.

eth_getWork

NOT IMPLEMENTED

Mining functionality to be defined separately.

eth_hashRate

NOT IMPLEMENTED

Mining functionality to be defined separately.

eth_mining

NOT IMPLEMENTED

Mining functionality to be defined separately.

eth_submitHashrate

NOT IMPLEMENTED

Mining functionality to be defined separately.

eth_submitWork

NOT IMPLEMENTED

Mining functionality to be defined separately.

For specific reasoning behind omitted functionality, see the Rationale section.

Test Cases

TBD.

Implementation

Copyright and related rights waived via CC0.