CipherLabs
/
besu
mirror of https://github.com/hyperledger/besu
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
An enterprise-grade Java-based, Apache 2.0 licensed Ethereum client https://wiki.hyperledger.org/display/besu
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
333 Commits
44 Branches
214 Tags
192 MiB
Tag: Branch: Tree: cb5ce853c6
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'cb5ce853c6'
${ noResults }
besu/docs/Reference/JSON-RPC-API-Objects.md

158 lines
20 KiB
Raw Normal View History Unescape

Doc migration (#381) Readthedoc migration, still some content to update from the wiki that were updated after I made the last diff - fixes #406 by configuring readthedocs - fixes #407 by configuring material theme - fixes #408 by adding footer with jQuery to enable readthedocs.org versions - fixes #409 - fixes #410 - fixes #411
6 years ago
description: Pantheon JSON-RPC API objects reference
<!--- END of page meta data -->
# JSON-RPC API Objects
The following objects are parameters for or returned by JSON-RPC Methods.
## Block Object
Returned by [eth_getBlockByHash](JSON-RPC-API-Methods.md#eth_getblockbyhash) and [eth_getBlockByNumber](JSON-RPC-API-Methods.md#eth_getblockbynumber).
| Key | Type | Value |
|----------------------|:---------------------:|----------------------------------------------------------------------------------------------------------------------------------|
| **number** | *Quantity*, Integer | Block number. `null` when block is pending. |
| **hash** | *Data*, 32&nbsp;bytes | Hash of the block. `null` when block is pending. |
| **parentHash** | *Data*, 32&nbsp;bytes | Hash of the parent block. |
| **nonce** | *Data*, 8&nbsp;bytes | Hash of the generated proof of work. `null` when block is pending. |
| **sha3Uncles** | *Data*, 32&nbsp;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&nbsp;bytes | Root of the transaction trie for the block. |
| **stateRoot** | Data, 32&nbsp;bytes | Root of the final state trie for the block. |
| **receiptsRoot** | Data, 32&nbsp;bytes | Root of the receipts trie for the block. |
| **miner** | Data, 20&nbsp;bytes | Address to which mining rewards were paid. |
| **difficulty** | Quantity, Integer | Difficulty for this block. |
| **totalDifficulty** | Quantity, Integer | Total difficulty of the chain until this block. |
| **extraData** | Data | Extra data field of this block. |
| **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 when block was collated. |
| **transactions** | Array | Array of [transaction objects](#transaction-object), or 32 byte transaction hashes depending on the specified boolean parameter. |
| **uncles** | Array | Array of uncle hashes. |
## Filter Options Object
Parameter for [eth_newFilter](JSON-RPC-API-Methods.md#eth_newfilter) and [eth_getLogs](JSON-RPC-API-Methods.md#eth_getlogs).
| Key | Type | Required/Optional | Value |
|---------------|:---------------------------------:|:-----------------:|---------------------------------------------------------------------------------------------------------------------------------------------|
| **fromBlock** | Quantity &#124; Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](Using-JSON-RPC-API.md#block-parameter). Default is `latest`. |
| **toBlock** | Quantity &#124; Tag | Optional | Integer block number or `latest`, `pending`, `earliest`. See [Block Parameter](Using-JSON-RPC-API.md#block-parameter). Default is `latest`. |
| **address** | Data &#124; Array | Optional | Contract address or array of addresses from which logs originate. |
| **topics** | Array of Data, 32&nbsp;bytes each | Optional | Array of 32-byte topics. Topics are order-dependent. Each topic can also be an array of DATA with "or" options. |
[eth_getLogs](JSON-RPC-API-Methods.md#eth_getlogs) has an additional key.
| Key | Type | Required/Optional | Value |
|------------|:-----------------:|:-----------------:|------|
| **blockhash** |Data, 32&nbsp;bytes | Optional | Hash of block for which to return logs. If `blockhash` is specified, `fromBlock` and `toBlock` cannot be specified. |
## Log Object
Returned by [eth_getFilterChanges](JSON-RPC-API-Methods.md#eth_getfilterchanges) and [transaction receipt objects](#transaction-receipt-object) can contain an array of log objects.
| Key | Type | Value |
|----------------------|-:- :------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **removed** | Tag | `true` when log removed due to chain reorganization. `false` if valid log. |
| **logIndex** | Quantity, Integer | Log index position in the block. `null` when log is pending. |
| **transactionIndex** | Quantity, Integer | Index position of transaction from which log was created. `null` when log is pending. |
| **transactionHash** | Data, 32&nbsp;bytes | Hash of transaction from which log was created. `null` when log is pending. |
| **blockHash** | Data, 32&nbsp;bytes | Hash of block in which log included. `null` when log is pending. |
| **blockNumber** | Quantity | Number of block in which log included. `null` when log is pending. |
| **address** | Data, 20&nbsp;bytes | Address from which log originated. |
| **data** | Data | Non-indexed arguments of log. |
| **topics** | Array of Data, 32&nbsp;bytes each | 0 to 4 indexed log arguments. In Solidity, the first topic is the hash of the signature of the event (for example, `Deposit(address, bytes32, unit256)`) except you declare the event with an anonymous specifier.) |
## Trace Object
Returned by [debug_traceTransaction](JSON-RPC-API-Methods.md#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 |
### Structured Log Object
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 that caused the EVM execution to terminate. These indicate 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 is returned but it is possible for more than one to occur at once. |
| **stack** | Array of 32&nbsp;byte arrays | EVM execution stack before executing current operation |
| **memory** | Array of 32&nbsp;byte arrays | Memory space of the contract before executing current operation |
| **storage** | Object | Storage entries changed by the current transaction |
## Transaction Object
Returned by [eth_getTransactionByHash](JSON-RPC-API-Methods.md#eth_gettransactionbyhash), [eth_getTransactionByBlockHashAndIndex](JSON-RPC-API-Methods.md#eth_gettransactionbyblockhashandindex), and [eth_getTransactionsByBlockNumberAndIndex](JSON-RPC-API-Methods.md#eth_gettransactionbyblocknumberandindex).
| Key | Type | Value |
|----------------------|:-------------------:|----------------------------------------------------------------------------------------|
| **blockHash** | Data, 32&nbsp;bytes | Hash of block containing this transaction. `null` when transaction is pending. |
| **blockNumber** | Quantity | Block number of block containing this transaction. `null` when transaction is pending. |
| **from** | Data, 20&nbsp;bytes | Address of the sender. |
| **gas** | Quantity | Gas provided by the sender. |
| **gasPrice** | Quantity | Gas price provided by the sender in Wei. |
| **hash** | Data, 32&nbsp;bytes | Hash of the transaction. |
| **input** | Data | Data sent with the transaction. |
| **nonce** | Quantity | Number of transactions made by the sender before this one. |
| **to** | Data, 20&nbsp;bytes | Address of the receiver. `null` if a contract creation transaction. |
| **transactionIndex** | Quantity, Integer | Index position of transaction in the block. `null` when transaction is pending. |
| **value** | Quantity | Value transferred in Wei. |
| **v** | Quantity | ECDSA Recovery ID |
| **r** | Data, 32&nbsp;bytes | ECDSA signature r |
| **s** | Data, 32&nbsp;bytes | ECDSA signature s |
## Transaction Call Object
Parameter for [eth_call](JSON-RPC-API-Methods.md#eth_call) and [eth_estimateGas](JSON-RPC-API-Methods.md#eth_estimategas).
!!!note
All parameters are optional for [eth_estimateGas](JSON-RPC-API-Methods.md#eth_estimategas)
| Key | Type | Required/Optional | Value |
|--------------|:-------------------:|:-----------------:|--------------------------------------------------------------------------------------------------------------------------------|
| **from** | Data, 20&nbsp;bytes | Optional | Address from which transaction sent. |
| **to** | Data, 20&nbsp;bytes | Required | Address to which transaction is directed. |
| **gas** | Quantity, Integer | Optional | Gas provided for the transaction execution. `eth_call` consumes zero gas, but this parameter may be needed by some executions. |
| **gasPrice** | Quantity, Integer | Optional | gasPrice used for each paid gas. |
| **value** | Quantity, Integer | Optional | Value sent with this transaction. |
| **data** | Data | Optional | Hash of the method signature and encoded parameters. For details see Ethereum Contract ABI. |
## Transaction Receipt Object
Returned by [eth_getTransactionReceipt](JSON-RPC-API-Methods.md#eth_gettransactionreceipt).
| Key | Type | Value |
|-----------------------|:--------------------:|--------------------------------------------------------------------------------------|
| **blockHash** | Data, 32&nbsp;bytes | Hash of block containing this transaction. |
| **blockNumber** | Quantity | Block number of block containing this transaction. |
| **contractAddress** | Data, 20&nbsp;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&nbsp;bytes | Address of the sender. |
| **gasUsed** | Quantity | Amount of gas used by this specific transaction. |
| **logs** | Array | Array of [log objects](#log-object) generated by this transaction. |
| **logsBloom** | Data, 256&nbsp;bytes | Bloom filter for light clients to quickly retrieve related logs. |
| **status** | Quantity | Either `1` (success) or `0` (failure) |
| **to** | Data, 20&nbsp;bytes | Address of the receiver, if sending ether; otherwise, null. |
| **transactionHash** | Data, 32&nbsp;bytes | Hash of the transaction. |
| **transactionIndex** | Quantity, Integer | Index position of transaction in the block. |
!!!note
For pre-Byzantium transactions, the transaction receipt object includes the following instead of `status`:
| Key | Type | Value |
|-------|:-----------------:|---------|
| **root** | Data, 32&nbsp;bytes| Post-transaction stateroot|