nimbus-eth1/fluffy
Kim De Mey 5048c87679
First go at the Fluffy book using mkdocs as for nimbus.guide (#1842)
* First go at the Fluffy book using mkdocs as for nimbus.guide

* reorganize a little the index page

* Add small paragraph on the what in index page
2023-10-23 15:29:54 +02:00
..
common Bump submodules and related fixes (#1729) 2023-10-17 14:19:50 +02:00
docs/the_fluffy_book First go at the Fluffy book using mkdocs as for nimbus.guide (#1842) 2023-10-23 15:29:54 +02:00
eth_data Bump submodules and related fixes (#1729) 2023-10-17 14:19:50 +02:00
grafana Add instance/container select for version panel in grafana dashboard (#1737) 2023-09-08 09:05:00 +02:00
network Don't send the processed bitlist if contentQueue is full (#1835) 2023-10-20 18:03:20 +02:00
network_data/testnet0 Update Fluffy bootstrap ENRs to nodes on new provider (#1619) 2023-06-28 21:29:48 +02:00
rpc Portal BeaconLightClientNetwork -> BeaconNetwork renaming (#1832) 2023-10-20 12:06:25 +02:00
scripts Change some Fluffy related cli defaults (#1833) 2023-10-20 14:30:21 +02:00
tests Portal BeaconLightClientNetwork -> BeaconNetwork renaming (#1832) 2023-10-20 12:06:25 +02:00
tools Portal BeaconLightClientNetwork -> BeaconNetwork renaming (#1832) 2023-10-20 12:06:25 +02:00
README.md First go at the Fluffy book using mkdocs as for nimbus.guide (#1842) 2023-10-23 15:29:54 +02:00
conf.nim Change some Fluffy related cli defaults (#1833) 2023-10-20 14:30:21 +02:00
content_db.nim Bump submodules and related fixes (#1729) 2023-10-17 14:19:50 +02:00
fluffy.nim Portal BeaconLightClientNetwork -> BeaconNetwork renaming (#1832) 2023-10-20 12:06:25 +02:00
fluffy.nim.cfg Fix name of fluffy config file and disable log colors for Windows (#1551) 2023-04-20 12:58:56 +02:00
logging.nim Improve logging and logging options in Fluffy (#1548) 2023-04-19 17:01:01 +02:00
network_metadata.nim Add new Portal BlockBody type for Shanghai fork (#1589) 2023-05-30 06:56:54 +02:00
nim.cfg Build Fluffy tools individually through Makefile (#1626) 2023-07-05 16:44:18 +02:00
seed_db.nim Bump stint to v2.0: new array backend (#1747) 2023-09-13 09:32:38 +07:00
version.nim Add clientInfo to ENR for easier testnet debugging (#1513) 2023-09-20 12:19:40 +02:00

README.md

Fluffy: The Nimbus Portal Network Client

Fluffy CI Stability: experimental License: Apache License: MIT

Discord: Nimbus Status: #nimbus-general

Introduction

This folder holds the development of the Nimbus client implementation supporting the Portal Network: Fluffy. The Portal Network is a project still heavily in research phase and fully in flux. This client is thus still highly experimental.

Current status of specifications can be found in the portal-network-specs repository.

Development Updates

Monthly development updates are shared here.

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

How to Build & Run

Prerequisites

  • GNU Make, Bash and the usual POSIX utilities. Git 2.9.4 or newer.

Build the Fluffy client

git clone git@github.com:status-im/nimbus-eth1.git
cd nimbus-eth1
make fluffy

# See available command line options
./build/fluffy --help

# Example command: Run the client and connect to a bootstrap node.
./build/fluffy --bootstrap-node:enr:<base64 encoding of ENR>

Update and rebuild the Fluffy client

# From the nimbus-eth1 repository
git pull
# To bring the git submodules up to date
make update

make fluffy

Run a Fluffy client on the public testnet

# Connect to the Portal testnet bootstrap nodes and enable the JSON-RPC APIs
./build/fluffy --rpc --table-ip-limit:1024 --bucket-ip-limit:24

The table-ip-limit and bucket-ip-limit options are needed to allow more nodes with the same IPs in the routing tables. The default limits are there as security measure. It is currently needed to increase the limits for the testnet because the fleet of Fluffy nodes runs on only 2 machines / network interfaces.

There is a public Portal testnet which contains nodes of different clients.

Fluffy will default join the network through these bootstrap nodes. You can also explicitly provide the --network:testnet0 option to join this network, or --network:none to not connect to any of these bootstrapn odes.

Note: The --network option selects automatically a static set of specific bootstrap nodes belonging to a "testnet". Currently testnet0 is the only option, which results in connecting to the testnet bootstrap nodes. It should be noted that there is currently no real way to distinguish a "specific" Portal network, and as long as the same Portal protocols are supported, nodes can simply connect to it and no real separation can be made. When testing locally the --network:none option can be provided to avoid connecting to any of the testnet bootstrap nodes.

The Portal testnet is slowly being filled up with historical data through bridge nodes. Because of this, more recent history data is more likely to be available.. This can be tested by using the JSON-RPC call eth_getBlockByHash:

# Get the hash of a block from your favorite block explorer, e.g.:
BLOCKHASH=0x34eea44911b19f9aa8c72f69bdcbda3ed933b11a940511b6f3f58a87427231fb # Replace this to the block hash of your choice
# Run this command to get this block:
curl -s -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":"1","method":"eth_getBlockByHash","params":["'${BLOCKHASH}'", true]}' http://localhost:8545 | jq

One can also use the blockwalk tool to walk down the blocks one by one, e.g:

make blockwalk

BLOCKHASH=0x34eea44911b19f9aa8c72f69bdcbda3ed933b11a940511b6f3f58a87427231fb # Replace this to the block hash of your choice
./build/blockwalk --block-hash:${BLOCKHASH}

Run Fluffy test suite

# From the nimbus-eth1 repository
make fluffy-test

Run Fluffy local testnet script

./fluffy/scripts/launch_local_testnet.sh

Find more details on the usage and workings of the local testnet script here.

Windows support

Follow the steps outlined here to build fluffy on Windows.

The basics for developers

When working on this repository, you can run the env.sh script to run a command with the right environment variables set. This means the vendored Nim and Nim modules will be used, just as when you use make.

E.g.:

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

More development tips can be found on the general nimbus-eth1 readme.

The code follows the Status Nim Style Guide.

Build local dev container for portal-hive

To develop code against portal-hive tests you will need:

  1. Clone and build portal-hive (#1)

  2. Modify Dockerfile for fluffy in portal-hive/clients/fluffy/Dockerfile (#2)

  3. Build local dev container using following command: docker build --tag fluffy-dev --file ./fluffy/tools/docker/Dockerfile.portalhive . You may need to change fluffy-dev to the tag you using in portal-hive client dockerfile.

  4. Run the tests

Also keep in mind that ./vendors is dockerignored and cached. If you have to make local changes to one of the dependencies in that directory you'll have to remove vendors/ from ./fluffy/tools/docker/Dockerfile.portalhive.dockerignore.

Metrics and their visualisation

To enable metrics run Fluffy with the --metrics flag:

./build/fluffy --metrics

Default the metrics are available at http://127.0.0.1:8008/metrics.

The address can be changed with the --metrics-address and --metrics-port options.

This provides only a snapshot of the current metrics. In order track the metrics over time and to also visualise them one can use for example Prometheus and Grafana.

The steps on how to set up such system is explained in this guide.

A Fluffy specific dashboard can be found here.

This is the dashboard used for our Fluffy testnet fleet. In order to use it locally, you will have to remove the {job="nimbus-fluffy-metrics"} part from the instance and container variables queries in the dashboard settings. Or they can also be changed to a constant value.

The other option would be to remove those variables and remove their usage in each panel query.

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.