Overview

The Miden Wallet Adapter is a modular TypeScript library that provides wallet integration capabilities for Miden blockchain applications. It's designed to connect Miden-compatible wallets to decentralized applications (dApps) in a standardized way.

Usage Pattern

1. Setup: Wrap your app with WalletProvider and specify available wallet adapters
2. Connection: Use WalletMultiButton to connect or do so programmatically
3. Interaction: Use the useWallet hook to access wallet state and methods, such as the wallet's publicKey
4. Transactions: Use transaction types to submit a consume or send transaction via the wallet, or a generic transaction using a Miden TransactionRequest object

Connecting a wallet

const walletAdapter = new MidenWalletAdapter({ appName: 'Your Miden App', });
<WalletProvider wallets={[walletAdapter]}> // Defines which wallets are supported
    <WalletModalProvider>
        <>
            Your app code...
            <WalletMultiButton /> {/* Launches the WalletModal, prompts the user to connect their wallet */}
        <>
    </WalletModalProvider>
</WalletProvider>

Submitting a send transaction

const { wallet, publicKey } = useWallet();
const midenTransaction = new SendTransaction(
    publicKey,
    toAddress,
    faucetId,
    sharePrivately ? 'private' : 'public',
    amount!
);
await wallet.adapter.requestSend(midenTransaction);

Submitting a custom transaction

const { wallet, publicKey } = useWallet();
const customTransaction = new CustomTransaction(
    publicKey, // AccountId the transaction request will be executed against
    transactionRequest // TransactionRequest object (will need to be generated using the Miden Web SDK)
);
await wallet.adapter.requestTransaction(customTransaction)

Architecture & Structure

This repository contains three main packages:

1. Core Base Package (@demox-labs/miden-wallet-adapter-base)

• Purpose: Provides the foundational infrastructure and interfaces
• Key Components:
  • BaseWalletAdapter: Abstract base class that all wallet adapters must extend
  • WalletAdapter interface: Defines the contract for wallet adapters
  • Event system: Uses EventEmitter3 for wallet state changes (connect, disconnect, error, readyStateChange)
  • Type definitions: Network types (Testnet, Localnet), decrypt permissions, transaction types
  • Error handling: Comprehensive error classes for different failure scenarios

2. React Integration Package (@demox-labs/miden-wallet-adapter-react)

• Purpose: React-specific hooks and context providers
• Key Components:
  • WalletProvider: React context provider that manages wallet state
  • useWallet hook: Provides wallet state and methods to React components
  • Auto-connection: Handles automatic wallet reconnection on page load
  • Local storage: Persists wallet selection across sessions

3. UI Components Package (@demox-labs/miden-wallet-adapter-reactui)

• Purpose: Pre-built React UI components for wallet interaction
• Key Components:
  • WalletModal: Modal dialog for wallet selection and connection
  • WalletConnectButton: Button component for initiating wallet connection
  • WalletMultiButton: Multi-purpose button that handles connect/disconnect states
  • WalletListItem: Individual wallet option in the selection modal

Wallet Adapters

Miden Wallet Adapter (@demox-labs/miden-wallet-adapter-miden)

• Purpose: Specific implementation for the Miden Wallet
• Features:
  • Detection: Automatically detects if Miden Wallet is installed
  • Connection management: Handles wallet connection/disconnection
  • Transaction support: Supports Miden-specific transaction types:
    • MidenSendTransaction
    • MidenConsumeTransaction
    • Generic MidenTransaction
  • Permission management: Handles different decrypt permissions
  • Error handling: Comprehensive error handling for wallet operations