Premix is premium gasoline mixed with lubricant oil and it is used in two-stroke internal combustion engines. It tends to produce a lot of smoke.

This Premix is a block validation debugging tool for the Nimbus Ethereum client. Premix will query transaction execution steps from other Ethereum clients and compare them with those generated by Nimbus. It will then produce a web page to present comparison results that can be inspected by the developer to pinpoint the faulty instruction.

Premix will also produce a test case for the specific problematic transaction, complete with a database snapshot to execute transaction validation in isolation. This test case can then be integrated with the Nimbus project's test suite.

Before you can use the Premix debugging tool there are several things you need to prepare. The first requirement is a recent version of geth installed from source or binary. The minimum required version is 1.8.18. Beware that version 1.8.x contains bugs in transaction tracer, upgrade it to 1.9.x soon after it has been released. Afterwards, you can run it with this command:

geth --rpc --rpcapi eth,debug --syncmode full --gcmode=archive

You need to run it until it fully syncs past the problematic block you want to debug (you might need to do it on an empty db, because some geth versions will keep on doing a fast sync if that's what was done before). After that, you can stop it by pressing CTRL-C and rerun it with the additional flag --maxpeers 0 if you want it to stop syncing

• or just let it run as is if you want to keep syncing.

The next requirement is building Nimbus and Premix:

# in the top-level directory:
make

After that, you can run Nimbus with this command:

./build/nimbus --prune:archive --port:30304

Nimbus will try to sync up to the problematic block, then stop and execute Premix which will then load a report page in your default browser. If it fails to do that, you can see the report page by manually opening premix/index.html.

In your browser, you can explore the tracing result and find where the problem is.

Premix is the main debugging tool. It produces reports that can be viewed in a browser and serialised debug data that can be consumed by the debug tool. Premix consumes data produced by either nimbus, persist, or dumper.

You can run it manually using this command:

./build/premix debug*.json

Because the Nimbus P2P layer still contains bugs, you may become impatient when trying to sync blocks. In the ./premix directory, you can find a persist tool. It will help you sync relatively quicker because it will bypass the P2P layer and download blocks from geth via rpc-api.

When it encounters a problematic block during syncing, it will stop and produce debugging data just like Nimbus does.

./build/persist [--dataDir:your_database_directory] [--head: blockNumber] [--maxBlocks: number] [--numCommits: number]

In the same ./premix directory you'll find the debug tool that you can use to process previously generated debugging info in order to work with one block and one transaction at a time instead of multiple confusing blocks and transactions.

./build/debug block*.json

where block*.json contains the database snapshot needed to debug a single block produced by the Premix tool.

Dumper was designed specifically to produce debugging data that can be further processed by Premix from information already stored in database. It will create tracing information for a single block if that block has been already persisted.

If you want to generate debugging data, it's better to use the Persist tool. The data generated by Dumper is usually used to debug Premix features in general and the report page logic in particular.

# usage:
./build/dumper [--datadir:your_path] --head:blockNumber

Hunter's purpose is to track down problematic blocks and create debugging info associated with them. It will not access your on-disk database, because it has its own prestate construction code.

Hunter will download all it needs from geth, just make sure your geth version is at least 1.8.18.

Hunter depends on eth_getProof(EIP1186). Make sure your installed geth supports this functionality (older versions don't have this implemented).

# usage:
./build/hunter --head:blockNumber --maxBlocks:number

blockNumber is the starting block where the hunt begins.

maxBlocks is the number of problematic blocks you want to capture before stopping the hunt.

Regress is an offline block validation tool. It will not download block information from anywhere like Persist tool. Regress will validate your already persisted block in database. It will try to find any regression introduced either by bugfixing or refactoring.

# usage:
./build/regress [--dataDir:your_db_path] --head:blockNumber