Account Balance Monitor

Build a real-time account balance monitor that tracks changes to a Solana account's balance and maintains a history of balance updates.

Requirements

Implement a monitoring service with the following capabilities:

1. Subscribe to Account Updates: Connect to a Solana cluster and subscribe to real-time updates for a specified account address.

2. Track Balance Changes: When the account is updated, extract the current lamport balance and store it along with a timestamp.

3. Maintain Update History: Keep a record of all balance updates received, including:

   • The lamport balance at each update
   • The timestamp when the update was received
   • The slot number of the update

4. Query Latest Balance: Provide a method to retrieve the most recent balance.

5. Query Balance History: Provide a method to retrieve the complete history of balance updates.

6. Graceful Shutdown: Properly clean up the subscription when monitoring is stopped.

Implementation Notes

• The monitor should work with any valid Solana account address
• Use the Solana devnet cluster for testing: wss://api.devnet.solana.com
• Balance values should be stored in lamports (1 SOL = 1,000,000,000 lamports)
• The monitor should handle the subscription lifecycle appropriately
• Ensure proper async iteration over subscription notifications

Test Cases

• The monitor successfully subscribes to account updates and receives notifications when the account balance changes. @test

• The monitor maintains an accurate history of balance updates with timestamps and slot numbers. @test

• The monitor provides the correct latest balance after receiving multiple updates. @test

Dependencies { .dependencies }

@solana/web3.js { .dependency }

Provides WebSocket subscription capabilities for real-time Solana blockchain data.

Implementation

@generates

API

/**
 * Represents a single balance update event
 */
export interface BalanceUpdate {
  /** Balance in lamports */
  lamports: bigint;
  /** Timestamp when the update was received */
  timestamp: number;
  /** Slot number of the update */
  slot: bigint;
}

/**
 * Account balance monitor that tracks real-time changes
 */
export class AccountBalanceMonitor {
  /**
   * Create a new account balance monitor
   * @param rpcUrl - WebSocket RPC endpoint URL
   * @param accountAddress - The account address to monitor (as a string)
   */
  constructor(rpcUrl: string, accountAddress: string);

  /**
   * Start monitoring the account for balance changes
   * This method subscribes to account notifications and begins collecting updates
   */
  start(): Promise<void>;

  /**
   * Stop monitoring and clean up the subscription
   */
  stop(): Promise<void>;

  /**
   * Get the most recent balance
   * @returns The latest balance in lamports, or null if no updates have been received
   */
  getLatestBalance(): bigint | null;

  /**
   * Get the complete history of balance updates
   * @returns Array of balance updates in chronological order
   */
  getBalanceHistory(): BalanceUpdate[];
}