@hsuite/smartnode-sdk NPM

@hsuite/smartnode-sdk

A comprehensive SDK for interacting with SmartNode services and Hedera Hashgraph network functionality. This SDK provides a unified interface for managing SmartNode operations, validator interactions, and multi-ledger blockchain services through a modern NestJS-based architecture.

Installation

npm install @hsuite/smartnode-sdk

Features

Multi-ledger SmartNode Operations - Core functionality for network operations and status monitoring
Validator Management - Comprehensive tools for consensus, token, and account validation topics
Hedera Hashgraph Integration - Complete support for HCS, HTS, accounts, and transactions
Type-safe SDK Configuration - Full TypeScript support with runtime validation
NestJS Module Integration - Seamless integration with NestJS dependency injection
Extensible Architecture - Modular design supporting future blockchain integrations
Comprehensive Logging - Built-in logging with LoggerHelper integration

Dependencies

Peer Dependencies

@nestjs/common: ^10.4.2
@nestjs/core: ^10.4.2
@hsuite/client: ^2.1.2
@hsuite/hashgraph-types: ^2.0.3
@hsuite/smart-network-types: ^2.0.0
@hsuite/validators-types: ^2.0.0

Dependencies

@hsuite/nestjs-swagger: ^1.0.3
@hashgraph/sdk: ^2.62.0

Dev Dependencies

@compodoc/compodoc: ^1.1.23

Usage

Basic Module Integration

import { SmartNodeSdkModule } from '@hsuite/smartnode-sdk';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    SmartNodeSdkModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: async (configService: ConfigService) => ({
        client: {
          enabled: true,
          baseUrl: configService.get('SMARTNODE_API_URL'),
          ledgers: {
            [ChainType.HASHGRAPH]: {
              chain: ChainType.HASHGRAPH,
              network: LedgerNetwork.HEDERA_TESTNET,
              credentials: {
                accountId: configService.get('HEDERA_ACCOUNT_ID'),
                privateKey: configService.get('HEDERA_PRIVATE_KEY'),
                publicKey: configService.get('HEDERA_PUBLIC_KEY')
              }
            }
          }
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}

Service Injection and Usage

import { Injectable } from '@nestjs/common';
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';

@Injectable()
export class MyService {
  constructor(private readonly smartNodeSdk: SmartNodeSdkService) {}

  async getNetworkStatus() {
    // Get SmartNode status
    const status = await this.smartNodeSdk.sdk.smartNode.general.getStatus();
    
    // Get network information
    const network = await this.smartNodeSdk.sdk.smartNode.general.getNetwork();
    
    // Get available utilities
    const utilities = await this.smartNodeSdk.sdk.smartNode.general.getUtilities();
    
    return { status, network, utilities };
  }

  async manageValidators() {
    // Add consensus validator
    const timestamp = await this.smartNodeSdk.sdk.smartNode.validators.addConsensusValidator({
      // validation parameters
    });

    // Read consensus validator
    const validator = await this.smartNodeSdk.sdk.smartNode.validators.readConsensusValidator(timestamp);
    
    return validator;
  }

  async hashgraphOperations() {
    // Account operations
    const accountInfo = await this.smartNodeSdk.sdk.hashgraph.accounts.getInfo('0.0.123456');
    const balance = await this.smartNodeSdk.sdk.hashgraph.accounts.getQueryBalance('0.0.123456');
    
    // Token operations
    const tokenInfo = await this.smartNodeSdk.sdk.hashgraph.hts.getTokenInfo('0.0.789012');
    
    // HCS operations
    const messageId = await this.smartNodeSdk.sdk.hashgraph.hcs.submitMessage({
      topicId: '0.0.111111',
      message: 'Hello, SmartNode!'
    });
    
    return { accountInfo, balance, tokenInfo, messageId };
  }
}

SDK Structure

The SDK provides a hierarchical structure through the SmartNodeSdkService:

sdk: {
  smartNode: {
    general: GeneralSdk;           // Core SmartNode operations
    validators: ValidatorsSdk;     // Validator management
  },
  hashgraph: {
    accounts: AccountsHashgraphSdk;      // Account management
    transactions: TransactionsHashgraphSdk; // Transaction operations
    hcs: HcsHashgraphSdk;               // Hedera Consensus Service
    hts: HtsHashgraphSdk;               // Hedera Token Service
  },
  ripple: {
    // Future: Ripple blockchain integration
  }
}

Core Services

SmartNode Services

GeneralSdk

Core SmartNode operations and network management:

getIdentifier() - Retrieve SmartNode operator entity details
getStatus() - Get current node operational status and health metrics
getNetwork() - Get comprehensive list of whitelisted smart-nodes
getUtilities() - Retrieve HSuite utility tokens and capabilities

ValidatorsSdk

Validator management across consensus, token, and account topics:

Consensus Validators:
- addConsensusValidator(params) - Submit new consensus validator
- readConsensusValidator(timestamp) - Retrieve consensus validator data
Token Validators:
- addTokenValidator(params) - Submit new token validator
- readTokenValidator(timestamp) - Retrieve token validator data
Account Validators:
- addAccountValidator(params) - Submit new account validator
- readAccountValidator(timestamp) - Retrieve account validator data

Hedera Hashgraph Services

AccountsHashgraphSdk

Comprehensive account management functionality:

Account Information:
- getInfo(accountId) - Retrieve detailed account information
- getKeys(accountId) - Get account public keys
- getQueryBalance(accountId) - Query account balance
Account Lifecycle:
- createAccount(params) - Create new Hashgraph account
- updateAccount(accountId, params) - Update account properties
- deleteAccount(accountId, params) - Delete account and transfer funds
Transfers:
- transferHbar(params) - Transfer HBAR between accounts
- transferToken(params) - Transfer fungible tokens
- transferNftToken(params) - Transfer NFTs
Advanced Operations:
- Atomic swaps
- Allowance management
- Staking operations

TransactionsHashgraphSdk

Transaction management and execution:

Transaction submission and status monitoring
Transaction history and queries
Fee estimation and optimization

HcsHashgraphSdk (Hedera Consensus Service)

Consensus service operations:

Topic management and configuration
Message submission and retrieval
Subscription and monitoring capabilities

HtsHashgraphSdk (Hedera Token Service)

Comprehensive token service functionality:

Token Management:
- Token creation and configuration
- Token information queries
- Token supply management
Token Operations:
- Token transfers and approvals
- NFT minting and burning
- Token association and dissociation

Configuration

SDK Options Interface

interface ISdk.IOptions {
  client: IClient.IOptions; // Client configuration from @hsuite/client-types
}

Asynchronous Module Configuration

interface SmartNodeSdkModuleAsyncOptions {
  imports?: Array<any>;
  useClass?: Type<any>;
  useFactory?: (...args: any[]) => Promise<ISdk.IOptions> | ISdk.IOptions;
  inject?: any[];
}

Configuration Patterns

Factory Function Pattern (Recommended):

SmartNodeSdkModule.forRootAsync({
  imports: [ConfigModule],
  useFactory: (configService: ConfigService) => ({
    client: {
      enabled: true,
      baseUrl: configService.get('API_URL'),
      ledgers: {
        // ledger configurations
      }
    }
  }),
  inject: [ConfigService]
})

Factory Class Pattern:

SmartNodeSdkModule.forRootAsync({
  useClass: MyConfigFactory,
  imports: [ConfigModule]
})

Type System

The SDK provides comprehensive TypeScript support through:

ISdk Namespace - Interface definitions for type safety
Sdk Namespace - Model classes with runtime validation
Integration with @hsuite/client-types - Unified client configuration
Swagger/OpenAPI decorators - Automatic API documentation

Architecture

src/
├── index.ts                           # Main exports
├── smartnode-sdk.module.ts           # NestJS module configuration
├── smartnode-sdk.service.ts          # Main SDK service
├── sdk-options.interface.ts          # Module options interface
├── types/                            # Type definitions
│   ├── interfaces/                   # Interface definitions
│   │   └── sdk.namespace.ts         # ISdk namespace
│   └── models/                      # Model implementations
│       └── sdk.namespace.ts         # Sdk namespace
├── smart-nodes/                     # SmartNode services
│   ├── base.smart-node.ts          # Base class for services
│   ├── general.smart-node.ts       # General operations
│   └── validators.smart-node.ts    # Validator management
└── hashgraph/                      # Hedera Hashgraph services
    ├── accounts.hashgraph.ts       # Account operations
    ├── transactions.hashgraph.ts   # Transaction management
    ├── hcs.hashgraph.ts           # Consensus service
    └── hts.hashgraph.ts           # Token service

Development

Documentation Generation

Generate comprehensive documentation using Compodoc:

npm run compodoc

Check documentation coverage:

npm run compodoc:coverage

Best Practices

Use dependency injection - Leverage NestJS DI for service access
Handle errors appropriately - All SDK methods include proper error handling
Configure logging - Use built-in LoggerHelper for debugging
Type safety - Always use provided TypeScript interfaces
Async operations - All SDK methods return promises for async operations

Error Handling

All SDK services include comprehensive error handling:

try {
  const result = await smartNodeSdk.sdk.smartNode.general.getStatus();
} catch (error) {
  // Handle specific errors
  console.error('SmartNode operation failed:', error.message);
}