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.
475 Commits
44 Branches
214 Tags
188 MiB
Tag: Branch: Tree: 93977c8c35
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '93977c8c35'
${ noResults }
besu/docs/Reference/JSON-RPC-API-Objects.md

158 lines
21 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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
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
Events, logs, and accessing logs content (#533) * Added content on events, logs, and using JSON-RPC methods to access logs Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
Parameter for [eth_newFilter](JSON-RPC-API-Methods.md#eth_newfilter) and [eth_getLogs](JSON-RPC-API-Methods.md#eth_getlogs). Used to [filter logs](../Using-Pantheon/Accessing-Logs-Using-JSON-RPC.md).
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| 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`. |
Events, logs, and accessing logs content (#533) * Added content on events, logs, and using JSON-RPC methods to access logs Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| **address** | Data &#124; Array | Optional | Contract address or array of addresses from which [logs](../Using-Pantheon/Events-and-Logs.md) originate. |
| **topics** | Array of Data, 32&nbsp;bytes each | Optional | Array of topics by which to [filter logs](../Using-Pantheon/Events-and-Logs.md#topic-filters). |
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
[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. |
Events, logs, and accessing logs content (#533) * Added content on events, logs, and using JSON-RPC methods to access logs Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| **topics** | Array of Data, 32&nbsp;bytes each | [Event signature hash](../Using-Pantheon/Events-and-Logs.md#event-signature-hash) and 0 to 3 [indexed log arguments](../Using-Pantheon/Events-and-Logs.md#event-parameters). |
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
## Trace Object
Merging changes made to Wiki post migration (#484) Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
Returned by [debug_traceTransaction](JSON-RPC-API-Methods.md#debug_tracetransaction).
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| 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
Merging changes made to Wiki post migration (#484) Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
Log information returned as part of the [Trace object](#trace-object).
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| 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)
fixes #522 remove mention of gas setting from eth_estimateGas (#593) * fixes #522 remove mention of gas setting from eth_estimateGas * fixes #522 clarify that gasLimit is irrelevant to estimation * fixes #522 clarifications on estimation process Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
| Key | Type | Required/Optional | Value |
|--------------|:-------------------:|:-----------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **from** | Data, 20&nbsp;bytes | Optional | Address from which transaction is 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 might be needed by some executions. `eth_estimateGas` ignores this value. |
| **gasPrice** | Quantity, Integer | Optional | Price used for each paid gas. |
| **value** | Quantity, Integer | Optional | Value sent with this transaction. |
| **data** | Data | Optional | Hash of the method signature and encoded parameters. For details, see [Ethereum Contract ABI](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI). |
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 Signed-off-by: Adrian Sutton <adrian.sutton@consensys.net>
6 years ago
## 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|