> For the complete documentation index, see [llms.txt](https://docs.megaeth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.megaeth.com/mega-evme/tracing/opcode-tracer.md).

# Opcode Tracer

The opcode tracer records every EVM instruction executed, along with gas costs, stack state, memory, and storage changes. This is the default tracer when you pass `--trace` without specifying `--tracer`.

## Usage

```bash
mega-evme run 0x60016000526001601ff3 --trace --tracer opcode
```

## Options

These flags control what the opcode tracer captures. Disabling memory and stack capture significantly reduces trace size for large executions.

| Flag                                | Default | Description                                                |
| ----------------------------------- | ------- | ---------------------------------------------------------- |
| `--trace.opcode.disable-memory`     | `false` | Omit memory snapshots from each step                       |
| `--trace.opcode.disable-stack`      | `false` | Omit stack snapshots from each step                        |
| `--trace.opcode.disable-storage`    | `false` | Omit storage change records                                |
| `--trace.opcode.enable-return-data` | `false` | Include return data in each step (off by default for size) |

## Output Format

The opcode tracer emits Geth-compatible JSON. The top-level object wraps the trace:

### Schema

| Field         | Type       | Description                      |
| ------------- | ---------- | -------------------------------- |
| `failed`      | bool       | Whether the transaction reverted |
| `gas`         | number     | Total gas used                   |
| `returnValue` | hex string | Return data from the transaction |
| `structLogs`  | array      | Array of per-opcode step objects |

Each entry in `structLogs`:

| Field        | Type       | Description                                              |
| ------------ | ---------- | -------------------------------------------------------- |
| `pc`         | number     | Program counter                                          |
| `op`         | string     | Opcode name (e.g., `PUSH1`, `SSTORE`)                    |
| `gas`        | number     | Gas remaining before this step                           |
| `gasCost`    | number     | Gas consumed by this step                                |
| `depth`      | number     | Call depth                                               |
| `stack`      | array      | Stack contents as hex strings (unless disabled)          |
| `memory`     | array      | Memory contents as 32-byte hex chunks (unless disabled)  |
| `storage`    | object     | Storage changes as key-value hex pairs (unless disabled) |
| `returnData` | hex string | Return data at this step (only if enabled)               |

### Example Output

Running `mega-evme run 0x60016000526001601ff3 --trace --tracer opcode` produces:

```json
{
  "failed": false,
  "gas": 60018,
  "returnValue": "0x01",
  "structLogs": [
    {
      "pc": 0,
      "op": "PUSH1",
      "gas": 9940000,
      "gasCost": 3,
      "depth": 1,
      "stack": [],
      "memory": []
    },
    {
      "pc": 2,
      "op": "PUSH1",
      "gas": 9939997,
      "gasCost": 3,
      "depth": 1,
      "stack": ["0x1"],
      "memory": []
    },
    {
      "pc": 4,
      "op": "MSTORE",
      "gas": 9939994,
      "gasCost": 6,
      "depth": 1,
      "stack": ["0x1", "0x0"],
      "memory": []
    },
    {
      "pc": 5,
      "op": "PUSH1",
      "gas": 9939988,
      "gasCost": 3,
      "depth": 1,
      "stack": [],
      "memory": [
        "0000000000000000000000000000000000000000000000000000000000000001"
      ]
    },
    {
      "pc": 7,
      "op": "PUSH1",
      "gas": 9939985,
      "gasCost": 3,
      "depth": 1,
      "stack": ["0x1"],
      "memory": [
        "0000000000000000000000000000000000000000000000000000000000000001"
      ]
    },
    {
      "pc": 9,
      "op": "RETURN",
      "gas": 9939982,
      "gasCost": 0,
      "depth": 1,
      "stack": ["0x1", "0x1f"],
      "memory": [
        "0000000000000000000000000000000000000000000000000000000000000001"
      ]
    }
  ]
}
```

## Examples

Minimal trace (no memory or stack, for compact output):

```bash
mega-evme run 0x60016000526001601ff3 \
  --trace --tracer opcode \
  --trace.opcode.disable-memory \
  --trace.opcode.disable-stack
```

Full trace to file with return data:

```bash
mega-evme run 0x60016000526001601ff3 \
  --trace --tracer opcode \
  --trace.opcode.enable-return-data \
  --trace.output trace.json
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.megaeth.com/mega-evme/tracing/opcode-tracer.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.