frost/bdk

志宇 6b43001951

feat!: Rework sqlite, changesets, persistence and wallet-construction

Rework sqlite: Instead of only supported one schema (defined in
`bdk_sqlite`), we have a schema per changeset type for more flexiblity.

* rm `bdk_sqlite` crate (as we don't need `bdk_sqlite::Store` anymore).
* add `sqlite` feature on `bdk_chain` which adds methods on each
  changeset type for initializing tables, loading the changeset and
  writing.

Rework changesets: Some callers may want to use `KeychainTxOutIndex`
where `K` may change per descriptor on every run. So we only want to
persist the last revealed indices by `DescriptorId` (which uniquely-ish
identifies the descriptor).

* rm `keychain_added` field from `keychain_txout`'s changeset.
* Add `keychain_added` to `CombinedChangeSet` (which is renamed to
  `WalletChangeSet`).

Rework persistence: add back some safety and convenience when persisting
our types. Working with changeset directly (as we were doing before) can
be cumbersome.

* Intoduce `struct Persisted<T>` which wraps a type `T` which stores
  staged changes to it. This adds safety when creating and or loading
  `T` from db.
* `struct Persisted<T>` methods, `create`, `load` and `persist`, are
  avaliable if `trait PersistWith<Db>` is implemented for `T`. `Db`
  represents the database connection and `PersistWith` should be
  implemented per database-type.
* For async, we have `trait PersistedAsyncWith<Db>`.
* `Wallet` has impls of `PersistedWith<rusqlite::Connection>`,
  `PersistedWith<rusqlite::Transaction>` and
  `PersistedWith<bdk_file_store::Store>` by default.

Rework wallet-construction: Before, we had multiple methods for loading
and creating with different input-counts so it would be unwieldly to add
more parameters in the future. This also makes it difficult to impl
`PersistWith` (which has a single method for `load` that takes in
`PersistWith::LoadParams` and a single method for `create` that takes in
`PersistWith::CreateParams`).

* Introduce a builder pattern when constructing a `Wallet`. For loading
  from persistence or `ChangeSet`, we have `LoadParams`. For creating a
  new wallet, we have `CreateParams`.

2024-07-18 03:25:41 +00:00

10 KiB

Raw Blame History

BDK

A modern, lightweight, descriptor-based wallet library written in Rust!

Project Homepage | Documentation

BDK Wallet

The bdk_wallet crate provides the Wallet type which is a simple, high-level interface built from the low-level components of bdk_chain. Wallet is a good starting point for many simple applications as well as a good demonstration of how to use the other mechanisms to construct a wallet. It has two keychains (external and internal) which are defined by miniscript descriptors and uses them to generate addresses. When you give it chain data it also uses the descriptors to find transaction outputs owned by them. From there, you can create and sign transactions.

For details about the API of Wallet see the module-level documentation.

Blockchain data

In order to get blockchain data for Wallet to consume, you should configure a client from an available chain source. Typically you make a request to the chain source and get a response that the Wallet can use to update its view of the chain.

Blockchain Data Sources

bdk_esplora: Grabs blockchain data from Esplora for updating BDK structures.
bdk_electrum: Grabs blockchain data from Electrum for updating BDK structures.
bdk_bitcoind_rpc: Grabs blockchain data from Bitcoin Core for updating BDK structures.

Examples

Persistence

To persist Wallet state data use a data store crate that reads and writes [bdk_chain::WalletChangeSet].

Implementations

bdk_file_store: Stores wallet changes in a simple flat file.

Example

use bdk_wallet::{bitcoin::Network, CreateParams, LoadParams, KeychainKind, ChangeSet};

// Open or create a new file store for wallet data.
let mut db =
    bdk_file_store::Store::<ChangeSet>::open_or_create_new(b"magic_bytes", "/tmp/my_wallet.db")
        .expect("create store");

// Create a wallet with initial wallet data read from the file store.
let network = Network::Testnet;
let descriptor = "wpkh(tprv8ZgxMBicQKsPdcAqYBpzAFwU5yxBUo88ggoBqu1qPcHUfSbKK1sKMLmC7EAk438btHQrSdu3jGGQa6PA71nvH5nkDexhLteJqkM4dQmWF9g/84'/1'/0'/0/*)";
let change_descriptor = "wpkh(tprv8ZgxMBicQKsPdcAqYBpzAFwU5yxBUo88ggoBqu1qPcHUfSbKK1sKMLmC7EAk438btHQrSdu3jGGQa6PA71nvH5nkDexhLteJqkM4dQmWF9g/84'/1'/0'/1/*)";
let load_params = LoadParams::with_descriptors(descriptor, change_descriptor, network)
    .expect("must parse descriptors");
let create_params = CreateParams::new(descriptor, change_descriptor, network)
    .expect("must parse descriptors");
let mut wallet = match load_params.load_wallet(&mut db).expect("wallet") {
    Some(wallet) => wallet,
    None => create_params.create_wallet(&mut db).expect("wallet"),
};

// Get a new address to receive bitcoin.
let receive_address = wallet.reveal_next_address(KeychainKind::External);
// Persist staged wallet data changes to the file store.
wallet.persist(&mut db).expect("persist");
println!("Your new receive address is: {}", receive_address.address);

Testing

Unit testing

cargo test

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.

10 KiB Raw Blame History

BDK