Hyra Node.js SDK

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

Installation

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

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

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:

{
  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:

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:

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:

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

Example:

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:

{
  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:

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:

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

Example:

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:

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:

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

Example:

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:

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:

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

Example:

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:

{
  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:

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:

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

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