stonecharioteer/forest

Forest is an implementation of Filecoin written in Rust. The implementation will take a modular approach to building a full Filecoin node in Rust from the Filecoin Protocol Specification, specifically the virtual machine, blockchain, and node system.

Our crates:

component	description/crates
`forest`	the command-line interface and daemon (3 crate/workspace)
`node`	the networking stack and storage (7 crates)
`blockchain`	the chain structure and synchronization (8 crates)
`vm`	state transition and actors, messages, addresses (9 crates)
`key_management`	Filecoin account management (1 crate)
`crypto`	cryptographic functions, signatures, and verification (1 crate)
`encoding`	serialization library for encoding and decoding (1 crate)
`ipld`	the IPLD model for content-addressable data (9 crates)
`types`	the forest types (2 crates)
`utils`	the forest toolbox (12 crates)

Questions

Have questions? Feel free to post them in Forest Q&A!

Run with Docker

No need to install Rust toolchain or other dependencies, you will need only Docker.

# daemon
❯ docker run --init -it --rm ghcr.io/chainsafe/forest:latest --help
# cli
❯ docker run --init -it --rm --entrypoint forest-cli ghcr.io/chainsafe/forest:latest --help

Follow other instructions for proper forest usage. You may need to mount a volume to import a snapshot, e.g.

❯ docker run --init -it -v $HOME/Downloads:/downloads ghcr.io/chainsafe/forest:latest --import-snapshot /downloads/minimal_finality_stateroots_latest.car

Use dockerized Forest with host database:

❯ docker run --init -it -v $HOME/.forest:/home/forest/.local/share/forest  --rm ghcr.io/chainsafe/forest:latest --target-peer-count 50 --encrypt-keystore false

Dependencies

Rust (toolchain version is specified in rust-toolchain.toml)

Install rustup

OS Base-Devel/Build-Essential
Clang compiler
OpenCL bindings
Protoc

Ubuntu (20.04)

sudo make install-deps

sudo apt install build-essential clang ocl-icd-opencl-dev protobuf-compiler cmake

Archlinux

sudo pacman -S base-devel clang ocl-icd openssl

NOTE: protobuf needs to be installed manually, and protoc needs to present in PATH

Fedora (36)

sudo dnf install -y clang-devel ocl-icd-devel protobuf-compiler cmake

Installation

# Clone repository
git clone --recursive https://github.com/chainsafe/forest
cd forest

# Install binary to $HOME/.cargo/bin and run node
# avx2 is enabled by default. To disable it, remove 
# -Ctarget-feature from RUSTFLAGS in .cargo/config.toml
make install

forest

To create release binaries, checkout the latest tag and compile with the release feature.

git checkout $TAG
make build # make debug build of forest daemon and cli
# or
make release # make release build of forest daemon and cli
# or
make install # install forest daemon and cli

Config

Run the node with custom config and bootnodes

forest --config /path/to/your_config.toml

Example of config options available:

data_dir = "<directory for all chain and networking data>"
genesis_file = "<relative file path of genesis car file>"

[network]
listening_multiaddr = "<multiaddress>"
bootstrap_peers = ["<multiaddress>"]

Example of a multiaddress: "/ip4/54.186.82.90/tcp/1347/p2p/12D3K1oWKNF7vNFEhnvB45E9mw2B5z6t419W3ziZPLdUDVnLLKGs"

Forest will look for config files in the following order and priority:

Paths passed to the command line via the --config flag.
The environment variable FOREST_CONFIG_PATH, if no config was passed through command line arguments.
If none of the above are found, Forest will look in the systems default configuration directory ($XDG_CONFIG_HOME on Linux systems).
After all locations are exhausted and a config file is not found, a default configuration is assumed and used.

Logging

The Forest logger uses Rust's log filtering options with the RUST_LOG environment variable. For example:

RUST_LOG="debug,forest_libp2p::service=info" forest

Will show all debug logs by default, but the forest_libp2p::service logs will be limited to info

Forest can also send telemetry to the endpoint of a Loki instance or a Loki agent (see Grafana Cloud). Use --loki to enable it and --loki-endpoint to specify the interface and the port.

Testing

# To run base tests
cargo nextest run # use `make test-release` for longer compilation but faster execution

# To pull serialization vectors submodule and run serialization tests
make test-vectors

# To run all tests and all features enabled
make test-all

Chain synchronization checks are run after every merge to main. This code is maintained in a separate repository - Forest IaC.

Linters

The project uses exhaustively a set of linters to keep the codebase clean and secure in an automated fashion. While the CI will has them installed, if you want to run them yourself before submitting a PR (recommended), you should install a few of them.

# You can install those linters also with other package managers or by manually grabbing the binaries from the projects' repositories.

# Rust code linter
rustup component add clippy

# Rust code formatter
rustup component add rustfmt

# TOML linter
cargo install taplo-cli --locked

# Scanning dependencies for security vulnerabilities
cargo install cargo-audit

# Unused dependencies check
cargo install cargo-udeps --locked

# Spellcheck
cargo install cargo-spellcheck

# Test runner
cargo install cargo-nextest --locked

After everything is installed, you can run make lint-all.

Joining the testnet

Select the builtin calibnet configuration with the --chain option. The --auto-download-snapshot will ensure that a snapshot is downloaded if needed without any prompts.

./target/release/forest --chain calibnet --auto-download-snapshot

Interacting with Forest via CLI

When the Forest daemon is started, an admin token will be displayed. You will need this for commands that require a higher level of authorization (like a password). Forest, as mentioned above, uses multiaddresses for networking. This is no different in the CLI. To set the host and the port to use, if not using the default port or using a remote host, set the FULLNODE_API_INFO environment variable. This is also where you can set a token for authentication.

FULLNODE_API_INFO="<token goes here>:/ip4/<host>/tcp/<port>/http

Note that if a token is not present in the FULLNODE_API_INFO env variable, the colon is removed.

Forest developers will prepend this variable to CLI commands over using export on Linux or its equivalent on Windows. This will look like the following:

FULLNODE_API_INFO="..." forest-cli auth api-info -p admin

The admin token can also be set using --token flag.

forest-cli --token <ADMIN_TOKEN>

Detaching Forest process

You can detach Forest process via the --detach flag so that it runs in the background:

./target/release/forest --target-peer-count 50 --detach

The command will block until the detached Forest process has started its RPC server, allowing you to chain some RPC command immediately after.

Documentation

Contributing

Check out our contribution guidelines: CONTRIBUTING.md

ChainSafe Security Policy

Reporting a Security Bug

We take all security issues seriously, if you believe you have found a security issue within a ChainSafe project please notify us immediately. If an issue is confirmed, we will take all necessary precautions to ensure a statement and patch release is made in a timely manner.

Please email a description of the flaw and any related information (e.g. reproduction steps, version) to security at chainsafe dot io.

License

Forest is dual licensed under MIT + Apache 2.0.

stonecharioteer / forest