Nimbus: an Ethereum Execution Client for Resource-Restricted Devices https://status-im.github.io/nimbus-eth1/
Go to file
Zahary Karadjov 74c67a4730
Move the beacon_node docker files to their own repo
2019-09-10 12:42:21 -04:00
.vscode vscode: add default build task 2018-08-22 21:43:22 -06:00
doc Update Nimbus - An Ethereum 2.0 Sharding Client_xt.md 2018-05-28 10:44:12 -07:00
docker Move the beacon_node docker files to their own repo 2019-09-10 12:42:21 -04:00
examples metrics HTTP server replacing the periodic "stats" logging 2019-07-19 15:17:51 +03:00
nimbus completing generateHeaderFromParentHeader implementation 2019-09-04 19:05:21 +02:00
nix [Nix] Some steps towards cross-compilation support 2019-02-20 01:23:05 +02:00
premix implement bc test fixtures parser 2019-09-04 19:05:21 +02:00
tests parsing complete 2019-09-04 19:05:21 +02:00
vendor bump vendor/nimbus-build-system [skip ci] 2019-09-05 13:53:05 +02:00
wrappers Refactor bootnodes and whispernodes 2019-08-16 08:51:40 +02:00
.appveyor.yml use nimbus-build-system 2019-08-22 02:02:32 +02:00
.gitignore refactor the C and Go wrapper build system 2019-08-02 18:13:47 +02:00
.gitmodules clean up .gitmodules 2019-08-30 17:28:11 +02:00
.travis.yml Travis: fix Nim caching 2019-08-28 16:19:08 +02:00
BlockchainTests.md implement bc test fixtures parser 2019-09-04 19:05:21 +02:00
GeneralStateTests.md modexp cleanup 2019-05-13 10:26:28 +03:00
LICENSE-APACHEv2 Update README badges and add dual-license header 2018-04-06 16:52:10 +02:00
LICENSE-MIT Update README badges and add dual-license header 2018-04-06 16:52:10 +02:00
Makefile Makefile: define SHELL for when submodules haven't been fetched yet [skip ci] 2019-09-10 02:48:34 +02:00
PersistBlockTests.md Add PersistBlockTest for block 1352922, fixes #363 2019-08-14 20:56:57 +02:00
PrecompileTests.md update PrecompileTests.md 2019-04-26 14:01:30 +02:00
README.md it's "libpcre3-dev" in Ubuntu too 2019-09-04 13:29:36 +02:00
TracerTests.md update test logs 2019-01-06 14:27:06 +01:00
TransactionTests.md update TransactionTests.md on 64-bit 2019-09-03 09:38:56 +02:00
default.nix [Nix] Some steps towards cross-compilation support 2019-02-20 01:23:05 +02:00
env.sh bump submodules 2019-08-24 21:12:43 +02:00
nim.cfg various changes: 2019-08-02 18:59:47 +02:00
nimbus.nimble tests: reduce RAM usage 2019-09-05 19:26:16 +02:00

README.md

Nimbus: an Ethereum 2.0 Sharding Client for Resource-Restricted Devices

Windows build status (Appveyor) Build Status (Travis) License: Apache License: MIT Stability: experimental

Join the Status community chats: Gitter: #status-im/nimbus Riot: #nimbus Riot: #dev-status

Rationale

Nimbus: an Ethereum 2.0 Sharding Client. The code in this repository is currently focusing on Ethereum 1.0 feature parity, while all 2.0 research and development is happening in parallel in nim-beacon-chain.

Development Updates

To keep up to date with changes and development progress, follow the Nimbus blog.

Building & Testing

We currently do not guarantee that Nimbus will work on Windows.

Prerequisites

(On Windows, a precompiled DLL collection download is available through the fetch-dlls Makefile target: (Windows instructions).)

Rocksdb

A recent version of Facebook's RocksDB is needed - it can usually be installed using your system's package manager:

# MacOS with Homebrew
brew install rocksdb

# Fedora
dnf install rocksdb-devel

# Debian and Ubuntu
sudo apt-get install librocksdb-dev

# Arch (AUR)
pakku -S rocksdb

You can also build and install it by following their instructions.

PCRE

If you don't already have it, you will also need PCRE to build Nimbus.

# MacOS with Homebrew
brew install pcre

# Fedora
dnf install pcre

# Debian and Ubuntu
sudo apt-get install libpcre3-dev

# Arch (AUR)
pakku -S pcre-static

Developer tools

GNU Make, Bash and the usual POSIX utilities

Obtaining the prerequisites through the Nix package manager

Experimental

Users of the Nix package manager can install all prerequisites simply by running:

nix-shell default.nix

Build & Develop

POSIX-compatible OS

To build Nimbus (in "build/nimbus"), just execute:

make # The first `make` invocation will update all Git submodules and prompt you to run `make` again.
     # It's only required once per Git clone. You'll run `make update` after each `git pull`, in the future,
     # to keep those submodules up to date.

make nimbus # build the Nimbus binary

Running ./build/nimbus --help will provide you with a list of the available command-line options. To start syncing with mainnet, just execute ./build/nimbus without any parameters.

To execute all tests:

make test

To pull the latest changes in all the Git repositories involved:

git pull
make update

To run a command that might use binaries from the Status Nim fork:

./env.sh bash # start a new interactive shell with the right env vars set
which nim
nim --version

# or without starting a new interactive shell:
./env.sh which nim
./env.sh nim --version

Our Wiki provides additional helpful information for debugging individual test cases and for pairing Nimbus with a locally running copy of Geth.

Windows

(Experimental support!)

Install Mingw-w64 for your architecture using the "MinGW-W64 Online Installer" (first link under the directory listing). Run it and select your architecture in the setup menu ("i686" on 32-bit, "x86_64" on 64-bit), set the threads to "win32" and the exceptions to "dwarf" on 32-bit and "seh" on 64-bit. Change the installation directory to "C:\mingw-w64" and add it to your system PATH in "My Computer"/"This PC" -> Properties -> Advanced system settings -> Environment Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin (it's "C:\mingw-w64\mingw32\bin" on 32-bit)

Install Git for Windows and use a "Git Bash" shell to clone and build Nimbus.

If you don't want to compile RocksDB and SQLite separately, you can fetch pre-compiled DLLs with:

mingw32-make # this first invocation will update the Git submodules
mingw32-make fetch-dlls # this will place the right DLLs for your architecture in the "build/" directory

You can now follow those instructions in the previous section by replacing make with mingw32-make (regardless of your 32-bit or 64-bit architecture):

mingw32-make nimbus # build the Nimbus binary
mingw32-make test # run the test suite
# etc.

Raspberry PI

Experimental The code can be compiled on a Raspberry PI:

  • Raspberry PI 3b+
  • 64gb SD Card (less might work too, but the default recommended 4-8GB will probably be too small)
  • Rasbian Buster Lite - Lite version is enough to get going and will save some disk space!

Assuming you're working with a freshly written image:


# Start by increasing swap size to 2gb:
sudo vi /etc/dphys-swapfile
# Set CONF_SWAPSIZE=2048
# :wq
sudo reboot

# Install prerequisites
sudo apt-get install git libgflags-dev libsnappy-dev

mkdir status
cd status

# Install rocksdb
git clone https://github.com/facebook/rocksdb.git
cd rocksdb
make shared_lib
sudo make install
cd..

# Raspberry pi doesn't include /usr/local/lib in library search path - need to add
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

git clone https://github.com/status-im/nimbus.git

cd nimbus

# Follow instructions above!

Development tips

  • you can switch the DB backend with a Nim compiler define: -d:nimbus_db_backend=... where the (case-insensitive) value is one of "rocksdb" (the default), "sqlite", "lmdb"

  • the Premix debugging tools are documented separately

  • you can control the Makefile's verbosity with the V variable (defaults to 0):

make V=1 # verbose
make V=2 test # even more verbose
make LOG_LEVEL=DEBUG nimbus # this is the default
make LOG_LEVEL=TRACE nimbus # log everything
  • pass arbitrary parameters to the Nim compiler:
make NIMFLAGS="-d:release"
  • if you want to use SSH keys with GitHub (also handles submodules):
make github-ssh
  • force a Nim compiler rebuild:
rm vendor/Nim/bin/nim
make -j8 build-nim

Git submodule workflow

Working on a dependency:

cd vendor/nim-chronicles
git checkout -b mybranch
# make some changes
git status
git commit -a
git push origin mybranch
# create a GitHub PR and wait for it to be approved and merged
git checkout master
git pull
git branch -d mybranch
# realise that the merge was done without "--no-ff"
git branch -D mybranch
# update the submodule's commit in the superproject
cd ../..
git status
git add vendor/nim-chronicles
git commit

It's important that you only update the submodule commit after it's available upstream.

You might want to do this on a new branch of the superproject, so you can make a GitHub PR for it and see the CI test results.

Don't update all Git submodules at once, just because you found the relevant Git command or make target. You risk updating submodules to other people's latest commits when they are not ready to be used in the superproject.

Adding the submodule "https://github.com/status-im/foo" to "vendor/foo":

vendor/nimbus-build-system/scripts/add_submodule.sh status-im/foo
# or
./env.sh add_submodule status-im/foo
# want to place it in "vendor/bar" instead?
./env.sh add_submodule status-im/foo vendor/bar

Removing the submodule "vendor/bar":

git submodule deinit -f -- vendor/bar
git rm -f vendor/bar

Checking out older commits, either to bisect something or to reproduce an older build:

git checkout <commit hash here>
make clean
make -j8 update

Running a dependency's test suite using nim instead of nimble (which cannot be convinced not to run a dependency check, thus clashing with our jury-rigged "vendor/.nimble/pkgs"):

cd vendor/nim-rocksdb
../nimbus-build-system/scripts/nimble.sh test
# or
../../env.sh nimble test

Troubleshooting

Report any errors you encounter, please, if not already documented!

  • Turn it off and on again:
make clean
make update

License

Licensed and distributed under either of

or

at your option. These files may not be copied, modified, or distributed except according to those terms.