@demox-labs/miden-sdk

Overview

The @demox-labs/miden-sdk is a comprehensive software development toolkit (SDK) for interacting with the Miden blockchain and virtual machine from within a web application. It provides developers with everything needed to:

• Interact with the Miden chain (e.g. syncing accounts, submitting transactions)
• Create and manage Miden transactions
• Run the Miden VM to execute programs
• Generate zero-knowledge proofs using the Miden Prover (with support for delegated proving)
• Integrate Miden capabilities seamlessly into browser-based environments

Whether you're building a wallet, dApp, or other blockchain-integrated application, this SDK provides the core functionality to bridge your frontend with Miden's powerful ZK architecture.

Note: This README provides a high-level overview of the web client SDK. For more detailed documentation, API references, and usage examples, see the documentation here (TBD).

SDK Structure and Build Process

This SDK is published as an NPM package, built from the web-client crate. The web-client crate is a Rust crate targeting WebAssembly (WASM), and it uses wasm-bindgen to generate JavaScript bindings. It depends on the lower-level rust-client crate, which implements the core functionality for interacting with the Miden chain.

Both a Cargo.toml and a package.json are present in the web-client directory to support Rust compilation and NPM packaging respectively.

The build process is powered by a custom rollup.config.js file, which orchestrates three main steps:

1. WASM Module Build: Compiles the web-client Rust crate into a WASM module using @wasm-tool/rollup-plugin-rust, enabling WebAssembly features such as atomics and bulk memory operations.

2. Worker Build: Bundles a dedicated web worker file that enables off-main-thread execution for computationally intensive functions.

3. Main Entry Point Build: Bundles the top-level JavaScript module (index.js) which serves as the main API surface for consumers of the SDK. This module also imports wasm.js, which provides a function to load the wasm module in an async way. Since there's a known issue with vite, there's a check to avoid loading the wasm module when SSR is enabled.

This setup allows the SDK to be seamlessly consumed in JavaScript environments, particularly in web applications.

Installation

Stable Version

A non-stable version of the SDK is also maintained, which tracks the next branch of the Miden client repository (essentially the development branch). To install the pre-release version, run:

npm i @demox-labs/miden-sdk

Or using Yarn:

yarn add @demox-labs/miden-sdk

Pre-release ("next") Version

A non-stable version is also maintained. To install the pre-release version, run:

npm i @demox-labs/miden-sdk@next

Or with Yarn:

yarn add @demox-labs/miden-sdk@next

Note: The next version of the SDK must be used in conjunction with a locally running Miden node built from the next branch of the miden-node repository. This is necessary because the public testnet runs the stable main branch, which may not be compatible with the latest development features in next. Instructions to run a local node can be found here on the next branch of the miden-node repository. Additionally, if you plan to leverage delegated proving in your application, you may need to run a local prover (see Remote prover instructions).

Building and Testing the Web Client

If you're interested in contributing to the web client and need to build it locally, you can do so via:

yarn install
yarn build

This will:

• Install all JavaScript dependencies,
• Compile the Rust code to WebAssembly,
• Generate the JavaScript bindings via wasm-bindgen,
• And bundle the SDK into the dist/ directory using Rollup.

To run integration tests after building, use:

yarn test

This runs a suite of integration tests to verify the SDK’s functionality in a web context.

Building the npm package

Follow the steps below to produce the contents that get published to npm (dist/ plus the license file). All commands are executed from crates/web-client.

1. Install prerequisites
   • Install the Rust toolchain version specified in rust-toolchain.toml.
   • Install Node.js ≥18 and Yarn.
2. Install dependencies

   yarn install

   This installs both the JavaScript tooling and the @wasm-tool/rollup-plugin-rust dependency that compiles the Rust crate.
3. Build the package

   yarn build

   The build script (see package.json) performs the following:
   • Removes the previous dist/ directory (rimraf dist).
   • Runs npm run build-rust-client-js, which builds the idxdb-store TypeScript helper that the SDK imports.
   • Invokes Rollup with RUSTFLAGS="--cfg getrandom_backend=\"wasm_js\"" so the Rust getrandom crate targets browser entropy and so that atomics/bulk-memory WebAssembly features are enabled.
   • Copies the generated TypeScript declarations from js/types into dist/.
   • Executes node clean.js to strip paths from the generated .js files, leaving only the artifacts needed on npm.
4. Inspect the artifacts
   • dist/index.js is the ESM entry point referenced by "main"/"browser"/"exports".
   • dist/index.d.ts and the rest of the .d.ts files provide the TypeScript surface. Use npm pack if you want to preview the exact tarball that would be published.

Tip: during development you can set MIDEN_WEB_DEV=true before running yarn build (or run npm run build-dev) to skip the clean step and keep extra debugging metadata in the bundled output. This debugging metadata also includes debug symbols for the generated wasm binary

Usage

The following are just a few simple examples to get started. For more details, see the API Reference.

Create a New Wallet

import { AccountStorageMode, WebClient } from "@demox-labs/miden-sdk";

// Instantiate web client object
const webClient = await WebClient.createClient();

// Set up newWallet params
const accountStorageMode = AccountStorageMode.private();
const mutable = true;

// Create new wallet
const account = await webClient.newWallet(accountStorageMode, mutable);

console.log(account.id().toString()); // account id as hex
console.log(account.isPublic()); // false
console.log(account.isPrivate()); // true
console.log(account.isNetwork()); // false
console.log(account.isFaucet()); // false

Create and Execute a New Consume Transaction

Using https://faucet.testnet.miden.io/, send some public test tokens using the account id logged during the new wallet creation. Consume these tokens like this:

// Once the faucet finishes minting the tokens, you need to call syncState() so the client knows there is a note available to be consumed. In an actual application, this may need to be in a loop to constantly discover claimable notes.
await webClient.syncState();

// Query the client for consumable notes, and retrieve the id of the new note to be consumed
let consumableNotes = await webClient.getConsumableNotes(account);
const noteIdToConsume = consumableNotes[0].inputNoteRecord().id();

// Create a consume transaction request object
const consumeTransactionRequest = webClient.newConsumeTransactionRequest([
  noteIdToConsume,
]);

// Execute, prove, submit, and apply the transaction in one step
const transactionId = await webClient.submitNewTransaction(
  account,
  consumeTransactionRequest
);

// Need to sync state again (in a loop) until the node verifies the transaction
await syncState();

// Check new account balance
const updatedAccount = await webClient.getAccount(account);
const accountBalance = updatedAccount
  .vault()
  .getBalance(/* id of remote faucet */)
  .toString();
console.log(accountBalance);

License

This project is licensed under the MIT License - see the LICENSE file for details.