Skip to content

BLOCKCHAIN_INTEGRATION.md

Latest commit

 

History

History
290 lines (216 loc) · 8.49 KB

BLOCKCHAIN_INTEGRATION.md

File metadata and controls

290 lines (216 loc) · 8.49 KB
Raw

🔗 Blockchain Integration Documentation

Overview

This integration connects the AI agent orchestrator system with smart contracts for decentralized agent discovery, payments, and reputation tracking. The system gracefully falls back to traditional operation when blockchain services are unavailable.

🏗️ Architecture

┌─────────────────────┐    ┌─────────────────────┐    ┌─────────────────────┐
│     Frontend        │    │    Orchestrator     │    │   Smart Contracts   │
│                     │    │                     │    │                     │
│ • Wallet Connect    │◄──►│ • Agent Discovery   │◄──►│ • AgentRegistry     │
│ • Rating UI         │    │ • Payment Handling  │    │ • ReputationLayer   │
│ • Blockchain Status │    │ • Reputation Updates│    │ • OrchestrationContract│
└─────────────────────┘    └─────────────────────┘    └─────────────────────┘

🚀 Features Implemented

✅ Smart Contract Integration

  • Agent Registry: Discover agents from blockchain
  • Reputation Layer: Track and rate agent performance
  • Orchestration Contract: Handle payments and task lifecycle

✅ Backend Orchestrator Enhancements

  • Enhanced agent discovery (blockchain + traditional fallback)
  • Automatic task completion recording on blockchain
  • Rating submission API endpoints
  • Blockchain status monitoring

✅ Frontend Integration

  • Wallet connection interface
  • Real-time blockchain status display
  • Rating submission to blockchain
  • Graceful error handling and fallbacks

✅ Graceful Fallbacks

  • Traditional agent discovery when blockchain unavailable
  • Local rating storage when blockchain fails
  • UI continues to work without wallet connection
  • Backend operates normally without blockchain

🔧 Technical Implementation

Smart Contracts (protocol/)

  • Location: protocol/src/
  • Contracts: AgentRegistry, ReputationLayer, OrchestrationContract
  • Tests: Comprehensive test suite with 51 passing tests
  • Deployment: Local Anvil testnet ready

Backend Services

  • BlockchainService (orchestrator/src/BlockchainService.ts)

    • Contract interaction layer
    • Agent discovery from blockchain
    • Task completion recording
    • Reputation data retrieval

  • Enhanced JobRunner (orchestrator/src/JobRunner.ts)

    • Blockchain-enhanced agent discovery
    • Automatic reputation tracking
    • Payment integration hooks

  • API Endpoints (orchestrator/src/server.ts)

    • POST /agents/rate - Submit agent ratings
    • GET /agents/:agentUrl/reputation - Get reputation data
    • GET /blockchain/status - Check blockchain availability
    • POST /feedback/submit - Submit comprehensive feedback

Frontend Integration

  • BlockchainService (frontend/src/services/blockchain.ts)

    • Wallet connection management
    • Contract interaction from frontend
    • User address retrieval

  • Enhanced ResultPanel (frontend/src/components/ResultPanel.tsx)

    • Blockchain rating submission
    • Transaction hash display
    • Fallback to local storage

  • Workflow Page (frontend/src/pages/workflow/index.tsx)

    • Real-time blockchain status
    • Wallet connection UI
    • Feature availability indicators

📋 API Endpoints

Rating & Reputation

// Submit agent rating
POST /agents/rate
{
  "agentUrl": "http://localhost:3001",
  "rating": 5,
  "userAddress": "0x...",
  "feedback": "Great agent!"
}

// Get agent reputation
GET /agents/{agentUrl}/reputation
Returns: {
  "success": true,
  "reputation": {
    "totalTasks": 10,
    "successfulTasks": 9,
    "successRate": 90,
    "averageRating": 4.5,
    "reputationScore": 8500
  }
}

// Submit comprehensive feedback
POST /feedback/submit
{
  "executionId": "exec_123",
  "modelRatings": {
    "DALL-E 3": 5,
    "NFT Deployer": 4
  },
  "overallFeedback": "Excellent workflow!",
  "userAddress": "0x..."
}

Blockchain Status

GET /blockchain/status
Returns: {
  "blockchain": {
    "isAvailable": true,
    "hasWallet": true,
    "features": {
      "agentDiscovery": true,
      "reputationTracking": true,
      "paymentProcessing": true
    }
  }
}

🧪 Testing the Integration

1. Start Local Blockchain

cd protocol
anvil --host 0.0.0.0 --port 8545

2. Deploy Contracts

cd protocol
PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 forge script script/Deploy.s.sol:DeployLocal --rpc-url http://localhost:8545 --broadcast

3. Start Orchestrator with Blockchain

cd orchestrator
export RPC_URL=http://localhost:8545
export ORCHESTRATOR_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
npm start

4. Start Frontend

cd frontend
npm run dev

5. Test Workflow

  1. Visit: http://localhost:5173
  2. Check Status: Blockchain status should show "Connected"
  3. Connect Wallet: Click "Connect Wallet" button
  4. Create Workflow: Use example prompt
  5. Submit Rating: After completion, rate agents
  6. Verify: Check console for blockchain interactions

🔍 Verification Points

Blockchain Integration Working:

  • ✅ Anvil testnet running on port 8545
  • ✅ Contracts deployed successfully
  • ✅ Orchestrator shows "Blockchain: Connected"
  • ✅ Frontend shows blockchain status
  • ✅ Wallet connection works
  • ✅ Rating submission shows transaction hashes

Graceful Fallbacks Working:

  • ✅ Works without anvil running
  • ✅ Works without wallet connected
  • ✅ Rating stored locally when blockchain fails
  • ✅ Agent discovery falls back to HTTP endpoints

🚨 Error Handling

Blockchain Unavailable

  • Agent Discovery: Falls back to configured HTTP endpoints
  • Task Recording: Skipped, logs warning
  • Rating Submission: Stored locally with warning message
  • UI Status: Shows "Blockchain: Offline"

Wallet Not Connected

  • Rating Submission: Uses orchestrator wallet as fallback
  • UI: Shows "Connect Wallet" button
  • Functionality: All features still work

Contract Interaction Failures

  • Network Issues: Retry logic with exponential backoff
  • Gas Failures: Graceful error messages
  • Invalid Data: Validation before submission

🎯 User Experience

With Blockchain Connected:

  1. User sees blockchain status in real-time
  2. Ratings are submitted to blockchain with transaction hashes
  3. Agent reputation is pulled from smart contracts
  4. Payments can be processed through escrow contracts

Without Blockchain:

  1. Traditional workflow execution continues
  2. Ratings stored locally for future blockchain submission
  3. Agent discovery uses configured HTTP endpoints
  4. All UI functionality remains available

🔧 Configuration

Environment Variables

# Orchestrator
RPC_URL=http://localhost:8545
ORCHESTRATOR_PRIVATE_KEY=0x...
AGENT_REGISTRY_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
REPUTATION_LAYER_ADDRESS=0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
ORCHESTRATION_CONTRACT_ADDRESS=0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0

# Frontend
VITE_ORCHESTRATOR_URL=http://localhost:8080

Contract Addresses (Local Development)

  • AgentRegistry: 0x5FbDB2315678afecb367f032d93F642f64180aa3
  • ReputationLayer: 0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512
  • OrchestrationContract: 0x9fE46736679d2D9a65F0992F2272dE9f3c7fa6e0

🎉 Success Metrics

  • ✅ 51 smart contract tests passing
  • ✅ Agent discovery enhanced with blockchain
  • ✅ Rating system integrated with reputation layer
  • ✅ Graceful fallbacks implemented
  • ✅ Real-time blockchain status monitoring
  • ✅ Wallet connection interface
  • ✅ Comprehensive error handling

The integration successfully bridges the AI agent orchestrator with blockchain infrastructure while maintaining backward compatibility and providing excellent user experience regardless of blockchain availability.

🔮 Future Enhancements

  • Agent Registration UI: Allow agents to register via frontend
  • Payment Processing: Full payment flow through OrchestrationContract
  • Multi-chain Support: Support for different blockchain networks
  • IPFS Integration: Store agent metadata on IPFS
  • Governance: DAO for protocol parameter updates