Neon Labs is currently working to implement a Tracing API to help developers better test, debug, and understand their smart contracts on the Neon EVM.
The API will give developers a full externality trace on any transaction executed on the chain. They’ll be able to rerun historic transactions, run new transactions on historic states, and analyze the state of the blockchain after the execution of each instruction.
Components of the Tracing API
The Tracing API consists of three main components:
- The API endpoint accessible to developers
- A database that stores historical data (transactions, account states, etc.)
- A Solana Node extension called “Account Dumper”
What the Tracing API Offers to Developers
Neon Labs’ implementation of the Tracing API provides users with a set of functions to obtain traces of transaction executions. These functions allow users to execute transactions (new or old) on a historic state of the blockchain, or re-execute a desired historic transaction. The trace information is returned as a JSON object and contains the complete set of instructions/operations that were carried out during the requested transaction. (This response is mostly compatible with Geth and OpenEth implementations of tracing methods.) These instructions/operations include placing data into a stack, multiplying, adding, dividing, etc. Additionally, states of the EVM stack and the target smart contract’s storage after each instruction/operation are saved and provided as a part of the trace.
Under the Hood of the Tracing API
As mentioned above, the Tracing API consists of three major components. In addition to these main components, the Tracing API contains an implementation of an interface called Account Storage, as well as a Neon EVM emulator extended to produce traces. Account Storage is an interface that allows VMs to access data in Solana accounts. The interface is also implemented inside the Neon EVM core and the Neon Proxy.
The Tracing API endpoints are implemented as an extended set of functions provided by Neon Proxy nodes, which is comparable to the OpenEthereum implementation of a similar set of functions.
To capture historic information on the Neon EVM, the Tracing API relies on the Account Dumper and Database Storage components. The Account Dumper operates in a Solana component called “message processor,” which executes all transactions in a validator node. The Account Dumper constantly filters the flow of transactions in search of Neon EVM transactions. When a Neon transaction is identified, Account Dumper will record the account states of the blockchain before and after execution. The account states and the Solana instructions associated with each transaction will then be written into the database collecting historical information. The information is indexed by block number and is easily accessible by the Tracing API functions.
When a user calls a Tracing API function, an instance of Account Storage is created to rebuild account states at a given block number, or account states that are associated with the desired transaction preconditions, depending on the type of request. The information used in this action is pulled from the historical information database. The rebuilt account state is then passed to the Neon EVM core along with the desired transaction to be executed. Transactions can be passed into the EVM core in two ways:
- Directly: The user will include transaction data to be executed, often to run new transactions on historic blockchain states.
- Indirectly: The user will specify a historic transaction, by transaction ID, to be run.
The trace information that results from the above execution is returned to the user as a JSON object. This information is not stored/persistent.
Description of Tracing API Endpoints
The Trace functions below emulate two different interfaces. Functions that begin with “debug_” emulate the Gth interface, and functions that begin with “trace_” emulate the OpenEth interface.
debug_traceCall and trace_rawTransaction: These functions return traces in the form of JSON objects for new transactions. The JSON returned includes information about changes in the EVM at each stage of instruction execution within the requested transaction.
trace_transaction and trace_replayTransaction: These functions return traces in the form of JSON objects for historic transactions that have already occurred on-chain. The user specifies the historic transaction using the transaction ID. The JSON returned includes information about changes in the EVM at each stage of instruction execution within the requested transaction.
debug_traceBlockByNumber and trace_replayBlockTransactions: These functions replay entire blocks that have already occurred on-chain. For these functions, the Tracing API will restore the blockchain account states before each transaction in a given block and sequentially replay each transaction. The JSON returned includes information about changes in the EVM at each stage of instruction execution within the requested transaction.
In addition to the Trace functions above, the Tracing API includes a number of extensions that mimic additional functionalities brought to Ethereum through EIP-1898. These functions also execute on a given block number, allowing users to obtain historic blockchain data or invoke past transactions.
eth_call: Executes a new transaction on a historic blockchain state. The function only returns the final result of the execution (value of the executed contract).
eth_getStorageAt: Returns the value from a storage position of an account at a given address (state of an account’s storage).
eth_getBalance: Returns the balance of an account at a given address.
eth_getCode: Returns code in an account at a given address. This function returns the String value of the compiled bytecode.
eth_getTransactionCount: Returns the number of transactions sent from a given address.
The Neon Team Is Here to Help
If this article leaves you with further questions, reach out to our team via Discord. We’ll be more than happy to help answer any questions regarding the Tracing API, and explain how it can help developers better understand smart contract operations on the Neon EVM.
