@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: 1.0.3
• @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.