# @hsuite/validators-types - Validation Type Definitions

A comprehensive TypeScript library providing type-safe validation for Hedera Hashgraph network operations, smart app interactions, and DAO governance.

## Quick Start

```bash
npm install @hsuite/validators-types
```

```typescript
import { IValidators, Validators } from '@hsuite/validators-types';

// Initialize helper
const helper = new Validators.Helper(
  smartConfigService,
  clientService,
  smartLedgersService,
  validatorOptions
);

// Create validators
const accountValidator = new Validators.Account.Create(helper, config);
const tokenValidator = new Validators.Token.Create(helper, config);

// Validate transactions
const result = await accountValidator.validate(transaction, { params });
```

## Documentation

### Complete Developer Guide

Comprehensive documentation covering all aspects of the library including:

* **Quick Start Guide** - Get up and running in 5 minutes
* **Architecture Overview** - Understand the dual-namespace design
* **Domain-Specific Guides** - Deep dive into account, token, and consensus validation
* **API Reference** - Complete interface and model documentation
* **Usage Examples** - Real-world implementation examples
* **Configuration** - Advanced setup and customization
* **Testing Patterns** - Unit and integration testing approaches
* **Best Practices** - Recommended patterns and practices

### Quick Access Guides

#### Quick Start

5-minute setup guide with practical examples for each validation domain.

#### Architecture Overview

System design principles, dual-namespace architecture, and extension points.

#### Account Validation

Account operations, security features, token gates, and multi-signature support.

#### Token Validation (HTS)

Token lifecycle, custom fees, compliance controls, and economic features.

#### Consensus Validation (HCS)

Topic management, message validation, access control, and security enforcement.

### API Reference

* **Interfaces** - TypeScript interface definitions and contracts
* **Models** - Implementation models and concrete validators
* **Enums** - Transaction types and enumeration definitions

## Key Features

### Dual Namespace Architecture

* **Interfaces** (`IValidators`) - Type contracts and definitions
* **Models** (`Validators`) - Concrete implementations and runtime logic
* Clean separation of concerns with full TypeScript support

### Comprehensive Validation

* **Account Operations** - Creation, updates, transfers, allowances
* **Token Operations** - HTS lifecycle, supply, compliance, fees
* **Consensus Operations** - HCS topics, messages, access control
* **Security Enforcement** - Multi-level security controls

### Advanced Features

* **Token Gates** - Access control based on token ownership
* **Custom Fees** - Fixed, fractional, and royalty fee structures
* **Smart Node Security** - Multi-level security enforcement
* **Network Integration** - Real-time network queries and validation

### Developer Experience

* **Type Safety** - Full TypeScript support with strict typing
* **Extensible** - Plugin architecture for custom validators
* **Testable** - Comprehensive testing patterns and utilities
* **NestJS Integration** - First-class framework support

## Supported Operations

| Domain              | Operations                                   | Features                                   |
| ------------------- | -------------------------------------------- | ------------------------------------------ |
| **Account**         | Create, Update, Delete, Transfer, Allowances | Token gates, Multi-sig, Security levels    |
| **Token (HTS)**     | Create, Mint, Burn, Transfer, Freeze, KYC    | Custom fees, Compliance, Supply management |
| **Consensus (HCS)** | Topic CRUD, Message submit                   | Access control, Size validation, Security  |

## Installation & Setup

### Prerequisites

* Node.js 18+
* TypeScript 5.3+
* Hedera SDK (compatible version)

### Installation

```bash
# npm
npm install @hsuite/validators-types

# yarn  
yarn add @hsuite/validators-types

# pnpm
pnpm add @hsuite/validators-types
```

### NestJS Integration

```typescript
@Module({
  imports: [
    ValidatorsTypesModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        network: configService.get('HEDERA_NETWORK'),
      }),
      inject: [ConfigService]
    })
  ]
})
export class AppModule {}
```

## Usage Examples

### Account Creation with Token Gates

```typescript
const validator = new Validators.Account.Create(helper, config);

const params: IValidators.IAccount.IValidationParams = {
  smartNodeSecurity: 'full',
  tokenGates: {
    fungibles: { tokens: ['0.0.123456'] },
    nonFungibles: { tokens: ['0.0.789012'] },
    timeRange: {
      start: Date.now() / 1000,
      end: (Date.now() / 1000) + 86400
    }
  }
};

const result = await validator.validate(transaction, { params });
```

### Token Creation with Custom Fees

```typescript
const validator = new Validators.Token.Create(helper, config);

const feeSchedule: IValidators.IToken.IFeeSchedule = {
  customFees: [
    {
      feeCollectorAccountId: '0.0.98765',
      fractionalFee: {
        numerator: 1,
        denominator: 100, // 1%
        minimumAmount: '10000000',
        maximumAmount: '1000000000'
      }
    }
  ]
};

const result = await validator.validate(transaction, { 
  params: { conditions: { feeSchedule } } 
});
```

### Consensus Message Validation

```typescript
const validator = new Validators.Consensus.Submit(helper, config);

const params: IValidators.IConsensus.ISubmissionParams = {
  messageValidation: {
    maxMessageSize: 1024,
    allowEmptyMessages: false,
    validateEncoding: true
  },
  accessControl: {
    requireSubmitKey: true,
    validateKeySignature: true
  }
};

const result = await validator.validate(transaction, { params });
```

## Testing

```typescript
describe('Token Validator', () => {
  let validator: Validators.Token.Create;
  let mockHelper: jest.Mocked<Validators.Helper>;

  beforeEach(() => {
    mockHelper = {
      getTokenInfo: jest.fn(),
      validateTransactionStructure: jest.fn().mockReturnValue(true)
    } as any;

    validator = new Validators.Token.Create(mockHelper, mockConfig);
  });

  it('should validate token creation', async () => {
    const result = await validator.validate(transaction, { params });
    expect(result.isValid).toBe(true);
  });
});
```

## Library Statistics

* **Interfaces**: 50+ TypeScript interface definitions
* **Models**: 30+ concrete validator implementations
* **Enums**: 15+ transaction type enumerations
* **Test Coverage**: 95%+ code coverage
* **Documentation**: Comprehensive guides and examples

## Related Libraries

* [**@hsuite/validators**](https://github.com/HSuiteNetwork/validators) - Core validation implementation
* [**@hsuite/smart-config**](https://github.com/HSuiteNetwork/smart-config) - Configuration management
* [**@hsuite/client**](https://github.com/HSuiteNetwork/client) - Hedera client wrapper

## Support & Contributing

* **Issues**: [GitHub Issues](https://github.com/HSuiteNetwork/validators-types/issues)
* **Discussions**: [GitHub Discussions](https://github.com/HSuiteNetwork/validators-types/discussions)
* **Documentation**: Complete implementation and API documentation

## License

MIT License - see [LICENSE](https://github.com/HSuiteNetwork/smart-engines/blob/develop/docs/developers/libs/validators-types/LICENSE/README.md) file for details.

***

**Version**: 2.0.2\
**Compatibility**: Node.js 18+, TypeScript 5.3+\
**Framework Support**: NestJS 10.4+

***

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