From 3eb6a1e70d310b485df8f93f8e26e5c96fc8d99d Mon Sep 17 00:00:00 2001 From: Steve Myers Date: Thu, 30 Jan 2025 14:57:30 -0600 Subject: [PATCH 1/2] Update docs to use page that link to book and apis --- docs/.vuepress/config.js | 55 ++++++++-------------------------------- docs/docs/README.md | 24 ++++++++++++++++++ 2 files changed, 35 insertions(+), 44 deletions(-) create mode 100644 docs/docs/README.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index b4583e8d19..a1f58ac1b8 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -9,42 +9,6 @@ const twitterUrl = 'https://twitter.com/intent/follow?screen_name=bitcoindevkit' const nostrUrl = 'nostr:npub13dk3dke4zm9vdkucm7f6vv7vhqgkevgg3gju9kr2wzumz7nrykdq0dgnvc' const themeColor = '#ffffff' -const docsSidebar = [ - { - title: 'Documentation', - collapsable: false, - children: [ - ['/getting-started', 'Getting Started'], - { - title: "BDK-CLI", - collapsable: true, - children: [ - '/bdk-cli/introduction', - '/bdk-cli/installation', - '/bdk-cli/concept', - '/bdk-cli/interface', - '/bdk-cli/regtest', - '/bdk-cli/compiler', - '/bdk-cli/playground' - ] - }, - '/descriptors/', - '/examples/', - ] - }, - { - title: 'API Reference', - collapsable: false, - children: [ - ['https://docs.rs/bdk_wallet/', 'Rust Stable Docs'], - ['https://bitcoindevkit.org/docs-rs/bdk/nightly/latest/bdk_wallet/', 'Rust Nightly Docs'], - ['https://bitcoindevkit.org/android/', 'Android Docs'], - ['https://bitcoindevkit.org/jvm/', 'Kotlin/JVM Docs'], - ['https://bitcoindevkit.org/java/', 'Java Docs'], - ], - } -] - const builtWithBdkSidebar = [ { title: 'Built With BDK', @@ -107,9 +71,13 @@ module.exports = { editLinks: true, sidebarDepth: 0, nav: [ + { + text: 'Github', + link: 'https://github.com/bitcoindevkit' + }, { text: 'Docs', - link: '/getting-started/' + link: '/docs/' }, { text: 'Adoption', @@ -129,7 +97,6 @@ module.exports = { '/_blog/': blogSidebar, '/blog/': blogSidebar, '/foundation/': foundationSidebar, - '/': docsSidebar, }, footer: { links: [ @@ -137,16 +104,16 @@ module.exports = { title: 'Docs', children: [ { - text: 'Getting Started', - link: '/getting-started/' + text: 'Book', + link: '/docs/#book' }, { - text: 'BDK-CLI', - link: '/bdk-cli/installation/' + text: 'Rust APIs', + link: '/docs/#rust-apis' }, { - text: 'Descriptors', - link: '/descriptors/' + text: 'Other APIs', + link: '/docs/#other-apis' } ] }, diff --git a/docs/docs/README.md b/docs/docs/README.md new file mode 100644 index 0000000000..ed20132c76 --- /dev/null +++ b/docs/docs/README.md @@ -0,0 +1,24 @@ +# Documentation + +## Book + +The "Book of BDK" is a gentle introduction to using the BDK suite of libraries. It includes a "Getting Started" guide and "Cookbook" with example code in Rust, Kotlin and Swift. It is still a work in progress, contributions welcome. + +- [Book of BDK](https://bitcoindevkit.github.io/book-of-bdk/) + +## Rust APIs + +- [bdk_wallet](https://docs.rs/bdk_wallet/) +- [bdk_chain](https://docs.rs/bdk_chain/) +- [bdk_sqlite](https://docs.rs/bdk_sqlite) +- [bdk_electrum](https://docs.rs/bdk_electrum) +- [bdk_esplora](https://docs.rs/bdk_esplora) +- [bdk_bitcoind_rpc](https://docs.rs/bdk_bitcoind_rpc) +- [esplora-client](https://docs.rs/esplora-client) +- [electrum-client](https://docs.rs/electrum-client) + +## Other APIs + +- [Android Docs](https://bitcoindevkit.org/android/) +- [Kotlin/JVM Docs](https://bitcoindevkit.org/jvm/) +- [Java Docs](https://bitcoindevkit.org/java/) \ No newline at end of file From a1bb718458c5219965cdaa37954e8c0966166b52 Mon Sep 17 00:00:00 2001 From: Steve Myers Date: Thu, 30 Jan 2025 22:30:48 -0600 Subject: [PATCH 2/2] Remove old, out of date pages --- docs/bdk-cli/compiler.md | 145 --------- docs/bdk-cli/concept.md | 20 -- docs/bdk-cli/installation.md | 99 ------ docs/bdk-cli/interface.md | 589 ----------------------------------- docs/bdk-cli/introduction.md | 13 - docs/bdk-cli/playground.md | 3 - docs/bdk-cli/regtest.md | 46 --- docs/descriptors/README.md | 116 ------- docs/examples/README.md | 26 -- docs/getting-started.md | 119 ------- 10 files changed, 1176 deletions(-) delete mode 100644 docs/bdk-cli/compiler.md delete mode 100644 docs/bdk-cli/concept.md delete mode 100644 docs/bdk-cli/installation.md delete mode 100644 docs/bdk-cli/interface.md delete mode 100644 docs/bdk-cli/introduction.md delete mode 100644 docs/bdk-cli/playground.md delete mode 100644 docs/bdk-cli/regtest.md delete mode 100644 docs/descriptors/README.md delete mode 100644 docs/examples/README.md delete mode 100644 docs/getting-started.md diff --git a/docs/bdk-cli/compiler.md b/docs/bdk-cli/compiler.md deleted file mode 100644 index 0a06a55158..0000000000 --- a/docs/bdk-cli/compiler.md +++ /dev/null @@ -1,145 +0,0 @@ -# Compiler - -## Introduction - -If you want to play around with more complicated spending policies, you'll start to find it harder and harder to manually create the descriptors. This is where the miniscript compiler comes in! The `bdk` library -includes a very simple compiler that can produce a descriptor given a spending policy. The syntax used to encode the spending policy is very well described [in this page](http://bitcoin.sipa.be/miniscript/), -specifically in the "Policy to Miniscript compiler". The compiler included in BDK does basically the same job, but produces descriptors for `rust-miniscript` that have some minor differences from -the ones made by the C++ implementation used in that website. - -## Installation - -To install the miniscript compiler run the following command: - -```bash -cargo install --git https://github.com/bitcoindevkit/bdk --features="compiler" --example miniscriptc -``` - -Once the command is done, you should have a `miniscriptc` command available. You can check if that's the case by running `miniscriptc --help`. - -## Usage - -In this case the interface is very simple: it accepts two arguments called "POLICY" and "TYPE", in this order. The first one, as the name implies, sets the spending policy to compile. The latter defines the type -of address that should be used to encapsulate the produced script, like a P2SH, P2WSH, etc. - -Optionally, the `--parsed_policy` flag can be enabled and it will make the compiler print the JSON "human-readable" version of the spending policy, as described in the [`policies subcommand`](/bdk-cli/interface/#policies) of the CLI. - -The `--network` flag can be used to change the network encoding of the address shown. - -::: tip Tip -Keep in mind that since the compiler loads and interprets the descriptor, all the public keys specified in the policy must be valid public keys. This differs from the web tool linked above that also accepts -placeholders too. As described in the previous sections of this guide, the keys can be either `xpub`/`xprv` with or without metadata and a derivation path, WIF keys or raw hex public keys. -::: - -## Example - -Let's take this policy for example: - -```bash -miniscriptc --parsed_policy "and(pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR),or(50@pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),older(1000)))" sh-wsh -``` - -The compiler should print something like: - -```bash -[2020-04-29T10:42:05Z INFO miniscriptc] Compiling policy: and(pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR),or(50@pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),older(1000))) -[2020-04-29T10:42:05Z INFO miniscriptc] ... Descriptor: sh(wsh(and_v(or_c(c:pk(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c),v:older(1000)),c:pk(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR)))) -[2020-04-29T10:42:05Z INFO miniscriptc] ... First address: 2MsqrJuZewY3o3ADAy1Uhi5vsBqTANjH3Cf -``` - -JSON policy: - -```json -{ - "type":"THRESH", - "items":[ - { - "type":"THRESH", - "items":[ - { - "type":"SIGNATURE", - "pubkey":"02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"NONE" - } - }, - { - "type":"RELATIVETIMELOCK", - "value":1000, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - "csv":1000 - } - } - } - ], - "threshold":1, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":2, - "m":1, - "items":[ - 1 - ], - "conditions":{ - "[1]":[ - { - "csv":1000 - } - ] - } - } - }, - { - "type":"SIGNATURE", - "pubkey":"02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - - } - } - } - ], - "threshold":2, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":2, - "m":2, - "items":[ - 0, - 1 - ], - "conditions":{ - "[0, 1]":[ - { - "csv":1000 - } - ] - } - } -} -``` - -## Troubleshooting - -#### Nothing is printed - -This might mean that you have a `RUST_LOG` variable set to a value that suppresses the compiler's log. You can try adding `miniscriptc=info` to your `RUST_LOG` value and see if that works, or open a new clean -shell. diff --git a/docs/bdk-cli/concept.md b/docs/bdk-cli/concept.md deleted file mode 100644 index a536422d10..0000000000 --- a/docs/bdk-cli/concept.md +++ /dev/null @@ -1,20 +0,0 @@ -# Concept - -Now, in order to better grasp some of the design choices made by BDK, it's important to understand the main concept driving the development of this project, and the goal that it's trying to -achieve. - -BDK is aiming first of all to be a **set of libraries and tools**, all meant to be very reusable and adaptable. Developers working on their own wallets or other projects that are trying to integrate -Bitcoin can pick the tools they need and piece them together to prototype and quickly ship a working product. This means that the `bdk-cli` that we've just installed is designed to be a **very thin layer** over the -APIs exposed by the various components of the library, **not a full, end-user-ready Bitcoin wallet**. - -This concept leads to a few design choices that are arguably very bad for the "UX" of this wallet, but that allow developers to work more directly with the underlying library. For instance: - -* BDK has an internal database that's used to store data about received transactions, spendable UTXOs, etc. This database is stored by default in your home folder, in `~/.bdk-bitcoin`. The database - **will never** contain any data that can't be recreated purely by looking at the blockchain. Keys, descriptors, Electrum endpoints **are not stored in the database**. This explains why you'll have to specify them every - time in the command line. It can be seen more like a *cache* and can be safely deleted without risking funds. -* BDK doesn't automatically "monitor" the blockchain, instead there's a `sync` command that has to be called by the user. -* When you create a transaction and then sign it, it's not automatically broadcast to the network. There's a `broadcast` command that does this. Moreover, the command doesn't accept a normal Bitcoin raw transaction, - but instead a *PSBT*. That's because internally transactions are always moved as PSBTs, and again, the `broadcast` command is just a very thin wrapper over the raw library call. - -There are probably more of these examples, but hopefully by this point you'll have more or less understood the gist of it. If you are not a developer, some parts of this will feel weird, inefficient, hard -to understand, and that's absolutely normal. Just try to survive through the pain and you'll be rewarded! diff --git a/docs/bdk-cli/installation.md b/docs/bdk-cli/installation.md deleted file mode 100644 index 9e38a7df2e..0000000000 --- a/docs/bdk-cli/installation.md +++ /dev/null @@ -1,99 +0,0 @@ -# Installation - -## Requirements - -The only requirement to run the `bdk-cli` tool is a Linux/macOS system with a fairly recent Rust -toolchain installed. Since Linux distros tend to lag behind with updates, the quickest way to -install the Rust compiler and Cargo is [rustup.rs](https://rustup.rs/). You can head there and -follow their instructions, after which you can test if everything went fine by running -`cargo version`, which should print something like: - -``` -cargo 1.56.0 (4ed5d137b 2021-10-04) -``` - -As an alternative to installing the Rust toolchain, you can try using a -[Docker image](https://hub.docker.com/_/rust) and working inside of it, but that's meant for more -advanced users and won't be covered in this guide. - -::: tip Note -At the time of writing, the project requires cargo >= 1.56.0, which is our minimum supported rust version (MSRV) as of May 2022. If you have an older version installed with rustup.rs, you can upgrade it with `rustup update`. -::: - -## Installing the `bdk-cli` tool - -Once Cargo is installed, you can proceed to install the interactive `bdk-cli` tool directly from -the GitHub repository, by running: - -All features with the blocking esplora client - -```sh -cargo install --git https://github.com/bitcoindevkit/bdk-cli --features=esplora-ureq,compiler -``` - -All features with the async esplora client - -```sh -cargo install --git https://github.com/bitcoindevkit/bdk-cli --features=esplora-reqwest,compiler -``` - -Minimal install (only repl feature is on by default) - -```sh -cargo install --git https://github.com/bitcoindevkit/bdk-cli -``` - -For Windows users, the default SQLite database requires extensive configuration and `bdk-cli` will not build properly if SQLite is unconfigured. To proceed with the installation using `sled` instead, run: - -Disable sqlite and use sled - -```sh -cargo install bdk-cli --no-default-features --features=key-value-db,esplora-ureq,compiler -``` - -This command may take a while to finish, since it will fetch and compile all the dependencies and the `bdk` library itself. - -Once it's done, you can check if everything went fine by running `bdk-cli --help` which should print something like this: - -``` -bdk-cli 0.5.0 -Alekos Filini :Riccardo Casatta :Steve Myers -The BDK Command Line Wallet App - -bdk-cli is a light weight command line bitcoin wallet, powered by BDK. This app can be used as a playground as well as -testing environment to simulate various wallet testing situations. If you are planning to use BDK in your wallet, bdk- -cli is also a great intro tool to get familiar with the BDK API. - -But this is not just any toy. bdk-cli is also a fully functioning Bitcoin wallet with taproot support! - - -USAGE: - bdk-cli [OPTIONS] - -FLAGS: - -h, --help - Prints help information - - -V, --version - Prints version information - - -OPTIONS: - -n, --network - Sets the network [default: testnet] - - -SUBCOMMANDS: - compile Compile a miniscript policy to an output descriptor - help Prints this message or the help of the given subcommand(s) - key Key Management Operations - repl REPL command loop mode - wallet Wallet Operations - -``` - -An example command to sync a testnet wallet to a default electrum server looks like this: - -```sh -bdk-cli wallet -w example --descriptor "wpkh(tprv8ZgxMBicQKsPexGYyaFwnAsCXCjmz2FaTm6LtesyyihjbQE3gRMfXqQBXKM43DvC1UgRVv1qom1qFxNMSqVAs88qx9PhgFnfGVUdiiDf6j4/0/*)" sync -``` diff --git a/docs/bdk-cli/interface.md b/docs/bdk-cli/interface.md deleted file mode 100644 index a06bb7debe..0000000000 --- a/docs/bdk-cli/interface.md +++ /dev/null @@ -1,589 +0,0 @@ -# Interface - -Remember the `bdk-cli --help` command you ran before? Let's analyze its output here to figure out the interface: - -## Flags - -``` -FLAGS: - -h, --help Prints help information - -V, --version Prints version information -``` - -These are the optional flags that can be set with every command. The `-h` flag prints the help message, the `-V` flag only prints the version. - -### Verbosity - -If you want to increase the verbosity of the output, you should use the `RUST_LOG` environment variable. You can set it like so to see a lot more of what's going on behind the scenes, before running the `bdk-cli` -command. You only have to do this once when you open a new shell, after that you can run the `bdk-cli` command multiple times. - -```bash -export RUST_LOG="bdk=debug" -``` - -## Options - -``` -OPTIONS: - -n, --network Sets the network [default: testnet] -``` - -These are the global options that can be set. They are pretty much like the flags, but they also take a value. - -The `--network` flag can be used to change the network. Right now only `testnet` and `regtest` are supported since the code is very much not production-ready yet. - -## Subcommands - -## key - -Commands to generate, restore and derive HD keys. - -To get more details about every single subcommand to the `key` command, run `bdk-cli key`. Under the `key` command we have the following subcommands to quickly generate, restore and derive HD keys. - -| Command | Description | -| ------- | ----------- | -| [generate](#generate) | Generates new random seed mnemonic phrase and corresponding master extended key | -| [restore](#restore) | Restore a master extended key from seed backup mnemonic words | -| [derive](#derive) | Derive a child key pair from a master extended key and a derivation path string (eg. "m/84'/1'/0'/0" or "m/84h/1h/0h/0") | - -### generate - -``` -OPTIONS: - -p, --password Seed password - -e, --entropy Entropy level based on number of random seed mnemonic words [default: 24] [possible values: 12, 24] -``` - -To use this subcommand, run `bdk-cli key generate`. This creates a BIP32 HD wallet master extended private key, a wallet fingerprint and BIP39 mnemonic words. The xprv can be used with `key derive` to derive extended public keys. - - -### restore - -``` -OPTIONS: - -m, --mnemonic Seed mnemonic words, must be quoted (eg. "word1 word2 ...") - -p, --password Seed password -``` - -To use this subcommand, run `bdk-cli key restore -m `. Format `` as shown in the options above. This recovers a BIP32 HD wallet seed from BIP39 mnemonic words. It outputs a wallet fingerprint and a master extended private key. - - -### derive - -``` -OPTIONS: - -p, --path Path to use to derive extended public key from extended private key - -x, --xprv Extended private key to derive from -``` - -To derive child keys from an extended private key, run `bdk-cli key derive -p -x `. - -## wallet - -These are the main "functions" of the wallet. Most of them are pretty self explanatory, but we'll go over them quickly anyways. You can get more details about the subcommands by running `bdk-cli wallet`. In addition, you can also get more details about every single command by running `bdk-cli wallet --help`. - -| Command | Description | -| ------- | ----------- | -| [broadcast](#broadcast) | Broadcasts a transaction to the network. Takes either a raw transaction or a PSBT to extract | -| [bump_fee](#bump_fee) | Bumps the fees of an RBF transaction | -| [combine_psbt](#combine_psbt) | Combines multiple PSBTs into one | -| [create_tx](#create_tx) | Creates a new unsigned tranasaction | -| [extract_psbt](#extract_psbt) | Extracts a raw transaction from a PSBT | -| [finalize_psbt](#finalize_psbt) | Finalizes a psbt | -| [get_balance](#get_balance) | Returns the current wallet balance | -| [get_new_address](#get_new_address) | Generates a new external address | -| [list_transactions](#list_transactions) | Lists all the incoming and outgoing transactions of the wallet -| [list_unspent](#list_unspent) | Lists the available spendable UTXOs | -| [policies](#policies) | Returns the available spending policies for the descriptor | -| [public_descriptor](#public_descriptor) | Returns the public version of the wallet's descriptor(s) | -| [help](#help) | Prints this message or the help of the given subcommand(s) | -| [sign](#sign) | Signs and tries to finalize a PSBT | -| [sync](#sync) | Syncs with the chosen Electrum server | - - -### Options - -``` -OPTIONS: - -c, --change_descriptor Sets the descriptor to use for internal addresses - --conc - Number of parallel requests sent to the esplora service (default: 4) [default: 4] - - -d, --descriptor Sets the descriptor to use for the external addresses - -s, --server - Use the esplora server if given as parameter [default: https://blockstream.info/testnet/api/] - - -p, --proxy Sets the SOCKS5 proxy for Blockchain backend - -r, --retries Sets the SOCKS5 proxy retries for the Electrum client [default: 5] - -a, --proxy_auth Sets the SOCKS5 proxy credential - -g, --stop_gap - Stop searching addresses for transactions after finding an unused gap of this length [default: 10] - - --timeout Socket timeout [default: 5] - -w, --wallet Selects the wallet to use -``` - -These are the global options that can be set. They are pretty much like the flags, but they also take a value. The only **required** one is the `--descriptor` or `-d` flag, since every wallet **must have an -associated descriptor**. - -The `--change-descriptor` flag can be used to set a different descriptor for the change addresses, sometimes called "internal" addresses in Bitcoin Core. Unfortunately there isn't -[really consensus](https://freenode.irclog.whitequark.org/bitcoin-wizards/2020-01-25#26222504;) on a nice way to encode information about the change derivation inside the standard descriptor, so we are stuck with having two separate ones. Keep in mind though, that even if you don't specify a change descriptor, you'll still be able to create transactions - the change address will simply be generated from the standard descriptor. - -The `--server` flag can be used to select the Electrum server to use. By default it's connecting to Blockstream's electrum servers, which seems pretty stable. -If you are having connection issues, you can also try with one of the other servers [listed here](https://1209k.com/bitcoin-eye/ele.php?chain=tbtc) and see if you have more luck with those. -Right now both plaintext and ssl servers are supported (prefix `tcp://` or no prefix at all for tcp, prefix `ssl://` for ssl). This flag can also be used to connect to an Esplora server. It should be set to the API's "base url". For public instances of Esplora this is `https://blockstream.info/api` for mainnet and `https://blockstream.info/testnet/api` for testnet. - -The `--proxy` flag can be optionally used to specify a SOCKS5 proxy to use when connecting to an `electrum`, `esplora` or `compact_filters` blockchain backend. Spawning a local Tor daemon and using it as a proxy will allow you to connect to the backend's `.onion` URLs. **Keep in mind that only plaintext server are supported over a proxy.** - -The `--retries` flag can be optionally used to specify the number of retries when connecting to -an `electrum`, `esplora` or `compact_filters` blockchain backend via the SOCKS5 proxy. - -The `--proxy_auth` flag can be optionally used to set the SOCKS5 proxy authentication credentials. - -The `--stop_gap` flag can be optionally used to stop searching addresses for transactions after finding an unused gap of this length. - -The `--wallet` flag can be used to select which wallet to use, if you have more than one of them. -If no `--wallet` option is passed, a random wallet name is generated based on the hash of the descriptor string. If you get a `ChecksumMismatch` error when you make some changes to your descriptor, it's because it does not match the one you've used to initialize the cache. One solution could be to switch to a new wallet name, or delete the cache directory at `~/.bdk-bitcoin` and start from scratch. - -## Subcommands - -### broadcast - -``` -OPTIONS: - --psbt Sets the PSBT to extract and broadcast - --tx Sets the raw transaction to broadcast -``` - -Broadcasts a transaction. The transaction can be a raw hex transaction or a PSBT, in which case it also has to be "finalizable" (i.e. it should contain enough partial signatures to construct a finalized valid scriptsig/witness). - -### bump\_fee - -``` -FLAGS: - --offline_signer - Make a PSBT that can be signed by offline signers and hardware wallets. Forces the addition of `non_witness_utxo` and more details to let the signer identify the change output - -OPTIONS: - --unspendable ... - Marks an utxo as unspendable, in case more inputs are needed to cover the extra fees - - --utxos ... - Selects which utxos *must* be added to the tx. Unconfirmed utxos cannot be used - - -f, --fee_rate The new targeted fee rate in sat/vbyte - -s, --shrink - Allows the wallet to reduce the amount to the specified address in order to increase fees - - -t, --txid TXID of the transaction to update -``` - -Bumps the fee of a transaction made with RBF. The transaction to bump is specified using the `--txid` flag and the new fee rate with `--fee_rate`. - - -### combine\_psbt - -``` -OPTIONS: - --psbt ... Add one PSBT to comine. This option can be repeated multiple times, one for each PSBT -``` - -Combines multiple PSBTs by merging metadata and partial signatures. It can be used to merge multiple signed PSBTs into a single PSBT that contains every signature and is ready to be [finalized](#finalize-psbt). - -### create\_tx - -``` -FLAGS: - -r, --enable_rbf Enables Replace-By-Fee (BIP125) - --offline_signer Make a PSBT that can be signed by offline signers and hardware wallets. Forces the addition - of `non_witness_utxo` and more details to let the signer identify the change output - -a, --send_all Sends all the funds (or all the selected utxos). Requires only one recipients of value 0 - -OPTIONS: - --to ... Adds a recipient to the transaction - --unspendable ... Marks a utxo as unspendable - --external_policy - Selects which policy should be used to satisfy the external descriptor - - --internal_policy - Selects which policy should be used to satisfy the internal descriptor - - --utxos ... Selects which utxos *must* be spent - -f, --fee_rate Fee rate to use in sat/vbyte -``` - -Creates a new unsigned PSBT. The flags allow to set a custom fee rate (the default is 1.0 sat/vbyte) with `--fee_rate` or `-f`, the list of UTXOs that should be considered unspendable with `--unspendable` (this option can be specified multiple times) and a list of UTXOs that must be spent with `--utxos` (again, this option can also be specified multiple times). - -The `--to` option sets the receiver address of the transaction, and should contain the address and amount in Satoshi separated by a colon, like: `--to 2NErbQPsooXRatRJdrXDm9wKR2fRiZDT9wL:50000`. This option can also be specified multiple times to send to multiple addresses at once. - -The `--send_all` flag can be used to send the value of all the spendable UTXOs to a single address, without creating a change output. If this flag is set, there must be only one `--to` address, and its value will be ignored (it can be set to 0). - -The `--external_policy` and `--internal_policy` options are two advanced flags that can be used to select the spending policy that the sender intends to satisfy in this transaction. They are normally not required if there's no ambiguity, but sometimes with a complex descriptor one or both of them have to be specified, or you'll get a `SpendingPolicyRequired` error. Those flags should be set to a JSON object that maps a policy node id to the list of child indexes that -the user intends to satisfy for that node. This is probably better explained with an example: - -Let's assume our descriptor is: `sh(thresh(2,pk(A),sj:and_v(v:pk(B),n:older(6)),snj:and_v(v:pk(C),after(630000))))`. There are three conditions and we need to satisfy two of them to be able to spend. The conditions are: - -1. Sign with the key corresponding to `pk(A)` -2. Sign with the key corresponding to `pk(B)` AND wait 6 blocks -2. Sign with the key corresponding to `pk(C)` AND wait that block 630,000 is reached - -So if we write down all the possible outcomes when we combine them, we get: - -1. Sign with `pk(A)` + `pk(B)` + wait 6 blocks -2. Sign with `pk(A)` + `pk(C)` + wait block 630,000 -3. Sign with `pk(B)` + `pk(C)` + wait 6 blocks + wait block 630,000 - -In other words: - -* If we choose option #1, the final transaction will need to have the `nSequence` of its inputs set to a value greather than or equal to 6, but the `nLockTime` can stay at 0. -* If we choose option #2, the final transaction will need to have its `nLockTime` set to a value greater than or equal to 630,000, but the `nSequence` can be set to a final value. -* If we choose option #3, both the `nSequence` and `nLockTime` must be set. - -The wallet can't choose by itself which one of these combination to use, so the user has to provide this information with the `--external_policy` flag. - -Now, let's draw the condition tree to understand better how the chosen policy is represented: every node has its id shown right next to its name, like `qd3um656` for the root node. These ids can be seen by running the [policies](#policies) command. -Some ids have been omitted since they are not particularly relevant, in this example we will actually only use the root id. - -```mermaid -graph TD; - subgraph " " - R["Root - qd3um656"] --> A["pk(A) - ykfuwzkl"] - R["Root - qd3um656"] --> B["B - ms3xjley"] - B["B - ms3xjley"] --> B_0["pk(B)"] - B["B - ms3xjley"] --> B_1["older(6)"] - end - C["C - d8jph6ax"] --> C_0["pk(C)"] - C["C - d8jph6ax"] --> C_1["after(630,000)"] - R["Root - qd3um656"] --> C["C - d8jph6ax"] -``` - -Let's imagine that we are walking down from the root, and we want to use option #1. So we will have to select `pk(A)` + the whole `B` node. Since these nodes have an id, we can use it to refer to them and say which children -we want to use. In this case we want to use children #0 and #1 of the root, so our final policy will be: `--external_policy {"qd3um656":[0,1]}`. - -### extract\_psbt - -``` -OPTIONS: - --psbt Sets the PSBT to extract -``` - -Extracts the global transaction from a PSBT. **Note that partial signatures are ignored in this step. If you want to merge the partial signatures back into the global transaction first, please use [finalize_psbt](#finalize-psbt) first** - -### finalize\_psbt - -``` -OPTIONS: - --psbt Sets the PSBT to finalize - --assume_height Assume the blockchain has reached a specific height - --trust_witness_utxo Whether the signer should trust the witness_utxo, if the non_witness_utxo hasn’t been provided -``` - -Tries to finalize a PSBT by merging all the partial signatures and other elements back into the global transaction. This command fails if there are timelocks that have not yet expired, but the check can be overridden by specifying `--assume_height` to make the wallet assume that a future height has already been reached. - -### get\_balance - -This subcommand has no extra flags, and simply returns the available balance in Satoshis. This command **should normally be called after [`sync`](#sync)**, since it only looks into the local cache to determine the list of UTXOs. - -### get\_new\_address - -This subcommand has no extra flags and returns a new address. It internally increments the derivation index and saves it in the database. - -### list\_transactions - -This subcommand has no extra flags and returns the history of transactions made or received by the wallet, with their txid, confirmation height and the amounts (in Satoshi) "sent" (meaning, the sum of the wallet's inputs spent in the transaction) and -"received" (meaning, the sum of the outputs received by the wallet). Just like [`get_balance`](#get-balance) it **should normally be called after [`sync`](#sync)**, since it only operates -on the internal cache. - -### list\_unspent - -This subcommand has no extra flags and returns the list of available UTXOs and their value in Satoshi. Just like [`get_balance`](#get-balance) it **should normally be called after [`sync`](#sync)**, since it only operates -on the internal cache. - -### policies - -This subcommand has no extra flags and returns the spending policies encoded by the descriptor in a more human-readable format. As an example, running the `policies` command on the descriptor shown earlier for the explanation of the [create_tx](#create-tx) command, it will return this: - -```json -{ - "id":"qd3um656", - "type":"THRESH", - "items":[ - { - "id":"ykfuwzkl", - "type":"SIGNATURE", - "pubkey":"...", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - - } - } - }, - { - "id":"ms3xjley", - "type":"THRESH", - "items":[ - { - "id":"xgfnp9rt", - "type":"SIGNATURE", - "pubkey":"...", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - - } - } - }, - { - "id":"5j96ludf", - "type":"RELATIVETIMELOCK", - "value":6, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - "csv":6 - } - } - } - ], - "threshold":2, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":2, - "m":2, - "items":[ - 0, - 1 - ], - "conditions":{ - "[0, 1]":[ - { - "csv":6 - } - ] - } - } - }, - { - "id":"d8jph6ax", - "type":"THRESH", - "items":[ - { - "id":"gdl039m6", - "type":"SIGNATURE", - "pubkey":"...", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - - } - } - }, - { - "id":"xpf2twg8", - "type":"ABSOLUTETIMELOCK", - "value":630000, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{ - "timelock":630000 - } - } - } - ], - "threshold":2, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":2, - "m":2, - "items":[ - 0, - 1 - ], - "conditions":{ - "[0, 1]":[ - { - "timelock":630000 - } - ] - } - } - } - ], - "threshold":2, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":3, - "m":2, - "items":[ - 0, - 1, - 2 - ], - "conditions":{ - "[0, 1]":[ - { - "csv":6 - } - ], - "[0, 2]":[ - { - "timelock":630000 - } - ], - "[1, 2]":[ - { - "csv":6, - "timelock":630000 - } - ] - } - } -} -``` - -This is a tree-like recursive structure, so it tends to get huge as more and more pieces are added, but it's in fact fairly simple. Let's analyze a simple node of the tree: - -```json -{ - "id":"qd3um656", - "type":"SIGNATURE", - "pubkey":"...", - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"COMPLETE", - "condition":{} - } -} -``` - -* `id` is a unique identifier to this specific node in the tree. -* `type`, as the name implies, represents the type of node. It defines what should be provided to satisfy that particular node. Generally some other data are provided to give meaning to - the type itself (like the `pubkey` field here in the example). There are basically two families of types: some of them can only be used as leaves, while some other can only be used as intermediate nodes. - - Possible leaf nodes are: - - `SIGNATURE`, requires a signature made with the specified key. Has a `pubkey` if it's a single key, a `fingerprint` if the key is an xpub, or a `pubkey_hash` if the full public key is not present in the descriptor. - - `SIGNATUREKEY`, requires a signature plus the raw public key. Again, it can have a `pubkey`, `fingerprint` or `pubkey_hash`. - - `SHA256PREIMAGE`, requires the preimage of a given `hash`. - - `HASH256PREIMAGE`, requires the preimage of a given `hash`. - - `RIPEMD160PREIMAGE`, requires the preimage of a given `hash`. - - `HASH160PREIMAGE`, requires the preimage of a given `hash`. - - `ABSOLUTETIMELOCK`, doesn't technically require anything to be satisfied, just waiting for the timelock to expire. Has a `value` field with the raw value of the timelock (can be both in blocks or time-based). - - `RELATIVETIMELOCK`, again only requires waiting for the timelock to expire. Has a `value` like `ABSOLUTETIMELOCK`. - - Possible non-leaf nodes are: - - `THRESH`, defines a threshold of policies that has to be met to satisfy the node. Has an `items` field, which is a list of policies to satisfy and a `threshold` field that defines the threshold. - - `MULTISIG`, Similar to `THRESH`, has a `keys` field, which is a list of keys represented again as either `pubkey`, `fingerprint` or `pubkey_hash` and a `threshold` field. - -* `satisfaction` is currently not implemented and will be used to provide PSBT introspection, like understanding whether or not a node is already satisfied and to which extent in a PSBT. -* `contribution` represents if so and how much, the provided descriptor can contribute to the node. - - The possible types are: - - `NONE`, which means that the descriptor cannot contribute. - - `COMPLETE`, which means that the descriptor by itself is enough to completely satisfy the node. It also adds a `condition` field which represent any potential extra condition that has to be met to - consider the node complete. An example are the timelock nodes, that are always complete *but* they have an extra `csv` or `timelock` condition. - - `PARTIAL`, which means that the descriptor can partially satisfy the policy. This adds a `m`, `n`, `items` that respectively represent the threshold, the number of available items to satisfy and the items - that the provided descriptor can satisfy. Also adds a `conditions` field which is an integer to list of conditions map. The key is the child index and the map are all the possibile extra conditions that - have to be satisfied if that node is used in the threshold. For instance, if you have a threshold of a SIGNATURE and a RELATIVETIMELOCK, in this order, the `conditions` field will be `1 ⇒ csv(x)`, - because the item at index 1 needs the extra csv condition. - - `PARTIALCOMPLETE`, which is basically a `PARTIAL` with the size of `items` >= `m`. It's treated as a separate entity to make the code a bit more clean and easier to implement. Like `PARTIAL`, it also has - a `m`, `n`, `items` fields but the `conditions field` is a bit different: it's a list of integers to list of conditions map. The key represents the combination that can be used to satisfy the threshold, - and the value contains all the possible conditions that also have to be satisfied. For instance, if you have a 2-of-2 threshold of a TIMELOCK and a RELATIVETIMELOCK, the `conditions` field will be `[0, 1] ⇒ - csv(x) + timelock(y)`, because if the combination of items 0 and 1 is picked, both of their conditions will have to be meet too. - -While the structure contains all of the intermediate nodes too, the root node is the most important one because it defines how the descriptor can contribute to spend outputs sent to its addresses. - -For instance, looking at the root node of the previous example (with the internal `items` omitted) from a descriptor that has all the three private keys for keys A, B and C, we can clearly see that it can satisfy -the descriptor (type = `PARTIALCOMPLETE`) and the three options are `[0, 1] ⇒ csv(6)` (Option #1), `[0, 2] ⇒ timelock(630,000)` (Option #2) or `[1, 2] ⇒ csv(6) + timelock(630,000)` (Option #3). - -```json -{ - "type":"THRESH", - "items":[], - "threshold":2, - "satisfaction":{ - "type":"NONE" - }, - "contribution":{ - "type":"PARTIALCOMPLETE", - "n":3, - "m":2, - "items":[ - 0, - 1, - 2 - ], - "conditions":{ - "[0, 1]":[ - { - "csv":6 - } - ], - "[0, 2]":[ - { - "timelock":630000 - } - ], - "[1, 2]":[ - { - "csv":6, - "timelock":630000 - } - ] - } - } -} -``` - -### `public_descriptor` - -This subcommand has no extra flags and returns the "public" version of the wallet's descriptor(s). It can be used to bootstrap a watch-only instance for the wallet. - -### `help` - -This subcommand has no extra flags. When used as `bdk-cli wallet help` it will displays all the -options and subcommands of the `wallet` command. When used as `bdk-cli wallet help ` -it will display all the details of the subcommand. - -### `sign` - -``` -OPTIONS: - --psbt Sets the PSBT to sign - --assume_height Assume the blockchain has reached a specific height. This affects the transaction finalization, if there are timelocks in the descriptor - --trust_witness_utxo Whether the signer should trust the witness_utxo, if the non_witness_utxo hasn’t been provided -``` - -Adds to the PSBT all the signatures it can produce with the secrets embedded in the descriptor (xprv or WIF keys). Returns the signed PSBT and, if there are enough item to satisfy the script, also the extracted raw Bitcoin transaction. - -Optionally, the `--assume_height` option can be specified to let the wallet assume the blockchain has reached a specific height. This affects the finalization of the PSBT which is done right at the end of the signing process: the wallet tries to satisfy the spending condition of each input using the partial signatures collected. In case timelocks are present the wallet needs to know whether or not they have expired. This flag is particularly useful for offline wallets. - -### `sync` - -This subcommand has no extra flags. It connects to the chosen Electrum server and synchronizes the list of transactions received and available UTXOs. diff --git a/docs/bdk-cli/introduction.md b/docs/bdk-cli/introduction.md deleted file mode 100644 index b62605d84c..0000000000 --- a/docs/bdk-cli/introduction.md +++ /dev/null @@ -1,13 +0,0 @@ -# Introduction - -[`bdk-cli`](https://github.com/bitcoindevkit/bdk-cli) is a lightweight [`repl`](https://codewith.mu/en/tutorials/1.0/repl) wrapper over `bdk` that comes as a command line application. It is useful for quick testing and prototyping of bdk functionalities. - -This can also be used as an example application to create your own command line bitcoin wallet tool using bdk. - -`bdk-cli` can interface with all the blockchain backends currently supported by `bdk`, like `rpc`, `electrum`, `esplora` and `compact_filters`. - - - -Check out [project documentation](https://docs.rs/bdk-cli/0.5.0/bdk_cli/) for more details. - -The following sections goes into more details on the installation and usage of `bdk-cli`. \ No newline at end of file diff --git a/docs/bdk-cli/playground.md b/docs/bdk-cli/playground.md deleted file mode 100644 index 631c523e9c..0000000000 --- a/docs/bdk-cli/playground.md +++ /dev/null @@ -1,3 +0,0 @@ -# Playground - - diff --git a/docs/bdk-cli/regtest.md b/docs/bdk-cli/regtest.md deleted file mode 100644 index 6e97e71af6..0000000000 --- a/docs/bdk-cli/regtest.md +++ /dev/null @@ -1,46 +0,0 @@ -# Regtest - -Running the `bdk-cli` tool in regtest requires having a local Electrum server set-up. There are two main implementations, [`electrs`](https://github.com/romanz/electrs) in Rust and [`ElectrumX`](https://github.com/spesmilo/electrumx) in Python. Since the Rust toolchain is already required to -use BDK, this page will focus mostly on the former. - -Electrs can be installed by running: - -```bash -cargo install --git https://github.com/romanz/electrs --bin electrs -``` - -Just like before, this command will probably take a while to finish. - -Once it's done, assuming you have a regtest bitcoind running in background, you can launch a new terminal and run the following command to actually start electrs: - -```bash -electrs --log-filters INFO --timestamp --db-dir /tmp/electrs-db --electrum-rpc-addr="127.0.0.1:50001" --network=regtest --cookie-file=$HOME/.bitcoin/regtest/.cookie -``` - -on macOS you should change the cookie-file to `$HOME/Library/Application Support/Bitcoin/regtest/.cookie`. - -This will start the Electrum server on port 50001. You can then add the `-n regtest -s 127.0.0.1:50001` to the `bdk-cli` commands to switch to the local regtest. - -## Troubleshooting - -#### Stuck with "*wait until bitcoind is synced (i.e. initialblockdownload = false)*" - -Just generate a few blocks with `bitcoin-cli generatetoaddress 1
` - -## Bonus: Docker - -If you have already installed Docker on your machine, you can also use 🍣 [Nigiri CLI](https://github.com/vulpemventures/nigiri) to spin-up a complete development environment in `regtest` that includes a `bitcoin` node, an `electrs` explorer and the [`esplora`](https://github.com/blockstream/esplora) web-app to visualize blocks and transactions in the browser. - -Install 🍣 Nigiri -```bash -$ curl https://getnigiri.vulpem.com | bash -``` - -Start Docker daemon and run Nigiri box -``` -$ nigiri start -``` - -This will start electrum RPC interface on port `51401`, the REST interface on `3000` and the esplora UI on `5000` (You can visit with the browser and look for blocks, addresses and transactions) - -You can then add the `-n regtest -s 127.0.0.1:51401` to the `bdk-cli` commands to switch to the local regtest. diff --git a/docs/descriptors/README.md b/docs/descriptors/README.md deleted file mode 100644 index e3a6402f74..0000000000 --- a/docs/descriptors/README.md +++ /dev/null @@ -1,116 +0,0 @@ -# Descriptors - -Descriptors are a compact and semi-standard way to easily encode, or "describe", how scripts (and subsequently, addresses) of a wallet should be generated. They can be especially helpful when working with multisigs or even -more complex scripts, where the structure of the script itself is not trivial. They are a big step forward in making wallets more portable across different tools and apps, because for the first time they create a common -language to describe a full bitcoin script that developers can use and integrate in their software. - -The ecosystem around descriptors is still very much in its early stage, but they are starting to see some adoption in [Bitcoin Core](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md) and other projects. BDK -aims to produce the first "Native Descriptor" Bitcoin library that can be used by developers to build their own ["Native Descriptor Wallets"](https://www.youtube.com/watch?v=xC25NzIjzog). - -### Compatibility Matrix - -Below are some tables to highlight the differences between Bitcoin Core's descriptor support, rust-miniscript's one and BDK's. - -#### Key Types - -
- -| Key Type | BDK | rust-miniscript | Bitcoin Core | -| -------- | --------------- | --------------- | ------------ | -| Hex PublicKey | ✅ | ✅ | ✅ | -| WIF PrivateKey | ✅ | ❌ | ✅ | -| Extended Keys (xpub/xprv) | ✅ | ❌ | ✅ | - -
- -#### Script Types (top level) - -
- -| Script Type | BDK | rust-miniscript | Bitcoin Core | -| -------- | --------------- | --------------- | ------------ | -| `pk()` | ✅ | ✅ | ✅ | -| `pkh()` | ✅ | ✅ | ✅ | -| `wpkh()` | ✅ | ✅ | ✅ | -| `tr()` | ✅ | ✅ | ✅ | -| `sh(wpkh())` | ✅ | ✅ | ✅ | -| `sh()` | ✅ | ✅ | ✅ | -| `wsh()` | ✅ | ✅ | ✅ | -| `sh(wsh())` | ✅ | ✅ | ✅ | -| `combo()` | ❌ | ❌ | ✅ | -| `addr()` | ❌ | ❌ | ✅ | -| `raw()` | ❌ | ❌ | ✅ | -| Bare scripts | ✅ | ✅ | ❌ | - -
- -#### Operators - -
- -| Operator | BDK | rust-miniscript | Bitcoin Core | -| -------- | --------------- | --------------- | ------------ | -| `pk()` | ✅ | ✅ | ✅ | -| `pkh()` | ✅ | ✅ | ✅ | -| `older()` | ✅ | ✅ | ✅ | -| `after()` | ✅ | ✅ | ✅ | -| `sha256()` | ✅ | ✅ | ✅ | -| `hash256()` | ✅ | ✅ | ✅ | -| `ripemd160()` | ✅ | ✅ | ✅ | -| `hash160()` | ✅ | ✅ | ✅ | -| `andor()` | ✅ | ✅ | ✅ | -| `and_{v,b,n}()` | ✅ | ✅ | ✅ | -| `or_{b,c,d,i}()` | ✅ | ✅ | ✅ | -| `multi()` | ✅ | ✅ | ✅ | -| `thresh()` | ✅ | ✅ | ✅ | -| `sortedmulti()` | ✅ | ✅ | ✅ | - -
- -#### Modifiers - -
- -| Script Type | BDK | rust-miniscript | Bitcoin Core | -| -------- | --------------- | --------------- | ------------ | -| `a:` | ✅ | ✅ | ✅ | -| `s:` | ✅ | ✅ | ✅ | -| `c:` | ✅ | ✅ | ✅ | -| `t:` | ✅ | ✅ | ✅ | -| `d:` | ✅ | ✅ | ✅ | -| `v:` | ✅ | ✅ | ✅ | -| `j:` | ✅ | ✅ | ✅ | -| `n:` | ✅ | ✅ | ✅ | -| `l:` | ✅ | ✅ | ✅ | -| `u:` | ✅ | ✅ | ✅ | - -
- -For a more thorough description of these operators and modifiers see [Sipa's Miniscript Page](http://bitcoin.sipa.be/miniscript/) and [Bitcoin Core's](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md). - -### Examples - -Some examples of valid BDK descriptors are: - -
- -| Spending Policy | Descriptor | Address 0 | Address 1 | -| --------------- | ---------- | --------- | --------- | -| Static P2PKH | `pkh(cSQPHDBwXGjVzWRqAHm6zfvQhaTuj1f2bFH58h55ghbjtFwvmeXR)` | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | -| Static P2PKH, watch-only | `pkh(02e96fe52ef0e22d2f131dd425ce1893073a3c6ad20e8cac36726393dfb4856a4c)` | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | mrkwtj5xpYQjHeJe5wsweNjVeTKkvR5fCr | -| P2WSH 2-of-2 with one private key | `wsh(multi(2,tprv8ZgxMBicQKsPePmENhT9N9yiSfTtDoC1f39P7nNmgEyCB6Nm4Qiv1muq4CykB9jtnQg2VitBrWh8PJU8LHzoGMHTrS2VKBSgAz7Ssjf9S3P/0/*,tpubDBYDcH8P2PedrEN3HxWYJJJMZEdgnrqMsjeKpPNzwe7jmGwk5M3HRdSf5vudAXwrJPfUsfvUPFooKWmz79Lh111U51RNotagXiGNeJe3i6t/1/*))` | tb1qqsat6c82fvdy73rfzye8f7nwxcz3xny7t56azl73g95mt3tmzvgs9a8vjs | tb1q7sgx6gscgtau57jduend6a8l445ahpk3dt3u5zu58rx5qm27lhkqgfdjdr | -| P2WSH-P2SH one key + 10 days timelock | `sh(wsh(and_v(vc:pk_h(tprv8ZgxMBicQKsPePmENhT9N9yiSfTtDoC1f39P7nNmgEyCB6Nm4Qiv1muq4CykB9jtnQg2VitBrWh8PJU8LHzoGMHTrS2VKBSgAz7Ssjf9S3P/0/*),older(1440))))` | 2Mtk2nyS98MCi2P7TkoBGLaJviBy956XxB1 | 2MuEStKzYhqb5HCFgHz9153tZsL5sVqV5xC | - -
- -### Implementation Details - -BDK extends the capabilities of [rust-miniscript](https://github.com/apoelstra/rust-miniscript) by introducing the concept of an *ExtendedDescriptor*: it represents a descriptor that contains one or more "derivable keys" like `xpubs` or `xprvs` -and can be "derived" from a normal Descriptor by deriving every single one of its keys. It is currently called "StringDescriptor" in the code, because it's implemented as a wrapped `miniscript::Descriptor`. - -ExtendedDescriptors are derived using a single index instead of a full derivation path: this is because normally most of the path is fixed and can be represented right after the xpub/xprv itself, and only the -final index changes for each address. This is what's normally called a *DescriptorExtendedKey* in the codebase, it is represented with a similar syntax to Bitcoin Core's, such as: - -``` -[d34db33f/44'/0'/0']xpub6ERApfZwUNrhL.......rBGRjaDMzQLcgJvLJuZZvRcEL/0/* -``` diff --git a/docs/examples/README.md b/docs/examples/README.md deleted file mode 100644 index c033044d62..0000000000 --- a/docs/examples/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# Examples - -Click the links below and learn from community-built example projects. - -## [BDK-CLI](https://github.com/bitcoindevkit/bdk-cli) -A command line interface to experiment with the bitcoindevkit. - -## [DevkitWallet](https://github.com/thunderbiscuit/devkit-wallet) -A demo app for the bitcoindevkit on Android using `bdk-kotlin`. -## [Padawan Wallet](https://github.com/thunderbiscuit/padawan-wallet) -A testnet-only bitcoin wallet full of tutorials on how to use bitcoin wallets. - -## [BDKSwiftExampleWallet](https://github.com/reez/BDKSwiftExampleWallet) -An example iOS app using `bdk-swift`. - -## [Tatooine](https://github.com/thunderbiscuit/tatooine) -Tatooine is a small bitcoin testnet faucet built with Ktor, a Kotlin asynchronous framework for creating microservices and web applications. - -## [SEBA Bank Proof of reserves](https://github.com/bitcoindevkit/bdk-reserves) -The `bdk` library aims to be the core building block for Bitcoin wallets of any kind. The `bdk-reserves` library provides an implementation of `proof-of-reserves` for bdk. - -## [Stackmate](https://github.com/StackmateNetwork/the-stackmate) -A multi-purpose Bitcoin Wallet. - -## [Spotbit](https://github.com/BlockchainCommons/spotbit) -Spotbit's purpose is to allow users to access price feeds in a customisable way that preserves privacy and mitigate the reliance on a single source of data. \ No newline at end of file diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 9dc5f9f6ae..0000000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,119 +0,0 @@ -# Bitcoin Dev Kit - -The [Bitcoin Dev Kit (BDK)](https://github.com/bitcoindevkit) project (originally called Magical Bitcoin 🧙) aims to build a collection of tools and libraries that are designed to be a solid foundation for cross platform Bitcoin wallets, along with a fully working *reference implementation* wallets for various platforms. -All BDK components are designed to be lightweight and modular so that they can be adapted for virtually any use-case: from single-sig mobile wallets to multi-billion-dollar cold storage vaults. - -The main long-term goal is to concentrate the development efforts of multiple people and companies into one open source and very well reviewed project, instead of dispersing them over multiple closed/semi-closed or -poorly designed projects. - -While some parts of the library are still considered "experimental" (check the docs for more info), the core [`Wallet`](https://docs.rs/bdk/latest/bdk/wallet/struct.Wallet.html) architecture is now considered stable. We still can't commit to keeping this same exact API forever, -but we are not expecting to do any major breaking change in that area. - -If you want to try out the library for your projects, now it's finally a good time to do it! You can start by checking out the ["getting started"](/getting-started/) section in our blog or joining our [Discord](https://discord.gg/dstn4dQ) -server to chat with us. - -## Initial Configuration - -Most Rust projects use Cargo to download and build the libraries the code depends on. To configure BDK package in the `Cargo.toml`, the following line can be added: - -``` -[dependencies] -bdk = "0.28.1" -``` - -Or it is possible to install only the features that will be used in the project. - -``` -[dependencies] -bdk = { version = "0.28.1", default-feature = false, features = ["all-keys", "key-value-db", "rpc"] } -``` - -BDK uses a set of [feature flags](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section) to reduce the amount of compiled code by allowing projects to only enable the features they need. - -By default, BDK enables two internal features, `key-value-db` and `electrum`. - -It is recommended that new users use the default features which will enable basic descriptor wallet functionality. More advanced users can disable the `default` features (`--no-default-features`) and build the BDK library with only the necessary features. - -Below is a list of the available feature flags and the additional functionality they provide. - -* `all-keys`: all features for working with bitcoin keys -* `async-interface`: async functions in bdk traits -* `keys-bip39`: [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) mnemonic codes for generating deterministic keys - -## Internal Features - -These features do not expose any new API, but influence internal implementation aspects of BDK. - -* `compact_filters`: [compact_filters](https://docs.rs/bdk/latest/bdk/blockchain/compact_filters/index.html) client protocol for interacting with the bitcoin P2P network -* `electrum`: [electrum](https://docs.rs/bdk/latest/bdk/blockchain/electrum/index.html) client protocol for interacting with electrum servers -* `esplora`: [esplora](https://docs.rs/bdk/latest/bdk/blockchain/esplora/index.html) client protocol for interacting with blockstream [electrs](https://github.com/Blockstream/electrs) servers -* `key-value-db`: key value [database](https://docs.rs/bdk/latest/bdk/database/index.html) based on [sled](https://crates.io/crates/sled) for caching blockchain data - - -## Playground - -As a way of demonstrating the flexibility of this project, a minimalistic command line tool (called `bdk-cli`) is available as a debugging tool in the [`bdk-cli`](https://github.com/bitcoindevkit/bdk-cli) -repo. It has been compiled to WebAssembly and can be used directly from the browser. See the [playground](/bdk-cli/playground) section to give it a try! - -The playground relies on [Esplora](https://blockstream.info) to monitor the blockchain and is currently locked in testnet-only mode, for obvious safety reasons. The native command line tool can also be used in regtest mode when installed on -a computer. See the [bdk-cli](/bdk-cli) section to learn more. - -## Descriptors - -One of the original milestones of this project was to provide wallets with "almost magical" support for very complex spending policies, without having to individually translate them into code. It may sound disappointing, but there isn't, in fact, -any real magic in this wallet: the generalization is achieved thanks to [*descriptors*](https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md), that are now slowly starting to see adoption in a few other Bitcoin projects as well. - -The author of this project strongly believes descriptors will be a big part of the future generation of Bitcoin wallets, since they provide a very flexible scripting language that can also be extended as the -technology and tooling of Bitcoin evolves and changes (Schnorr signatures, Taproot, etc). - -To learn more, check out the specific [Descriptors section](/descriptors). - -The following code shows how to generate a random mnemonic, the extended (and deterministic) keys from that mnemonic and finally the descriptors from the extended private keys. - -To be able to run this code, the `bdk` dependency in `Cargo.toml` must be set as follows: - -``` -[dependencies] -bdk = { version = "0.28.1", default-feature = false, features = ["all-keys"] } -``` - -```rust -use bdk::bitcoin::Network; -use bdk::database::MemoryDatabase; -use bdk::keys::{DerivableKey, GeneratableKey, GeneratedKey, ExtendedKey, bip39::{Mnemonic, WordCount, Language}}; -use bdk::template::Bip84; -use bdk::{miniscript, Wallet, KeychainKind}; - -fn main() { - println!("Hello, world!"); - - let network = Network::Testnet; // Or this can be Network::Bitcoin, Network::Signet or Network::Regtest - - // Generate fresh mnemonic - let mnemonic: GeneratedKey<_, miniscript::Segwitv0> = Mnemonic::generate((WordCount::Words12, Language::English)).unwrap(); - // Convert mnemonic to string - let mnemonic_words = mnemonic.to_string(); - // Parse a mnemonic - let mnemonic = Mnemonic::parse(&mnemonic_words).unwrap(); - // Generate the extended key - let xkey: ExtendedKey = mnemonic.into_extended_key().unwrap(); - // Get xprv from the extended key - let xprv = xkey.into_xprv(network).unwrap(); - - // Create a BDK wallet structure using BIP 84 descriptor ("m/84h/1h/0h/0" and "m/84h/1h/0h/1") - let wallet = Wallet::new( - Bip84(xprv, KeychainKind::External), - Some(Bip84(xprv, KeychainKind::Internal)), - network, - MemoryDatabase::default(), - ) - .unwrap(); - - println!("mnemonic: {}\n\nrecv desc (pub key): {:#?}\n\nchng desc (pub key): {:#?}", - mnemonic_words, - wallet.get_descriptor_for_keychain(KeychainKind::External).to_string(), - wallet.get_descriptor_for_keychain(KeychainKind::Internal).to_string()); -} -``` - -More information about each component used in the code can be found in [BDK Documentation](https://docs.rs/bdk/latest/bdk/index.html).