HSuite Libraries

HbarSuite Smart Engines Libraries

A comprehensive suite of libraries for building enterprise-grade applications on the Hedera Hashgraph network.

Overview

The HbarSuite Smart Engines library collection provides a robust and modular framework for developing applications on the Hedera Hashgraph network. Each library is designed to handle specific aspects of blockchain interaction, network management, and distributed systems.

Core Libraries

Authentication & Security

  • @hsuite/auth: Authentication and authorization system

  • @hsuite/auth-types: Type definitions for authentication

  • @hsuite/api-key: API key management and validation

Client & SDK

  • @hsuite/client: Core client implementation

  • @hsuite/client-types: Type definitions for client operations

  • @hsuite/smartnode-sdk: SDK for smart node interactions

Distributed Systems

  • @hsuite/dkg-types: Type definitions for DKG operations

  • @hsuite/hashgraph-types: Type definitions for Hashgraph operations

Network & Transactions

  • @hsuite/smart-config: Configuration management

  • @hsuite/smart-network-types: Network type definitions

  • @hsuite/smart-transaction-types: Transaction type definitions

System Management

  • @hsuite/health: Health check and monitoring

  • @hsuite/helpers: Common utility functions

  • @hsuite/ipfs: IPFS integration

  • @hsuite/snapshots: System state snapshots

User & Access Control

  • @hsuite/users: User management and operations

  • @hsuite/users-types: Type definitions for user management

  • @hsuite/validators-types: Type definitions for validators

  • @hsuite/throttler: Rate limiting and request throttling

  • @hsuite/throttler-types: Type definitions for throttling

  • @hsuite/subscriptions: Subscription management

  • @hsuite/subscriptions-types: Type definitions for subscriptions

Installation

Each library can be installed individually using npm:

npm install @hsuite/[library-name]

For example:

npm install @hsuite/client
npm install @hsuite/auth
npm install @hsuite/smart-config

Documentation

Each library includes detailed documentation that can be generated using Compodoc:

# Generate documentation for a specific library
cd libs/[library-name]
yarn compodoc

# Generate documentation with coverage information
yarn compodoc:coverage

Development

Prerequisites

  • Node.js ≥ 14

  • npm or yarn

  • NestJS framework knowledge

  • Hedera network access

Setup

  1. Clone the repository

  2. Install dependencies: yarn install

  3. Build all libraries: yarn build

  4. Run tests: yarn test

Architecture

The libraries follow a modular architecture with clear separation of concerns:

  • Core Services: Client, Authentication, and Network integration

  • Support Services: Throttling, Validation, and User Management

  • Utility Services: Configuration, Health Checks, and Helpers

  • Type Definitions: Separate -types packages for type safety

Best Practices

  1. Use TypeScript for type safety

  2. Follow NestJS patterns and practices

  3. Implement proper error handling

  4. Include comprehensive documentation

  5. Write unit and integration tests

  6. Follow semantic versioning

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Commit your changes

  4. Push to the branch

  5. Create a Pull Request

License

This project is part of the HbarSuite ecosystem and is covered by its license terms.

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

HbarSuite Core Libraries Documentation

📁 Library Structure

This directory contains modular, reusable libraries that form the foundation of the HbarSuite ecosystem. Each library is designed to be independently usable while providing seamless integration with other ecosystem components.

🔍 Validators Ecosystem

The validators ecosystem provides comprehensive transaction validation capabilities for the Hedera Hashgraph network.

📚 validators - Core Validation Library

Purpose: Comprehensive NestJS validation library for Hedera Hashgraph transactions and operations

Key Features:

  • ✅ Multi-Entity Support: Consensus topics, tokens, and accounts

  • ✅ Transaction Validation: All major Hedera transaction types

  • ✅ REST API: Complete HTTP API for validator management

  • ✅ Type-Safe: Full TypeScript support with comprehensive definitions

  • ✅ Modular Architecture: Easy NestJS integration

  • ✅ Rule Management: Dynamic validation parameters via API

Core Components:

Supported Operations:

// Consensus Operations
TopicCreateTransaction, TopicUpdateTransaction, TopicDeleteTransaction, TopicMessageSubmitTransaction

// Token Operations  
TokenCreateTransaction, TokenUpdateTransaction, TokenMintTransaction, TokenBurnTransaction,
TokenFreezeAccountTransaction, TokenGrantKycTransaction, TokenAssociateTransaction, ...

// Account Operations
AccountCreateTransaction, AccountUpdateTransaction, TransferTransaction,
AccountAllowanceApproveTransaction, ...

🏗️ validators-types - Type Definition Library

Purpose: Complete TypeScript type system for validators with comprehensive interfaces and models

Key Features:

  • 🏷️ Namespace Architecture: Organized type hierarchy by domain

  • 📝 Interface Definitions: Comprehensive validation interfaces

  • 🔧 Model Implementations: Concrete validation model classes

  • 📊 Transaction Enums: Standardized transaction type constants

  • 🎨 Design Patterns: Factory, Strategy, and Interface Segregation patterns

Core Components:

  • 🏗️ Source Code - Type system architecture and implementation

  • 🔗 Interfaces - Core interface definitions

  • 📦 Models - Implementation model classes

  • 🏷️ Enums - Transaction type enumerations

Type Hierarchy:

IValidators
├── IConsensus                # Consensus topic validation
│   ├── IValidationParams    # Parameter interfaces
│   └── IEntity              # Validation entity contracts
├── IToken                   # Token operation validation
│   ├── IValidationParams    # Token-specific parameters
│   └── IEntity              # Token validation entities
└── IAccount                 # Account operation validation
    ├── IValidationParams    # Account-specific parameters
    └── IEntity              # Account validation entities

🔗 Integration Example

Basic Validator Setup

import { ValidatorsModule } from '@hsuite/validators';
import { IValidators } from '@hsuite/validators-types';

@Module({
  imports: [
    ValidatorsModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        hedera: {
          network: configService.get('HEDERA_NETWORK'),
          operatorId: configService.get('HEDERA_OPERATOR_ID'),
          operatorKey: configService.get('HEDERA_OPERATOR_KEY')
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

Transaction Validation Usage

import { ValidatorsService } from '@hsuite/validators';
import { TokenTransactionType } from '@hsuite/validators-types';

@Injectable()
export class TokenService {
  constructor(private validators: ValidatorsService) {}

  async validateTokenMint(tokenId: string, amount: string) {
    const tokenMintTx = new TokenMintTransaction()
      .setTokenId(tokenId)
      .setAmount(amount);

    const result = await this.validators.validate(
      tokenMintTx,
      TokenId.fromString(tokenId),
      { checkSupply: true }
    );

    return result.isValid ? 
      'Valid transaction' : 
      `Validation failed: ${result.reason}`;
  }
}

REST API Usage

# Add token validator
curl -X POST http://localhost:3000/validators/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "conditions": {
      "maxTransferAmount": "100000",
      "allowMinting": true,
      "requireKyc": false
    }
  }'

# Response: "1234567890.123456789" (consensus timestamp)

# Read validator
curl http://localhost:3000/validators/tokens/1234567890.123456789

🔧 Other Core Libraries

Authentication & Security

  • auth - Core authentication module supporting Web2 and Web3 methods

  • auth-types - Type definitions for authentication systems

  • api-key - API key management with rate limiting capabilities

Client & Network

  • client - Main HSUITE client module with connection pooling

  • client-types - Type definitions for client operations

  • smart-network - Smart Network ecosystem implementation

  • smart-network-types - Type definitions for network operations

  • hashgraph - Hedera Hashgraph integration layer

  • hashgraph-types - Type definitions for Hashgraph operations

Security & Access Control

  • throttler - Rate limiting and DDoS protection mechanisms

  • throttler-types - Type definitions for throttling operations

  • license-manager - License generation and verification for enterprise

User Management

  • users - User management functionality with profile management

  • users-types - Type definitions for user data structures

  • subscriptions - Subscription and service tier management

  • subscriptions-types - Type definitions for subscription models

Distributed Systems

  • dkg - Distributed Key Generation for secure multi-party operations

  • dkg-types - Type definitions for DKG operations

  • smartnode-sdk - SDK for SmartNode infrastructure interaction

  • ipfs - IPFS integration for decentralized storage

  • cluster - Clustering and distributed processing capabilities

System Utilities

  • smart-config - Configuration management with secure storage

  • smart-transaction - Transaction processing with atomicity guarantees

  • smart-transaction-types - Type definitions for transactions

  • health - Health checks and system monitoring

  • helpers - Common utility functions and shared tools

  • snapshots - System state snapshot management

  • mirrors - Mirror node integration with query optimization

  • trust-score - Trust scoring and reputation systems

  • _tools - Command-line utilities for development and deployment

🛠️ Development Guidelines

Library Development Standards

  1. Type Safety: Use corresponding -types libraries for consistent interfaces

  2. Documentation: Include comprehensive JSDoc comments and README files

  3. Modularity: Design for independent importability with minimal dependencies

  4. Testing: Implement thorough unit and integration tests

  5. Performance: Optimize for production use with efficient algorithms

Adding New Libraries

  1. Create library structure with src/, README.md, package.json, tsconfig.lib.json

  2. Define public API in src/index.ts with comprehensive exports

  3. Implement corresponding -types library if type definitions are extensive

  4. Add library to main libs/README.md with proper categorization

  5. Update main project README with library description and usage

Documentation Standards

  • README.md: Library overview, features, installation, usage examples

  • src/README.md: Detailed implementation documentation

  • JSDoc: Comprehensive inline code documentation

  • Examples: Practical usage examples with explanations

  • API Documentation: Generated documentation using Compodoc

📋 Integration Patterns

Module Registration Pattern

// Standard async module registration
SomeModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: async (configService: ConfigService) => ({
    // Configuration options
  }),
  inject: [ConfigService]
})

Service Injection Pattern

@Injectable()
export class MyService {
  constructor(
    private someService: SomeLibraryService,
    private anotherService: AnotherLibraryService
  ) {}
}

Type-Safe Usage Pattern

import { ISomeLibrary } from '@hsuite/some-library-types';

// Use interfaces for type safety
const params: ISomeLibrary.IParams = {
  // Type-safe parameter object
};

🔄 Library Lifecycle

Development Phase

  1. Design interfaces in -types library

  2. Implement core functionality

  3. Add comprehensive tests

  4. Document API and usage

  5. Review and refactor

Integration Phase

  1. Register module in main application

  2. Configure dependency injection

  3. Test integration points

  4. Validate type safety

  5. Performance testing

Maintenance Phase

  1. Monitor performance metrics

  2. Update dependencies regularly

  3. Maintain documentation

  4. Handle bug reports

  5. Plan feature enhancements

🚀 Getting Started

For Library Users

  1. Read the library-specific README for overview and features

  2. Check src/README.md for detailed implementation documentation

  3. Review code examples and integration patterns

  4. Set up configuration based on your requirements

  5. Start with basic usage and gradually explore advanced features

For Library Developers

  1. Study existing library patterns and conventions

  2. Follow TypeScript and NestJS best practices

  3. Implement comprehensive error handling

  4. Add thorough test coverage

  5. Document all public APIs with JSDoc

📚 Additional Resources

PreviousHSuite Smart App - Enterprise Hedera Application FrameworkNext@hsuite/api-key - Enterprise API Key Authentication System

Last updated