:url-project: https://sambacha.github.io/besu-api :url-docs: https://sambacha.github.io/besu-api :url-org: https://sambacha.github.io/ :url-group: {url-org}/besu-api :url-site-readme: {url-group}/besu-api/blob/master/README.adoc :url-besu: https://besu.hyperledger.org/ :public-key: /gpg/6F6EB43E.asc :active-key: {url-group}{public-key} :docbook:

:toc: = API-first Smart Contract Design

== Run JSON RPC in Postman

image::https://run.pstmn.io/button.svg[link="https://god.postman.co/run-collection/1231c564d4789c586507"]

== View the JSON RPC API

link:https://api.besu.io[View Postman Catalog]

link:https://sambacha.github.io/besu-api/[View the JSON RPC Catalog]

:description: Optimizing solidity contracts for API access, focusing on Hyperledger Besu

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

link:https://dashboard.alchemyapi.io/signup?referral=496d4069-ca19-4c95-9cee-cd15c699a355[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

link:cloudflare-eth.com/[cloudflare-eth.com]

link:https://www.cloudflare.com/distributed-web-gateway/#ethereum-gateway[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 xref:../HowTo/Interact/Filters/Accessing-Logs-Using-JSON-RPC.adoc[JSON-RPC API filter methods] or subscribe to logs using the link:../HowTo/Interact/APIs/RPC-PubSub.md#logs[RPC Pub/Sub API].

Use link:../Reference/API-Methods.md#admin_generatelogbloomcache[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

[source, javascript]

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

[source, cfg]

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,event signature hash>> and up to three topics are the indexed <<event-parameters,event parameters>>.

Example 1

A log entry for an event with one indexed parameter:

[source,json]

{
"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:

[source, solidity]

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:

[source,json]

{
"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:

[source, solidity]

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, 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:

[source, json]

[
{
"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

link:../Reference/API-Objects.md#filter-options-object[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
[[A, C], [B, D]] - 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 with valueIndexed set to 5 or 9:

[source, json]

{
"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 link:API-Methods.md#eth_getblockbyhash[eth_getBlockByHash] and link:API-Methods.md#eth_getblockbynumber[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 link:../Reference/CLI/CLI-Syntax.md#miner-extra-data[--miner-extra-data] command line option. Stores extra data when used with link:../HowTo/Configure/Consensus-Protocols/Clique.md#genesis-file[Clique] and link:../HowTo/Configure/Consensus-Protocols/IBFT.md#genesis-file[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-object,transaction objects>>, or 32 byte transaction hashes depending on the specified boolean parameter.

| uncles | Array | Array of uncle hashes. |===

= Filter options object

Parameter for link:API-Methods.md#eth_newfilter[eth_newFilter], link:API-Methods.md#eth_getlogs[eth_getLogs], and link:API-Methods.md#priv_getlogs[priv_getLogs]. Used to link:../HowTo/Interact/Filters/Accessing-Logs-Using-JSON-RPC.xml[filter logs].

link:API-Methods.md#eth_getlogs[eth_getLogs] and link:API-Methods.md#priv_getlogs[priv_getLogs] have an extra key.

= Log object

Returned by link:API-Methods.md#eth_getfilterchanges[eth_getFilterChanges] and link:API-Methods.md#priv_getlogs[priv_getLogs]. <<transaction-receipt-object,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 | link:../Concepts/Events-and-Logs.md#event-signature-hash[Event signature hash] and 0 to 3 link:../Concepts/Events-and-Logs.md#event-parameters[indexed log arguments]. |===

= Pending transaction object

Returned by link:API-Methods.md#txpool_besupendingtransactions[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 link:API-Methods.md#priv_getprivatetransaction[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 | https://docs.orion.pegasys.tech/en/stable/[Orion] public key of the sender.

| privateFor | Array of Data, 32 bytes each | https://docs.orion.pegasys.tech/en/stable/[Orion] public keys of recipients. Not returned if using privacyGroupId to link:../Concepts/Privacy/Privacy-Groups.md#privacy-types[send the transaction].

| privacyGroupId | Data, 32 bytes | https://docs.orion.pegasys.tech/en/stable/[Orion] privacy group ID of recipients. Not returned if using privateFor to link:../Concepts/Privacy/Privacy-Groups.md#privacy-types[send the transaction].

| restriction | String | Must be link:../Concepts/Privacy/Private-Transactions.xml[restricted]. |===

= Range object

Returned by link:API-Methods.md#debug_storagerangeat[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,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 link:API-Methods.md#debug_traceblock[debug_traceBlock], link:API-Methods.md#debug_traceblockbyhash[debug_traceBlockByHash], link:API-Methods.md#debug_traceblockbynumber[debug_traceBlockByNumber], and link:API-Methods.md#debug_tracetransaction[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 link:API-Methods.md#eth_gettransactionbyhash[eth_getTransactionByHash], link:API-Methods.md#eth_gettransactionbyblockhashandindex[eth_getTransactionByBlockHashAndIndex], and link:API-Methods.md#eth_gettransactionbyblocknumberandindex[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 link:../Concepts/Privacy/Privacy-Overview.xml[private transactions], it's a pointer to the transaction location in https://docs.orion.pegasys.tech/en/stable/[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 link:API-Methods.md#eth_call[eth_call] and link:API-Methods.md#eth_estimategas[eth_estimateGas].

!!!note

All parameters are optional for eth_estimateGas.

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

= Transaction receipt object

Returned by link:API-Methods.md#eth_gettransactionreceipt[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-object,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 link:../HowTo/Send-Transactions/Revert-Reason.xml[reason for reverting the transaction]. Only available if revert reason is link:../Reference/CLI/CLI-Syntax.md#revert-reason-enabled[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 link:API-Methods.md#trace_replayblocktransactions[trace_replayBlockTransactions].

|=== | Key | Type | Value

| output | Boolean | Transaction result. 1 for success and 0 for failure.

| stateDiff | Object | link:Trace-Types.md#statediff[State changes in the requested block].

| trace | Array | link:Trace-Types.md#trace[Ordered list of calls to other contracts].

| vmTrace | Object | link:Trace-Types.md#vmtrace[Ordered list of EVM actions].

| transactionHash | Data, 32 bytes | Hash of the replayed transaction. |===

= Private transaction receipt object

Returned by link:API-Methods.md#priv_getTransactionReceipt[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 | https://docs.orion.pegasys.tech/en/stable/[Orion] public key of the sender.

| privateFor or privacyGroupId | Array or Data, 32 bytes | https://docs.orion.pegasys.tech/en/stable/[Orion] public keys or privacy group ID of the recipients.

| status | Quantity | Either 0x1 (success) or 0x0 (failure).

| logs | Array | Array of <<log-object,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-mailbitpshrnet-erik-marks-rekmarks-discussions-to-httpsethereum-magiciansorgteip-remote-procedure-call-specification1537-status-draft-type-standards-track-category-interface-created-2018-10-02]] ==== 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[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 https://www.ietf.org/rfc/rfc2119.txt[RFC-2119].

==== JSON-RPC

Communication with Ethereum nodes is accomplished using https://www.jsonrpc.org/specification[JSON-RPC], a stateless, lightweight https://en.wikipedia.org/wiki/Remote_procedure_call[remote procedure call] protocol that uses http://www.json.org/[JSON] as its data format. Ethereum RPC methods MUST be called using https://www.jsonrpc.org/specification#request_object[JSON-RPC request objects] and MUST respond with https://www.jsonrpc.org/specification#response_object[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:

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

Example error response:

[source,sh]

{
"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:

===== 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, link:./eip-1898.md[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:

[cols=",,",options="header",] |=== |Property |Type |Description |[blockNumber] |{link:#quantity[Quantity]} |The block in the canonical chain with this number

|OR [blockHash] |{link:#data[Data]} |The block uniquely identified by this hash. The blockNumber and blockHash properties are mutually exclusive; exactly one of them must be set.

|requireCanonical |{boolean} |(optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the blockHash tag. Defaults to false. |===

If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is -32001: Resource not found. If the tag is blockHash and requireCanonical is true, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is -32000: Invalid input and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.

===== 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:

===== Proposing changes

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

===== Returns

{link:#data[Data]} - return value of executed contract

===== Example

[source,sh]

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" }] }'

Response

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

'''''

==== eth_coinbase

===== Description

Returns the coinbase address for this client

===== Parameters

(none)

===== Returns

{link:#data[Data]} - coinbase address

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_coinbase", "params": [] }'

Response

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

'''''

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

'''''

==== eth_getBlockByHash

===== Description

Returns information about a block specified by hash

===== Parameters

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |hash of a block

|2 |{boolean} |true will pull full transaction objects, false will pull transaction hashes |===

===== Returns

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

{link:#data[Data]} extraData - "extra data" field of this block
{link:#data[Data]} hash - block hash or null if pending
{link:#data[Data]} logsBloom - logs bloom filter or null if
pending
{link:#data[Data]} miner - address that received this block's
mining rewards
{link:#data[Data]} nonce - proof-of-work hash or null if
pending
{link:#data[Data]} parentHash - parent block hash
{link:#data[Data]} receiptsRoot -root of the this block's
receipts trie
{link:#data[Data]} sha3Uncles - SHA3 of the uncles data in this
block
{link:#data[Data]} stateRoot - root of this block's final state
trie
{link:#data[Data]} transactionsRoot - root of this block's
transaction trie
{link:#quantity[Quantity]} difficulty - difficulty for this block
{link:#quantity[Quantity]} gasLimit - maximum gas allowed in this
block
{link:#quantity[Quantity]} gasUsed - total used gas by all
transactions in this block
{link:#quantity[Quantity]} number - block number or null if
pending
{link:#quantity[Quantity]} size - size of this block in bytes
{link:#quantity[Quantity]} timestamp - unix timestamp of when
this block was collated
{link:#quantity[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

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getBlockByHash", "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", true] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#quantity[Quantity]|string} |block number, or one of "latest", "earliest" or "pending"

|2 |{boolean} |true will pull full transaction objects, false will pull transaction hashes |===

===== Returns

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

{link:#data[Data]} extraData - "extra data" field of this block
{link:#data[Data]} hash - block hash or null if pending
{link:#data[Data]} logsBloom - logs bloom filter or null if
pending
{link:#data[Data]} miner - address that received this block's
mining rewards
{link:#data[Data]} nonce - proof-of-work hash or null if
pending
{link:#data[Data]} parentHash - parent block hash
{link:#data[Data]} receiptsRoot -root of the this block's
receipts trie
{link:#data[Data]} sha3Uncles - SHA3 of the uncles data in this
block
{link:#data[Data]} stateRoot - root of this block's final state
trie
{link:#data[Data]} transactionsRoot - root of this block's
transaction trie
{link:#quantity[Quantity]} difficulty - difficulty for this block
{link:#quantity[Quantity]} gasLimit - maximum gas allowed in this
block
{link:#quantity[Quantity]} gasUsed - total used gas by all
transactions in this block
{link:#quantity[Quantity]} number - block number or null if
pending
{link:#quantity[Quantity]} size - size of this block in bytes
{link:#quantity[Quantity]} timestamp - unix timestamp of when
this block was collated
{link:#quantity[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

{link:#data[Data]} address - address from which this log
originated
{link:#data[Data]} blockHash - hash of block containing this log
or null if pending
{link:#data[Data]} data - contains the non-indexed arguments of
the log
{link:#data[Data]} transactionHash - hash of the transaction that
created this log or null if pending
{link:#quantity[Quantity]} blockNumber - number of block
containing this log or null if pending
{link:#quantity[Quantity]} logIndex - index of this log within
its block or null if pending
{link:#quantity[Quantity]} transactionIndex - index of the
transaction that created this log or null if pending
{link:#data[Data[]]} topics - list of order-dependent topics
{boolean} removed - true if this filter has been destroyed and
is invalid

Note: The return value of eth_getFilterChanges when retrieving logs from eth_newBlockFilter and eth_newPendingTransactionFilter filters will be an array of hashes, not an array of Log objects.

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getFilterChanges", "params": ["0x16"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#quantity[Quantity]} |ID of the filter |===

===== Returns

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

{link:#data[Data]} address - address from which this log originated
{link:#data[Data]} blockHash - hash of block containing this log or
null if pending
{link:#data[Data]} data - contains the non-indexed arguments of the
log
{link:#data[Data]} transactionHash - hash of the transaction that
created this log or null if pending
{link:#quantity[Quantity]} blockNumber - number of block containing
this log or null if pending
{link:#quantity[Quantity]} logIndex - index of this log within its
block or null if pending
{link:#quantity[Quantity]} transactionIndex - index of the
transaction that created this log or null if pending
{Array<Data>} topics - list of order-dependent topics
{boolean} removed - true if this filter has been destroyed and is
invalid

Note: The return value of eth_getFilterLogs when retrieving logs from eth_newBlockFilter and eth_newPendingTransactionFilter filters will be an array of hashes, not an array of Log objects.

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getFilterLogs", "params": ["0x16"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{object} |@property {link:#quantity[Quantity]|string} [fromBlock] - block number, or one of "latest", "earliest" or "pending"@property {link:#quantity[Quantity]|string} [toBlock]

block number, or one of "latest", "earliest" or
"pending"@property {link:#data[Data]|link:#data[Data[]]}
[address] - contract address or a list of addresses from which logs
should originate@property {link:#data[Data[]]} [topics] - list of
order-dependent topics@property {link:#data[Data]} [blockhash] -
restrict logs to a block by hash
|===

Note: If blockhash is passed, neither fromBlock nor toBlock are allowed or respected.

===== Returns

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

{link:#data[Data]} address - address from which this log
originated
{link:#data[Data]} blockHash - hash of block containing this log
or null if pending
{link:#data[Data]} data - contains the non-indexed arguments of
the log
{link:#data[Data]} transactionHash - hash of the transaction that
created this log or null if pending
{link:#quantity[Quantity]} blockNumber - number of block
containing this log or null if pending
{link:#quantity[Quantity]} logIndex - index of this log within
its block or null if pending
{link:#quantity[Quantity]} transactionIndex - index of the
transaction that created this log or null if pending
{link:#data[Data]} topics - list of order-dependent topics
{boolean} removed - true if this filter has been destroyed and
is invalid

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getLogs", "params": [{ "topics":["0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b"] }] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |address of stored data

|2 |{link:#quantity[Quantity]} |index into stored data

|3 |{link:#quantity[Quantity]|string|link:#block-identifier[Block Identifier]} |block number, or one of "latest", "earliest" or "pending", or a block identifier as described in link:#block-identifier[Block Identifier] |===

===== Returns

{link:#data[Data]} - value stored at the given address and data index

===== Example

[source,sh]

Request

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

Response

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

'''''

==== eth_getTransactionByBlockHashAndIndex

===== Description

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

===== Parameters

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |hash of a block

|2 |{link:#quantity[Quantity]} |index of a transaction in the specified block |===

===== Returns

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

{link:#data[Data]} r - ECDSA signature r
{link:#data[Data]} s - ECDSA signature s
{link:#data[Data]} blockHash - hash of block containing this
transaction or null if pending
{link:#data[Data]} from - transaction sender
{link:#data[Data]} hash - hash of this transaction
{link:#data[Data]} input - contract code or a hashed method call
{link:#data[Data]} to - transaction recipient or null if
deploying a contract
{link:#quantity[Quantity]} v - ECDSA recovery ID
{link:#quantity[Quantity]} blockNumber - number of block
containing this transaction or null if pending
{link:#quantity[Quantity]} gas - gas provided for transaction
execution
{link:#quantity[Quantity]} gasPrice - price in wei of each gas
used
{link:#quantity[Quantity]} nonce - unique number identifying this
transaction
{link:#quantity[Quantity]} transactionIndex - index of this
transaction in the block or null if pending
{link:#quantity[Quantity]} value - value in wei sent with this
transaction

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getTransactionByBlockHashAndIndex", "params":["0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331", "0x0"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#quantity[Quantity]|string} |block number, or one of "latest", "earliest" or "pending"

|2 |{link:#quantity[Quantity]} |index of a transaction in the specified block |===

===== Returns

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

{link:#data[Data]} r - ECDSA signature r
{link:#data[Data]} s - ECDSA signature s
{link:#data[Data]} blockHash - hash of block containing this
transaction or null if pending
{link:#data[Data]} from - transaction sender
{link:#data[Data]} hash - hash of this transaction
{link:#data[Data]} input - contract code or a hashed method call
{link:#data[Data]} to - transaction recipient or null if
deploying a contract
{link:#quantity[Quantity]} v - ECDSA recovery ID
{link:#quantity[Quantity]} blockNumber - number of block
containing this transaction or null if pending
{link:#quantity[Quantity]} gas - gas provided for transaction
execution
{link:#quantity[Quantity]} gasPrice - price in wei of each gas
used
{link:#quantity[Quantity]} nonce - unique number identifying this
transaction
{link:#quantity[Quantity]} transactionIndex - index of this
transaction in the block or null if pending
{link:#quantity[Quantity]} value - value in wei sent with this
transaction

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getTransactionByBlockNumberAndIndex", "params":["0x29c", "0x0"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |hash of a transaction |===

===== Returns

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

{link:#data[Data]} r - ECDSA signature r
{link:#data[Data]} s - ECDSA signature s
{link:#data[Data]} blockHash - hash of block containing this
transaction or null if pending
{link:#data[Data]} from - transaction sender
{link:#data[Data]} hash - hash of this transaction
{link:#data[Data]} input - contract code or a hashed method call
{link:#data[Data]} to - transaction recipient or null if
deploying a contract
{link:#quantity[Quantity]} v - ECDSA recovery ID
{link:#quantity[Quantity]} blockNumber - number of block
containing this transaction or null if pending
{link:#quantity[Quantity]} gas - gas provided for transaction
execution
{link:#quantity[Quantity]} gasPrice - price in wei of each gas
used
{link:#quantity[Quantity]} nonce - unique number identifying this
transaction
{link:#quantity[Quantity]} transactionIndex - index of this
transaction in the block or null if pending
{link:#quantity[Quantity]} value - value in wei sent with this
transaction

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getTransactionByHash", "params": ["0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |address to query for sent transactions

===== Returns

{link:#quantity[Quantity]} - number of transactions sent from the specified address

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getTransactionCount", "params": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f", "latest"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |hash of a transaction |===

===== Returns

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

{link:#data[Data]} blockHash - hash of block containing this
transaction
{link:#data[Data]} contractAddress - address of new contract or
null if no contract was created
{link:#data[Data]} from - transaction sender
{link:#data[Data]} logsBloom - logs bloom filter
{link:#data[Data]} to - transaction recipient or null if
deploying a contract
{link:#data[Data]} transactionHash - hash of this transaction
{link:#quantity[Quantity]} blockNumber - number of block
containing this transaction
{link:#quantity[Quantity]} cumulativeGasUsed - gas used by this
and all preceding transactions in this block
{link:#quantity[Quantity]} gasUsed - gas used by this transaction
{link:#quantity[Quantity]} status - 1 if this transaction was
successful or 0 if it failed
{link:#quantity[Quantity]} transactionIndex - index of this
transaction in the block
{Array<Log>} logs - list of log objects generated by this
transaction

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getTransactionReceipt", "params": ["0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#data[Data]} |hash of a block |2 |{link:#quantity[Quantity]} |index of uncle |===

===== Returns

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

{link:#data[Data]} extraData - "extra data" field of this block
{link:#data[Data]} hash - block hash or null if pending
{link:#data[Data]} logsBloom - logs bloom filter or null if
pending
{link:#data[Data]} miner - address that received this block's
mining rewards
{link:#data[Data]} nonce - proof-of-work hash or null if
pending
{link:#data[Data]} parentHash - parent block hash
{link:#data[Data]} receiptsRoot -root of the this block's
receipts trie
{link:#data[Data]} sha3Uncles - SHA3 of the uncles data in this
block
{link:#data[Data]} stateRoot - root of this block's final state
trie
{link:#data[Data]} transactionsRoot - root of this block's
transaction trie
{link:#quantity[Quantity]} difficulty - difficulty for this block
{link:#quantity[Quantity]} gasLimit - maximum gas allowed in this
block
{link:#quantity[Quantity]} gasUsed - total used gas by all
transactions in this block
{link:#quantity[Quantity]} number - block number or null if
pending
{link:#quantity[Quantity]} size - size of this block in bytes
{link:#quantity[Quantity]} timestamp - unix timestamp of when
this block was collated
{link:#quantity[Quantity]} totalDifficulty - total difficulty of
the chain until this block
{Array<Transaction>} uncles - list of uncle hashes

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_getUncleByBlockHashAndIndex", "params": ["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b", "0x0"] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#quantity[Quantity]|string} |block number, or one of "latest", "earliest" or "pending"

|2 |{link:#quantity[Quantity]} |index of uncle |===

===== Returns

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

{link:#data[Data]} extraData - "extra data" field of this block
{link:#data[Data]} hash - block hash or null if pending
{link:#data[Data]} logsBloom - logs bloom filter or null if
pending
{link:#data[Data]} miner - address that received this block's
mining rewards
{link:#data[Data]} nonce - proof-of-work hash or null if
pending
{link:#data[Data]} parentHash - parent block hash
{link:#data[Data]} receiptsRoot -root of the this block's
receipts trie
{link:#data[Data]} sha3Uncles - SHA3 of the uncles data in this
block
{link:#data[Data]} stateRoot - root of this block's final state
trie
{link:#data[Data]} transactionsRoot - root of this block's
transaction trie
{link:#quantity[Quantity]} difficulty - difficulty for this block
{link:#quantity[Quantity]} gasLimit - maximum gas allowed in this
block
{link:#quantity[Quantity]} gasUsed - total used gas by all
transactions in this block
{link:#quantity[Quantity]} number - block number or null if
pending
{link:#quantity[Quantity]} size - size of this block in bytes
{link:#quantity[Quantity]} timestamp - unix timestamp of when
this block was collated
{link:#quantity[Quantity]} totalDifficulty - total difficulty of
the chain until this block
{Array<Transaction>} uncles - list of uncle hashes

[] - "anything"
[A] - "A in first position (and anything after)"
[null, B] - "anything in first position AND B in second position
(and anything after)"
[A, B] - "A in first position AND B in second position (and anything
after)"
[[A, B], [A, B]] - "(A OR B) in first position AND (A OR B) in
second position (and anything after)"

{link:#data[Data]} - signature hash of the transaction object

===== Example

[source,sh]

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" }] }'

Response

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

'''''

{
"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:

{link:#quantity[Quantity]} currentBlock - number of the
most-recent block synced
{link:#quantity[Quantity]} highestBlock - number of latest block
on the network
{link:#quantity[Quantity]} startingBlock - block number at which
syncing started

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_syncing", "params": [] }'

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

[cols=",,",options="header",] |=== |# |Type |Description |1 |{link:#quantity[Quantity]} |ID of the filter to destroy |===

===== Returns

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

===== Example

[source,sh]

Request

curl -X POST --data '{ "id": 1337, "jsonrpc": "2.0", "method": "eth_uninstallFilter", "params": ["0xb"] }'

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:

'''''

[[eip-1767-title-graphql-interface-to-ethereum-node-data-author-nick-johnson-arachnid-raúl-kripalani-raulk-kris-shinn-kshinn-discussions-to-httpsethereum-magiciansorgtgraphql-interface-to-ethereum-node-data2710-status-draft-type-standards-track-category-interface-created-2019-02-14]] == 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[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 https://github.com/ConsenSys/ethql[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:

[cols=",,",options="header",] |=== |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
https://github.com/ethereum/go-ethereum/releases/tag/v1.9.0[Go-ethereum
1.9.0]
Implemented and released in
https://github.com/PegaSysEng/pantheon/blob/master/CHANGELOG.md#111[Pantheon
1.1.1]
Work in progress in
https://github.com/ethereum/trinity/issues/302[Trinity]
Work in progress in
https://github.com/paritytech/parity-ethereum/issues/10933[Parity]

== Copyright

Related Projects

blockhead

An open-source interface for the decentralized web. Track, visualize and explore EVM-based blockc...

22 Oct 2020 114

weth-invariant-testing

05 Feb 2023 270

viewfinder

One API for most EVM blockchain explorers & their clones

19 Apr 2022 8

solidity-cheatsheet

Cheat sheet and best practices for solidity. Write smart contracts for Ethereum.

21 Nov 2017 1,432

solidity-shell

An interactive Solidity Shell

30 Aug 2021 545

dune-snippets

dune snippets is a collection of sql queries for duneanalytics.com / Google BigQuery

26 Apr 2020 145

ctf-blockchain

A summary of 200+ CTF blockchain challenges

08 Dec 2021 803

ethereum.rb

Ethereum library for the Ruby language

25 Nov 2016 730

metatx

A smart contract to enable ERC-20 token meta-transactions on Ethereum.

02 Jul 2021 43

statesweep

18 Nov 2016 12

portal-network-specs

Official repository for specifications for the Portal Network

22 Jan 2020 272

hardhat-gas-reporter

Gas Usage Analytics for Hardhat

20 Jun 2019 411

full-blockchain-solidity-course-js

Learn Blockchain, Solidity, and Full Stack Web3 Development with Javascript

17 Jan 2022 12,404

q-evm

MEV Bot and Flashbots Bundler written in q using kdb+

17 Apr 2022 393

blockchain

blockchain (crypto) tools, libraries & scripts in ruby

16 Sep 2017 215

ethereum-api

[source, javascript]

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

[source, cfg]

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

[source,json]

[source, solidity]

function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public { valueIndexed = _valueIndexed; valueNotIndexed = _valueNotIndexed; emit Event1(_valueIndexed, _valueNotIndexed); } }

[source,json]

[source, solidity]

}

[source, json]

[source, json]

[source,sh]

{ "id": 1337 "jsonrpc": "2.0", "error": { "code": -32003, "message": "Transaction rejected" } }

[source,sh]

Request

Response

{ "id": 1337, "jsonrpc": "2.0", "result": "Mist/v0.9.3/darwin/go1.4.1" }

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

{ "id": 1337, "jsonrpc": "2.0", "result": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"] }

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

[source,sh]

Request

Response

[source,sh]

Request

Response

[source,sh]

Request

Response

{ "id": 1337, "jsonrpc": "2.0", "result": "0xc" }

[source,sh]

Request

Response

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

[source,sh]

Request

Response

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

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

function setValue(uint256 _valueIndexed, uint256 _valueNotIndexed) public {
valueIndexed = _valueIndexed;
valueNotIndexed = _valueNotIndexed;
emit Event1(_valueIndexed, _valueNotIndexed);
}
}

{
"id": 1337
"jsonrpc": "2.0",
"error": {
"code": -32003,
"message": "Transaction rejected"
}
}

{
"id": 1337,
"jsonrpc": "2.0",
"result": "Mist/v0.9.3/darwin/go1.4.1"
}

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

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

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

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

{
"id": 1337,
"jsonrpc": "2.0",
"result": ["0xc94770007dda54cF92009BFF0dE90c06F603a09f"]
}

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

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

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

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

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

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

{
"id": 1337,
"jsonrpc": "2.0",
"result": "0xc"
}

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

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

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

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

{
"id": 1337,
"jsonrpc": "2.0",
"result": "0xc"
}

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

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

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