@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:
-
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.
-
Worker Build: Bundles a dedicated web worker file that enables off-main-thread execution for computationally intensive functions.
-
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.
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";
const webClient = await WebClient.createClient();
const accountStorageMode = AccountStorageMode.private();
const mutable = true;
const account = await webClient.newWallet(accountStorageMode, mutable);
console.log(account.id().toString());
console.log(account.isPublic());
console.log(account.isFaucet());
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:
await webClient.syncState();
let consumableNotes = await webClient.getConsumableNotes(account);
const noteIdToConsume = consumableNotes[0].inputNoteRecord().id();
const consumeTransactionRequest = webClient.newConsumeTransactionRequest([
noteIdToConsume,
]);
const consumeTransactionResult = await webClient.newTransaction(
account,
consumeTransactionRequest
);
await webClient.submitTransaction(consumeTransactionResult);
await syncState();
const accountBalance = account
.vault()
.getBalance()
.toString();
console.log(accountBalance);
License
This project is licensed under the MIT License - see the LICENSE file for details.