From: Pedro Felix Date: Fri, 2 Sep 2022 22:11:43 +0000 (-0700) Subject: Add bdk-cli introduction tutorial X-Git-Url: http://internal-gitweb-vhost/script/%22https:/database/scripts/theme.js?a=commitdiff_plain;h=864d5d47e6c5bb0986a4287c442aa60c05d70454;p=bitcoindevkit.org Add bdk-cli introduction tutorial --- diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index df422e592d..8d2178250a 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -59,6 +59,7 @@ const tutorialSidebar = [ '/tutorials/exploring_bdk_rn', '/tutorials/using_bdk_with_hardware_wallets', '/tutorials/exploring_bdk_flutter', + '/tutorials/bdk_cli_basics', ], } ] diff --git a/docs/tutorials/bdk_cli_basics.md b/docs/tutorials/bdk_cli_basics.md new file mode 100644 index 0000000000..41832d58f0 --- /dev/null +++ b/docs/tutorials/bdk_cli_basics.md @@ -0,0 +1,357 @@ +--- +title: "Command Line introduction to Bitcoin Wallet Development using bdk-cli" +description: "Intro to bdk-cli and wallet dev" +authors: + - waterst0ne +date: "2022-09-22" +tags: ["bdk-cli", "basics", "novice"] +--- +## Tutorial Goals +- The goal for this tutorial is to introduce you to [bdk-cli](https://github.com/bitcoindevkit/bdk-cli), a powerful command-line program. You will be exposed to many of the basic skills that go into creating and managing bitcoin wallets. +- If you've read most of the ["Mastering Bitcoin"](https://github.com/bitcoinbook/bitcoinbook) book, this tutorial could serve as a stepping stone into your Bitcoin wallet development journey. + +- This short tutorial will expose you to the [`bdk library` ](https://docs.rs/bdk/latest/bdk/) and the practical knowledge needed for bitcoin wallet development. As a consequence you will deepen your technical understanding about bitcoin and the bdk library. + +- BDK also has [language-bindings](https://github.com/bitcoindevkit/bdk-ffi) for **Kotlin/Java, Swift, Python** which enable the use of BDK's **Rust** library as an API. You can later use these similar steps to create your own bitcoin mobile, desktop or even WebApp by using the bdk-ffi language bindings. + +*** + +## A few things before you begin: + +- Three things to look out for in each step of the tutorial: + - 1) :arrow_forward: / :large_orange_diamond: - Commands for the Terminal or Shell + - 2) :+1: - Preview of the command output. Note, not all commands will output code. + - 3) Preview Video of the tutorial for reference of what things should look like in action. + +*** +### Outline of Tutorial and Installation notes: + +### Brief Outline of Tutorial +- Step 1: Creating a mnemonic word list + XPRV (Extended Private Key) +- Step 2: Generate testnet Receive Address +- Step 3: Send funds to newly generated address +- Step 4: Sync Wallet +- Step 5: Check Balance of Wallet +- Step 6: Create a Transaction (PSBT) +- Step 7: Sign the Transaction (PSBT) +- Step 8: Broadcast Transaction + +*** +### Rust and Cargo installation: +- [Rust and Cargo Installation](https://rustup.rs/) + +*** +### `bdk-cli` installation: +- Download the [`bdk-cli` github repository locally](https://github.com/bitcoindevkit/bdk-cli.git) + - Enter the folder `cd bdk-cli` + - Install `cargo install --path . --features electrum,repl,compiler ` + - Once installation is done exit and reopen your terminal (command-line interface) + +### Emoji Legend: + +:arrow_forward: : Unix/Linux Commands to copied and pasted +:large_orange_diamond: : Windows Powershell Commands to copied and pasted +:+1: : Output/ preview of code + +*** +## Step 0: Check Version of bdk-cli +:arrow_forward: / :large_orange_diamond: `bdk-cli -V` +:+1: The output below confirms the command was successful. +``` +bdk-cli 0.6.0 +``` + +![](https://i.imgur.com/IcuyeMS.gif) + + +### Preview of bdk-cli help menu +:arrow_forward: / :large_orange_diamond: `bdk-cli --help` +:+1: The output below confirms the command was successful. + +```shell +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! + +For more information checkout + +USAGE: + bdk-cli [OPTIONS] + +FLAGS: + -h, --help Prints help information + -V, --version Prints version information + +OPTIONS: + -d, --datadir Sets the wallet data directory. Default value : "~/.bdk-bitcoin + -n, --network Sets the network [default: testnet] [possible values: bitcoin, testnet, signet, regtest] + +SUBCOMMANDS: + compile Compile a miniscript policy to an output descriptor + help Prints this message or the help of the given subcommand(s) + key Subcommands for Key operations + repl Options to configure a SOCKS5 proxy for a blockchain client connection + wallet Wallet subcommands that can be issued without a blockchain backend +``` + --- + +## Step 1: Seed Generate + +### 1a: Mnemonic word-list + XPRV (Exteneded Private Key) :key: + +Linux/Terminal: +:arrow_forward: `bdk-cli key generate | tee key.json` + +Windows Powershell: +:large_orange_diamond: `bdk-cli key generate | Out-File -FilePath "key.json"` + +```shell +{ + "fingerprint": "42b15d2f", + "mnemonic": "party salon worth satoshi envelope suggest garlic dry add pitch throw clap keen narrow antique oyster ketchup purchase gasp visual work venue fog crater", + "xprv": "tprv8ZgxMBicQKsPdwpamtjqMFpYRTafnE1bN2SphLEybCtRKakk6S1TgQCsZgiBwJuJNWe3jYdgVCTsKf9weMxj6tW4zNNKWptykszJpS2L8wE" +} +``` + +![](https://i.imgur.com/ii62Hul.gif) + +*** +### 1b: Save XPRV (Extended Private Key) into environment variable +Linux/Terminal: +:arrow_forward: `export XPRV_00=$(cat key.json | jq -r .xprv)` + +Windows Powershell: + +:large_orange_diamond: `$json = Get-Content -Path .\key.json | ConvertFrom-Json` + +:large_orange_diamond: `$mykeyValue = $json.xprv` + +:large_orange_diamond: `[System.Environment]::SetEnvironmentVariable('XPRV',$mykeyValue, 'Process')` + +![](https://i.imgur.com/KYW2Cdo.gif) + +*** +### 1c: Verify environment variable XPRV_00 is active +Linux/Terminal: +:arrow_forward: `env | grep XPRV` + +Windows Powershell: +:large_orange_diamond: `$env:XPRV` + +![](https://i.imgur.com/ZahbJwe.gif) + +*** +### 1d: Create Descriptor and Save into environment variable + +Linux/Terminal: +:arrow_forward: `export my_descriptor="wpkh($XPRV_00/84h/1h/0h/0/*)"` + +Windows Powershell: +:large_orange_diamond: `[System.Environment]::SetEnvironmentVariable('my_descriptor', "wpkh($env:XPRV/84h/1h/0h/0/*)", 'Process')` + + + +![](https://i.imgur.com/UV4Vgsq.gif) + +*** +### 1e: Verify environment variable my_descriptor is active + +Linux/Terminal: +:arrow_forward: `env | grep my_descriptor` + +Windows Powershell: +:large_orange_diamond: `$env:my_descriptor ` + +![](https://i.imgur.com/s7ZeRQN.gif) + + + +*** +## Step 2: Generate Receive-Address +Linux/Terminal: + +:arrow_forward: `bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor get_new_address` + +Windows Powershell: +:large_orange_diamond:`bdk-cli wallet --descriptor $env:my_descriptor get_new_address` + + + +![](https://i.imgur.com/P8PjTAo.gif) + + + +:+1: The output below confirms the command was successful. + +```shell +{ + "address": "tb1qrh4sq5va0unqtxyfv8al9lz3sna3988cj59uya" +} +``` + +*** +## Step 3: Send testnet bitcoin to the newly created receive-address +Use a faucet to send funds to your newly created address. Here is a link to one: [Bitcoin Testnet Faucet](https://bitcoinfaucet.uo1.net) + +*** +## Step 4: Sync the wallet +Linux/Terminal: +:arrow_forward: ```bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor sync``` + +Windows Powershell: +:large_orange_diamond: ``` bdk-cli wallet --descriptor $env:my_descriptor sync``` + + +:+1: The output below confirms the command was successful. + +```shell +{} +``` + +![](https://i.imgur.com/WFYBgVB.gif) + +*** +## Step 5: Check the balance + +Linux/Terminal: +:arrow_forward: `bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor get_balance ` + +Windows Powershell: +:large_orange_diamond: +`bdk-cli wallet --descriptor $env:my_descriptor get_balance` + +:::tip +Note: The balance will only show after the transaction has been confirmed in a block at least once. +::: + +:+1: The output below confirms the command was successful: +```shell +{ + "satoshi": { + "confirmed": 100000, + "immature": 0, + "trusted_pending": 0, + "untrusted_pending": 0 + } +} +``` + +![](https://i.imgur.com/v8MAYB2.gif) + +*** +## Step 6: Create Transaction (PSBT) + +To create a PSBT (partially-signed-bitcoin-transaction) run the command: + +Linux/Terminal: +:arrow_forward: `bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor create_tx --to tb1qw2c3lxufxqe2x9s4rdzh65tpf4d7fssjgh8nv6:50000` + + +Windows Powershell: +:large_orange_diamond: +` bdk-cli wallet --descriptor $env:my_descriptor create_tx --to tb1qjk6n943uwhqhdf7en600tnwxpslvwtr0udsehp:0 --send_all` +![](https://i.imgur.com/EUCovcJ.gif) + +:+1: The output below confirms the command was successful. + +```shell +{ + "details": { + "confirmation_time": null, + "fee": 113, + "received": 0, + "sent": 123000, + "transaction": null, + "txid": "029173d76253e3441f9dc26f91e6ef30dff486848e91a7941f0cacd0af25ee30" + }, + "psbt": "cHNidP8BAFUBAAAAAak8uMR3UGkAGUKWsq8Mv45qg2fdD93JQRIsa2P0wFloAQAAAAD/////AQfgAQAAAAAAGXapFDRKD0jKFQ7CuQOBdmC5tosTpnAmiKwAAAAAAAEA3gIAAAAAAQFY9sVfEEbyjrHXSlxXDxL+71WOMnsPpVElwk+3E/J9vAAAAAAA/v///wIYZRIAAAAAABYAFBKYf7yF+ss6EFdw2rDZTfdLhep8eOABAAAAAAAWABQd6wBRnX8mBZiJYfvy/FGE+xKc+AJHMEQCIFSIkvEUI9yUgEw4JocRs1aiVsBlKKXrOQaQb3XFqR21AiBqiEVzCVVSRGjckyPDgAQBnOdSzBYR6Rw6KFcCP+E27wEhAwIlXdfM2WYnYa36Hp4MS6YkplBAgBsb1tYG9NiWFWTKzPYhAAEBH3jgAQAAAAAAFgAUHesAUZ1/JgWYiWH78vxRhPsSnPgiBgP80FpaWYQzGzCnNI9blXbei61YpAmtoezMRxpVvBJ6SxgTizKsVAAAgAEAAIAAAACAAAAAAAAAAAAAAA==" +} +``` + +*** +### 6a: export PSBT to environment-variable +Linux/Terminal: + :arrow_forward: `export PSBT="PASTE_PSBT_HERE"` + + +Windows Powershell: +:large_orange_diamond:`[System.Environment]::SetEnvironmentVariable('PSBT',"PASTE_PSBT_HERE",'Process')` +![](https://i.imgur.com/CEDKcPZ.gif) + +*** +## Step 7: Sign Transaction (PSBT) + +Linux/Terminal: +:arrow_forward: ` bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor sign --psbt $PSBT` + +Windows Powershell: +:large_orange_diamond:`bdk-cli wallet --descriptor $env:my_descriptor sign --psbt $env:PSBT` + + +- DON'T FORGET to COPY the PSBT for the next step + +![](https://i.imgur.com/f4o4Ce8.gif) + + +:+1: The output below confirms the command was successful. + + + +```shell +{ + "is_finalized": true, + "psbt": "cHNidP8BAFUBAAAAAak8uMR3UGkAGUKWsq8Mv45qg2fdD93JQRIsa2P0wFloAQAAAAD/////AQfgAQAAAAAAGXapFDRKD0jKFQ7CuQOBdmC5tosTpnAmiKwAAAAAAAEA3gIAAAAAAQFY9sVfEEbyjrHXSlxXDxL+71WOMnsPpVElwk+3E/J9vAAAAAAA/v///wIYZRIAAAAAABYAFBKYf7yF+ss6EFdw2rDZTfdLhep8eOABAAAAAAAWABQd6wBRnX8mBZiJYfvy/FGE+xKc+AJHMEQCIFSIkvEUI9yUgEw4JocRs1aiVsBlKKXrOQaQb3XFqR21AiBqiEVzCVVSRGjckyPDgAQBnOdSzBYR6Rw6KFcCP+E27wEhAwIlXdfM2WYnYa36Hp4MS6YkplBAgBsb1tYG9NiWFWTKzPYhAAEBH3jgAQAAAAAAFgAUHesAUZ1/JgWYiWH78vxRhPsSnPgiAgP80FpaWYQzGzCnNI9blXbei61YpAmtoezMRxpVvBJ6S0gwRQIhALWkBRSJzxuf0od4tPu3qFmEfJ2Y+/QBGtfjSFObWsPeAiA4QJx8Rk5pacrjHv5EOdw6RNHXcdtepFs+m0/Za/h0UQEiBgP80FpaWYQzGzCnNI9blXbei61YpAmtoezMRxpVvBJ6SxgTizKsVAAAgAEAAIAAAACAAAAAAAAAAAABBwABCGwCSDBFAiEAtaQFFInPG5/Sh3i0+7eoWYR8nZj79AEa1+NIU5taw94CIDhAnHxGTmlpyuMe/kQ53DpE0ddx216kWz6bT9lr+HRRASED/NBaWlmEMxswpzSPW5V23outWKQJraHszEcaVbwSeksAAA==" +} +``` + +*** +### 7a: export signed psbt to environment variable +Linux/Terminal: +:arrow_forward: `export SIGNED_PSBT="Paste_PSBT_HERE"` + +Windows Powershell: +:large_orange_diamond: +` $env:PSBTSIGNED = "STRINGHERE"` +![](https://i.imgur.com/VJsl8zR.gif) + +*** +## Step 8: Broadcast Transaction +Linux/Terminal: +:arrow_forward: `bdk-cli wallet --wallet wallet_name --descriptor $my_descriptor broadcast --psbt $SIGNED_PSBT` + +Windows Powershell: +:large_orange_diamond: +` bdk-cli wallet --descriptor $env:my_descriptor broadcast --psbt $env:PSBTSIGNED` + +![](https://i.imgur.com/yQZZk0d.gif) + + +:+1: The output below confirms the command was successful. + +```shell +{ + "txid": "a0877b7ce91ea6d141ba63277673f5bdf0edfdd45f91a39ba1a1ace15f839b52" +} +``` + +- Verify transcation in the memory pool on testnet [Mempool-testnet!](https://mempool.space/testnet) + +:::tip +Run sync one more time and see that the balance has decreased. +::: + +*** + +## Resources +- [BIP-32: Hierarchical Deterministic Wallets](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) +- [BIP: 39 - Mnemonic code for generating deterministic keys](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) +- [BIP: 44 - Multi-Account Hierarchy for Deterministic Wallets](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) +- [BIP: 84 - Derivation scheme for P2WPKH based accounts](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki) +- [BIP: 174 - Partially Signed Bitcoin Transaction Format](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) +- [What are Descriptors and miniscript?](https://blog.summerofbitcoin.org/miniscript-policy-descriptors-hidden-powers-of-bitcoin/) +- [Master Private Key and Extended Private Key](https://bitcoin.stackexchange.com/questions/97242/bip39-tool-bip32-extended-private-key-vs-bip32-root-key) +- [Minsc A Miniscript-based scripting language for Bitcoin contracts](https://min.sc) \ No newline at end of file