Debug API & Trace Module¶
Introduction¶
Geth's debug and txpool APIs and OpenEthereum's trace module provide non-standard RPC methods for deeper insight into transaction processing. Some of these non-standard RPC methods are supported as part of Moonbeam's goal of providing a seamless Ethereum experience for developers. Supporting these RPC methods is an essential milestone because many projects like The Graph rely on them to index blockchain data.
This guide will cover the supported RPC methods available on Moonbeam and how to invoke them using curl commands against a tracing node with the debug, txpool, and tracing flags enabled. You can access a tracing node in one of two ways: through a supported tracing RPC provider or by spinning up a tracing node of your own.
To view a list of tracing RPC providers, please check out the Network Endpoints page.
If you wish to set up your own tracing node, you can follow the Running a Tracing Node guide. The RPC HTTP endpoint of your tracing node should be at http://127.0.0.1:9944
and your node should display similar logs to the following:
-u $(id -u ${USER}):$(id -g ${USER}) \ moonbeamfoundation/moonbeam-tracing:v0.39.0-3100-latest \
--name="Moonbean-Tracing-Tutorial" \
--unsafe-rpc-external \
--ethapi=debug,trace,txpool \
--wasm-runtime-overrides=/moonbeam/moonbase-substitutes-tracing \
--runtime-cache-size 64 \
--dev
CLI parameter `--execution` has no effect anymore and will be removed in the future!
2024-04-29 13:52:00 Moonbeam Parachain Collator
2024-04-29 13:52:00 ✌️ version 0.39.0-be5032c7749
2024-04-29 13:52:00 ❤️ by PureStake, 2019-2024
2024-04-29 13:52:00 📋 Chain specification: Moonbase Development Testnet
2024-04-29 13:52:00 🏷 Node name: Moonbean-Tracing-Tutorial
2024-04-29 13:52:00 👤 Role: AUTHORITY
2024-04-29 13:52:00 💾 Database: RocksDb at /tmp/substrateO3YeRz/chains/moonbase_dev/db/full
2024-04-29 14:52:13 Found wasm override. version=moonbase-300 (moonbase-0.tx2.au3) file=/moonbeam/moonbase-substitutes-tracing/moonbase-runtime-300-substitute-tracing.wasm
...
2024-04-29 14:56:34 💤 Idle (0 peers), best: #0 (0x18e6…2eb1), finalized #0 (0x18e6…2eb1), ⬇ 0 ⬆ 0
Supported Debug and Trace JSON-RPC Methods¶
debug_traceTransaction
This method attempts to replay a transaction in the same manner as it was executed on the network. Refer to Geth's documentation for more information.
transaction_hash
string - the hash of the transaction to be tracedtracer_config
string - (optional) a JSON object for configuring the tracer that contains the following field:tracer
string - sets the type of tracer
If no tracer_config
is provided, the opcode logger will be the default tracer. The opcode logger provides the following additional fields:
opcode_config
string - (optional) a JSON object for configuring the opcode logger:disableStorage
boolean — (optional, default:false
) setting this totrue
disables storage capturedisableMemory
boolean — (optional, default:false
) setting this totrue
disables memory capturedisableStack
boolean — (optional, default:false
) setting this totrue
disables stack capture
If you supplied a tracer_config
, the result
object contains the following fields:
type
- the type of the callfrom
- the address the transaction is sent fromto
- the address the transaction is directed tovalue
- the integer of the value sent with this transactiongas
- the integer of the gas provided for the transaction executiongasUsed
- the integer of the gas usedinput
- the data given at the time of inputoutput
- the data which is returned as an outputerror
- the type of error, if anyrevertReason
- the type solidity revert reason, if anycalls
- a list of sub-calls, if any
If you used the default opcode logger, the result
object contains the following fields:
gas
- the integer of the gas provided for the transaction executionreturnValue
- the output produced by the execution of the transactionstructLogs
- an array of objects containing a detailed log of each opcode executed during the transactionfailed
- a boolean indicating whether the transaction execution failed or succeeded
Using the tracer_config
:
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc":"2.0",
"id": 1,
"method": "debug_traceTransaction",
"params": ["INSERT_TRANSACTION_HASH", {"tracer": "callTracer"}]
}'
Using the default opcode logger:
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc":"2.0",
"id": 1,
"method": "debug_traceTransaction",
"params": ["INSERT_TRANSACTION_HASH"]
}'
debug_traceBlockByNumber
This method attempts to replay a block in the same manner as it was executed on the network. Refer to Geth's documentation for more information.
block_number
string - the block number of the block to be tracedtracer_config
string - a JSON object for configuring the tracer that contains the following field:tracer
string - sets the type of tracer. This must be set tocallTracer
, which only returns transactions and sub-calls. Otherwise, the tracer will attempt to default to the opcode logger, which is not supported at this time due to the heavy nature of the call
The result
array contains objects with the following fields:
type
- the type of the callfrom
- the address the transaction is sent fromto
- the address the transaction is directed tovalue
- the integer of the value sent with this transactiongas
- the integer of the gas provided for the transaction executiongasUsed
- the integer of the gas usedinput
- the data given at the time of inputoutput
- the data which is returned as an outputerror
- the type of error, if anyrevertReason
- the type solidity revert reason, if anycalls
- a list of sub-calls, if any
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceBlockByNumber",
"params": ["INSERT_BLOCK_NUMBER", {"tracer": "callTracer"}]
}'
debug_traceBlockByHash
This method attempts to replay a block in the same manner as it was executed on the network. Refer to Geth's documentation for more information.
block_hash
string - the block hash of the block to be tracedtracer_config
string - a JSON object for configuring the tracer that contains the following field:tracer
string - sets the type of tracer. This must be set tocallTracer
, which only returns transactions and sub-calls. Otherwise, the tracer will attempt to default to the opcode logger, which is not supported at this time due to the heavy nature of the call
The result
array contains objects with the following fields:
type
- the type of the callfrom
- the address the transaction is sent fromto
- the address the transaction is directed tovalue
- the integer of the value sent with this transactiongas
- the integer of the gas provided for the transaction executiongasUsed
- the integer of the gas usedinput
- the data given at the time of inputoutput
- the data which is returned as an outputerror
- the type of error, if anyrevertReason
- the type solidity revert reason, if anycalls
- a list of sub-calls
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceBlockByHash",
"params": ["INSERT_BLOCK_HASH", {"tracer": "callTracer"}]
}'
debug_traceCall
This method executes an eth_call within the context of the given block using the final state of the parent block as the base. Refer to Geth's documentation for more information.
call_object
object the transaction object to be executedblock_hash
string - the block hash of the base block
gas
- the integer of the gas provided for the transaction executionreturnValue
- the output produced by the execution of the transactionstructLogs
- an array of objects containing a detailed log of each opcode executed during the transaction
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "debug_traceCall",
"params": [{
"from": "INSERT_FROM_ADDRESS",
"to":"INSERT_TO_ADDRESS",
"data":"INSERT_CALL_DATA"
}, "INSERT_BLOCK_HASH"]
}'
trace_filter
This method returns matching traces for the given filters. Refer to Open Ethereum's documentation for more information.
fromBlock
string — (optional) either block number (hex),earliest
, which is the genesis block, orlatest
(default), which is the best block available. The trace starting blocktoBlock
string — (optional) either block number (hex),earliest
, which is the genesis block, orlatest
, which is the best block available. The trace-ending blockfromAddress
array — (optional) filter transactions from these addresses only. If an empty array is provided, no filtering is done with this fieldtoAddress
array — (optional) filter transactions to these addresses only. If an empty array is provided, no filtering is done with this fieldafter
uint — (optional) the default offset is0
. The trace offset (or starting) numbercount
uint — (optional) number of traces to display in a batch
There are a couple of default values that you should be aware of:
- The maximum number of trace entries a single request of
trace_filter
is allowed to return is500
. A request exceeding this limit will return an error - Blocks processed by requests are temporarily stored in the cache for
300
seconds, after which they are deleted
You can configure additional flags when spinning up your tracing node to change the default values.
The result
array contains an array of objects for the block traces. All objects will contain the following fields:
blockHash
- the hash of the block where this transaction was inblockNumber
- the block number where this transaction was insubtraces
- the traces of contract calls made by the transactiontraceAddress
- the list of addresses where the call was executed, the address of the parents, and the order of the current sub-calltransactionHash
- the hash of the transactiontransactionPosition
- the transaction positiontype
- the value of the method, such ascall
orcreate
If the type
of the transaction is a call
, these additional fields will exist:
action
- an object containing the call information:from
- the address of the sendercallType
- the type of method, such ascall
anddelegatecall
gas
- the gas provided by the sender, encoded as hexadecimalinput
- the data sent along with the transactionto
- the address of the receivervalue
- the integer of the value sent with this transaction, encoded as hexadecimal
result
- an object containing the result of the transactiongasUsed
- the amount of gas used by this specific transaction aloneoutput
- the value returned by the contract call, and it only contains the actual value sent by the return method. If the return method was not executed, the output is empty bytes
If the type
of the transaction is a create
, these additional fields will exist:
action
- an object containing information on the contract creation:from
- the address of the sendercreationMethod
- the creation method, such ascreate
gas
- the gas provided by the sender, encoded as hexadecimalinit
- the initialization code of the contractvalue
- the integer of the value sent with this transaction, encoded as hexadecimal
result
- an object containing the result of the transactionaddress
- the address of the contractcode
- the bytecode of the contractgasUsed
- the amount of gas used by this specific transaction alone
This example starts with a zero offset and provides the first 20 traces:
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "trace_filter", "params":
[{
"fromBlock": "INSERT_FROM_BLOCK",
"toBlock": "INSERT_TO_BLOCK",
"toAddress": ["INSERT_ADDRESS_TO_FILTER"],
"after": 0,
"count": 20
}]
}'
txpool_content
Returns the details for all currently pending transactions waiting to be included in the next block(s) and all queued transactions for future execution. Refer to Geth's documentation for more information.
None
The result
object contains the following fields:
pending
- an object containing the pending transaction details, which maps an address to a batch of scheduled transactionsaddress
- the address initiating a transaction, which maps the addresses' associating nonces with their transactionsnonce
- the nonce of the sending addressblockHash
- the hash of the block where this transaction was included. For pending transactions, this is an empty 32-byte string in hexadecimal formatblockNumber
- the block number where this transaction was added encoded as a hexadecimal. For pending transactions, this isnull
from
- the address of the sendergas
- the total amount of gas units used in the transactiongasPrice
- the total amount in Wei the sender is willing to pay for the transactionmaxFeePerGas
- the maximum amount of gas willing to be paid for the transactionmaxPriorityFeePerGas
- the maximum amount of gas to be included as a tip to the minerhash
- the hash of the transactioninput
- the encoded transaction input datanonce
- the number of transactions the sender has sent till nowto
- the address of the receiver.null
when it's a contract creation transactiontransactionIndex
- an integer of the transactions index position in the block encoded as a hexadecimal format. For pending transactions, this isnull
value
- the value transferred in Wei encoded as a hexadecimal format
queued
- an object containing the queued transaction details, which maps an address to a batch of scheduled transactionsaddress
- the address initiating a transaction, which maps the addresses' associating nonces with their transactionsnonce
- the nonce of the sending addressblockHash
- the hash of the block where this transaction was included. For queued transactions, this is an empty 32-byte string in hexadecimal formatblockNumber
- the block number where this transaction was added encoded as a hexadecimal. For queued transactions, this isnull
from
- the address of the sendergas
- the total amount of gas units used in the transactiongasPrice
- the total amount in wei the sender is willing to pay for the transactionmaxFeePerGas
- the maximum amount of gas willing to be paid for the transactionmaxPriorityFeePerGas
- the maximum amount of gas to be included as a tip to the minerhash
- the hash of the transactioninput
- the encoded transaction input datanonce
- the number of transactions the sender has sent till nowto
- the address of the receiver.null
when it's a contract creation transactiontransactionIndex
- an integer of the transactions index position in the block encoded as a hexadecimal format. For queued transactions, this isnull
value
- the value transferred in Wei encoded as a hexadecimal format
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "txpool_content", "params":[]
}'
txpool_inspect
Returns a summary for all currently pending transactions waiting to be included in the next block(s) and all queued transactions for future execution. Refer to Geth's documentation for more information.
None
The result
object contains the following fields:
pending
- an object containing the pending transaction summary strings, which maps an address to a batch of scheduled transactionsaddress
- the address initiating a transaction, which maps the addresses' associating nonces with their transaction summary strings
queued
- an object containing the queued transaction summary strings, which maps an address to a batch of scheduled transactionsaddress
- the address initiating a transaction, which maps the addresses' associating nonces with their transaction summary strings
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method" "txpool_inspect", "params":[]
}'
txpool_status
Returns the total number of transactions currently pending transactions waiting to be included in the next block(s) and all queued transactions for future execution. Refer to Geth's documentation for more information.
None
The result
object contains the following fields:
pending
- a counter representing the number of pending transactionsqueued
- a counter representing the number of queued transactions
curl http://127.0.0.1:9944 -H "Content-Type:application/json;charset=utf-8" -d \
'{
"jsonrpc": "2.0",
"id": 1,
"method": "txpool_status", "params":[]
}'
| Created: April 17, 2024