# @hsuite/smartnode-sdk - SmartNode Software Development Kit

> 🚀 **Comprehensive SDK for SmartNode services and multi-ledger blockchain operations**

Enterprise-grade TypeScript SDK providing unified access to SmartNode network operations, validator management, and complete Hedera Hashgraph integration with extensible architecture for multi-blockchain support.

***

## 📚 Table of Contents

* [✨ Quick Start](#-quick-start)
* [🏗️ Architecture](#️-architecture)
* [🔧 API Reference](#-api-reference)
* [📖 Guides](#-guides)
* [🎯 Examples](#-examples)
* [🔗 Integration](#-integration)

***

## ✨ Quick Start

### Installation

```bash
npm install @hsuite/smartnode-sdk
```

### Basic Setup

```typescript
import { SmartNodeSdkModule } from '@hsuite/smartnode-sdk';

@Module({
  imports: [
    SmartNodeSdkModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        client: {
          baseUrl: configService.get('SMARTNODE_BASE_URL'),
          timeout: configService.get('SMARTNODE_TIMEOUT', 30000),
          headers: {
            'Authorization': `Bearer ${configService.get('SMARTNODE_API_KEY')}`
          }
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}
```

### Basic Usage

```typescript
@Injectable()
export class BlockchainService {
  constructor(private smartNodeSdk: SmartNodeSdkService) {}

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

  async manageAccount(accountId: string) {
    // Get account information via Hedera integration
    const accountInfo = await this.smartNodeSdk.sdk.hashgraph.accounts.getInfo(accountId);
    const balance = await this.smartNodeSdk.sdk.hashgraph.accounts.getAccountBalance(accountId);
    
    return { accountInfo, balance };
  }
}
```

***

## 🏗️ Architecture

### Hierarchical SDK Structure

The SDK provides a comprehensive, hierarchical structure through the `SmartNodeSdkService`:

```typescript
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 Components

#### 🌐 **SmartNode Services**

* **General Operations** - Node identification, status monitoring, network management
* **Validator Management** - Consensus, token, and account validator operations
* **Network Coordination** - Multi-node communication and coordination

#### ⚡ **Hedera Hashgraph Integration**

* **Account Services** - Complete account lifecycle management
* **Transaction Services** - Transaction submission and monitoring
* **Consensus Service (HCS)** - Topic management and messaging
* **Token Service (HTS)** - Token operations and management

#### 🔄 **Extensible Architecture**

* **Multi-Ledger Support** - Ready for Ripple and other blockchain integrations
* **Modular Design** - Independent service modules with clear separation
* **Type-Safe Configuration** - Full TypeScript support with runtime validation

### Module Structure

```
src/
├── smartnode-sdk.service.ts        # Main SDK orchestration service
├── smartnode-sdk.module.ts         # NestJS module configuration
├── sdk-options.interface.ts        # Configuration interfaces
├── smart-nodes/
│   ├── base.smart-node.ts          # Base SDK class
│   ├── general.smart-node.ts       # General SmartNode operations
│   └── validators.smart-node.ts    # Validator management
├── hashgraph/
│   ├── accounts.hashgraph.ts       # Account operations
│   ├── transactions.hashgraph.ts   # Transaction management
│   ├── hcs.hashgraph.ts           # Consensus service
│   └── hts.hashgraph.ts           # Token service
└── types/
    ├── interfaces/                 # TypeScript interfaces
    └── models/                     # Implementation models
```

***

## 🔧 API Reference

### SmartNodeSdkService

#### Core SDK Structure

```typescript
class SmartNodeSdkService {
  readonly sdk: {
    smartNode: {
      general: GeneralSdk;
      validators: ValidatorsSdk;
    };
    hashgraph: {
      accounts: AccountsHashgraphSdk;
      transactions: TransactionsHashgraphSdk;
      hcs: HcsHashgraphSdk;
      hts: HtsHashgraphSdk;
    };
    ripple: {};
  };
}
```

### SmartNode Services

#### GeneralSdk - Core SmartNode Operations

**`getIdentifier(): Promise<ISmartNetwork.IOperator.IEntity>`**

* Retrieves SmartNode operator entity details
* **Returns**: Unique identifier and node details
* **Usage**: Node identification in network operations

**`getStatus(): Promise<ISmartNetwork.ISmartNode.IState>`**

* Gets current operational status and health metrics
* **Returns**: Node status, uptime, performance metrics
* **Usage**: Health monitoring and diagnostics

**`getNetwork(): Promise<Array<ISmartNetwork.INetwork.IEntity>>`**

* Retrieves comprehensive list of whitelisted smart-nodes
* **Returns**: Array of network entities with status and capabilities
* **Usage**: Network topology and node discovery

**`getUtilities(): Promise<any>`**

* Retrieves HSuite utility tokens and capabilities
* **Returns**: Available utilities and their configurations
* **Usage**: Feature discovery and capability assessment

#### ValidatorsSdk - Validator Management

**Consensus Validators:**

* `addConsensusValidator(params): Promise<string>` - Submit new consensus validator
* `readConsensusValidator(timestamp): Promise<IValidators.IConsensus.IValidationParams>` - Retrieve consensus validator

**Token Validators:**

* `addTokenValidator(params): Promise<string>` - Submit new token validator
* `readTokenValidator(timestamp): Promise<IValidators.IToken.IValidationParams>` - Retrieve token validator

**Account Validators:**

* `addAccountValidator(params): Promise<string>` - Submit new account validator
* `readAccountValidator(timestamp): Promise<IValidators.IAccount.IValidationParams>` - Retrieve account validator

### Hedera Hashgraph Services

#### AccountsHashgraphSdk - Account Management

**Account Information:**

* `getInfo(accountId): Promise<IHashgraph.ILedger.IAccounts.IResponse.IInfo>` - Account details
* `getKeys(accountId): Promise<any>` - Account public keys
* `getAccountBalance(accountId): Promise<any>` - Account balance query

**Account Lifecycle:**

* `createAccount(params): Promise<any>` - Create new account
* `updateAccount(accountId, params): Promise<any>` - Update account properties
* `deleteAccount(accountId, params): Promise<any>` - Delete account

**Transfer Operations:**

* `transferHbar(params): Promise<any>` - HBAR transfers
* `transferToken(params): Promise<any>` - Fungible token transfers
* `transferNftToken(params): Promise<any>` - NFT transfers

#### TransactionsHashgraphSdk - Transaction Management

**Transaction Operations:**

* Transaction submission and status monitoring
* Transaction history and queries
* Fee estimation and optimization
* Batch transaction processing

#### HcsHashgraphSdk - Hedera Consensus Service

**Topic Management:**

* Topic creation, update, and deletion
* Topic configuration and permissions
* Topic information retrieval

**Message Operations:**

* Message submission to topics
* Message retrieval and history
* Subscription management

#### HtsHashgraphSdk - Hedera Token Service

**Token Management:**

* Token creation and configuration
* Token information queries
* Supply management operations

**Token Operations:**

* Token transfers and approvals
* NFT minting and burning
* Token association and dissociation

### Configuration Interfaces

#### SDK Options Interface

```typescript
interface ISdk.IOptions {
  client: IClient.IOptions;
}

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

***

## 📖 Guides

### **SmartNode Network Guide**

Learn about SmartNode network operations and topology management. Comprehensive guide covering network architecture, node discovery, consensus mechanisms, validator management, and enterprise-grade SmartNode deployment and operations.

### **Validator Setup Guide**

Configure and manage validators across different topics. Advanced configuration guide covering validator deployment, consensus topic management, validation rules, performance monitoring, and enterprise validator infrastructure management.

### **Hedera Integration Guide**

Complete guide to using Hedera Hashgraph services through the SDK. Detailed integration guide covering Hedera account management, transaction processing, token operations, consensus service, and enterprise Hedera blockchain integration.

***

## 🎯 Examples

### SmartNode Network Operations

```typescript
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';

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

  async monitorNetworkHealth() {
    try {
      // Get current node status
      const nodeStatus = await this.smartNodeSdk.sdk.smartNode.general.getStatus();
      
      // Get network topology
      const networkNodes = await this.smartNodeSdk.sdk.smartNode.general.getNetwork();
      
      // Get node identifier
      const nodeIdentifier = await this.smartNodeSdk.sdk.smartNode.general.getIdentifier();
      
      // Get available utilities
      const utilities = await this.smartNodeSdk.sdk.smartNode.general.getUtilities();

      return {
        currentNode: {
          identifier: nodeIdentifier,
          status: nodeStatus,
          health: nodeStatus.health || 'unknown'
        },
        network: {
          totalNodes: networkNodes.length,
          activeNodes: networkNodes.filter(node => node.status === 'active').length,
          nodes: networkNodes.map(node => ({
            id: node.id,
            status: node.status,
            capabilities: node.capabilities
          }))
        },
        utilities: utilities,
        monitoredAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Network monitoring failed: ${error.message}`);
    }
  }

  async getNetworkConnectivity() {
    const network = await this.smartNodeSdk.sdk.smartNode.general.getNetwork();
    
    const connectivityReport = {
      totalNodes: network.length,
      onlineNodes: 0,
      offlineNodes: 0,
      nodeDetails: []
    };

    for (const node of network) {
      const isOnline = node.status === 'active' || node.status === 'online';
      
      if (isOnline) {
        connectivityReport.onlineNodes++;
      } else {
        connectivityReport.offlineNodes++;
      }

      connectivityReport.nodeDetails.push({
        nodeId: node.id,
        status: node.status,
        lastSeen: node.lastSeen || 'unknown',
        networkRole: node.role || 'participant'
      });
    }

    return {
      ...connectivityReport,
      networkHealth: (connectivityReport.onlineNodes / connectivityReport.totalNodes * 100).toFixed(2) + '%',
      timestamp: new Date().toISOString()
    };
  }
}
```

### Validator Management Operations

```typescript
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';
import { IValidators } from '@hsuite/validators-types';

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

  async setupConsensusValidator(validationConfig: any) {
    try {
      const validationParams: Omit<IValidators.IConsensus.IValidationParams, 'validateParams'> = {
        conditions: {
          requireSubmitKey: validationConfig.requireSubmitKey || true,
          maxMessageSize: validationConfig.maxMessageSize || 1024,
          allowPublicSubmission: validationConfig.allowPublicSubmission || false,
          messageEncoding: validationConfig.messageEncoding || 'utf-8'
        }
      };

      // Add consensus validator
      const timestamp = await this.smartNodeSdk.sdk.smartNode.validators.addConsensusValidator(
        validationParams
      );

      return {
        success: true,
        validatorTimestamp: timestamp,
        validatorType: 'consensus',
        configuration: validationParams,
        message: 'Consensus validator added successfully'
      };
    } catch (error) {
      throw new Error(`Consensus validator setup failed: ${error.message}`);
    }
  }

  async setupTokenValidator(tokenValidationConfig: any) {
    try {
      const validationParams: Omit<IValidators.IToken.IValidationParams, 'validateParams'> = {
        conditions: {
          maxTransferAmount: tokenValidationConfig.maxTransferAmount || '1000000',
          allowMinting: tokenValidationConfig.allowMinting !== false,
          allowBurning: tokenValidationConfig.allowBurning !== false,
          requireKyc: tokenValidationConfig.requireKyc || false,
          freezeDefault: tokenValidationConfig.freezeDefault || false,
          decimals: tokenValidationConfig.decimals || 18,
          maxSupply: tokenValidationConfig.maxSupply || '10000000000'
        }
      };

      const timestamp = await this.smartNodeSdk.sdk.smartNode.validators.addTokenValidator(
        validationParams
      );

      return {
        success: true,
        validatorTimestamp: timestamp,
        validatorType: 'token',
        configuration: validationParams
      };
    } catch (error) {
      throw new Error(`Token validator setup failed: ${error.message}`);
    }
  }

  async setupAccountValidator(accountValidationConfig: any) {
    try {
      const validationParams: Omit<IValidators.IAccount.IValidationParams, 'validateParams'> = {
        smartNodeSecurity: accountValidationConfig.securityLevel || 'partial',
        updateConditions: {
          values: accountValidationConfig.allowedUpdates || ['maxAutomaticTokenAssociations', 'accountMemo'],
          controller: accountValidationConfig.updateController || 'owner'
        },
        actionsConditions: {
          values: accountValidationConfig.allowedActions || ['transfer', 'update'],
          controller: accountValidationConfig.actionController || 'owner'
        },
        tokenGates: {
          fungibles: { tokens: accountValidationConfig.fungibleTokenGates || [] },
          nonFungibles: { tokens: accountValidationConfig.nftTokenGates || [] },
          timeRange: accountValidationConfig.tokenGateTimeRange || null
        },
        swapConditions: {
          prices: accountValidationConfig.swapPrices || []
        }
      };

      const timestamp = await this.smartNodeSdk.sdk.smartNode.validators.addAccountValidator(
        validationParams
      );

      return {
        success: true,
        validatorTimestamp: timestamp,
        validatorType: 'account',
        configuration: validationParams
      };
    } catch (error) {
      throw new Error(`Account validator setup failed: ${error.message}`);
    }
  }

  async getValidatorStatus(validatorType: 'consensus' | 'token' | 'account', timestamp: string) {
    try {
      let validator;

      switch (validatorType) {
        case 'consensus':
          validator = await this.smartNodeSdk.sdk.smartNode.validators.readConsensusValidator(timestamp);
          break;
        case 'token':
          validator = await this.smartNodeSdk.sdk.smartNode.validators.readTokenValidator(timestamp);
          break;
        case 'account':
          validator = await this.smartNodeSdk.sdk.smartNode.validators.readAccountValidator(timestamp);
          break;
        default:
          throw new Error(`Unsupported validator type: ${validatorType}`);
      }

      return {
        validatorType,
        timestamp,
        configuration: validator,
        status: 'active',
        retrievedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Validator status retrieval failed: ${error.message}`);
    }
  }
}
```

### Hedera Account Management

```typescript
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';
import { IHashgraph } from '@hsuite/hashgraph-types';

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

  async getCompleteAccountInfo(accountId: string) {
    try {
      // Get account information
      const accountInfo = await this.smartNodeSdk.sdk.hashgraph.accounts.getInfo(accountId);
      
      // Get account balance
      const balance = await this.smartNodeSdk.sdk.hashgraph.accounts.getAccountBalance(accountId);
      
      // Get account keys (if available)
      let keys;
      try {
        keys = await this.smartNodeSdk.sdk.hashgraph.accounts.getKeys(accountId);
      } catch (error) {
        console.warn('Failed to retrieve account keys:', error.message);
        keys = null;
      }

      return {
        account: {
          id: accountId,
          balance: balance,
          info: accountInfo,
          keys: keys
        },
        status: 'active',
        retrievedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Account information retrieval failed: ${error.message}`);
    }
  }

  async performAccountOperations(operations: any[]) {
    const results = [];

    for (const operation of operations) {
      try {
        let result;

        switch (operation.type) {
          case 'create':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.createAccount(operation.params);
            break;
          case 'update':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.updateAccount(
              operation.accountId,
              operation.params
            );
            break;
          case 'delete':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.deleteAccount(
              operation.accountId,
              operation.params
            );
            break;
          case 'transferHbar':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferHbar(operation.params);
            break;
          case 'transferToken':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferToken(operation.params);
            break;
          case 'transferNft':
            result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferNftToken(operation.params);
            break;
          default:
            throw new Error(`Unsupported operation type: ${operation.type}`);
        }

        results.push({
          operation: operation.type,
          success: true,
          result: result,
          executedAt: new Date().toISOString()
        });
      } catch (error) {
        results.push({
          operation: operation.type,
          success: false,
          error: error.message,
          failedAt: new Date().toISOString()
        });
      }
    }

    return {
      totalOperations: operations.length,
      successful: results.filter(r => r.success).length,
      failed: results.filter(r => !r.success).length,
      results: results
    };
  }

  async batchTransferHbar(transfers: Array<{from: string, to: string, amount: number}>) {
    const transferResults = [];

    for (const transfer of transfers) {
      try {
        const result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferHbar({
          from: transfer.from,
          to: transfer.to,
          amount: transfer.amount,
          memo: `Batch transfer ${new Date().toISOString()}`
        });

        transferResults.push({
          from: transfer.from,
          to: transfer.to,
          amount: transfer.amount,
          success: true,
          transactionResult: result
        });
      } catch (error) {
        transferResults.push({
          from: transfer.from,
          to: transfer.to,
          amount: transfer.amount,
          success: false,
          error: error.message
        });
      }
    }

    return {
      batchSize: transfers.length,
      successful: transferResults.filter(r => r.success).length,
      failed: transferResults.filter(r => !r.success).length,
      totalAmount: transfers.reduce((sum, t) => sum + t.amount, 0),
      results: transferResults
    };
  }
}
```

### Hedera Consensus Service Operations

```typescript
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';

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

  async manageConsensusTopic(topicOperations: any) {
    try {
      const results = {};

      // Create topic if requested
      if (topicOperations.create) {
        const createResult = await this.smartNodeSdk.sdk.hashgraph.hcs.createTopic(
          topicOperations.create
        );
        results['create'] = createResult;
      }

      // Update topic if requested
      if (topicOperations.update && topicOperations.topicId) {
        const updateResult = await this.smartNodeSdk.sdk.hashgraph.hcs.updateTopic(
          topicOperations.topicId,
          topicOperations.update
        );
        results['update'] = updateResult;
      }

      // Submit message if requested
      if (topicOperations.submitMessage && topicOperations.topicId) {
        const messageResult = await this.smartNodeSdk.sdk.hashgraph.hcs.submitMessage({
          topicId: topicOperations.topicId,
          message: topicOperations.submitMessage.message,
          signature: topicOperations.submitMessage.signature
        });
        results['submitMessage'] = messageResult;
      }

      // Get topic info if requested
      if (topicOperations.getInfo && topicOperations.topicId) {
        const infoResult = await this.smartNodeSdk.sdk.hashgraph.hcs.getTopicInfo(
          topicOperations.topicId
        );
        results['info'] = infoResult;
      }

      return {
        success: true,
        topicId: topicOperations.topicId,
        operations: Object.keys(results),
        results: results,
        completedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Consensus topic management failed: ${error.message}`);
    }
  }

  async subscribeToTopic(topicId: string, onMessage: (message: any) => void) {
    try {
      // Note: Actual subscription implementation would depend on the SDK method
      const subscription = await this.smartNodeSdk.sdk.hashgraph.hcs.subscribeTo(
        topicId,
        onMessage
      );

      return {
        success: true,
        topicId: topicId,
        subscriptionId: subscription.subscriptionId || 'unknown',
        subscribedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Topic subscription failed: ${error.message}`);
    }
  }
}
```

### Hedera Token Service Operations

```typescript
import { SmartNodeSdkService } from '@hsuite/smartnode-sdk';

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

  async manageToken(tokenOperations: any) {
    try {
      const results = {};

      // Create token if requested
      if (tokenOperations.create) {
        const createResult = await this.smartNodeSdk.sdk.hashgraph.hts.createToken(
          tokenOperations.create
        );
        results['create'] = createResult;
      }

      // Update token if requested
      if (tokenOperations.update && tokenOperations.tokenId) {
        const updateResult = await this.smartNodeSdk.sdk.hashgraph.hts.updateToken(
          tokenOperations.tokenId,
          tokenOperations.update
        );
        results['update'] = updateResult;
      }

      // Mint tokens if requested
      if (tokenOperations.mint && tokenOperations.tokenId) {
        const mintResult = await this.smartNodeSdk.sdk.hashgraph.hts.mintToken(
          tokenOperations.tokenId,
          tokenOperations.mint
        );
        results['mint'] = mintResult;
      }

      // Burn tokens if requested
      if (tokenOperations.burn && tokenOperations.tokenId) {
        const burnResult = await this.smartNodeSdk.sdk.hashgraph.hts.burnToken(
          tokenOperations.tokenId,
          tokenOperations.burn
        );
        results['burn'] = burnResult;
      }

      // Get token info if requested
      if (tokenOperations.getInfo && tokenOperations.tokenId) {
        const infoResult = await this.smartNodeSdk.sdk.hashgraph.hts.getTokenInfo(
          tokenOperations.tokenId
        );
        results['info'] = infoResult;
      }

      return {
        success: true,
        tokenId: tokenOperations.tokenId,
        operations: Object.keys(results),
        results: results,
        completedAt: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`Token management failed: ${error.message}`);
    }
  }

  async performTokenTransfers(transfers: any[]) {
    const transferResults = [];

    for (const transfer of transfers) {
      try {
        let result;

        if (transfer.type === 'fungible') {
          result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferToken({
            tokenId: transfer.tokenId,
            from: transfer.from,
            to: transfer.to,
            amount: transfer.amount
          });
        } else if (transfer.type === 'nft') {
          result = await this.smartNodeSdk.sdk.hashgraph.accounts.transferNftToken({
            tokenId: transfer.tokenId,
            from: transfer.from,
            to: transfer.to,
            serialNumber: transfer.serialNumber
          });
        } else {
          throw new Error(`Unsupported transfer type: ${transfer.type}`);
        }

        transferResults.push({
          ...transfer,
          success: true,
          result: result
        });
      } catch (error) {
        transferResults.push({
          ...transfer,
          success: false,
          error: error.message
        });
      }
    }

    return {
      totalTransfers: transfers.length,
      successful: transferResults.filter(r => r.success).length,
      failed: transferResults.filter(r => !r.success).length,
      results: transferResults
    };
  }
}
```

### Comprehensive SDK Integration

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

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

  async performComplexWorkflow(workflowConfig: any) {
    const workflowResults = {
      workflowId: workflowConfig.id || Date.now().toString(),
      startedAt: new Date().toISOString(),
      steps: [],
      errors: []
    };

    try {
      // Step 1: Check SmartNode network health
      const networkStatus = await this.smartNodeSdk.sdk.smartNode.general.getStatus();
      workflowResults.steps.push({
        step: 'network_health_check',
        success: true,
        result: { health: networkStatus.health, status: 'operational' }
      });

      // Step 2: Setup validators if required
      if (workflowConfig.setupValidators) {
        const validatorTimestamp = await this.smartNodeSdk.sdk.smartNode.validators.addConsensusValidator(
          workflowConfig.validatorConfig
        );
        workflowResults.steps.push({
          step: 'validator_setup',
          success: true,
          result: { timestamp: validatorTimestamp }
        });
      }

      // Step 3: Create Hedera account if required
      if (workflowConfig.createAccount) {
        const accountResult = await this.smartNodeSdk.sdk.hashgraph.accounts.createAccount(
          workflowConfig.accountConfig
        );
        workflowResults.steps.push({
          step: 'account_creation',
          success: true,
          result: accountResult
        });
      }

      // Step 4: Create token if required
      if (workflowConfig.createToken) {
        const tokenResult = await this.smartNodeSdk.sdk.hashgraph.hts.createToken(
          workflowConfig.tokenConfig
        );
        workflowResults.steps.push({
          step: 'token_creation',
          success: true,
          result: tokenResult
        });
      }

      // Step 5: Submit consensus message if required
      if (workflowConfig.submitMessage) {
        const messageResult = await this.smartNodeSdk.sdk.hashgraph.hcs.submitMessage({
          topicId: workflowConfig.topicId,
          message: workflowConfig.message
        });
        workflowResults.steps.push({
          step: 'consensus_message',
          success: true,
          result: messageResult
        });
      }

      workflowResults['completedAt'] = new Date().toISOString();
      workflowResults['status'] = 'completed';
      workflowResults['successfulSteps'] = workflowResults.steps.filter(s => s.success).length;

      return workflowResults;
    } catch (error) {
      workflowResults.errors.push({
        error: error.message,
        occurredAt: new Date().toISOString()
      });

      workflowResults['status'] = 'failed';
      workflowResults['failedAt'] = new Date().toISOString();

      throw new Error(`Workflow execution failed: ${error.message}`);
    }
  }

  async getSystemOverview() {
    try {
      // Get SmartNode information
      const [nodeIdentifier, nodeStatus, network, utilities] = await Promise.allSettled([
        this.smartNodeSdk.sdk.smartNode.general.getIdentifier(),
        this.smartNodeSdk.sdk.smartNode.general.getStatus(),
        this.smartNodeSdk.sdk.smartNode.general.getNetwork(),
        this.smartNodeSdk.sdk.smartNode.general.getUtilities()
      ]);

      return {
        smartNode: {
          identifier: nodeIdentifier.status === 'fulfilled' ? nodeIdentifier.value : null,
          status: nodeStatus.status === 'fulfilled' ? nodeStatus.value : null,
          network: network.status === 'fulfilled' ? network.value : null,
          utilities: utilities.status === 'fulfilled' ? utilities.value : null
        },
        sdk: {
          services: ['smartNode', 'hashgraph'],
          smartNodeServices: ['general', 'validators'],
          hashgraphServices: ['accounts', 'transactions', 'hcs', 'hts'],
          futureServices: ['ripple']
        },
        timestamp: new Date().toISOString()
      };
    } catch (error) {
      throw new Error(`System overview generation failed: ${error.message}`);
    }
  }
}
```

***

## 🔗 Integration

### Required Dependencies

```json
{
  "@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",
  "@hsuite/nestjs-swagger": "^1.0.3",
  "@hashgraph/sdk": "^2.62.0",
  "@hsuite/helpers": "^2.1.0"
}
```

### Environment Variables

```env
# SmartNode Configuration
SMARTNODE_BASE_URL=https://api.smartnode.example.com
SMARTNODE_API_KEY=your_api_key_here
SMARTNODE_TIMEOUT=30000

# Network Configuration
SMARTNODE_NETWORK_ID=testnet
SMARTNODE_OPERATOR_ID=0.0.123456
SMARTNODE_OPERATOR_KEY=your_operator_key

# Client Configuration
HTTP_TIMEOUT=30000
MAX_RETRIES=3
ENABLE_LOGGING=true
```

### Module Configuration

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

@Module({
  imports: [
    SmartNodeSdkModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        client: {
          baseUrl: configService.get('SMARTNODE_BASE_URL'),
          timeout: configService.get('SMARTNODE_TIMEOUT', 30000),
          headers: {
            'Authorization': `Bearer ${configService.get('SMARTNODE_API_KEY')}`,
            'Content-Type': 'application/json'
          },
          retries: configService.get('MAX_RETRIES', 3),
          enableLogging: configService.get('ENABLE_LOGGING', true)
        }
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}
```

### Integration with HSuite Ecosystem

```typescript
// Complete integration with other HSuite modules
@Module({
  imports: [
    AuthModule,
    SmartNodeSdkModule,
    ValidatorsModule,
    HashgraphModule,
    SmartConfigModule
  ]
})
export class BlockchainEcosystemModule {}

@Injectable()
export class IntegratedBlockchainService {
  constructor(
    private smartNodeSdk: SmartNodeSdkService,
    private authService: AuthService,
    private validatorsService: ValidatorsService
  ) {}

  async executeSecureOperation(
    operation: any,
    session: IAuth.ICredentials.IWeb3.IEntity
  ) {
    // 1. Validate permissions
    const hasPermission = await this.authService.validatePermission(
      session,
      `smartnode:${operation.type}`
    );

    if (!hasPermission) {
      throw new Error('Insufficient permissions for SmartNode operation');
    }

    // 2. Check network health
    const networkStatus = await this.smartNodeSdk.sdk.smartNode.general.getStatus();
    if (networkStatus.health !== 'healthy') {
      throw new Error('SmartNode network is not healthy');
    }

    // 3. Execute operation via SDK
    let result;
    switch (operation.type) {
      case 'account_create':
        result = await this.smartNodeSdk.sdk.hashgraph.accounts.createAccount(operation.params);
        break;
      case 'token_create':
        result = await this.smartNodeSdk.sdk.hashgraph.hts.createToken(operation.params);
        break;
      case 'validator_add':
        result = await this.smartNodeSdk.sdk.smartNode.validators.addConsensusValidator(operation.params);
        break;
      default:
        throw new Error(`Unsupported operation type: ${operation.type}`);
    }

    return {
      success: true,
      operation: operation.type,
      result: result,
      executedBy: session.walletId,
      executedAt: new Date().toISOString()
    };
  }
}
```

***

**🚀 Enterprise SDK**: Comprehensive SmartNode integration with full TypeScript support and enterprise-grade reliability.

**🌐 Multi-Ledger Ready**: Extensible architecture supporting Hedera Hashgraph with planned Ripple integration.

**⚡ Developer Focused**: Type-safe APIs with comprehensive documentation and extensive example implementations.

***

<p align="center">Built with ❤️ by the HSuite Team<br>Copyright © 2025 HSuite. All rights reserved.</p>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hsuite.network/developers/libs/smartnode-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.