feat: add 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

@@ -42,7 +42,7 @@ For a lightweight library providing stateless utility functions, see [`bitcoinjs
 ## Browser Usage
 
 ```sh
-yarn add bdk
+yarn add bitcoindevkit
 ```
 
 ## Notes on WASM Specific Considerations

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,
+    },
+};