History

andri lim 729686ff57 add debug tool		2019-01-15 15:30:25 +02:00
..
assets	add report page assets	2019-01-15 15:30:25 +02:00
configuration.nim	add configuration	2019-01-15 15:30:25 +02:00
debug.nim	add debug tool	2019-01-15 15:30:25 +02:00
debug.nim.cfg	add debug tool	2019-01-15 15:30:25 +02:00
downloader.nim	add premix support tools	2019-01-15 15:30:25 +02:00
parser.nim	add premix support tools	2019-01-15 15:30:25 +02:00
persist.nim	fix persist tool	2019-01-15 15:30:25 +02:00
readme.md	update readme.md	2019-01-15 15:30:25 +02:00

readme.md

Premix

Premix was premium(subsidized gasoline) mixed [with lubricant oil] used for two stroke internal combustion engines and it tends to produce a lot of smoke.

Today premix is a block validation debugging tool targeting at nimbus ethereum client. Premix will query transaction execution steps from other ethereum clients and compare it with nimbus'.

Premix then will produce a web page to present comparison result that can be inspected by developer to pinpoint where the faulty instruction located.

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

Requirements

Before you start to use premix debugging tool there are several things you need to prepare. The first one is you need to install geth from source or binary. Then you can run it with this command:

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

You need to run it until it synced past the problematic block you want to debug. After that you can stop it by pressing CTRL-C and rerun it with addition flags --maxpeers 0 if you want it to stop syncing or let it run as is if you want keep syncing.

The next requirement is you should build nimbus and premix with latest dependencies:

nim c nimbus/nimbus
nim c premix/premix

After you successfully build nimbus and premix, you can run nimbus with this command.

nimbus --prune:archive

Nimbus will try to sync up to problematic block then it will stop and execute premix. You can see the premix report page by opening premix/index.html if premix failed to open your default browser.

In the browser, you can try to navigate tracing result and find where the problem/bug is.

Helper tools

Persist Tool Because nimbus p2p layer still contains bugs, you may become impatient when try to syncing blocks. In /premix directory, you can find a persist.nim tool. It will help you to sync relative quicker because it will bypass p2p layer and download blocks from geth via rpc-api.

nim c -r premix/persist --dataDir:your_database_directory

Debug Tool Premix debugging tool also produce a set of debugging meta data that you can use to quickly find the bug without the need to run p2p layer or any other unnecessary code. Also in /premix directory you'll find debug.nim tool that you can use to execute this debug meta data and you'll only need to work with one block and one transaction at a time instead of multiple confusing multiple blocks or transactions.

nim c -r premix/debug (TODO: more options will come)