Smart Contracts Overview
Smart Contracts Overview
Section titled “Smart Contracts Overview”The Hyra Network is built on a comprehensive smart contract architecture that enables fully decentralized AI inference with native HYRA token payments, Zero-Knowledge Proof (ZKP) verification, and automated task distribution.
Architecture Overview
Section titled “Architecture Overview”The Hyra Network consists of five core smart contracts that work together to create a complete decentralized AI inference platform:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐│ End Users │ │ AI Workers │ │ Verifiers ││ │ │ │ │ ││ • Request AI │ │ • Claim tasks │ │ • Verify ZKP ││ • Pay HYRA │ │ • Run models │ │ • Pay rewards ││ • Get results │ │ • Submit proofs │ │ • Update results│└─────────────────┘ └─────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼┌─────────────────────────────────────────────────────────────────┐│ HYRA AI Network ││ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ModelRegistry│◄──►│ TaskRouter │◄──►│TaskPool │ ││ │ │ │ │ │ │ ││ │• User reqs │ │• Task dist │ │• Task mgmt │ ││ │• Payments │ │• Worker mgmt│ │• Queues │ ││ │• Results │ │• Pool disc │ │• Rewards │ ││ └─────────────┘ └─────────────┘ └─────────────┘ ││ │ ││ ▼ ││ ┌───────────────┐ ││ │TaskPoolFactory│ ││ │ │ ││ │• Pool creat │ ││ │• Pool mgmt │ ││ └───────────────┘ │└─────────────────────────────────────────────────────────────────┘Core Smart Contracts
Section titled “Core Smart Contracts”1. ModelRegistry
Section titled “1. ModelRegistry”Central contract for managing AI models and user inference requests with automatic task creation.
Key Features:
- Owner-only model registration
- Native HYRA token payments only
- Simple pricing:
price = token_count × token_price - Efficient token calculation: 4 bytes = 1 token
- Automatic AI task creation upon user requests
- Direct integration with TaskRouter and TaskPool
2. TaskPoolFactory
Section titled “2. TaskPoolFactory”Factory contract for creating and managing multiple TaskPool instances using minimal proxy pattern.
Key Features:
- Creates TaskPool clones for gas efficiency
- Manages pool lifecycle (active/inactive)
- Integrates with ModelRegistry for automatic task creation
- Owner and user pool creation
3. TaskPoolImplementation
Section titled “3. TaskPoolImplementation”Core task pool contract that manages AI tasks with full metadata support.
Key Features:
- Extended Task struct with AI-specific fields (requestId, modelId, inputData, resultData)
- Queue management for task distribution
- ZKP verification and reward distribution
- Integration with ModelRegistry for result updates
4. TaskRouter
Section titled “4. TaskRouter”Central router for AI workers to efficiently interact with multiple task pools.
Key Features:
- Best task discovery across all pools
- Pool load balancing and recommendations
- Unified interface for task claiming and submission
- Global statistics and monitoring
5. TaskPoolViewer
Section titled “5. TaskPoolViewer”Utility contract for reading and monitoring task pool data.
Key Features:
- Comprehensive pool data retrieval
- Task statistics and monitoring
- User activity tracking
- Expired task management
Complete Workflow
Section titled “Complete Workflow”1. User Request → User pays HYRA tokens and requests AI inference
Section titled “1. User Request → User pays HYRA tokens and requests AI inference”2. Auto Task Creation → ModelRegistry automatically creates AI task in available TaskPool
Section titled “2. Auto Task Creation → ModelRegistry automatically creates AI task in available TaskPool”3. AI Worker Claims → AI worker claims task via TaskRouter and gets model data
Section titled “3. AI Worker Claims → AI worker claims task via TaskRouter and gets model data”4. AI Processing → AI worker runs the model and generates result + ZKP proof
Section titled “4. AI Processing → AI worker runs the model and generates result + ZKP proof”5. Result Submission → AI worker submits result and proof via TaskRouter
Section titled “5. Result Submission → AI worker submits result and proof via TaskRouter”6. ZKP Verification → Verifier validates the proof and pays rewards
Section titled “6. ZKP Verification → Verifier validates the proof and pays rewards”7. Result Update → ModelRegistry is updated with the final result
Section titled “7. Result Update → ModelRegistry is updated with the final result”8. User Gets Result → User can read the result from ModelRegistry
Section titled “8. User Gets Result → User can read the result from ModelRegistry”Key Benefits
Section titled “Key Benefits”For Users
Section titled “For Users”- Simple Interface: Easy to request AI inference
- Native HYRA Payments: Pay with HYRA tokens
- Transparent Pricing: Clear cost calculation
- Automatic Processing: No manual task management needed
For AI Workers
Section titled “For AI Workers”- Easy Task Discovery: Unified interface via TaskRouter
- Clear Rewards: Transparent reward structure
- Automated Payments: Automatic reward distribution
- Multi-Pool Access: Access tasks from all pools
For Verifiers
Section titled “For Verifiers”- Streamlined Verification: Simple ZKP verification process
- Automated Updates: Automatic result updates
- Clear Workflow: Well-defined verification process
For Platform
Section titled “For Platform”- Fully Decentralized: No single point of failure
- Transparent: All operations on blockchain
- Scalable: Multiple task pools for high throughput
- Secure: ZKP verification prevents cheating
Security Features
Section titled “Security Features”Access Control
Section titled “Access Control”- Owner-only model registration and system configuration
- Verifier-only ZKP validation and reward distribution
- Proper authorization checks with custom modifiers
Reentrancy Protection
Section titled “Reentrancy Protection”- All state-changing functions are protected with ReentrancyGuard
- Safe external calls and proper state management
Input Validation
Section titled “Input Validation”- Comprehensive parameter validation
- Array length checks for batch operations
- Deadline enforcement and task expiration
Emergency Features
Section titled “Emergency Features”- Emergency withdrawal functions
- Task expiration and release mechanisms
- Pool deactivation and reactivation
Gas Optimization
Section titled “Gas Optimization”The contracts are optimized for gas efficiency:
- Custom Errors: Instead of string error messages
- Minimal Proxy Pattern: For TaskPool creation
- Efficient Storage: Optimized struct layout
- Simple Calculations: 4-bytes-per-token calculation
- Enum Usage: For pricing types instead of strings
- Native HYRA Only: No complex ERC20 handling
- Batch Operations: Process multiple items in single transactions
Network Support
Section titled “Network Support”The contracts are compatible with:
- Hyra Network (Layer 3)
- Ethereum Mainnet
- Ethereum Testnets (Sepolia, Goerli)
- Other EVM-compatible chains
Next Steps
Section titled “Next Steps”Ready to dive deeper into the smart contracts? Check out the detailed documentation:
- Model Registry - Learn about AI model management
- Task Pool - Understand task management
- Task Router - Explore task routing
- Task Pool Factory - Learn about pool creation