frost/bdk
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge bitcoindevkit/bdk#1378: Update bdk README

Browse Source 
06d7dc5c3a890f0a141de4cf6f421fe766d99ec3 doc(bdk): Update bdk README (vmammal)

Pull request description:

  fixes #1044

  ### Notes

  The code snippet is a compile fail because variables `txout` and `outpoint` are not initialized. Any other suggestions are welcome.

  There is still some old commented code in the file that's probably not needed unless we want to provide another example snippet, say for getting new address info.

  * [x] Fix broken links
  * [x] Use a new unused tprv
  * [ ] Try to make persistence example make sense, or maybe just do away with it

  #### All Submissions:

  * [x] I've signed all my commits
  * [x] I followed the [contribution guidelines](https://github.com/bitcoindevkit/bdk/blob/master/CONTRIBUTING.md)
  * [x] I ran `cargo fmt` and `cargo clippy` before committing

ACKs for top commit:
  evanlinjin:
    ACK 06d7dc5c3a890f0a141de4cf6f421fe766d99ec3

Tree-SHA512: 09a671bc6bea574d7a4b42b64718380ee71a0c5d36c6b7ca1dc19a2c567de510b27ccc91fe05e7178bf31c562db66bc64f660415de5bb2f32f369b13c44ad3d2
This commit is contained in:
志宇 2024-03-22 15:05:44 +08:00
commit a837cd349b
No known key found for this signature in database
1 changed files with 24 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
crates/bdk/README.md
View File

@ -26,7 +26,7 @@
## `bdk` ## `bdk`
The `bdk` crate provides the [`Wallet`](`crate::Wallet`) type which is a simple, high-level The `bdk` 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 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 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 construct a wallet. It has two keychains (external and internal) which are defined by
@ -34,51 +34,51 @@ construct a wallet. It has two keychains (external and internal) which are defin
chain data it also uses the descriptors to find transaction outputs owned by them. From there, you chain data it also uses the descriptors to find transaction outputs owned by them. From there, you
can create and sign transactions. can create and sign transactions.
For more information, see the [`Wallet`'s documentation](https://docs.rs/bdk/latest/bdk/wallet/struct.Wallet.html). For details about the API of `Wallet` see the [module-level documentation][`Wallet`].
### Blockchain data ### Blockchain data
In order to get blockchain data for `Wallet` to consume, you have to put it into particular form. In order to get blockchain data for `Wallet` to consume, you should configure a client from
Right now this is [`KeychainScan`] which is defined in [`bdk_chain`]. 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.
This can be created manually or from blockchain-scanning crates.
**Blockchain Data Sources** **Blockchain Data Sources**
* [`bdk_esplora`]: Grabs blockchain data from Esplora for updating BDK structures. * [`bdk_esplora`]: Grabs blockchain data from Esplora for updating BDK structures.
* [`bdk_electrum`]: Grabs blockchain data from Electrum 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** **Examples**
* [`example-crates/wallet_esplora`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_esplora) * [`example-crates/wallet_esplora_async`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_esplora_async)
* [`example-crates/wallet_esplora_blocking`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_esplora_blocking)
* [`example-crates/wallet_electrum`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_electrum) * [`example-crates/wallet_electrum`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_electrum)
* [`example-crates/wallet_rpc`](https://github.com/bitcoindevkit/bdk/tree/master/example-crates/wallet_rpc)
### Persistence ### Persistence
To persist the `Wallet` on disk, `Wallet` needs to be constructed with a To persist the `Wallet` on disk, it must be constructed with a [`PersistBackend`] implementation.
[`Persist`](https://docs.rs/bdk_chain/latest/bdk_chain/keychain/struct.KeychainPersist.html) implementation.
**Implementations** **Implementations**
* [`bdk_file_store`]: a simple flat-file implementation of `Persist`. * [`bdk_file_store`]: A simple flat-file implementation of [`PersistBackend`].
**Example** **Example**
```rust <!-- compile_fail because outpoint and txout are fake variables -->
use bdk::{bitcoin::Network, wallet::{AddressIndex, Wallet}}; ```rust,compile_fail
use bdk::{bitcoin::Network, wallet::{ChangeSet, Wallet}};
fn main() { fn main() {
// a type that implements `Persist` // Create a new file `Store`.
let db = (); let db = bdk_file_store::Store::<ChangeSet>::open_or_create_new(b"magic_bytes", "path/to/my_wallet.db").expect("create store");
let descriptor = "wpkh(tprv8ZgxMBicQKsPdy6LMhUtFHAgpocR8GC6QmwMSFpZs7h6Eziw3SpThFfczTDh5rW2krkqffa11UpX3XkeTTB2FvzZKWXqPY54Y6Rq4AQ5R8L/84'/0'/0'/0/*)"; let descriptor = "wpkh(tprv8ZgxMBicQKsPdcAqYBpzAFwU5yxBUo88ggoBqu1qPcHUfSbKK1sKMLmC7EAk438btHQrSdu3jGGQa6PA71nvH5nkDexhLteJqkM4dQmWF9g/84'/1'/0'/0/*)";
let mut wallet = Wallet::new(descriptor, None, db, Network::Testnet).expect("should create"); let mut wallet = Wallet::new_or_load(descriptor, None, db, Network::Testnet).expect("create or load wallet");
// get a new address (this increments revealed derivation index) // Insert a single `TxOut` at `OutPoint` into the wallet.
println!("revealed address: {}", wallet.get_address(AddressIndex::New)); let _ = wallet.insert_txout(outpoint, txout);
println!("staged changes: {:?}", wallet.staged()); wallet.commit().expect("must write to database");
// persist changes
wallet.commit().expect("must save");
} }
``` ```
@ -218,9 +218,11 @@ 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 license, shall be dual licensed as above, without any additional terms or
conditions. conditions.
[`Wallet`]: https://docs.rs/bdk/1.0.0-alpha.7/bdk/wallet/struct.Wallet.html
[`PersistBackend`]: https://docs.rs/bdk_chain/latest/bdk_chain/trait.PersistBackend.html
[`bdk_chain`]: https://docs.rs/bdk_chain/latest [`bdk_chain`]: https://docs.rs/bdk_chain/latest
[`bdk_file_store`]: https://docs.rs/bdk_file_store/latest [`bdk_file_store`]: https://docs.rs/bdk_file_store/latest
[`bdk_electrum`]: https://docs.rs/bdk_electrum/latest [`bdk_electrum`]: https://docs.rs/bdk_electrum/latest
[`bdk_esplora`]: https://docs.rs/bdk_esplora/latest [`bdk_esplora`]: https://docs.rs/bdk_esplora/latest
[`KeychainScan`]: https://docs.rs/bdk_chain/latest/bdk_chain/keychain/struct.KeychainScan.html [`bdk_bitcoind_rpc`]: https://docs.rs/bdk_bitcoind_rpc/latest
[`rust-miniscript`]: https://docs.rs/miniscript/latest/miniscript/index.html [`rust-miniscript`]: https://docs.rs/miniscript/latest/miniscript/index.html