HbarSuite Developer Documentation

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

Type Safety
- Use corresponding -types libraries for consistent interfaces
- Define clear interfaces and types with JSDoc documentation
- Implement runtime validation with class-validator
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
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

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
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
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:

Fork the repository and create your branch from main
Install dependencies and set up your development environment
Make your changes with appropriate tests and documentation
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.

PreviousWelcome to HbarSuite NextHbarSuite Smart Engine Applications

Last updated 1 month ago