Updated 2020-03-25

Hyperledger Besu API objects

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

Block object

Returned by eth_getBlockByHash and eth_getBlockByNumber.

Key Type Value
number Quantity, Integer Block number. null when block is pending.
hash Data, 32 bytes Hash of the block. null when block is pending.
parentHash Data, 32 bytes Hash of the parent block.
nonce Data, 8 bytes Hash of the generated proof of work. null when block is pending.
sha3Uncles Data, 32 bytes SHA3 of the uncle’s data in the block.
logsBloom Data, 256 bytes Bloom filter for the block logs. null when block is pending.
transactionsRoot Data, 32 bytes Root of the transaction trie for the block.
stateRoot Data, 32 bytes Root of the final state trie for the block.
receiptsRoot Data, 32 bytes Root of the receipts trie for the block.
miner Data, 20 bytes Address to pay mining rewards to.
difficulty Quantity, Integer Difficulty for this block.
totalDifficulty Quantity, Integer Total difficulty of the chain until this block.
extraData Data Extra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option. Stores extra data when used with Clique and IBFT.
size Quantity, Integer Size of block in bytes.
gasLimit Quantity Maximum gas allowed in this block.
gasUsed Quantity Total gas used by all transactions in this block.
timestamp Quantity Unix timestamp for block assembly.
transactions Array Array of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.
uncles Array Array of uncle hashes.

Filter options object

Parameter for eth_newFilter and eth_getLogs. Used to filter logs.

Key Type Required/Optional Value
fromBlock Quantity | Tag Optional Integer block number or latest, pending, earliest. See Block Parameter. Default is latest.
toBlock Quantity | Tag Optional Integer block number or latest, pending, earliest. See Block Parameter. Default is latest.
address Data | Array Optional Contract address or array of addresses from which logs originate.
topics Array of Data, 32 bytes each Optional Array of topics by which to filter logs.

eth_getLogs has an extra key.

Key Type Required/Optional Value
blockhash Data, 32 bytes Optional. Hash of block for which to return logs. If you specify blockhash, you cannot specify fromBlock and toBlock.

Log object

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

Key Type Value
removed Tag true if log removed because of a chain reorganization. false if a valid log.
logIndex Quantity, Integer Log index position in the block. null when log is pending.
transactionIndex Quantity, Integer Index position of the starting transaction for the log. null when log is pending.
transactionHash Data, 32 bytes Hash of the starting transaction for the log. null when log is pending.
blockHash Data, 32 bytes Hash of the block that includes the log. null when log is pending.
blockNumber Quantity Number of block that includes the log. null when log is pending.
address Data, 20 bytes Address the log originated from.
data Data Non-indexed arguments of the log.
topics Array of Data, 32 bytes each Event signature hash and 0 to 3 indexed log arguments.

Private transaction object

Returned by priv_getPrivateTransaction.

Key Type Value
from Data, 20 bytes Address of the sender.
gas Quantity Gas provided by the sender.
gasPrice Quantity Gas price, in Wei, provided by the sender.
hash Data, 32 bytes Hash of the transaction.
input Data The data to create or invoke a contract.
nonce Quantity Number of transactions made by the sender to the privacy group before this one.
to Data, 20 bytes null if a contract creation transaction; otherwise, the contract address.
value Quantity null because private transactions cannot transfer Ether.
v Quantity ECDSA Recovery ID.
r Data, 32 bytes ECDSA signature r.
s Data, 32 bytes ECDSA signature s.
privateFrom Data, 32 bytes Orion public key of the sender.
privateFor Array of Data, 32 bytes each Orion public keys of recipients. Not returned if using privacyGroupId to send the transaction.
privacyGroupId Data, 32 bytes Orion privacy group ID of recipients. Not returned if using privateFor to send the transaction.
restriction String Must be restricted.

Range object

Returned by debug_storageRangeAt.

Key Type Value
storage Object Key hash and value. Preimage key is null if it falls outside the cache.
nextKey Hash Hash of next key if further storage in range. Otherwise, not included.

Structured log object

Log information returned as part of the Trace object.

Key Type Value
pc Integer Current program counter.
op String Current OpCode.
gas Integer Gas remaining.
gasCost Integer Cost in wei of each gas unit.
depth Integer Execution depth.
exceptionalHaltReasons Array One or more strings representing an error condition causing the EVM execution to terminate. These strings suggest that EVM execution terminated for reasons such as running out of gas or attempting to execute an unknown instruction. Generally a single exceptional halt reason returns but it’s possible for more than one to occur at once.
stack Array of 32 byte arrays EVM execution stack before executing current operation.
memory Array of 32 byte arrays Memory space of the contract before executing current operation.
storage Object Storage entries changed by the current transaction.

Trace object

Returned by debug_traceBlock, debug_traceBlockByHash, debug_traceBlockByNumber, and debug_traceTransaction.

Key Type Value
gas Integer Gas used by the transaction.
failed Boolean True if transaction failed; otherwise, false.
returnValue String Bytes returned from transaction execution (without a 0x prefix).
structLogs Array Array of structured log objects.

Transaction object

Returned by eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, and eth_getTransactionsByBlockNumberAndIndex.

Key Type Value
blockHash Data, 32 bytes Hash of the block containing this transaction. null when transaction is pending.
blockNumber Quantity Block number of the block containing this transaction. null when transaction is pending.
from Data, 20 bytes Address of the sender.
gas Quantity Gas provided by the sender.
gasPrice Quantity Gas price, in wei, provided by the sender.
hash Data, 32 bytes Hash of the transaction.
input Data Data sent with the transaction to create or invoke a contract. For private transactions, it’s a pointer to the transaction location in Orion.
nonce Quantity Number of transactions made by the sender before this one.
to Data, 20 bytes Address of the receiver. null if a contract creation transaction.
transactionIndex Quantity, Integer Index position of the transaction in the block. null when transaction is pending.
value Quantity Value transferred, in wei.
v Quantity ECDSA Recovery ID.
r Data, 32 bytes ECDSA signature r.
s Data, 32 bytes ECDSA signature s.

Transaction call object

Parameter for eth_call and eth_estimateGas.

Note

All parameters are optional for eth_estimateGas.

Key Type Required/Optional Value
from Data, 20 bytes Optional Address of the transaction sender.
to Data, 20 bytes Required Address of the transaction receiver.
gas Quantity, Integer Optional Gas provided for the transaction execution. eth_call consumes zero gas, but other executions might need this parameter. eth_estimateGas ignores this value.
gasPrice Quantity, Integer Optional Price used for each paid gas.
value Quantity, Integer Optional Value sent with this transaction.
data Data Optional Hash of the method signature and encoded parameters. For details, see Ethereum Contract ABI.

Transaction receipt object

Returned by eth_getTransactionReceipt.

Key Type Value
blockHash Data, 32 bytes Hash of block containing this transaction.
blockNumber Quantity Block number of block containing this transaction.
contractAddress Data, 20 bytes Contract address created, if contract creation transaction; otherwise, null.
cumulativeGasUsed Quantity Total amount of gas used by previous transactions in the block and this transaction.
from Data, 20 bytes Address of the sender.
gasUsed Quantity Amount of gas used by this specific transaction.
logs Array Array of log objects generated by this transaction.
logsBloom Data, 256 bytes Bloom filter for light clients to quickly retrieve related logs.
status Quantity Either 0x1 (success) or 0x0 (failure)
to Data, 20 bytes Address of the receiver, if sending ether; otherwise, null.
transactionHash Data, 32 bytes Hash of the transaction.
transactionIndex Quantity, Integer Index position of transaction in the block.
revertReason String ABI-encoded string that displays the reason for reverting the transaction. Only available if revert reason is enabled.

Note

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

Key Type Value
root Data, 32 bytes Post-transaction stateroot

Transaction trace object

Returned by trace_replayBlockTransactions.

Key Type Value
output Boolean Transaction result. 1 for success and 0 for failure.
stateDiff Object State changes in the requested block..
trace Array Ordered list of calls to other contracts..
vmTrace Object Ordered list of EVM actions..
transactionHash Data, 32 bytes Hash of the replayed transaction.

Private transaction receipt object

Returned by priv_getTransactionReceipt.

Key Type Value
contractAddress Data, 20 bytes Contract address created if a contract creation transaction; otherwise, null.
from Data, 20 bytes Address of the sender.
output Data RLP-encoded return value of a contract call if a value returns; otherwise, null.
commitmentHash Data, 32 bytes Hash of the privacy marker transaction.
transactionHash Data, 32 bytes Hash of the private transaction.
privateFrom Data, 32 bytes Orion public key of the sender.
privateFor or privacyGroupId Array or Data, 32 bytes Orion public keys or privacy group ID of the recipients.
status Quantity Either 0x1 (success) or 0x0 (failure).
logs Array Array of log objects generated by this private transaction.