Miden Web Wallet

- Unauthenticated Notes
- Indexing Transactions

Quickstart

The Miden Typescript SDK is the easiest way to interact with the Miden blockchain. The SDK handles everything from account creation, creating and consuming notes, signing and sending transactions. The quickstart covers client interactions such as creating accounts, creating tokens, sending tokens and consuming notes.

Getting Started

Install the sdk via a package manager

npm install @demox-labs/miden-sdk

Working with the SDK

The web client uses WASM bindings with the Rust client and the IndexedDB for storage of things like account headers, block headers, notes etc. in a complex way to interact with the Miden blockchain. The client does not run on the main thread but rather on a worker thread which offloads the computationally heavy tasks. For more detail on this you can read web-client-methods-worker.js

The web SDK abstracts away the underlying complexity, so you can get started quickly with a straightforward interface. Here is how you can begin:

interact.ts

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC

async function fnThatUsesClient(){
    // dynamic import the sdk as this runs the wasm worker
    const { WebClient } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);

    // now you can interact with the client
    // for example finding the latest block number you can do
    const syncSummary = await client.syncState();
    console.log(syncSummary.blockNum())

    // terminate the client when done
    client.terminate();
}

A few points to keep in mind while using the client:

Always import @demox-labs/miden-sdk dynamically to ensure the worker and WASM are initialized properly.
Terminate the client when you are done with your interactions. This is important as the garbage collector will not terminate the worker thread automatically.
Whenever client.submitTransaction is called, the local prover is used. This may not be suitable for browser environments with limited resources. Consider using a remote prover like done in the examples below.

Accounts

Accounts on Miden are a complex entity but for user-facing apps they are nothing more than a simple address. Like Ethereum EOAs, they are capable of holding assets but can also store data and execute custom code.

The web SDK provides a simple interface to manage these accounts, creating accounts and fetching accounts:

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC

async function createAccount() {
    // imports and init the client
    const { 
        WebClient, 
        AccountStorageMode 
    } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);

    // create a new private account
    const newAccount = await client.newWallet(
        AccountStorageMode.private(), 
        true // account is mutable i.e it can change its state 
    )

    console.log("New account created with address:", newAccount.id().toBech32());

    // you can store the account in local storage to fetch it 
    // later when we need to retreive the account for things like balances etc.
    localStorage.setItem("account_id", newAccount.id().toBech32());

    // terminate the client when done
    client.terminate();
}

Tokens

Tokens or assets are digital units of value that can be transferred between accounts. On Miden, token transfers are handled through notes. Notes are pretty much similar to currencies like euros, dollars: in every transaction, you either spend dollars (sending notes) or receive dollars (receiving notes). Also, new bills/notes can be issued to you from the banks (minting). Additionally, the assets can be fungible, for example ERC20 tokens, or non-fungible like NFTs.

In the following sections you will see how easy it is to work with faucets, assets, creating notes, and consuming notes through the SDK.

Minting Tokens

The minting of tokens is handled by a special type of account called a faucet account. These faucets create notes that can be consumed by the receiver. The faucet ID or the account ID for the faucet account can be thought of as the token address for the asset. The code for creating faucet accounts and fetching faucet accounts via the SDK:

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC

async function createFaucet() {
    // imports and init the client
    const { 
        WebClient, 
        AccountStorageMode 
    } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);

    // create a new asset and the faucet account
    const fungibleFaucetAccount = await client.newFaucet(
        AccountStorageMode.public(), // public faucet
        false, // immutable
        "MID", // token symbol
        8, // decimals
        BigInt(1_000_000), // max supply
    );
    const fungibleFaucetId = fungibleFaucetAccount.id().toBech32();
    console.log("Fungible faucet created with address:", fungibleFaucetId);

    await client.syncState(); // sync the state
    // you can store the faucet account in local storage 
    // to fetch it later when we need to retreive the faucet id
    localStorage.setItem("faucet_id", fungibleFaucetAccount.id().toBech32());
    
    // terminate the client when done
    client.terminate();
}

Consuming Notes

The consuming of public notes is pretty straightforward, but for private notes you would have to get the serialized NoteFile via the client.exportNote(noteId) method and send those bytes via some communication channel (for example our app uses WebRTC) and then import them via client.importNote(noteBytes). The code below consumes all the notes found by the client, both public and private:

consume.ts

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC
export const TX_PROVER_ENDPOINT = 'https://tx-prover.testnet.miden.io';

async function consumeTokens() {
    // run setup to get the client, sender, receiver and fungibleFaucetAccount
    const {
        WebClient,
        AccountId,
        TransactionProver,
    } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);
    const prover = TransactionProver.newRemoteProver(TX_PROVER_ENDPOINT);

    // fetch the account from local storage
    const accountId = AccountId.fromBech32(localStorage.getItem("account_id")!);
    const consumableNotes = await client.getConsumableNotes();

    // if no consumable notes are found, return
    if (consumableNotes.length === 0) {
        console.log("No pending balance to consume");
        return;
    }

    // get all the noteIds and create a consume transaction request
    const noteIds = consumableNotes.map(
        (note: any) => note.inputNoteRecord().id().toString()
    );
    const consumeTxRequest = client.newConsumeTransactionRequest(noteIds)

    const txResult = await client.newTransaction(accountId, consumeTxRequest)
    const txId = txResult.executedTransaction().id().toHex()
    await client.submitTransaction(txResult, prover)

    console.log("Consumed notes successfully with transaction id:", txId);
    
    // terminate the client when done
    client.terminate();
}

Sending Tokens

Sending tokens is pretty simple in the SDK:

send.ts

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC
export const TX_PROVER_ENDPOINT = 'https://tx-prover.testnet.miden.io';

async function sendTokens(
    to: string,
    amount: bigint, // assuming amount is in base denom
    isPrivate: boolean = false,
) {
    // imports and init the client and prover
    const {
        WebClient,
        AccountId,
        TransactionProver,
        NoteType
    } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);
    const prover = TransactionProver.newRemoteProver(TX_PROVER_ENDPOINT);

    // setup send transaction params
    const noteType = isPrivate ? NoteType.Private : NoteType.Public;
    const faucet_id = AccountId.fromBech32(
        localStorage.getItem("faucet_id")! 
    );
    const accountId = AccountId.fromBech32(
        localStorage.getItem("account_id")! 
    );
    const toAccountId = to.startsWith("0x") ? 
        AccountId.fromHex(to) : 
        AccountId.fromBech32(to);

    const sendTxRequest = client.newSendTransactionRequest(
        accountId,
        toAccountId,
        FAUCET_ID,
        noteType,
        amount
    )

    const txResult = await client.newTransaction(accountId, sendTxRequest);
    const txId = txResult.executedTransaction().id().toHex()
    await client.submitTransaction(txResult, prover);

    console.log("Send transaction submitted with id:", txId);
    
    // terminate the client when done
    client.terminate();
}

You're all set!

With these examples, you should be able to get started building powerful applications on Miden using the TypeScript SDK. For more advanced topics and detailed documentation, check out the Miden book. The section below covers some of the primitives used in this browser wallet.

Concepts

For greater detail on Miden protocol primitives you can refer to the Protocol Section of the Miden Book.

Unauthenticated Notes

Unauthenticated Notes allow consumption of Notes that are not fully committed yet. This means that both the creation and consumption of notes can happen in the same block, allowing for sub-block time settlements. There has to be a side channel for communication of note bytes generated by your application, which is quite simple to set up and is a good tradeoff for the speedup that you get.

mint.ts

const RPC_ENDPOINT = "https://rpc.testnet.miden.io:443"; // testnet RPC

async function unauthNotesExample(
    to: string,
    from: string,
    faucetId: string,
    amount: bigint, // assuming amount is in base denom 
    isPrivate: boolean = false,
) {
    // imports and init the client
    const { 
        WebClient, 
        AccountId,
        Note,
        NoteType,
        NoteExecutionMode,
        NoteAssets,
        NoteAndArgsArray,
        NoteAndArgs,
        OutputNote,
        FungibleAsset,
        OutputNotesArray,
        TransactionProver,
        TransactionRequestBuilder,
        Word,
        Felt
    } = await import("@demox-labs/miden-sdk");
    const client = await WebClient.createClient(RPC_ENDPOINT);
    const prover = TransactionProver.newRemoteProver(TX_PROVER_ENDPOINT);

    // make AccountId from bech32
    const toAccountId = AccountId.fromBech32(to);
    const fromAccountId = AccountId.fromBech32(from);
    const faucetAccountId = AccountId.fromBech32(faucetId);

    const noteType = isPrivate ? NoteType.Private : NoteType.Public;
    const noteAssets = new NoteAssets([
        new FungibleAsset(faucetAccountId, amount)
    ])
    const randomNums = crypto.getRandomValues(new Uint32Array(4));
    const serialNum = Word.newFromFelts([
        new Felt(BigInt(randomNums[0])),
        new Felt(BigInt(randomNums[1])),
        new Felt(BigInt(randomNums[2])),
        new Felt(BigInt(randomNums[3]))
    ]);
    const p2idNote = Note.createP2IDNote(
        accountId,
        toAccountId,
        noteAssets,
        noteType,
        serialNum,
        new Felt(BigInt(0))
    );

    const outputP2ID = OutputNote.full(p2idNote);
    let sendTxRequest = new TransactionRequestBuilder()
        .withOwnOutputNotes(new OutputNotesArray([outputP2ID]))
        .build()
        
    await client.submitTransaction(txResult, prover);

    // now you can send the note via a side channel
    // example: this wallet sends it via webrtc
    // consmuption of unauthenticated notes

    const noteAndArgs = new NoteAndArgs(p2idNote, null);
    
    const consumeRequest = new TransactionRequestBuilder()
      .withUnauthenticatedInputNotes(new NoteAndArgsArray([noteAndArgs]))
      .build();

    const consumeTransaction = await client.newTransaction(
      receiver.id(),
      consumeRequest,
    );

    await client.submitTransaction(consumeTransaction, prover); 

    // terminate the client when done
    client.terminate();
}

Indexing Transactions

Indexing transactions is a way to get the transaction data from the blockchain. This is useful for things like displaying transaction history, getting account balances etc. The RPC provides the functionality to get updates for interested accounts. You can do this in Rust via:

indexer.rs

use miden_client::rpc::{TonicRpcClient, Endpoint};
use std::collections::BTreeSet;


async fn index_transactions() {
    let endpoint = Endpoint::testnet();
    let rpc: TonicRpcClient = TonicRpcClient::new(&endpoint, 100_000);

    // create a vector of account ids to be tracked
    let accounts_to_be_tracked = vec![];

    // add note tags to be tracked
    let btree_set = BtreeSet::new();

    let mut last_sync_block = 0;

    loop {
        // the sync result returns the
        // `SyncStateInfo` struct which has the transactions and note inclusions
        let sync_reuslt = rpc
            .sync_state(
                last_sync_block.into(),
                &accounts_to_be_tracked,
                &btree_set,
            )
            .await
            .expect("Sync failed");
        last_sync_block = sync_result.chain_tip.as_u32();

        // update the db here
        // update_db_with_sync_result(sync_result).await; 

        println!("Transactions {:?}", sync_result.transactions);
        println!("Notes {:?}", sync_result.note_inclusions);
    }

}

Use Case

In the quickstart, you learned how to mint, send, and receive tokens. While these may seem like basic operations, combining them with Unauthenticated Notes enables sub-block time payment settlement. As the protocol becomes faster, this will allow for near-instant payment settlements, resulting in smoother user experiences in scenarios such as:

Microtransactions or micropayments which are useful for in-game purchases, pay for content like TV show episodes, and other scenarios where small payments are frequent like tipping.
Enable x402 in a verifiable privacy-preserving way or pay-per-API call usage which is pretty useful in things like AI credits etc.
This one goes without saying but instant global privacy-preserving verifiable cheap payments can be made possible.