npm package: @hyra-ai/hyra-client
Description: Official Node.js SDK for the Hyra Network - a decentralized AI inference platform
Author: hyra-ai
Latest version: 0.1.10

# Hyra Node.js SDK

Official Node.js SDK for the Hyra Network - a decentralized AI inference platform powered by zero-knowledge proofs.

## Installation

```bash
npm install @hyra-ai/hyra-client
# or
yarn add @hyra-ai/hyra-client
# or
pnpm add @hyra-ai/hyra-client
# or
bun add @hyra-ai/hyra-client
```

## Quick Start

```typescript
import { HyraClient } from '@hyra-ai/hyra-client';

// Initialize the client with your private key
const privateKey = '0x...'; // Your Ethereum private key
const client = new HyraClient(privateKey);

// Claim a task
const task = await client.claimTask();
console.log('Task claimed:', task);

// Submit the task result
const txHash = await client.submitTask(task.taskId, 'Your AI inference result');
console.log('Task submitted:', txHash);
```

## API Reference

### `HyraClient`

Main client class for interacting with the Hyra Network.

#### Constructor

```typescript
constructor(privateKey: string)
```

- `privateKey`: Your Ethereum private key (must start with `0x`)

#### Methods

##### `claimTask()`

Claims an available task from the network. If you already have an active task, it returns the current task details.

**Returns:** Promise resolving to a task object with the following structure:

```typescript
{
  taskId: number;
  taskPool: string;
  reward: string; // Reward in ETH (formatted)
  deadline: string; // ISO 8601 timestamp
  assignedTo: string; // Wallet address
  requestId: number;
  model: {
    id: number;
    type: string;
    url: string;
    pricingType: number;
    isActive: boolean;
    createdAt: string; // ISO 8601 timestamp
    tokenPrice: string; // Price in ETH (formatted)
  };
  inputRawData: string;
  inputDecryptedData: string; // Decrypted input data for AI processing
}
```

**Example:**

```typescript
const task = await client.claimTask();
console.log('Task ID:', task.taskId);
console.log('Model:', task.model.type);
console.log('Input:', task.inputDecryptedData);
```

##### `submitTask(taskId: number, result: string)`

Submits the result of a completed AI inference task. The result is encrypted and includes a zero-knowledge proof.

**Parameters:**

- `taskId`: The ID of the task to submit
- `result`: The AI inference result as a string

**Returns:** Promise resolving to the transaction hash (string)

**Example:**

```typescript
const task = await client.claimTask();
// ... process the task with your AI model ...
const result = 'Your AI inference result here';
const txHash = await client.submitTask(task.taskId, result);
console.log('Transaction hash:', txHash);
```

##### `currentStatus()`

Gets the current status of your active task.

**Returns:** Promise resolving to user status object:

```typescript
{
  activePool: string;
  activeTaskId: number;
  deadline: string; // ISO 8601 timestamp
  reward: number; // Reward in ETH
  hasActiveTask: boolean;
}
```

**Example:**

```typescript
const status = await client.currentStatus();
if (status.hasActiveTask) {
  console.log('Active task ID:', status.activeTaskId);
  console.log('Deadline:', status.deadline);
  console.log('Reward:', status.reward);
}
```

##### `taskDetails(poolAddress: string, taskId: number)`

Gets detailed information about a specific task in a pool.

**Parameters:**

- `poolAddress`: The address of the task pool
- `taskId`: The ID of the task

**Returns:** Promise resolving to task details object:

```typescript
{
  taskId: number;
  reward: number; // Reward in ETH
  deadline: string; // ISO 8601 timestamp
  assignedTo: string; // Wallet address
  requestId: number;
  model: {
    id: number;
    type: string;
    url: string;
  };
}
```

**Example:**

```typescript
const details = await client.taskDetails('0x...', 123);
console.log('Task reward:', details.reward);
console.log('Model:', details.model.type);
```

##### `getPoolsStatus()`

Gets global statistics about all pools in the network.

**Returns:** Promise resolving to pool statistics:

```typescript
{
  totalPools: number;
  activePools: number;
  totalAvailableTasks: number;
  totalActiveTasks: number;
  totalPendingTasks: number;
  totalProcessedTasks: number;
  totalRewardsDistributed: number; // Total rewards in ETH
}
```

**Example:**

```typescript
const stats = await client.getPoolsStatus();
console.log('Total pools:', stats.totalPools);
console.log('Available tasks:', stats.totalAvailableTasks);
```

##### `estimateClaimGas(poolAddress: string)`

Estimates the gas cost for claiming a task from a specific pool.

**Parameters:**

- `poolAddress`: The address of the task pool

**Returns:** Promise resolving to the estimated gas cost (bigint)

**Example:**

```typescript
const gasEstimate = await client.estimateClaimGas('0x...');
console.log('Estimated gas:', gasEstimate.toString());
```

##### `getContractAddresses()`

Gets the addresses of all deployed contracts used by the SDK.

**Returns:** Object containing contract addresses:

```typescript
{
  poolRouter: string;
  modelRegistry: string;
  publicKeyVault: string;
}
```

**Example:**

```typescript
const addresses = client.getContractAddresses();
console.log('Pool Router:', addresses.poolRouter);
```

##### `getActiveModels()`

Gets a list of all active model IDs in the registry.

**Returns:** Promise resolving to an array of model IDs (strings)

**Example:**

```typescript
const modelIds = await client.getActiveModels();
console.log('Active models:', modelIds);
```

##### `getModelDetail(modelId: string)`

Gets detailed information about a specific AI model.

**Parameters:**

- `modelId`: The ID of the model

**Returns:** Promise resolving to model details:

```typescript
{
  name: string;
  description: string;
  modelPricingType: number;
  isActive: boolean;
  createdAt: number; // Unix timestamp
  tokenPrice: number; // Price in ETH
}
```

**Example:**

```typescript
const model = await client.getModelDetail('1');
console.log('Model name:', model.name);
console.log('Price:', model.tokenPrice);
```

##### `getInferenceRequest(requestId: number)`

Gets details about a specific inference request.

**Parameters:**

- `requestId`: The ID of the inference request

**Returns:** Promise resolving to request details:

```typescript
{
  user: string; // Wallet address of the requester
  modelId: string;
  prompt: string;
  tokenCount: number;
  totalCost: number; // Cost in ETH
  timestamp: number; // Unix timestamp
  resultData: string;
  hasResult: boolean;
}
```

**Example:**

```typescript
const request = await client.getInferenceRequest(123);
console.log('Prompt:', request.prompt);
console.log('Has result:', request.hasResult);
```

##### `supportedModels()`

Get list of supported AI models (coming soon).

## Features

- 🔐 **Secure**: End-to-end encryption for task data
- 🔒 **Zero-Knowledge Proofs**: ZKP verification for AI inference results
- ⚡ **Fast**: Optimized for performance
- 📦 **TypeScript**: Full TypeScript support with type definitions
- 🌐 **Blockchain**: Built on Ethereum-compatible networks

## Requirements

- Node.js 18+ or Bun
- An Ethereum wallet with a private key
- Sufficient balance for gas fees

## Network Configuration

The SDK is currently configured for the Hyra testnet:

- RPC URL: `https://rpc-testnet.hyra.network`
- Chain ID: `34131050525`

## Error Handling

All methods throw errors that should be caught:

```typescript
try {
  const task = await client.claimTask();
} catch (error) {
  console.error('Error claiming task:', error.message);
}
```

Common errors:

- `"No active task found"`: No task is currently assigned
- `"Task ID mismatch"`: The task ID doesn't match your active task
- `"Failed to decrypt input data"`: Decryption service error
- `"Failed to generate proof"`: ZKP generation failed
- `"Failed to get model details"`: Model not found or inactive
- `"Failed to get task details"`: Task not found in the specified pool

## Development

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run in development mode
bun run dev
```

## License

MIT

## Support

For issues and questions, please open an issue on the GitHub repository.