feat: Implement TEE reputation system (#49)

[addnad]

Implements a comprehensive on-chain reputation system for TEEs that tracks performance metrics and provides reputation scores to help clients intelligently select the best TEEs for inference requests.

Problem

Issue #49: OpenGradient needs a way to track successful/failed requests, downtime, etc. by TEEs to help clients decide which one is best to use, and potentially blacklist problematic ones.

Solution

Created TEEReputation.sol - a smart contract that:

Core Features

• Performance Tracking: Monitors per-TEE statistics

  • Total requests, successful requests, failed requests
  • Average response time (moving average)
  • Request timestamps for historical analysis

• Downtime Monitoring: Records downtime windows with audit trail

  • Purpose: "heartbeat_missed", "pcr_revoked", "manual_disable"
  • Tracks total downtime seconds per TEE
  • Maintains complete history for auditing

• Reputation Scoring: Weighted algorithm combining three metrics

  • Success rate: 50% weight (successful / total requests)
  • Uptime ratio: 35% weight (uptime / total time)
  • Response quality: 15% weight (based on average response time)
  • Scale: 0-10000 (fixed-point, divide by 100 for percentage)

• Reputation Tiers: Four-tier classification

  • Poor (0-3999): Below 40% reputation
  • Fair (4000-6999): 40-70% reputation
  • Good (7000-8999): 70-90% reputation
  • Excellent (9000+): 90%+ reputation

• Client Query API: Find best TEEs by reputation

  • getTopTEEsByReputation(teeType, minTier, limit) - get top rated TEEs
  • Sorted by reputation score, filtered by tier requirement
  • Returns both TEE IDs and their reputation scores

Configuration

• Admin Controls: Configurable weights and thresholds

  • Adjust scoring formula weights on-the-fly
  • Tune tier thresholds based on network evolution
  • updateWeights() and updateTierThresholds()

• Role-Based Access Control

  • SETTLEMENT_RECORDER_ROLE - off-chain indexer records settlements
  • HEARTBEAT_MONITOR_ROLE - monitor service tracks downtime
  • DEFAULT_ADMIN_ROLE - manage configuration

Integration

Off-Chain Services Required

1. Settlement Indexer

   • Listens to InferenceSettlementRelay.IndividualSettlement events
   • Queries result from Walrus/IPFS to determine success/failure
   • Calls recordSettlement(teeId, successful, responseTimeMs)

2. Heartbeat Monitor

   • Periodically checks TEE heartbeat freshness (max 30 min via TEERegistry)
   • Calls recordDowntime(teeId, 0, "heartbeat_missed") when stale
   • Calls resolveDowntime(teeId) when heartbeat received

No Breaking Changes

• Existing contracts (TEERegistry, InferenceSettlementRelay) unchanged
• Reputation contract reads from existing contracts, minimal coupling
• Purely additive feature

Testing

Comprehensive test suite included (TEEReputation.t.sol):

• ✅ Settlement recording (success/fail, multiple, response time averaging)
• ✅ Downtime tracking (record, resolve, multiple windows)
• ✅ Reputation calculation (no data, perfect record, with failures, with downtime)
• ✅ Configuration (weights, tier thresholds)
• ✅ Access control (role-based restrictions)
• ✅ Integration scenarios (end-to-end flow)

Files Changed

• contracts/solidity/TEEReputation.sol (450 lines) - Main contract
• contracts/solidity/tests/TEEReputation.t.sol (350+ lines) - Test suite
• contracts/solidity/TEE_REPUTATION_GUIDE.md (400+ lines) - Integration documentation

Documentation

Included detailed guide (TEE_REPUTATION_GUIDE.md):

• Architecture overview with data flow diagrams
• Step-by-step deployment instructions
• Off-chain service setup code examples (JavaScript)
• Usage examples for clients and administrators
• Role assignment and permission setup
• Deployment checklist
• Future enhancement suggestions

Impact

✅ Solves issue #49 completely
✅ Enables intelligent TEE selection for clients
✅ Provides basis for future reputation-based incentives/slashing
✅ Fully self-contained, no external dependencies
✅ Gas-efficient (cached scores, batch-friendly)

Deployment Steps

1. Deploy contract with TEERegistry address
2. Grant roles to indexer and monitor services
3. Configure initial weights (optional)
4. Start off-chain services
5. Update client SDKs to use getTopTEEsByReputation()

See TEE_REPUTATION_GUIDE.md for detailed checklist.

Resolves #49