Welcome to Floresta: a lightweight Bitcoin full node implementation written in Rust and powered by Utreexo, a novel dynamic accumulator designed for the Bitcoin UTXO set.
This project is composed of two parts, libfloresta and florestad. libfloresta is
a set of reusable components that can be used to build Bitcoin applications. florestad is built on top of libfloresta to provide a full node implementation, including a watch-only wallet and an Electrum server. If you just want to run a full node, you can use florestad directly, either by building it from source or by downloading a pre-built binary from the releases.
For developers, detailed documentation for libfloresta is available here. Additionally, the floresta-docs mdBook provides an in-depth look at the libraries' architecture and internals.
- Building
- Running
- Running the Tests
- Running Benchmarks
- Fuzzing
- Contributing
- Using Nix
- License
- Acknowledgments
- Consensus Implementation
If you want to discuss this project, you can join our Discord server here. If you want to disclose
a security vulnerability, please email Davidson Souza at me AT dlsouza DOT lol, using the PGP key 2C8E0F 836FD7D BBBB9E 9B2EF899 64EC3AB 22B2E3.
sudo apt update
sudo apt install gcc build-essential pkg-config libssl-devYou'll need Rust and Cargo, refer to this for more details. Minimum support version is rustc 1.74 and newer.
Once you have Cargo, clone the repository with:
git clone https://github.com/vinteumorg/Floresta.gitgo to the Floresta directory
$ cd Floresta/and build with cargo build
cargo build --release
# Optionally, you can add florestad and floresta-cli to the path with
cargo install --path ./florestad
cargo install --path ./crates/floresta-cliThe following steps should be executed in a Terminal application. Tip: press Command (⌘) + Space and search for terminal.
To install, run the following command from your terminal:
xcode-select --installUpon running the command, you should see a popup appear.
Click on Install to continue the installation process.
Homebrew is a package manager for macOS that allows one to install packages from the command line easily. You can use the package manager of your preference.
To install the Homebrew package manager, see: https://brew.sh
Note: If you run into issues while installing Homebrew or pulling packages, refer to Homebrew's troubleshooting page.
On the Terminal, using Homebrew, run the following:
brew update
brew install gcc pkg-config openssl- At this point you can proceed from cargo and rust at the previous section.
If you're using Nix, you can add Florestad to your system with its overlay.
{
#Here you declare the floresta set for your flake
inputs.floresta-node = {
url = "github:vinteumorg/Floresta";
inputs = {
nixpkgs.follows = "nixpkgs";
flake-parts.follows = "flake-parts";
};
};
#Pass floresta-node as a input to "output".
outputs = { self, floresta-node }:
{
imports = [
{
overlays = [
# Here you use the floresta overlay with your others
floresta-node.overlay.default
];
}
];
};then florestad and floresta-cli will be available just like any other package with
pkgs.floresta-nodeAfter building, florestad and floresta-cli will be available in the target directory. You can run the full node with
$ ./target/release/florestad
# or, if you installed it with cargo install
$ florestadYou may run it as a background process with the --daemon flag.
florestad --daemonThis will start the full node, and you can connect to it with an Electrum wallet or with the floresta-cli tool.
$ floresta-cli getblockchaininfoFor more information on how to use the floresta-cli tool, you can check the api documentation.
Before running you can create the SSL certificates. If you don't do it, it will display a logging Failed to load SSL certificates, ignoring SSL. However, it is not mandatory to have the certificates to run the full node.
If you want to start your node and get up and running quickly, you can use the Assume Utreexo feature. This is enabled by defalt, but you can disable it with the --no-assume-utreexo flag.
$ florestad --no-assume-utreexoAfter the node starts it will validate everything in the background, downloading blocks from genesis to the assumed height, validating them and compare with the provided value. This way, you can start using the node right away, but still validate everything. This option, however, will take some time to complete, using a lot of CPU and bandwidth.
This is the default behavior of the florestad if no flags are provided. You can disable it using:
$ florestad --no-backfillFloresta supports compact block filters, which can be used to scan for transactions in a block without downloading the entire block. You can start the node with the --cfilters flag to download the filters for the blocks that you're interested in. You can also use the --filters-start-height flag to specify the block height that you want to start downloading the filters from. This is useful if you want to download only the filters for a specific range of blocks.
$ florestad --cfilters --filters-start-height 800000You can get a list of all the available commands by running
$ floresta-cli helpand you can get the cli parameters by running
$ floresta-cli help <command>Floresta comes with a watch-only wallet that you can use to track your transactions. You just need to provide the wallet
information, either as a configuration file or as a command line argument. See the sample configuration file for an example config. Floresta supports SLIP-132 extended public keys (xpubs) and output descriptors. You can add new wallets to follow at any time, just
call the rescan rpc after adding the wallet.
You can add new descriptors to the wallet with the importdescriptor rpc.
$ floresta-cli importdescriptor "wpkh(xpub6CFy3kRXorC3NMTt8qrsY9ucUfxVLXyFQ49JSLm3iEG5gfAmWewYFzjNYFgRiCjoB9WWEuJQiyYGCdZvUTwPEUPL9pPabT8bkbiD9Po47XG/<0;1>/*)"The rescan assumes that you have compact block filters for the blocks that you're scanning. You can either download all the filters
(about 11GB on mainnet) or, if you know the block range that you're interested in, you can download only the filters for that range
using the --filters-start-height option. Let's you know that none of your wallets are older than block 800,000. Just start the node with.
$ ./target/release/florestad --cfilters --filters-start-height 800000if you add a wallet and want to rescan the blocks from 800,000 to the current height, you can use the rescan rpc.
$ floresta-cli rescan 800000Once you have a transaction cached in your watch-only, you can use either the rpc or integrated electrum server to retrieve information about your wallet. You can use wallets like Electrum or Sparrow to connect to your node and retrieve information about your wallet. Just connect with the server running at 127.0.0.1:50001:t. On electrum you may want to use the --oneserver flag to connect to a single server, for better privacy.
The tests in floresta-cli depend on the compiled florestad binary. Make sure to build the entire project first by running:
$ cargo buildFunctional Tests also need some dependencies, we use python for writing them and uv to manage its dependencies.
Our tests also needs the Utreexod and florestad binaries to match some funcionalities and we have some helper scripts to avoid conflicts, which happens a lot while developing but can help one that have one of them installed in the system.
See Setting Functional Tests Binaries for more instructions.
There's a set of tests that you can run with:
$ cargo testFor the full test suite, including long-running tests, use:
cargo test --releaseWe provide two helper scripts to support our functional tests and ensure the correct binaries are used.
-
prepare.sh checks for build dependencies for both
utreexodandflorestad, builds them, and sets the$FLORESTA_TEMP_DIRenvironment variable. This variable points to where our functional tests will look for the binaries — specifically at$FLORESTA_TEMP_DIR/binaries. -
run.sh adds the binaries found at
$FLORESTA_TEMP_DIR/binariesto your$PATHand runs the tests in that environment.
Using these scripts, you have a few options for running the tests and verifying the functionality of florestad:
-
Manually: Build the binaries yourself and place them at
$FLORESTA_TEMP_DIR/binaries, where$FLORESTA_TEMP_DIRis set to be an arbitrary directory. -
(Recommended): Use the helper scripts — prepare.sh and run.sh — to automatically build and run the tests.
-
With installed binaries: If you’ve already installed the binaries system-wide, you can simply run the tests directly.
Additional functional tests are available (minimum python version: 3.12).
-
Recommended: install uv: a rust-based python package and project manager.
-
Configure an isolated environment:
# create a virtual environment
# (it's good to not mess up with your os)
uv venv
# Alternatively, you can specify a python version (e.g, 3.12),
uv venv --python 3.12
# activate the python virtual environment
source .venv/bin/activate
# check if the python path was modified
which python- Install module dependencies:
# installs dependencies listed in pyproject.toml.
# in local development environment
# it do not remove existing packages.
uv pip install -r pyproject.toml
# if you're a old-school pythonist,
# install from requirements.txt
# without remove existing packages.
uv pip install -r tests/requirements.txt
# Alternatively, you can synchronize it
# uses the uv.lock file to enforce
# reproducible installations.
uv sync- Format code
uv run black ./tests
# if you want to just check
uv run black --check --verbose ./tests- Lint code
uv run pylint ./tests- Run tests:
Our tests are separated by "test suites". Suites are folders located in ./tests/<suite> and the tests are the ./tests/<suite>/*-test.py files. To run all suites, type:
uv run tests/run_tests.pyYou can list all suites with:
uv run tests/run_tests.py --list-suitesTo run a specific suite:
uv run tests/run_tests.py --test-suite <suite>You can even add more:
uv run tests/run_tests.py --test-suite <suite_A> --test-suite <suite_B>If you have nix, we provide a devshell that you can access with
nix develop .#func-tests-envThe func-tests-env devshell provides:
uv.- Python dependencies
utreexodincluded in$PATHand linked in$FLORESTA_TEMP_DIRflorestadincluded in$PATHand linked in$FLORESTA_TEMP_DIRrun_testalias.run_test="uv run tests/run_tests.py"
Floresta uses criterion.rs for benchmarking. You can run the default set of benchmarks with:
cargo benchBy default, benchmarks that are resource-intensive are excluded to allow for quicker testing. If you'd like to include all benchmarks, use the following command:
EXPENSIVE_BENCHES=1 cargo benchNote: Running with
EXPENSIVE_BENCHES=1enables the full benchmark suite, which will take several minutes to complete.
This project uses cargo-fuzz (libfuzzer) for fuzzing, you can run a fuzz target with:
cargo +nightly fuzz run local_address_strYou can replace local_address_str with the name of any other target you want to run.
This project uses Prometheus as a monitoring system. To enable it you must build the project with the metrics feature enabled:
cargo build --release --features metricsThe easiest way to visualize those metrics is by using some observability graphic tool like Grafana. To make it easier, you can also straight away use the docker-compose.yml file to spin up an infrastructure that will run the project with Prometheus and Grafana.
To run it, first make sure you have Docker Compose installed and then:
docker-compose up -d --buildGrafana should now be available to you at http://localhost:3000. To log in, please check the credentials defined in the docker-compose.yml file.
Contributions are welcome, feel free to open an issue or a pull request. Check out our CONTRIBUTING.md for more information on best practices and guidelines.
If you want to contribute but don't know where to start, take a look at the issues, there's a few of them marked as good first issue.
If you already have Nix you just need to do:
$ nix developand use our flake for development which include
- nix(fmt) and rust(fmt) in pre-commit.
- pre-commit.
- rustup.
- Typos in pre-commit.
- Just, the command runner.
If you do not have Nix you can Check their guide.
This project is licensed under the MIT License - see the LICENSE file for details
One of the most challenging parts of working with Bitcoin is keeping up with the consensus rules. Given its nature as a consensus protocol, it's very important to make sure that the implementation is correct. Instead of reimplementing a Script interpreter, we use rust-bitcoinconsensus to verify transactions. This is a bind around a shared library that is part of Bitcoin Core. This way, we can be sure that the consensus rules are the same as Bitcoin Core, at least for scripts.
Although tx validation is arguably the hardest part in this process. This integration can be further improved by using libbitcoinkernel, that will increase the scope of libbitcoinconsensus to outside scripts, but this is still a work in progress.