bdk-floresta

A Floresta-powered chain-source crate for BDK.

Synopsis

This crate is a novel chain-source crate implementation meant for wallet applications built with BDK, allowing for zero-trust and completely local wallet synchronization, by embedding a lightweight full node direcly inside a wallet application.

By leveraging Utreexo and Floresta, it's possible to implement a lightweight full node with minimal resource requirements, making it possible for every wallet to have it's own node.

Developing

This project uses just for command running, and cargo-rbmt to manage everything related to cargo, such as formatting, linting, testing and CI. It also uses uv to run Zizmor, for GitHub Action static analysis.

To install them with cargo, run:

~$ cargo install just

~$ cargo install cargo-rbmt

~$ cargo install uv

Alternatively, use your preferred package manager to install just and uv.

A justfile is provided for convenience. Run just to see available commands:

~$ just
> bdk-floresta
> A Floresta-powered chain-source crate for BDK

Available recipes:
    audit                  # Run `cargo audit` [alias: a]
    build                  # Build `bdk-floresta` and examples [alias: b]
    check                  # Check code formatting, compilation, linting, and commit signatures [alias: c]
    check-features         # Check that all feature combinations compile
    check-sigs             # Check if commits are PGP-signed
    delete item="data"     # Delete files: data, target, lockfiles [alias: d]
    doc                    # Generate documentation
    doc-open               # Generate and open documentation
    example-client-regtest # Run the `client_regtest` example [alias: cr]
    example-client-signet  # Run the `client_signet` example [alias: cs]
    fmt                    # Format code [alias: f]
    lock                   # Regenerate `Cargo-recent.lock` and `Cargo-minimal.lock` [alias: l]
    pre-push               # Run pre-push checks [alias: p]
    test                   # Run tests across all toolchains and lockfiles [alias: t]
    toolchains             # Install and/or Update `cargo-rbmt` and Stable and Nightly toolchains
    zizmor                 # Run Zizmor [alias: z]

Architecture

This crate is implemented on top of libfloresta, a set of libraries for building lightweight Bitcoin nodes, and is composed of two main components: the Builder and the Node.

Wallet updates can either stem from new blocks that the Node validates, which can then be applied to the wallet, or from a blockchain scan using Compact Block Filters.

libfloresta

The crates below are used to implement the Node:

• floresta-chain: Implements the Node's chain state, and validates blocks and transactions.

• floresta-compact-filters: Implements a storage mechanism for Compact Block Filters, used to figure out which blocks to request from the P2P network to update the wallet.

• floresta-mempool: Implements the Node's mempool, used to relay and cache transactions, as well as generating fee estimates.

• floresta-wire: Implements all of the Node's peer-to-peer logic.

Minimum Supported Rust Version

This library should compile with any combination of features on Rust 1.85.0.

To build with the MSRV toolchain, copy Cargo-minimal.lock to Cargo.lock.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.