Fantom's off-the-chain testing framework based on Transaction Substate Recorder/Replayer.

substate-cli uses two submodules

1. go-opera-substate
2. go-ethereum-substate

To fetch all the data from submodules, run git submodule init and git submodule update.

To build all substate-cli, run make. You can find substate-cli binary in the build directory.

To replay substrate in a given block range,

substate-cli replay 0 41000000

The command replays transactions from block 0 to block 41000000. If the execution result in the replayer does not match the recorder result, it is immediately terminated with an error message. By default, substate-cli executes using 4 worker threads and reads the substate database from ./substate.fantom directory. These parameters can be adjusted. The number of worker threads can be set via --workers option.

substate-cli replay --workers 32 0 41000000

If substate database is located in another location, the directory path can be explicitly specified via the --substatedir option.

substate-cli replay --substatedir /path/to/substate_directory 0 41000000

Substates of the first 41 million blocks can be downloaded from here

More details of substate-cli can be found in substate-cli/README.md

In addition to functionality testing, the recorder/replayer is useful to obtain execution metrics for smart contracts such as EVM call runtime or opcode/instruction statistics. substate-cli is a command-line interface for the replayer and applications to obtain mentioned metrics.

NAME:
   substate-cli - Fantom substate command line interface

USAGE:
   substate-cli [global options] command [command options] [arguments...]

VERSION:
   1.10.8-stable

COMMANDS:
     replay        executes full state transitions and checks output consistency
     storage-size  returns changes in storage size by transactions in the specified block range
     code-size     reports code size and nonce of smart contracts in the specified block range
     code          write all contracts into a contract database
     dump          returns content in substates in json format
     db            A set of commands on substate DB
     help, h       Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

To execute substrate in a given block range,

substate-cli replay 0 41000000

To measure EVM call runtime of transactions in a given block range,

substate-cli replay --profiling-call  0 41000000

Output format

call: <Block>, <Nonce>, <Account>, <runtime in ns>

To get micro-profiling statistics,

substate-cli replay --profiling-opcode 0 41000000

The returned statistics include

• opcode frequency: the total number of times an opcode is used.
• opcode runtime: the total runtime of an opcode in nanoseconds.
• instruction frequency: a distribution showing number of times an instruction is executed.
• step length frequency: a distribution showing number of steps per smart contract invocation.

Output format

opcode-freq: <opcode>, <execution count>
opcode-runtime: <opcode>, <total runtime in ns>
instruction-freq: <execution frequency>, <instruction count>
steplen-freq: <execution steps>, <number of contracts>

To profile storage update size after each transaction in a given block range,

substate-cli storage-size 0 41000000

Output format

metric: <Block>, <Transaction>, <Unix timestamp>, <Account>, <Storage size change> ,<Size in input substate>, <Size in output substate>

To profile smart contract code size and nonce in a given block range,

substate-cli code-size 0 41000000

Output format

metric: <Block>, <Transaction>, <Unix timestamp>, <Account>, <Code size> ,<Nonce>, <Transaction type>

Produce a contract database for a block range. All smart contracts in this block range are written into a contract database. The contract database is a levelDB instance. The keys are the smart contract addressed and their values are the bytecode of the contract.