API-first Smart Contract Design

Table of Contents

• Run JSON RPC in Postman
• View the JSON RPC API
• Service Providers
• Schemas
• Connectivity to Ethereum Mainnet
  • Cloudflare JSON-RPC Gateway
• API Design Overview
• Events in Solidity
  • Example of Event Indexing
• DotEnv Configuration
• Topics
• Event parameters
• Event signature hash
• Topic filters
• Hyperledger Besu EVM API Objects
  • Block object
• Filter options object
• Log object
• Pending transaction object
• Private transaction object
• Range object
  • Structured log object
• Trace object
• Transaction object
• Transaction call object
• Transaction receipt object
• Transaction trace object
• Private transaction receipt object
  • Data Model
    • Projects and Named Resources
    • Data Model Resources
    • Combined Data Model
  • JSON RPC
  • 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
    • Methods
  • Rationale
  • Backwards compatibility
  • Implementation
  • 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
  • Motivation
  • Prior Art
  • Specification
    • Node API
    • Schema
  • Rationale
  • Backwards Compatibility
  • Test Cases
  • Implementation
  • Copyright

Run JSON RPC in Postman

View the JSON RPC API

View Postman Catalog

View the JSON RPC Catalog

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

Alchemyapi Referral

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

cloudflare-eth.com

cloudflare.com/distributed-web-gateway/#ethereum-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

Returned by eth_getBlockByHash and eth_getBlockByNumber.

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

Returned by txpool_besuPendingTransactions.

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

Returned by priv_getPrivateTransaction.

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

Returned by debug_traceBlock, debug_traceBlockByHash, debug_traceBlockByNumber, and debug_traceTransaction.

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

Returned by eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, and eth_getTransactionsByBlockNumberAndIndex.

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

Returned by eth_getTransactionReceipt.

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

Returned by trace_replayBlockTransactions.

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

Returned by priv_getTransactionReceipt.

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

• Implemented and released in Go-ethereum 1.9.0

• Implemented and released in Pantheon 1.1.1

• Work in progress in Trinity

• Work in progress in Parity

Copyright

Copyright and related rights waived via CC0.