From: BitcoinZavior Date: Sun, 28 Aug 2022 23:31:54 +0000 (-0400) Subject: draft bdk-rn tutorial X-Git-Url: http://internal-gitweb-vhost/script/%22https:/struct.EncoderStringWriter.html?a=commitdiff_plain;h=654a0da7b4477a28fbe32c0d8e651aed263d224f;p=bitcoindevkit.org draft bdk-rn tutorial --- diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index cdebf6c271..4c0336698e 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -53,7 +53,8 @@ const tutorialSidebar = [ '/tutorials/descriptors_in_the_wild', '/tutorials/hidden-power-of-bitcoin', '/tutorials/descriptor_based_paper_wallet', - '/tutorials/spending_policy_demo' + '/tutorials/spending_policy_demo', + '/tutorials/exploring_bdk_rn', ], } ] diff --git a/docs/tutorials/exploring_bdk_rn.md b/docs/tutorials/exploring_bdk_rn.md new file mode 100644 index 0000000000..f9ed578fe3 --- /dev/null +++ b/docs/tutorials/exploring_bdk_rn.md @@ -0,0 +1,507 @@ +--- +title: "BDK-RN: Building React Native Apps with BDK" +description: "A guide to using bdk-rn for building bitcoin apps" +authors: + - Bitcoin Zavior +date: "2022-08-05" +tags: ["bdk-rn", "bdk", "tutorial", "guide", "wallet"] +--- + +## Introduction + +// TODO: Improve context at start + +The wallet we create will be a non custodial HD Wallet, the app will be able to create a new wallet or restore from a known mnemonic seed phrase. Creating new addresses, syncing all UTXOs from a bitcoin node to get balance and send bitcoin. Figure 1. is our end goal. +The tutorial will focus on bitcoin and bdk-rn concepts and api and will gloss over react native related aspects. +All the code for this tutorial is available on Github at https://github.com/LtbLightning/AwesomeBitcoinApp + +Figure 1. is our end goal, an app that interacts with the bitcoin network manages keys and utxos, and synchs utxos from new blocks and broadcasts tansactioins. + + + +// TODO: replace with image based on the respository , ensure buttons are in the same order and section styles are the same as the repository + +BDK RN Quick Start + +### Prerequisites + +In order ot use bdk-rn in a React Native app a React Native development environment is required. Please refer to resources out there on the internet if you need to set this, here is one of many good resources to guide you https://reactnative.dev/docs/environment-setup + +### Bitcoin Basics + +The bitcoin concepts used in this blog post are detailed and explained very well in external bitcoin resources here are some links for reference: + +Mastering Bitcoin(HD Wallet chapter): https://www.oreilly.com/library/view/mastering-bitcoin/9781491902639/ch04.html +Bitcoin Output Descriptors from bitocoin GitHub: https://github.com/bitcoin/bitcoin/blob/master/doc/descriptors.md + +Now lets jumpt into Bitcoin Dev Kit 🪂 + +## Bitcoin Dev Kit and bdk-rn + +`bdk-rn` is a React Native library of Bitcoin Dev Kit(BDK) for building React Native Apps. +It encapsulates all of the low level api and methods for BDK and exposes them in a react native context. To use BDK in React Native(RN) apps only `bdk-rn` module is required. `Bdk-rn` can be used like any other react native library and is available in public package managers. + +## Getting Started + +Although we wont delve deep into RN we will focus more on bitcoin and bdk-rn, however some rudimentary RN setup is required, especially a basic RN app to add our bitocoin code. + +Lets start by creating a new RN project. + +`npx react-native init AwesomeBitcoinApp` + +If this fails end is error on an M1 Mac please use + `arch -x86_64 pod install --repo-update` + +Once done lets `cd` into the new project and run the basic RN app thats created + +```shell +cd AwesomeBitcoinApp +yarn ios +``` + +This should start building the app and then launch the app in an ios simulator. So far we have created a basic RN project if this doesn't work then refer to the react native development setup guide to troubleshoot. + + + + + +## Setting up styles and RN app structure + +Lets setup a very basic app structure and some RN scaffolding. Lets create a `src` folder in the project root and then add new folders for `assets`, `elements`, `screens` and `styles` + +To make this quick you can download the styles and images used in the tutorial from the repository. The image assets, `Button.tsx` and `styles.js` can be take from https://github.com/LtbLightning/AwesomeBitcoinApp/tree/master/src and moved the folders as shown. Alternatively you can write your own styles and use your own images if you intend to style the app in a different way. + +Lets create a `home.js` file under screens, this will be where we will be adding most of our code. + +Once done the file structure should look like Figure 3. + + + + + +Locate `App.js` in the project root, this will have the default code adde by react-native init, lets delete all contents of `App.js` and replace with code to import `home.js` as our main screen. + +```javascript +// App.js + +import React from 'react'; +import Home from './src/screens/home'; + +const App = () => { + return ; +}; + +export default App; + +``` + +This will probably crash your app in the simulator but thats fine, it will be fixed in the next step. + +## Installing `bdk-rn` + +With the RN app project in place, we can now add `bdk-rn` using either npm or yarn. + +Using npm: + +```shell +npm i --save bdk-rn +``` + +Using yarn: + +```shell +yarn add bdk-rn +``` + +[IOS Only] Install pods: + +```shell +npx pod-install +or +cd ios && pod install && cd .. +``` + +Verify that `bdk-rn` has been added to `package.json`, once done `bdk-rn` is installed and ready to be used in our **AwesomeBitcoinApp** + +## Importing `bdk-rn` + +Locate home.js which we added in the setup section and import bdk-rn and also create a RN functional component. + +```javascript +// screens/home.js + +import BdkRn from 'bdk-rn'; + +const Home = () => { +} + +export default Home; + +``` + + +Before we start using `bdk-rn` lets add some additional RN component imports, as well as importing styles, button and image assets to create a basic layout to build our home screen + +```jsx +// screens/home.js + +import BdkRn from 'bdk-rn'; +import React, { Fragment, useState } from 'react'; +import { + ActivityIndicator, + SafeAreaView, + ScrollView, + StatusBar, + Text, + TextInput, + View, + Image, +} from 'react-native'; +import Button from '../elements/Button'; +import { styles } from '../styles/styles'; +const bitcoinLogo = require('../assets/bitcoin_logo.png'); +const bdkLogo = require('../assets/bdk_logo.png'); + +const Home = () => { + // BDK-RN method calls and state variables will be added here + + return ( + + + + {/* Header */} + + + BDK-RN Tutorial + + + + {/* Balance */} + + {/* method call result */} + + {/* buttons for method calls */} + + {/* input boxes and send transaction button */} + + + + ); +}; + +export default Home; + +``` + + +We now have a app title section and a structure to hold the rest of our app components. + + + +## Calling bdk-rn methods + +All `bdk-rn` methods return a json response with a data and error**All methods return response as follows:** + +```javascript +Promise = { + error: true | false; // success returns true else false. + data: string | object | any; // output data for the method call. +} +``` + +The first step in creating a non custodial bitcoin app is creating a mnemonic seed phrase for the wallet. + +`bdk-rn` provides `generateMnemonic()` method to create a default 12 word length mnemonic. + +```javascript +import BdkRn from 'bdk-rn'; + +const response = await BdkRn.generateMnemonic(); +const mnemonic = response.data; +``` + +We can specify a longer length or we can also specify the bits of entropy we need by passing the length or entropy arguments. + +To create a mnemonic with an entropy of 256 bits which will be a 24 word length mnemonic sentence we can use. +Refer to readme on Github: https://github.com/LtbLightning/bdk-rn#generatemnemomic + +```javascript +const {data: mnemonic} = await BdkRn.generateMnemonic({ entropy: 256 }); +// here data is destructured and saved as 'mnemonic' +``` + +In order ot use this in our RN app lets create a state variable to store the mnemonic and internal `generateMnemonic` method which we can invoke when a button is clicked. We will also need a button which will invoke generateMnemonic when clicked. Adding the following code achieves all of this. + +```jsx +// screens/home.js + +const Home = () => { + // BDK-RN method calls and state variables will be added here + // state variable to store and set mnemonic + const [mnemonic, setMnemonic] = useState(''); + + // internal method to call bdk-rn to generate mnemonic + const getMnemonic = async () => { + // call bdk-rn to generate mnemonic + const {data} = await BdkRn.generateMnemonic({ + length: 12 + }); + // save generated mnemonic to state variable + setMnemonic(data); + }; + +return ( + + + + {/* Header */} + + + BDK-RN Tutorial + + + + {/* Balance */} + + {/* method call result */} + + {/* buttons for method calls */} + +