Developer Resources
Block ExplorerGitHubRun a NodeMigration GuideETN Testnet Faucet
  • Overview
  • Foundational topics
    • Intro to the Electroneum Smart Chain
    • Intro to ETN
    • Intro to dapps
    • Web2 vs Web3
    • Accounts
    • Transactions
    • Blocks
    • Electroneum Virtual Machine (EVM)
      • Opcodes
    • Gas and Fees
    • Nodes and clients
    • Networks
    • Consensus mechanisms
      • IBFT
  • Electroneum Stack
    • Intro to the stack
    • Smart contracts
    • Development networks
    • Development frameworks
    • Electroneum client APIs
      • JavaScript APIs
      • JSON-RPC
    • Storage
    • Integrated Development Environments (IDEs)
    • Metamask
  • Advanced
    • Bridges
    • Standards
      • Token standards
        • ERC-20 Fungible Tokens
        • ERC-721 NFTs
    • Oracles
    • Networking layer
      • Network addresses
    • Data structures and encoding
      • Patricia Merkle Trie
      • Recursive-length prefix (RLP)
      • Web3 secret storage definition
  • Design fundamentals
    • Intro to design and UX
  • ETN-SC Client
    • Getting started
      • Introduction
      • Hardware requirements
      • Instaling ETN-SC
    • Fundamentals
      • Command-line options
      • Security
      • Sync-modes
      • Account management
      • Databases
      • Backup & restore
      • Logs
      • Connecting to peers
      • Pruning
      • Private networks
      • Config files
      • Light client
    • Interacting with ETN-SC
      • JSON-RPC Server
        • Batch requests
        • Real-time events
      • JSON-RPC Namespaces
        • admin
        • clique
        • debug
        • eth
        • istanbul
        • les
        • miner
        • net
        • personal
        • txpool
      • JS Console
      • JS Console 2: Contracts
      • GraphQL Server
    • Developers
      • Introduction
      • Dapp developers
        • Dev mode
        • Go API
        • Go Account Management
        • Go Contract Bindings
      • EVM tracing
        • Introduction
        • Basic traces
        • Built-in tracers
        • Custom EVM tracer
        • Tutorial for JavaScript tracing
      • ETN-SC developer
        • Developer guide
        • Disclosures
        • DNS discovery setup guide
        • Code review guidelines
      • Contributing
    • Monitoring
      • Creating Dashboards
      • Understanding Dashboards
      • Ethstats
      • Metrics
    • Tools
      • Clef
        • Introduction
        • APIs
        • Rules
        • Setup
        • Datatypes
        • Tutorial
        • Clique-signing
      • abigen
      • devp2p
    • FAQs
  • Migration to Smart Chain
    • Overview
    • How to Migrate
      • ETN Online Wallets
      • Paper Wallets
      • CLI Wallet Users
      • Exchange Holders
      • Exchanges
    • Bridge Smart Contract
  • Misc. Guides
    • Set up Ledger + Metamask
  • MY.ELECTRONEUM.COM
    • Vendor API
Powered by GitBook
On this page
  • Generating basic traces
  • Limits of basic traces
  • Summary

Was this helpful?

  1. ETN-SC Client
  2. Developers
  3. EVM tracing

Basic traces

The simplest type of transaction trace that Etn-sc can generate are raw EVM opcode traces. For every VM instruction the transaction executes, a structured log entry is emitted, containing all contextual metadata deemed useful. This includes the program counter, opcode name, opcode cost, remaining gas, execution depth and any occurred error. The structured logs can optionally also contain the content of the execution stack, execution memory and contract storage.

The entire output of a raw EVM opcode trace is a JSON object having a few metadata fields: consumed gas, failure status, return value; and a list of opcode entries:

{
  "gas": 25523,
  "failed": false,
  "returnValue": "",
  "structLogs": []
}

An example log for a single opcode entry has the following format:

{
  "pc": 48,
  "op": "DIV",
  "gasCost": 5,
  "gas": 64532,
  "depth": 1,
  "error": null,
  "stack": [
    "00000000000000000000000000000000000000000000000000000000ffffffff",
    "0000000100000000000000000000000000000000000000000000000000000000",
    "2df07fbaabbe40e3244445af30759352e348ec8bebd4dd75467a9f29ec55d98d"
  ],
  "memory": [
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000000",
    "0000000000000000000000000000000000000000000000000000000000000060"
  ],
  "storage": {}
}

Generating basic traces

In its simplest form, traceTransaction accepts a transaction hash as its only argument. It then traces the transaction, aggregates all the generated data and returns it as a large JSON object. A sample invocation from the Etn-sc console would be:

debug.traceTransaction('0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f');

The same call can also be invoked from outside the node too via HTTP RPC (e.g. using Curl). In this case, the HTTP endpoint must be enabled in Etn-sc using the --http command and the debug API namespace must be exposed using --http.api=debug.

$ curl -H "Content-Type: application/json" -d '{"id": 1, "jsonrpc": "2.0", "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f"]}' localhost:8545

It is also possible to configure the trace by passing Boolean (true/false) values for four parameters that tweak the verbosity of the trace. By default, the EVM memory and Return data are not reported but the EVM stack and EVM storage are. To report the maximum amount of data:

enableMemory: true
disableStack: false
disableStorage: false
enableReturnData: true

An example call, made in the Etn-sc Javascript console, configured to report the maximum amount of data looks as follows:

debug.traceTransaction('0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f', {
  enableMemory: true,
  disableStack: false,
  disableStorage: false,
  enableReturnData: true
});
$ curl -H "Content-Type: application/json" -d '{"id": 1, "jsonrpc": "2.0", "method": "debug_traceTransaction", "params": ["0xfc9359e49278b7ba99f59edac0e3de49956e46e530a53c15aa71226b7aa92c6f", {"disableStack": true, "disableStorage": true}]}' localhost:8545

Limits of basic traces

Although the raw opcode traces generated above are useful, having an individual log entry for every single opcode is too low level for most use cases, and will require developers to create additional tools to post-process the traces. Additionally, a full opcode trace can easily go into the hundreds of megabytes, making them very resource intensive to get out of the node and process externally.

To avoid those issues, Etn-sc supports running custom JavaScript tracers within the Electroneum node, which have full access to the EVM stack, memory and contract storage. This means developers only have to gather the data they actually need, and do any processing at the source.

Summary

This page described how to do basic traces in Etn-sc. Basic traces are very low level and can generate lots of data that might not all be useful. Therefore, it is also possible to use a set of built-in tracers or write custom ones in Javascript or Go.

PreviousIntroductionNextBuilt-in tracers

Last updated 1 year ago

Was this helpful?

To generate a raw EVM opcode trace, Etn-sc provides a few . The most commonly used is .

To follow along with this tutorial, transaction hashes can be found from a local Etn-sc node (e.g. by attaching a and running eth.getBlock('latest') then passing a transaction hash from the returned block to debug.traceTransaction()) or from a block explorer (for or a ).

Alternatively, disabling EVM Stack, EVM Memory, Storage and Return data (as demonstrated in the Curl request below) results in the following, much shorter, .

Read more about and traces.

Javascript console
Mainnet
testnet
trace dump
built-in
custom
RPC API endpoints
debug_traceTransaction