XState v5 Wallet Machine Example

This is a demonstration project showing how to use XState v5 to model a cryptocurrency wallet connection lifecycle.

Features

The WalletMachine demonstrates:

• Connection Management: Handle wallet connection/disconnection
• Hierarchical States: Parent connected state with child states for chain validation
• Guards: Conditional transitions using isChainSupported guard
• Actions & Context: Managing state data (wallet address, chain ID, balance)
• Actors/Invocations: Handling asynchronous operations (connect, fetch balance, switch chain)
• Global Transitions: SWITCH_CHAIN event can interrupt any child state

Project Structure

src/
  __tests__/
    utils.ts                  # Test utilities for state machine testing
  services/
    wallet/
      controllers/
        walletController.ts    # Mocked wallet business logic
  xstate/
    wallet/
      walletMachine.ts         # XState v5 state machine definition
      walletMachine.test.ts    # Comprehensive test suite
  index.ts                    # Main entry point with demonstration

Installation

npm install

Usage

Run the demonstration:

npm run dev

Or build and run:

npm run build
npm start

Testing

The project includes comprehensive tests using Vitest. The test suite uses a transition-based testing approach that tracks state transitions rather than relying on timeouts, making tests more reliable and maintainable.

Run tests:

npm test

Run tests in watch mode:

npm run test:watch

Test Structure

Tests are located in src/xstate/wallet/walletMachine.test.ts and cover:

• State Transitions: Verifying correct state transitions for all events
• Hierarchical States: Testing nested states within the connected parent state
• Global Transitions: Testing that SWITCH_CHAIN can interrupt any child state
• Error Handling: Testing error states and recovery
• Context Updates: Verifying that context (address, chainId, balance) is updated correctly

The test utilities in src/__tests__/utils.ts provide helpers for:

• Creating and tracking state machine actors
• Managing controllable promises for async operations
• Extracting nested state values

State Machine Overview

States

• disconnected: Initial state, wallet not connected
• connecting: Asynchronously connecting to wallet
• connected: Wallet connected (parent state)
  • checkingChain: Validating if chain is supported
  • chainReady: Chain is supported, ready for operations
  • unsupportedChain: Chain is not supported
  • fetchingBalance: Fetching wallet balance
  • switchingChain: Switching to a different chain
• error: Error state accessible from any async operation

Events

• CONNECT: Connect wallet with address
• DISCONNECT: Disconnect wallet
• FETCH_BALANCE: Fetch wallet balance
• SWITCH_CHAIN: Switch to a different chain (global transition)
• RETRY: Retry from error state

Key Concepts Demonstrated

1. Hierarchical States: The connected state contains child states
2. Guards: isChainSupported guard determines chain validation
3. Global Transitions: SWITCH_CHAIN at the connected level can interrupt any child state
4. Async Operations: Using fromPromise actors for async wallet operations
5. Context Management: Storing wallet address, chain ID, balance, and errors