154 lines
5.1 KiB
Markdown
154 lines
5.1 KiB
Markdown
# Premix
|
|
|
|
> Premix is **pre**mium gasoline **mix**ed 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.
|
|
|
|
|
|
|
|
## Requirements
|
|
|
|
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](https://github.com/ethereum/go-ethereum/releases) or
|
|
[binary](https://ethereum.github.io/go-ethereum/downloads/). 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# in the top-level directory:
|
|
make
|
|
```
|
|
|
|
After that, you can run Nimbus with this command:
|
|
|
|
```bash
|
|
./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.
|
|
|
|
## Tools
|
|
|
|
### Premix
|
|
|
|
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:
|
|
|
|
```bash
|
|
./build/premix debug*.json
|
|
```
|
|
|
|
### Persist
|
|
|
|
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.
|
|
|
|
```bash
|
|
./build/persist [--dataDir:your_database_directory] [--head: blockNumber] [--maxBlocks: number] [--numCommits: number]
|
|
```
|
|
|
|
### Debug
|
|
|
|
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.
|
|
|
|
```bash
|
|
./build/debug block*.json
|
|
```
|
|
|
|
where `block*.json` contains the database snapshot needed to debug a single
|
|
block produced by the Premix tool.
|
|
|
|
### Dumper
|
|
|
|
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.
|
|
|
|
```bash
|
|
# usage:
|
|
./build/dumper [--datadir:your_path] --head:blockNumber
|
|
```
|
|
|
|
### Hunter
|
|
|
|
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)](https://github.com/ethereum/EIPs/issues/1186). Make
|
|
sure your installed `geth` supports this functionality (older versions don't
|
|
have this implemented).
|
|
|
|
```bash
|
|
# 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
|
|
|
|
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.
|
|
|
|
```bash
|
|
# usage:
|
|
./build/regress [--dataDir:your_db_path] --head:blockNumber
|
|
```
|