# run Execute arbitrary EVM bytecode in a controlled local environment. ## Usage ``` mega-evme run [OPTIONS] [CODE] ``` `CODE` is the bytecode to execute, given as a `0x`-prefixed hex string. You can also supply bytecode from a file with `--codefile`. Exactly one of these two inputs must be provided. ## Code Input | Argument | Description | | ------------------- | --------------------------------------------------------------- | | `CODE` | EVM bytecode as a `0x`-prefixed hex string (positional) | | `--codefile ` | Path to a file containing bytecode. Use `-` to read from stdin. | ## Execution Modes ### Call Mode (default) By default, `run` operates in call mode. Before execution, the bytecode is deployed at the receiver address (default: `0x0000000000000000000000000000000000000000`). The transaction is then a `CALL` to that address. Input data supplied via `--input` or `--inputfile` is passed as calldata. Use `--receiver` to target a specific address, or rely on the default zero address for simple bytecode tests. ### Create Mode (`--create`) Pass `--create true` to treat the bytecode as init code. Any input data supplied via `--input` or `--inputfile` is appended to the init code before execution, allowing you to pass constructor arguments. On success, the output is the deployed contract's runtime bytecode, and the tool prints the resulting contract address. In create mode, `--receiver` must not be set. ## Options `run` accepts several groups of shared options. Each group is documented on its own page. | Group | Flags | Reference | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | Transaction | `--create`, `--gas`, `--basefee`, `--priority-fee`, `--tx-type`, `--value`, `--sender`, `--receiver`, `--nonce`, `--input`, `--inputfile`, `--source-hash`, `--mint`, `--auth`, `--access` | [Transaction Types](https://docs.megaeth.com/mega-evme/reference/transaction-types) | | State management | `--prestate`, `--sender.balance`, `--dump`, `--dump.output` | [State Management](https://docs.megaeth.com/mega-evme/configuration/state-management) | | Chain and spec | `--spec`, `--chain-id` | [Chain and Spec](https://docs.megaeth.com/mega-evme/configuration/chain-and-spec) | | Block environment | `--block.number`, `--block.coinbase`, `--block.timestamp`, `--block.gaslimit`, `--block.basefee`, `--block.difficulty`, `--block.prevrandao`, `--block.blobexcessgas` | [Block Environment](https://docs.megaeth.com/mega-evme/configuration/block-environment) | | SALT buckets | `--bucket-capacity` | [SALT Buckets](https://docs.megaeth.com/mega-evme/configuration/salt-buckets) | | RPC cache / retry | `--rpc.cache-size`, `--rpc.cache-dir`, `--rpc.no-cache-file`, `--rpc.chain-id`, `--rpc.clear-cache`, `--rpc.max-retries`, `--rpc.backoff-ms`, `--rpc.rate-limit` | [RPC Cache and Retry](https://docs.megaeth.com/mega-evme/configuration/state-management#rpc-cache-and-retry) | | Tracing | `--trace`, `--tracer`, `--trace.output`, and tracer-specific flags | [Tracing Overview](https://docs.megaeth.com/mega-evme/tracing/overview) | | Output | `--json` | See [JSON output](#json-output) below | **Key defaults for `run`:** | Option | Default | | ------------ | -------------------------------------------- | | `--spec` | `Rex4` | | `--gas` | `10000000` | | `--sender` | `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` | | `--receiver` | `0x0000000000000000000000000000000000000000` | ## JSON Output Pass `--json` to emit a single `ExecutionSummary` JSON object to stdout instead of the human-readable banner. No banners or diagnostic text are printed in JSON mode — stdout contains exactly one JSON object. The object includes these fields: | Field | Type | Description | | ------------------ | ---------------- | ---------------------------------------------------------------------------- | | `success` | `bool` | Whether execution succeeded | | `gas_used` | `number` | Gas consumed | | `output` | `string \| null` | Hex-encoded return data (present only on success with non-empty output) | | `contract_address` | `string \| null` | Deployed address (present only for successful `--create` transactions) | | `logs_count` | `number` | Number of log entries emitted | | `revert_reason` | `string \| null` | Decoded revert reason (present only on revert) | | `halt_reason` | `string \| null` | Halt reason (present only on halt) | | `trace` | `object \| null` | Execution trace (when `--trace` is enabled without `--trace.output`) | | `state` | `object \| null` | Post-execution state dump (when `--dump` is enabled without `--dump.output`) | When `--trace` or `--dump` is used with an output file (`--trace.output`, `--dump.output`), data is written to that file and the corresponding JSON field is omitted. When no output file is specified, the data is inlined into the JSON object. ```bash mega-evme run 0x60016000526001601ff3 --json ``` ## Examples ### Simple bytecode execution Execute bytecode that stores `1` in memory and returns it: ```bash mega-evme run 0x60016000526001601ff3 ``` ### Execute from a file Read bytecode from a hex file: ```bash mega-evme run --codefile contract.hex ``` Read from stdin: ```bash cat contract.hex | mega-evme run --codefile - ``` ### Contract deployment with `--create` Deploy a contract using init code. The tool prints the deployed contract address on success: ```bash mega-evme run --create true 0x6080604052... ``` Dump the resulting state to inspect what was deployed: ```bash mega-evme run --create true 0x6080604052... --dump ``` ### Execute with input data Call the bytecode at the receiver address with calldata: ```bash mega-evme run 0x60016000526001601ff3 --input 0xabcdef01 ``` Pass constructor arguments in create mode (appended to init code): ```bash mega-evme run --create true 0x6080604052... \ --input 0x0000000000000000000000001234567890abcdef1234567890abcdef12345678 ``` ### Trace execution Run with opcode-level tracing and save the output: ```bash mega-evme run 0x60016000526001601ff3 \ --trace --tracer opcode \ --trace.output trace.json ``` ## Full Help Output ``` Run arbitrary EVM bytecode Usage: mega-evme run [OPTIONS] [CODE] Arguments: [CODE] EVM bytecode as hex string (positional argument) Options: --codefile File containing EVM code. If '-' is specified, code is read from stdin -v... Increase logging verbosity (-v = error, -vv = warn, -vvv = info, -vvvv = debug, -vvvvv = trace) --log.file Log file path. If specified, logs are written to this file instead of stderr [aliases: --log-file] --log.no-color Disable colorful console logging. Only applies when logging to stderr (no --log.file) [aliases: --log-no-color] -h, --help Print help (see a summary with '-h') Transaction Options: --tx-type Transaction type (0=Legacy, 1=EIP-2930, 2=EIP-1559, etc.) [default: 0] [aliases: --type, --ty] --gas Gas limit for the evm [default: 10000000] [aliases: --gas-limit] --basefee Price set for the evm (gas price) [default: 0] [aliases: --gas-price, --price, --base-fee] --priority-fee Gas priority fee (EIP-1559) [aliases: --priorityfee, --tip] --sender The transaction origin [default: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266] [aliases: --from] --receiver The transaction receiver (execution context) [aliases: --to] --nonce The transaction nonce --create Indicates the action should be create rather than call [possible values: true, false] --value Value set for the evm. VALUE can be: plain number (wei), or number with suffix (ether, gwei, wei). Examples: `--value 1ether`, `--value 100gwei` --input Transaction data (input) as hex string [aliases: --data] --inputfile File containing transaction data (input). If '-' is specified, input is read from stdin [aliases: --datafile, --input-file, --data-file] --source-hash Source hash for deposit transactions (tx-type 126) [aliases: --sourcehash] --mint Amount of ETH to mint for deposit transactions (wei) --auth EIP-7702 authorization in format `AUTHORITY:NONCE->DELEGATION` (can be repeated) [aliases: --authorization] --access EIP-2930 access list entry in format `ADDRESS` or `ADDRESS:KEY1,KEY2,...` (can be repeated) [aliases: --accesslist, --access-list] State Options: --fork Fork state from a remote RPC endpoint --fork.block Block number of the state (post-block state) to fork from --rpc RPC URL [env: RPC_URL=] [default: http://localhost:8545] [aliases: --rpc-url] [compat alias: --fork.rpc] --prestate JSON file with prestate (genesis) config [aliases: --pre-state] --block-hash History block hashes for BLOCKHASH opcode. Format: `block_number:block_hash` (repeatable) [aliases: --blockhash, --block-hashes, --blockhashes] --sender.balance Balance to allocate to the sender account. Supports suffixes: ether, gwei, wei [aliases: --from.balance] --faucet Add ether to addresses. Format: `ADDRESS+=VALUE` (repeatable, supports suffixes) --balance Override balance for addresses. Format: `ADDRESS=VALUE` (repeatable, supports suffixes) --storage Override storage slots. Format: `ADDRESS:SLOT=VALUE` (repeatable) Chain Options: --spec Spec to use: MiniRex, Equivalence, Rex, Rex1, Rex2, Rex3, Rex4 [default: Rex4] --chain-id Chain ID [default: 6342] [aliases: --chainid] Block Options: --block.number Block number [default: 1] --block.coinbase Block coinbase [default: 0x0...0] [aliases: --block.beneficiary] --block.timestamp Block timestamp [default: 1] --block.gaslimit Block gas limit [default: 10000000000] --block.basefee Block base fee [default: 0] --block.difficulty Block difficulty [default: 0] --block.prevrandao Previous randao [aliases: --block.random] --block.blobexcessgas Blob excess gas [default: 0] External Environment Options: --bucket-capacity Bucket capacity configuration. Format: `bucket_id:capacity` (repeatable) State Dump Options: --dump Dump state after the run --dump.output Output file for state dump Output Options: --json Output results as JSON instead of human-readable text Trace Options: --trace Enable tracing --trace.output Output file for trace data --tracer Tracer: opcode, call, pre-state [default: opcode] --trace.opcode.disable-memory Disable memory capture --trace.opcode.disable-stack Disable stack capture --trace.opcode.disable-storage Disable storage capture --trace.opcode.enable-return-data Enable return data capture --trace.call.only-top-call Only trace top-level call --trace.call.with-log Include logs in call trace --trace.prestate.diff-mode Show state diff --trace.prestate.disable-code Disable code in prestate output --trace.prestate.disable-storage Disable storage in prestate output ``` ## See Also * [Transaction Types](https://docs.megaeth.com/mega-evme/reference/transaction-types) — full option reference for `--tx-type`, `--input`, `--access`, and more * [Chain and Spec](https://docs.megaeth.com/mega-evme/configuration/chain-and-spec) — choosing a spec and chain ID * [Block Environment](https://docs.megaeth.com/mega-evme/configuration/block-environment) — controlling block number, timestamp, coinbase, and other block fields * [State Management](https://docs.megaeth.com/mega-evme/configuration/state-management) — loading prestate and dumping final state * [SALT Buckets](https://docs.megaeth.com/mega-evme/configuration/salt-buckets) — configuring bucket capacities for storage gas testing * [Tracing Overview](https://docs.megaeth.com/mega-evme/tracing/overview) — opcode, call, and pre-state tracers * [Cookbook](https://docs.megaeth.com/mega-evme/cookbook) — worked examples for common use cases