Welcome to Floresta, a lightweight Bitcoin full node implementation written in Rust, 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.
If you want to use libfloresta to build your own Bitcoin application, you can find the documentation here.
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 to the path with
cargo install --path ./florestadIf you're using Nix, you can add Florestad to your system with its overlay.
{
#Here you declare the import for your flake
inputs.florestad = {
url = "github:vinteumorg/Floresta";
inputs = {
nixpkgs.follows = "nixpkgs";
flake-parts.follows = "flake-parts";
};
};
outputs = inputs @ { self, ... }:
{
imports = [
{
nixpkgs.overlays = [
# Here you use the floresta overlay with your others
inputs.florestad.overlays.default
];
}
];
};then Florestad will be available just like any other package with
pkgs.florestadBut if you just want to test it or quickly run a instance you can do
$ nix run github:vinteumorg/FlorestaAfter 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.
If you want to skip the IBD process, you can use the --assume-utreexo flag. This flag will start the node at a given height, with the state
provided by this implementation. Therefore, you're trusting that we are giving you the correct state. Everything after that height will be
verified by the node just like any other node.
florestad --assume-utreexoFloresta 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.
cargo buildThere's a set of unit tests that you can run with
cargo testThere's also a set of functional tests that you can run with
pip3 install -r tests/requirements.txt
python tests/run_tests.pyThis 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.
Contributions are welcome, feel free to open an issue or a pull request.
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.
Here's some Guidelines:
- Has to compile.
- Has to run.
- Use pre-commit for the language that you're using (if possible đź‘Ť).
You can accomplish that using our flake.nix for development.
If you already have Nix you just need to do:
$ nix developand use our flake for development which include
- nix(fmt) and rust(fmt) pre-commit.
- Rust Msrv(1.74.0).
- Clippy and some libs so rust can compile.
- Typos for good spelling.
If you do not have Nix 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 it's 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.