HbarSuite Developer Documentation

HSuite Logo

Enterprise-grade and Degen-grade Web3 Infrastructure Platform

Overview

HbarSuite is a comprehensive Web3 infrastructure platform that bridges the gap between enterprise and retail blockchain solutions. Our ecosystem provides battle-tested tools and services designed for both businesses (B2B) and consumers (B2C), enabling seamless blockchain integration, management, and scalability on the Hedera Hashgraph network.

The platform is built with a security-first approach, offering robust transaction processing, node operation management, and distributed systems capabilities that power everything from NFT marketplaces to decentralized exchanges.

Repository Structure

This monorepo is organized into two primary sections:

/
├── libs/        # Core libraries and reusable modules
└── apps/        # Standalone applications

Core Libraries (/libs)

Our libraries follow a modular architecture with clear separation of concerns and are designed to be used independently or as part of the larger ecosystem.

Authentication & Security

• auth - Core authentication module supporting both Web2 and Web3 authentication methods, including API-key, JWT, and wallet-based authentication

• auth-types - Type definitions for authentication systems, security contexts, and identity verification

• api-key - API key management, validation, and security controls with rate limiting capabilities

Client & Network

• client - Main HSUITE client module for interacting with the ecosystem with connection pooling and retry mechanisms

• client-types - Type definitions for client operations, requests, and responses

• smart-network - Smart Network ecosystem implementation and node management with peer discovery

• smart-network-types - Type definitions for network operations, topology, and peer information

• hashgraph - Hedera Hashgraph integration and interaction layer for transaction creation and account management

• hashgraph-types - Type definitions for Hashgraph operations, accounts, and consensus services

Security & Access Control

• throttler - Rate limiting and DDoS protection mechanisms with configurable rules

• throttler-types - Type definitions for throttling operations and rate limit configurations

• validators - 🔍 Comprehensive NestJS validation library for Hedera Hashgraph transactions and operations with multi-entity support, REST API, and type-safe validation rules

  • 📋 Implementation Guide - Detailed source code documentation, architecture, and usage examples

  • 🏗️ Core Components: ValidatorsService, ValidatorsController, ValidatorsModule with full NestJS integration

  • ✅ Supported Operations: Consensus topics, token operations, account management, and transaction validation

  • 🌐 REST API: Complete HTTP endpoints for validator management and rule configuration

• validators-types - 🏷️ Complete TypeScript type system for validators with comprehensive interfaces, models, and enums

  • 📝 Type System Documentation - Detailed interface definitions, model implementations, and design patterns

  • 🎯 Namespace Architecture: Organized hierarchy by domain (IConsensus, IToken, IAccount)

  • 🔧 Model Implementations: Concrete validation classes with factory and strategy patterns

  • 📊 Transaction Enums: Standardized transaction type constants for type safety

• license-manager - License generation, verification, and management for enterprise deployments

User Management

• users - User management functionality and account operations with profile management

• users-types - Type definitions for user data structures and account states

• subscriptions - Subscription and service tier management with billing integration

• subscriptions-types - Type definitions for subscription models and payment structures

Distributed Systems

• dkg - Distributed Key Generation for secure multi-party operations and threshold signatures

• dkg-types - Type definitions for DKG operations and key sharing protocols

• smartnode-sdk - SDK for interacting with SmartNode infrastructure, including node provisioning

• ipfs - IPFS integration for decentralized storage with file management capabilities

• cluster - Clustering and distributed processing capabilities for horizontal scaling

System Utilities

• smart-config - Configuration management and environment handling with secure storage

• smart-transaction - Transaction processing and management with atomicity guarantees

• smart-transaction-types - Type definitions for transactions and multi-step operations

• health - Health checks and system monitoring with alerting capabilities

• helpers - Common utility functions and shared tools for cross-module operations

• snapshots - System state snapshot management for backup and restore operations

• mirrors - Mirror node integration and data access with query optimization

• trust-score - Trust scoring and reputation systems for network participants

• _tools - Command-line utilities for development, build, and deployment workflows including library building and NPM publishing

Applications (/apps)

Each application in the ecosystem is a standalone service with specific functionality while maintaining interoperability with the entire suite.

Infrastructure & Node Services

• smart-node - Core node infrastructure service providing:

  • Network operations and Hedera interaction

  • Transaction processing and management

  • Blockchain state synchronization

  • Performance monitoring and optimization

  • High-availability configuration

• smart-app - Application management and orchestration service featuring:

  • Microservice deployment and configuration

  • Service discovery and routing

  • Health monitoring and auto-remediation

  • Application metrics and analytics

• smart-registry - Service registry and discovery system providing:

  • Dynamic service registration

  • Health checking and availability monitoring

  • Configuration management

  • Service dependency tracking

NFT Ecosystem

• nft-exchange - Complete NFT marketplace with:

  • Collection management and curation

  • Royalty systems and creator benefits

  • Trading mechanisms and order books

  • Auction systems and price discovery

  • Metadata management and verification

DeFi Infrastructure

• exchange - Decentralized exchange (DEX) platform featuring:

  • Token swapping and liquidity pools

  • Automated Market Maker (AMM) functionality

  • Advanced trading features

  • Order book management

  • Price discovery mechanisms

• cross-chain-exchange - Multi-chain bridge and trading system:

  • Cross-chain asset transfers

  • Liquidity management across networks

  • Security protocols for multi-chain operations

  • Transaction verification and finality

Project Launch & Governance

• launchpad - Token and project launch platform with:

  • Token sale management

  • Vesting schedule implementation

  • KYC/AML compliance tools

  • Fair launch mechanisms

  • Project milestone tracking

• dao - Decentralized Autonomous Organization platform:

  • Governance and voting systems

  • Treasury management

  • Proposal creation and execution

  • Delegate management

  • On-chain and off-chain governance integration

Enterprise Tools

• multisig - Multi-signature wallet and approval system:

  • Multi-party transaction approval

  • Configurable signature thresholds

  • Transaction proposal workflow

  • Key management and recovery

  • Role-based access controls

• token-manager - Token creation and management system:

  • Token issuance and configuration

  • Asset management and distribution

  • Compliance and regulatory tools

  • Supply management and monitoring

  • Token burn and mint capabilities

Technical Stack

• Backend Framework: NestJS with Express adapters

• Language: TypeScript 4.x+ with strict typing

• Primary Database: MongoDB with Mongoose ODM

• Cache Database: Redis with clustering support

• Message Queue: Bull for background processing

• Blockchain Network: Hedera Hashgraph (@hashgraph/sdk v2.51.0+)

• Distributed Storage: IPFS with kubo-rpc-client

• Containerization: Docker with multi-platform support

• Monitoring: OpenTelemetry with Prometheus integration

• Documentation: Swagger/OpenAPI and Compodoc

• Testing: Jest with MongoDB memory server

Development Guidelines

Library Development

1. Type Safety

   • Use corresponding -types libraries for consistent interfaces

   • Define clear interfaces and types with JSDoc documentation

   • Implement runtime validation with class-validator

2. Modularity

   • Design for independent importability with minimal dependencies

   • Minimize cross-dependencies between modules

   • Follow dependency injection patterns for testability

   • Use NestJS providers and services pattern

3. Documentation

   • Include comprehensive JSDoc comments for all public methods

   • Provide usage examples with TypeScript code

   • Mark experimental features clearly with @beta or @experimental tags

   • Document error handling and edge cases

Application Development

1. Security-First Approach

   • Follow blockchain security best practices and OWASP guidelines

   • Implement proper input validation at all entry points

   • Handle edge cases and failure scenarios

   • Use rate limiting and implement appropriate access controls

   • Follow principle of least privilege

2. Testing Strategy

   • Maintain high unit test coverage for business logic

   • Implement integration testing for service interactions

   • Perform security and performance testing

   • Use test doubles and mocks appropriately

   • Test for race conditions in distributed systems

3. Integration Patterns

   • Ensure cross-application compatibility through standard interfaces

   • Design for shared resource management

   • Follow consistent API patterns across the ecosystem

   • Implement circuit breakers for external dependencies

   • Use standardized error handling and logging

Installation & Setup

Each library can be installed individually:

npm install @hsuite/[library-name]
# Example: npm install @hsuite/client

For multiple libraries, you can install them together:

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

For application setup, refer to the README in each application directory for specific instructions.

Quick Start

// Example: Initializing the client
import { HsuiteClient } from '@hsuite/client';

const client = new HsuiteClient({
  apiKey: 'your-api-key',
  environment: 'development'
});

// Using the client to interact with the Hedera network
const accountInfo = await client.network.getAccountInfo('0.0.12345');

Documentation

Generate documentation for any module:

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

# Generate documentation with coverage information
yarn compodoc:coverage

# Generate documentation for the entire project
yarn generate:compodocs

Comprehensive API documentation is available in the documentation/ and docs/ directories after generation.

Contributing

We welcome contributions from the community. Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.

The contribution process includes:

1. Fork the repository and create your branch from main

2. Install dependencies and set up your development environment

3. Make your changes with appropriate tests and documentation

4. Submit a pull request with a clear description of the changes

Before submitting your PR:

• Ensure tests pass: yarn test

• Verify linting standards: yarn lint

• Generate documentation: yarn compodoc

• Make sure all CI checks pass

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.