@hsuite/snapshots

A powerful NestJS module for generating, managing, and storing token holder snapshots on the Hedera network with real-time progress tracking via WebSockets.

Features

• Asynchronous snapshot generation using Bull queues

• Real-time progress tracking via WebSocket events

• IPFS integration for decentralized storage

• JWT authentication for secure WebSocket connections

• Rate-limited API calls to Hedera network

• Comprehensive error handling and logging

• TypeScript support with full type definitions

Installation

npm install @hsuite/snapshots

Dependencies

This module requires the following peer dependencies:

• @nestjs/common: ^10.4.2

• @nestjs/core: ^10.4.2

And the following dependencies:

• @hsuite/hashgraph: 2.0.0

• @hsuite/auth-types: 2.0.0

• @hsuite/ipfs: 2.0.0

• @hsuite/nestjs-swagger: 2.0.0

• @hashgraph/sdk: ^2.51.0

Module Configuration

Import and configure the module in your NestJS application:

import { SnapshotsModule } from '@hsuite/snapshots';

@Module({
  imports: [
    SnapshotsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        bull: {
          redis: {
            url: config.get('REDIS_URL'),
            password: config.get('REDIS_PASSWORD')
          },
          defaultJobOptions: {
            attempts: 3,
            backoff: {
              type: 'exponential',
              delay: 1000
            }
          }
        },
        jwt: {
          secret: config.get('JWT_SECRET')
        }
      }),
      useExisting: [ConfigService]
    })
  ]
})
export class AppModule {}

Usage

Generating Snapshots

import { SnapshotsService } from '@hsuite/snapshots';

@Injectable()
export class YourService {
  constructor(private snapshotsService: SnapshotsService) {}

  async generateSnapshot(tokenId: string, session: IAuth.ICredentials.IWeb3.IEntity) {
    const result = await this.snapshotsService.generateSnapshot(tokenId, session);
    return result; // Returns { jobId: string }
  }
}

WebSocket Client Integration

// Connect to WebSocket with JWT authentication
const socket = io('ws://your-server/snapshots', {
  auth: { accessToken: 'your-jwt-token' }
});

// Listen for snapshot events
socket.on('snapshots_events', (event) => {
  switch (event.type) {
    case 'snapshots_progress':
      console.log(`Progress: ${event.payload.progress}%`);
      break;
    case 'snapshots_completed':
      console.log(`Snapshot completed: ${event.payload.jobId}`);
      break;
    case 'snapshots_failed':
      console.error(`Error: ${event.payload.error}`);
      break;
  }
});

WebSocket Events

The module emits the following events:

Event Type	Description	Payload
snapshots_progress	Progress update during generation	{ jobId, jobName, snapshotId, status: 'running', progress }
snapshots_active	Job started processing	{ jobId, jobName, snapshotId, status: 'activated', progress: 0 }
snapshots_completed	Job completed successfully	{ jobId, jobName, snapshotId, status: 'completed', progress: 100 }
snapshots_failed	Job failed with error	{ jobId, jobName, snapshotId, status: 'error', error }

Architecture

The module consists of several key components:

1. SnapshotsService: Main service for initiating snapshot generation

2. SnapshotsConsumer: Bull queue consumer for processing snapshots

3. SnapshotsGateway: WebSocket gateway for real-time updates

4. SnapshotsEvents: Event handling for queue operations

Processing Flow

1. Client requests snapshot generation via REST API

2. Service creates a Bull queue job

3. Consumer processes job in background:

   • Fetches token balances from Hedera (rate-limited)

   • Updates progress via WebSocket

   • Uploads final data to IPFS

4. Client receives real-time updates via WebSocket

Rate Limiting

The module implements rate limiting for Hedera API calls:

• Batch size: 25 accounts per request

• Delay: 1 second between API calls

• Progress tracking: Updates after each batch

Documentation

Generate detailed documentation using Compodoc:

npm run compodoc

For documentation with coverage report:

npm run compodoc:coverage

License

This package is part of the HSuite Enterprise ecosystem.

Contributing

Please refer to the HSuite contribution guidelines.

---

Built with ❤️ by the HbarSuite Team Copyright © 2024 HbarSuite. All rights reserved.