Feature/example app

.cargo/config.toml

@@ -0,0 +1,3 @@
+[env]
+AR = "/opt/homebrew/opt/llvm/bin/llvm-ar"
+CC = "/opt/homebrew/opt/llvm/bin/clang"

.gitignore

@@ -1,9 +1,7 @@
 /target
 **/*.rs.bk
-/.vscode
 .idea
 *.swp
-.cargo
 .npmrc
 
 bin/

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "rust-analyzer.server.extraEnv": {
+        "AR": "/opt/homebrew/opt/llvm/bin/llvm-ar",
+        "CC": "/opt/homebrew/opt/llvm/bin/clang"
+    },
+    "rust-analyzer.cargo.target": "wasm32-unknown-unknown"
+}

README.md

@@ -4,7 +4,7 @@
   <img src="./static/bdk.png" width="220" />
 
   <p>
-    <strong>The Bitcoin Dev Kit for Browsers and Node</strong>
+    <strong>The Bitcoin Dev Kit for Browsers, Node, and React Native</strong>
   </p>
 
   <p>
@@ -42,9 +42,32 @@ For a lightweight library providing stateless utility functions, see [`bitcoinjs
 ## Browser Usage
 
 ```sh
-yarn add bdk
+yarn add bitcoindevkit
 ```
 
+## Notes on WASM Specific Considerations
+
+> ⚠️ **Important:** There are several limitations to using BDK in WASM. Basically any functionality that requires OS access is not directly available in WASM and must therefore be handled in JavaScript. However, there are viable workarounds documented below. Some key limitations include:
+>
+> - No access to the file system
+> - No access to the system time
+> - Network access is limited to http(s)
+
+## WASM Considerations Overview
+
+### No access to the file system
+With no direct access to the file system, persistence cannot be handled by BDK directly. Instead, an in memory wallet must be used in the WASM environment, and the data must be exported using `wallet.take_staged()`. This will export the changeset for the updates to the wallet state, which must then be merged with current wallet state in JS (will depend on your persistence strategy). When you restart your app, you can feed your persisted wallet data to `wallet.load()` to recover the wallet state.
+
+### No access to the system time
+Any function that requires system time, such as any sort of timestamp, must access system time through a wasm binding to the JavaScript environment. However, in the case of `wallet.apply_update()`, this is being handled behind the scenes. If it weren't you'd have to use `wallet.apply_update_at()` instead. But it's worth keeping this limitation in mind in case you do hit an error related to system time access limitations.
+
+### Network access is limited to http(s)
+This effectively means that the blockchain client must be an Esplora instance. Both RPC and Electrum clients require sockets and will not work for BDK in a WASM environment out of the box.
+
+### Troubleshooting
+WASM errors can be quite cryptic, so it's important to understand the limitations of the WASM environment. One common error you might see while running a BDK function through a WASM binding in the browser is `unreachable`. This indicates you're trying to access OS level functionality through rust that isn't available in WASM.
+
+
 ## Development Environment
 
 ### Requirements

examples/browser/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+
+package-lock.json

examples/browser/.tool-versions

@@ -0,0 +1 @@
+nodejs 20.9.0

examples/browser/README.md

@@ -0,0 +1,27 @@
+# WASM App Example
+
+## Server app to test a WASM package
+
+`npm install`
+`npm start`
+
+open browser to http://localhost:8080/
+open browser console to see scan rusults
+
+
+## Build WASM package
+
+By default the example will pull the bitcoindevkit package from npm.
+However, if you want to pull from the local package (say for development) modify the dependency in the index.js file, and build:
+
+From parent folder (the wasm-package):
+`wasm-pack build --features esplora`
+
+### Mac Users
+
+Note: to build successfully on mac required installing llvm with homebrew (even though there's a default version) https://github.com/bitcoindevkit/bdk/issues/1671#issuecomment-2456858895
+And properly pointing to it in which is being done in .cargo and .vscode folders
+
+### Non-Mac Users
+
+You may need to delete the .cargo and .vscode folders, our point them to the appropriate llvm version.

examples/browser/index.js

@@ -0,0 +1,93 @@
+import {  Wallet, EsploraClient, ChangeSet } from 'bitcoindevkit';// pull from npm
+// import {  Wallet, EsploraClient, ChangeSet } from 'bdk';//pulling from local package
+
+// simple string storage example
+const Store = {
+    save: data => {
+        if (!data) {
+            console.log("No data to save");
+            return;
+        }
+        localStorage.setItem("walletData", data);  // data is already a JSON string
+    },
+    load: () => {
+        return localStorage.getItem("walletData");  // return the JSON string directly
+    }
+}
+
+const externalDescriptor = "tr([12071a7c/86'/1'/0']tpubDCaLkqfh67Qr7ZuRrUNrCYQ54sMjHfsJ4yQSGb3aBr1yqt3yXpamRBUwnGSnyNnxQYu7rqeBiPfw3mjBcFNX4ky2vhjj9bDrGstkfUbLB9T/0/*)#z3x5097m";
+const internalDescriptor = "tr([12071a7c/86'/1'/0']tpubDCaLkqfh67Qr7ZuRrUNrCYQ54sMjHfsJ4yQSGb3aBr1yqt3yXpamRBUwnGSnyNnxQYu7rqeBiPfw3mjBcFNX4ky2vhjj9bDrGstkfUbLB9T/1/*)#n9r4jswr";
+
+async function run() {    
+    let walletDataString = Store.load();
+    console.log("Wallet data:", walletDataString);
+
+    let wallet;
+    let client = new EsploraClient("https://mutinynet.com/api");
+    if (!walletDataString) {
+        console.log("Creating new wallet");
+        wallet = Wallet.create(
+            "signet",
+            externalDescriptor,
+            internalDescriptor
+        );
+
+        console.log("Performing Full Scan...");
+        let full_scan_request = wallet.start_full_scan();
+        let update = await client.full_scan(full_scan_request, 1);
+        wallet.apply_update(update);
+
+        const stagedDataString = wallet.take_staged().to_json();
+        console.log("Staged:", stagedDataString);
+
+        Store.save(stagedDataString);
+        console.log("Wallet data saved to local storage");
+        walletDataString = stagedDataString;
+    } else {
+        console.log("Loading wallet");
+        let changeSet = ChangeSet.from_json(walletDataString);
+        wallet = Wallet.load(
+            changeSet,
+            externalDescriptor,
+            internalDescriptor
+        );
+
+        console.log("Syncing...");
+        let sync_request = wallet.start_sync_with_revealed_spks();
+        let update = await client.sync(sync_request, 1);
+        wallet.apply_update(update);
+
+        const updateChangeSet = wallet.take_staged();
+        if (updateChangeSet) {
+            console.log("Update:", updateChangeSet.to_json());
+            let currentChangeSet = ChangeSet.from_json(walletDataString);
+            console.log("Current:", currentChangeSet.to_json());
+            currentChangeSet.merge(updateChangeSet);
+            console.log("Merged:", currentChangeSet.to_json());
+            Store.save(currentChangeSet.to_json());
+        }
+    }
+
+    // Test balance
+    console.log("Balance:", wallet.balance().confirmed.to_sat());
+
+    // Test address generation
+    console.log("New address:", wallet.reveal_next_address().address);
+
+
+    // handle merging
+    walletDataString = Store.load();
+    const updateChangeSet = wallet.take_staged();
+    console.log("Update:", updateChangeSet.to_json());
+    let currentChangeSet = ChangeSet.from_json(walletDataString);
+    console.log("Current:", currentChangeSet.to_json());
+    currentChangeSet.merge(updateChangeSet);
+    console.log("Merged:", currentChangeSet.to_json());
+    Store.save(currentChangeSet.to_json());
+    console.log("new address saved");
+}
+
+run().catch(console.error);
+
+// to clear local storage:
+// localStorage.removeItem("walletData");

examples/browser/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "example-bdk-wasm",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "start": "npx webpack serve --mode development",
+    "build": "npx webpack --mode production",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "devDependencies": {
+    "webpack": "^5.96.1",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.1.0"
+  },
+  "dependencies": {
+    "bdk": "file:../../pkg",
+    "bitcoindevkit": "^0.1.3"
+  }
+}

examples/browser/public/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <title>BDK WASM Test</title>
+  </head>
+  <body>
+    <h1>BDK-WASM Test</h1>
+    <p>Open the console to see the output.</p>
+    <script src="bundle.js"></script>
+  </body>
+</html>

examples/browser/webpack.config.js

@@ -0,0 +1,20 @@
+const path = require('path');
+
+module.exports = {
+    entry: './index.js',
+    output: {
+        path: path.resolve(__dirname, 'public'),
+        filename: 'bundle.js',
+    },
+    mode: 'development',
+    experiments: {
+        asyncWebAssembly: true,
+    },
+    devServer: {
+        static: {
+            directory: path.join(__dirname, 'public'),
+        },
+        compress: true,
+        port: 8080,
+    },
+};