# @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>


---

# 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/validators-types.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.