Skip to main content

Besu API objects

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

info

This reference contains API objects that apply to both public and private networks. For private-network-specific API objects, see the private network API object reference.

Block object

Returned by eth_getBlockByHash and eth_getBlockByNumber.

KeyTypeValue
numberQuantity, IntegerBlock number. null when block is pending.
hashData, 32 bytesHash of the block. null when block is pending.
parentHashData, 32 bytesHash of the parent block.
nonceData, 8 bytesHash of the generated proof of work. null when block is pending.
sha3UnclesData, 32 bytesSHA3 of the uncle's data in the block.
logsBloomData, 256 bytesBloom filter for the block logs. null when block is pending.
transactionsRootData, 32 bytesRoot of the transaction trie for the block.
stateRootData, 32 bytesRoot of the final state trie for the block.
receiptsRootData, 32 bytesRoot of the receipts trie for the block.
minerData, 20 bytesAddress to pay mining rewards to.
difficultyQuantity, IntegerDifficulty for this block.
totalDifficultyQuantity, IntegerTotal difficulty of the chain until this block. This value will always be 0 for an uncle block.
extraDataDataExtra 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.
sizeQuantity, IntegerSize of block in bytes.
gasLimitQuantityMaximum gas allowed in this block.
gasUsedQuantityTotal gas used by all transactions in this block.
timestampQuantityUnix timestamp for block assembly.
transactionsArrayArray of transaction objects, or 32 byte transaction hashes depending on the specified boolean parameter.
unclesArrayArray of uncle hashes.
baseFeePerGasQuantityThe block's base fee per gas. This field is empty for blocks created before EIP-1559.

Fee history results object

Returned by eth_feeHistory for the requested block range. If blocks in the specified block range are not available, then only the fee history for available blocks is returned.

KeyTypeValue
oldestBlockQuantity, IntegerLowest number block of the returned range.
baseFeePerGasArrayArray of block base fees per gas, including an extra block value. The extra value is the next block after the newest block in the returned range. Returns zeroes for blocks created before EIP-1559.
gasUsedRatioArrayArray of block gas used ratios. These are calculated as the ratio of gasUsed and gasLimit.
rewardArrayArray of effective priority fee per gas data points from a single block. All zeroes are returned if the block is empty.

Filter options object

Parameter for eth_newFilter, eth_getLogs, and priv_getLogs. Used to filter logs.

KeyTypeRequired/OptionalValue
fromBlockQuantity | TagOptionalInteger block number or latest, pending, earliest. See block parameter. Default is latest.
toBlockQuantity | TagOptionalInteger block number or latest, pending, earliest. See block parameter. Default is latest.
addressData | ArrayOptionalContract address or array of addresses from which logs originate.
topicsArray of Data, 32 bytes eachOptionalArray of topics by which to filter logs.

eth_getLogs and priv_getLogs have an extra key.

KeyTypeRequired/OptionalValue
blockHashData, 32 bytesOptional.Hash of block for which to return logs. If you specify blockHash, you cannot specify fromBlock and toBlock.

Log object

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

KeyTypeValue
removedTagtrue if log removed because of a chain reorganization. false if a valid log.
logIndexQuantity, IntegerLog index position in the block. null when log is pending.
transactionIndexQuantity, IntegerIndex position of the starting transaction for the log. null when log is pending.
transactionHashData, 32 bytesHash of the starting transaction for the log. null when log is pending.
blockHashData, 32 bytesHash of the block that includes the log. null when log is pending.
blockNumberQuantityNumber of block that includes the log. null when log is pending.
addressData, 20 bytesAddress the log originated from.
dataDataNon-indexed arguments of the log.
topicsArray of Data, 32 bytes eachEvent signature hash and 0 to 3 indexed log arguments.

Miner data object

Returned by eth_getMinerDataByBlockHash and eth_getMinerDataByBlockNumber.

KeyTypeValue
netBlockRewardQuantity, IntegerThe net block reward, in Wei, is staticBlockReward + transactionFee + uncleInclusionReward.
staticBlockRewardQuantity, IntegerThe static block reward, in Wei, is preset on a hard fork.
transactionFeeQuantity, IntegerThe transaction fee, in Wei, is sum of upfront cost - refund amount for all transactions.
uncleInclusionRewardQuantity, IntegerThe uncle inclusion reward, in Wei, is static block reward * number of ommers/32.
uncleRewardsMapMap of uncle block hashes and uncle miner coinbase addresses.
coinbaseData, 20 bytesCoinbase address.
extraDataDataExtra data field for this block. The first 32 bytes is vanity data you can set using the --miner-extra-data command line option.
difficultyQuantity, IntegerDifficulty of this block.
totalDifficultyQuantity, IntegerTotal difficulty of the chain until this block.

Pending transaction object

Returned by txpool_besuPendingTransactions.

KeyTypeValue
accessListArray(Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.
fromData, 20 bytesAddress of the sender.
gasQuantityGas provided by the sender.
gasPriceQuantity(Optional) Gas price, in Wei, provided by the sender. Not used only in EIP1559 transactions.
maxPriorityFeePerGasQuantity, Integer(Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.
maxFeePerGasQuantity, Integer(Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.
hashData, 32 bytesHash of the transaction.
inputDataData sent with the transaction to create or invoke a contract.
nonceQuantityNumber of transactions made by the sender before this one.
toData, 20 bytesAddress of the receiver. null if a contract creation transaction.
transactionTypeStringTransaction type.
valueQuantityValue transferred, in Wei.
vQuantityECDSA Recovery ID.
rData, 32 bytesECDSA signature r.
sData, 32 bytesECDSA signature s.

Range object

Returned by debug_storageRangeAt.

KeyTypeValue
storageObjectKey hash and value. Pre-image key is null if it falls outside the cache.
nextKeyHashHash of next key if further storage in range. Otherwise, not included.

Structured log object

Log information returned as part of the Trace object.

KeyTypeValue
pcIntegerCurrent program counter.
opStringCurrent OpCode.
gasIntegerGas remaining.
gasCostIntegerCost in wei of each gas unit.
depthIntegerExecution depth.
exceptionalHaltReasonsArrayOne 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.
stackArray of 32 byte arraysEVM execution stack before executing current operation.
memoryArray of 32 byte arraysMemory space of the contract before executing current operation.
storageObjectStorage entries changed by the current transaction.

Trace object

Returned by debug_traceBlock, debug_traceBlockByHash, debug_traceBlockByNumber, and debug_traceTransaction.

KeyTypeValue
gasIntegerGas used by the transaction.
failedBooleanTrue if transaction failed, otherwise, false.
returnValueStringBytes returned from transaction execution (without a 0x prefix).
structLogsArrayArray of structured log objects.

Trace filter options object

Parameter for trace_filter. All parameters are optional.

KeyTypeValue
fromBLockString | TagTrace starts at this block.
toBlockString | TagTrace stops at this block.
fromAddressStringInclude only traces sent from this address.
toAddressStringInclude only traces with this destination address.
afterQuantityThe offset trace number.
countIntegerNumber of traces to display in a batch.

Transaction object

Returned by eth_getTransactionByHash, eth_getTransactionByBlockHashAndIndex, and eth_getTransactionByBlockNumberAndIndex.

KeyTypeValue
accessListArray(Optional) List of addresses and storage keys the transaction plans to access. Used in ACCESS_LIST transactions and may be used in EIP1559 transactions.
blockHashData, 32 bytesHash of the block containing this transaction. null when transaction is pending.
blockNumberQuantityBlock number of the block containing this transaction. null when transaction is pending.
chainIdQuantityChain ID.
fromData, 20 bytesAddress of the sender.
gasQuantityGas provided by the sender.
gasPriceQuantity(Optional) Gas price, in Wei, provided by the sender. Used only in non-EIP1559 transactions.
maxPriorityFeePerGasQuantity, Integer(Optional) Maximum fee, in Wei, the sender is willing to pay per gas above the base fee. Used only in EIP1559 transactions.
maxFeePerGasQuantity, Integer(Optional) Maximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Used only in EIP1559 transactions.
hashData, 32 bytesHash of the transaction.
inputDataData sent with the transaction to create or invoke a contract. For private transactions, it's a pointer to the transaction location in Tessera.
nonceQuantityNumber of transactions made by the sender before this one.
toData, 20 bytesAddress of the receiver. null if a contract creation transaction.
transactionIndexQuantity, IntegerIndex position of the transaction in the block. null when transaction is pending.
transactionTypeStringTransaction type.
valueQuantityValue transferred, in Wei.
vQuantityECDSA Recovery ID.
rData, 32 bytesECDSA signature r.
sData, 32 bytesECDSA signature s.

Transaction call object

Parameter for eth_call, eth_createAccessList, and eth_estimateGas.

All transaction call object parameters are optional.

KeyTypeValue
fromData, 20 bytesAddress of the sender.
toData, 20 bytesAddress of the action receiver.
gasQuantity, IntegerGas provided by the sender. eth_call consumes zero gas, but other executions might need this parameter. eth_estimateGas ignores this value.
gasPriceQuantity, IntegerGas price, in Wei, provided by the sender. The default is 0. Used only in non-EIP1559 transactions.
maxPriorityFeePerGasQuantity, IntegerMaximum fee, in Wei, the sender is willing to pay per gas above the base fee. Can be used only in EIP1559 transactions. If used, must specify maxFeePerGas.
maxFeePerGasQuantity, IntegerMaximum total fee (base fee + priority fee), in Wei, the sender is willing to pay per gas. Can be used only in EIP1559 transactions. If used, must specify maxPriorityFeePerGas.
valueQuantity, IntegerValue transferred, in Wei.
dataDataHash of the method signature and encoded parameters. For details, see Ethereum Contract ABI.
accessListArrayList of addresses and storage keys that the transaction plans to access. Used only in non-FRONTIER transactions.
strictTagIf true, checks that the from account’s ether balance is sufficient to cover the transaction and gas fee. If false, the gasPrice and baseFee are set to zero, in order to simulate a transaction without enforcing a balance check. The default is false.

Transaction receipt object

Returned by eth_getTransactionReceipt.

KeyTypeValue
blockHashData, 32 bytesHash of block containing this transaction.
blockNumberQuantityBlock number of block containing this transaction.
contractAddressData, 20 bytesContract address created, if contract creation transaction, otherwise, null. A failed contract creation transaction still produces a contract address value.
cumulativeGasUsedQuantityTotal amount of gas used by previous transactions in the block and this transaction.
effectiveGasPriceQuantityThe actual value per gas deducted from the sender's account.
fromData, 20 bytesAddress of the sender.
gasUsedQuantityAmount of gas used by this specific transaction.
logsArrayArray of log objects generated by this transaction.
logsBloomData, 256 bytesBloom filter for light clients to quickly retrieve related logs.
statusQuantityEither 0x0 (failure), 0x1 (success), or 0x2 (invalid).
toData, 20 bytesAddress of the receiver, if sending ether, otherwise, null.
transactionHashData, 32 bytesHash of the transaction.
transactionIndexQuantity, IntegerIndex position of transaction in the block.
transactionTypeStringTransaction type.
revertReasonStringABI-encoded string that displays the reason for reverting the transaction. Only available if revert reason is enabled.
typeQuantityTransaction type, 0x00 for legacy transactions, 0x01 for access list types, 0x02 for dynamic fees.
note

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

KeyTypeValue
rootData, 32 bytesPost-transaction state root

Transaction trace object

Returned by trace_replayBlockTransactions.

KeyTypeValue
outputBooleanTransaction result. 1 for success and 0 for failure.
stateDiffObjectState changes in the requested block.
traceArrayOrdered list of calls to other contracts.
vmTraceObjectOrdered list of EVM actions.
transactionHashData, 32 bytesHash of the replayed transaction.