Skip to content

WASM Example

WASM bindings can be used to access rust code from virtually any JavaScript environment: browsers, Node.js, ReactNative, etc.

Info

This page details how to build a custom WASM package that uses BDK rust crate under the hood. If you want an out of the box solution for JS(WASM) bindings for BDK which don't require writing any rust code, see the WASM section on the 3rd Party Bindings page for a pre-packaged npm module.

Because rust can compile to WASM, it is possible to use BDK in the browser. However, there are a few limitations to keep in mind which will be highlighted in this example. That being said, there are perfectly viable work-arounds for these limitations that should suffice for most use cases.

Warning

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. 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 through a binding to the JavaScript environment to be persisted.

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. This means some BDK functions that are commonly used in rust won't work in WASM and instead an alternate rust function that takes a timestamp as an argument must be used (I.E. instead of .apply_update() we must use .apply_update_at()).

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 error likely will not point you to the actual BDK function that is causing the error. Instead you need to be able to assess whether you are calling a function that uses a rust feature that is unsupported in the WASM environment. For example, if you do a scan and then try to use .apply_update() you will get an unreachable error. This is because .apply_update() requires system time, which is not available in the WASM environment. Instead you need to use .apply_update_at() which takes an explicit timestamp as an argument (see below).

WASM App Example

In this example we will cover basic BDK functionality in a WASM environment. We will show code snippets for both the rust and JavaScript necessary to create a custom WASM package, and we will highlight the key differences from the plain rust examples (due to WASM limitations).

Info

The WASM example code is split into two project folders: a rust project that uses wasm-pack to compile rust code to WASM files, and a JavaScript project that pulls the WASM project as a dependency. The JS project represents the web app and the rust project is used to generate an npm module.

Initializing a Wallet

From JS running in our browser, first we need our descriptors:

1
2
const externalDescriptor = "tr([12071a7c/86'/1'/0']tpubDCaLkqfh67Qr7ZuRrUNrCYQ54sMjHfsJ4yQSGb3aBr1yqt3yXpamRBUwnGSnyNnxQYu7rqeBiPfw3mjBcFNX4ky2vhjj9bDrGstkfUbLB9T/0/*)#z3x5097m";
const internalDescriptor = "tr([12071a7c/86'/1'/0']tpubDCaLkqfh67Qr7ZuRrUNrCYQ54sMjHfsJ4yQSGb3aBr1yqt3yXpamRBUwnGSnyNnxQYu7rqeBiPfw3mjBcFNX4ky2vhjj9bDrGstkfUbLB9T/1/*)#n9r4jswr";

Then we can initialize the wallet, we'll use some conditional logic here to either 1) create a new wallet and perform a full scan, or 2) load a wallet from stored data and sync it to get recent updates.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
let walletDataString = Store.load();
console.log("Wallet data:", walletDataString);

let wallet;
if (!walletDataString) {
    console.log("Creating new wallet");
    wallet = new WalletWrapper(
        "signet",
        externalDescriptor,
        internalDescriptor,
        "https://mutinynet.com/api"
    );

    console.log("Performing Full Scan...");
    await wallet.scan(2);

    const stagedDataString = wallet.take_staged();
    console.log("Staged:", stagedDataString);

    Store.save(stagedDataString);
    console.log("Wallet data saved to local storage");
    walletDataString = stagedDataString;
} else {
    console.log("Loading wallet");
    wallet = WalletWrapper.load(
        walletDataString,
        "https://mutinynet.com/api",
        externalDescriptor,
        internalDescriptor
    );

    console.log("Syncing...");
    await wallet.sync(2);

    const stagedDataString = wallet.take_staged();
    console.log("Staged:", stagedDataString);

    Store.save(stagedDataString);
    console.log("Wallet data saved to local storage");
}

Network Consideration

Notice we are including blockchain client details in wallet initialization (Signet, and the esplora url). This is because we are forced to use esplora, so we may as well initialize the client at the same time as the wallet.

Here is the relevant rust code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
#[wasm_bindgen(constructor)]
pub fn new(
    network: String,
    external_descriptor: String,
    internal_descriptor: String,
    esplora_url: String,
) -> Result<WalletWrapper, String> {
    let network = match network.as_str() {
        "mainnet" => Network::Bitcoin,
        "testnet" => Network::Testnet,
        "testnet4" => Network::Testnet4,
        "signet" => Network::Signet,
        "regtest" => Network::Regtest,
        _ => return Err("Invalid network".into()),
    };

    let wallet_opt = Wallet::load()
        .descriptor(KeychainKind::External, Some(external_descriptor.clone()))
        .descriptor(KeychainKind::Internal, Some(internal_descriptor.clone()))
        .extract_keys()
        .check_network(network)
        .load_wallet_no_persist(ChangeSet::default())
        .map_err(|e| format!("{:?}", e))?;

    let wallet = match wallet_opt {
        Some(wallet) => wallet,
        None => Wallet::create(external_descriptor, internal_descriptor)
            .network(network)
            .create_wallet_no_persist()
            .map_err(|e| format!("{:?}", e))?,
    };

    let client = esplora_client::Builder::new(&esplora_url)
        .max_retries(6)
        .build_async_with_sleeper()
        .map_err(|e| format!("{:?}", e))?;

    Ok(WalletWrapper { wallet, client })
}

pub fn load(
    changeset_str: &str,
    url: &str,
    external_descriptor: &str,
    internal_descriptor: &str,
) -> JsResult<WalletWrapper> {
    let changeset_value: Value = serde_json::from_str(changeset_str)?;
    let changeset: ChangeSet = serde_json::from_value(changeset_value)?;

    let wallet_opt = Wallet::load()
        .descriptor(
            KeychainKind::External,
            Some(external_descriptor.to_string()),
        )
        .descriptor(
            KeychainKind::Internal,
            Some(internal_descriptor.to_string()),
        )
        .extract_keys()
        .load_wallet_no_persist(changeset)?;

    let wallet = match wallet_opt {
        Some(wallet) => wallet,
        None => return Err(JsError::new("Failed to load wallet, check the changeset")),
    };

    let client = esplora_client::Builder::new(&url).build_async_with_sleeper()?;

    Ok(WalletWrapper { wallet, client })
}

pub async fn scan(&mut self, stop_gap: usize) -> Result<(), String> {
    let wallet = &mut self.wallet;
    let client = &self.client;

    let request = wallet.start_full_scan();

    let update = client
        .full_scan(request, stop_gap, PARALLEL_REQUESTS)
        .await
        .map_err(|e| format!("{:?}", e))?;

    let now = (Date::now() / 1000.0) as u64;
    wallet
        .apply_update_at(update, now)
        .map_err(|e| format!("{:?}", e))?;

    Ok(())
}

pub async fn sync(&mut self, parallel_requests: usize) -> JsResult<()> {
    let request = self.wallet.start_sync_with_revealed_spks();
    let update = self.client.sync(request, parallel_requests).await?;

    let now = (Date::now() / 1000.0) as u64;
    self.wallet.apply_update_at(update, now)?;

    Ok(())
}

The first time you load the page in your browser, you should see info in the console confirming that a new wallet was created and a full scan was performed. If you then reload the page you should see that the wallet was loaded from the previously saved data and a sync was performed instead of a full scan.

System Time Consideration

Notice we are using a JS binding to access system time with js_sys::Date::now(), then passing that timestamp to the apply_update_at() function, rather than attempting to use the .apply_update() function which would throw an error.

Persistence Consideration

Also notice we are using an in-memory wallet with .create_wallet_no_persist(). If you try to use persistence through file or database you will get an error because those features require OS access. Instead we have to create a binding to pass the wallet data to the JavaScript environment where we can handle persistence. We have a method to grab the new updates to the wallet data, and a method to merge new updates with existing data. With this simple approach to persistence we must always merge existing data with the updates unless there is no existing data (i.e. after new wallet creation). The rust side methods to extract the wallet data are:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
pub fn take_staged(&mut self) -> JsResult<String> {
    match self.wallet.take_staged() {
        Some(changeset) => {
            let value = serde_json::to_value(&changeset)?;
            Ok(serde_json::to_string(&value)?)
        }
        None => Ok("null".to_string()),
    }
}

pub fn take_merged(&mut self, previous: String) -> JsResult<String> {
    match self.wallet.take_staged() {
        Some(curr_changeset) => {
            let previous_value: Value = serde_json::from_str(&previous)?;
            let mut previous_changeset: ChangeSet = serde_json::from_value(previous_value)?;
            previous_changeset.merge(curr_changeset);
            let final_value = serde_json::to_value(&previous_changeset)?;
            Ok(serde_json::to_string(&final_value)?)
        }
        None => Ok("null".to_string()),
    }
}

Notice we're converting the wallet data to a JSON string so that it plays nicely with WASM; and on the JS side we'll save our data string with a minimal custom browser store:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// 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
    }
}

This is just to show an example of how the wallet data can be persisted. We're using local storage here, but in practice a wallet app would generally use cloud storage of some sort since browser local storage tends to be temporary.

Balance and Addresses

We can now get the balance of our wallet and generate a new address. Here is the JS code:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
// Test balance
console.log("Balance:", wallet.balance());

// Test address generation
console.log("New address:", wallet.reveal_next_address());

// handle changeset merge on rust side
const mergedDataString = wallet.take_merged(walletDataString);

console.log("Merged:", mergedDataString);

Store.save(mergedDataString);
console.log("new address saved");

Here is the rust code that gets called:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
pub fn balance(&self) -> u64 {
    let balance = self.wallet.balance();
    balance.total().to_sat()
}

pub fn reveal_next_address(&mut self) -> String {
    let address = self.wallet.reveal_next_address(KeychainKind::External);

    address.to_string()
}

Notice we call take_merged() and Store.save() after generating a new address so our wallet keeps track of generated addresses (so we don't re-use them). If you reload the browser you can see the generated address value updated along with the index.