Crate kaccy_reputation 

Kaccy Reputation System

A comprehensive, production-ready reputation system for the Kaccy Protocol that provides scoring, commitment tracking, tier management, and advanced analytics.

Overview

The reputation system enables users to build trust through verifiable commitments and track their standing within the community. It includes sophisticated features like:

• Dynamic Scoring: Multi-component reputation scoring (0-1000 scale)
• Tier System: 6 tiers from Unverified to Diamond with progressive benefits
• Commitment Tracking: Create, verify, and track deliverable commitments
• Circuit Breaker: Automatic protection against low-reputation actors
• Caching Layer: High-performance in-memory caching
• Analytics: System-wide statistics and user insights
• Export/Import: Data portability and backup support

Quick Start

use kaccy_reputation::*;
use rust_decimal_macros::dec;

// Calculate a reputation score from components
let components = ScoreComponents {
    commitment_fulfillment: dec!(85.0),  // 35% weight
    response_time: dec!(75.0),           // 15% weight
    quality_rating: dec!(90.0),          // 30% weight
    community_trust: dec!(80.0),         // 15% weight
    longevity: dec!(70.0),               // 5% weight
};

let overall = components.calculate_overall();      // Weighted average (0-100)
let score = components.calculate_scaled_overall(); // Scaled to 0-1000

// Determine tier from score
let tier = ReputationTier::from_score(score);
let benefits = tier.benefits();

println!("Score: {}, Tier: {}, Can issue tokens: {}",
         score, tier, benefits.can_issue_tokens);

Architecture

The crate is organized into several key subsystems:

Core Reputation System

• score - Reputation scoring and calculation
• tier - Tier system and benefits
• circuit_breaker - Automatic restrictions for low reputation
• confidence - Data confidence tracking and weighting

Commitment System

• commitment - Basic commitment tracking
• milestone - Milestone-based commitments
• recurring - Recurring commitment schedules
• templates - Pre-defined commitment templates

Advanced Features

• cache - In-memory caching for performance
• events - Event sourcing and notifications
• holder_ratings - Community trust ratings
• time_decay - Inactivity-based score decay

AI & Verification

• ai_scoring - AI-assisted quality evaluation
• dispute - Dispute resolution and appeals
• sbt - Soulbound token integration
• portability - Cross-platform reputation import/export

Analytics & Monitoring

• analytics - System-wide statistics
• audit - Comprehensive audit trail
• batch - High-performance bulk operations
• leaderboard - Rankings and achievements
• maintenance - Health checks and data integrity

Integration

• integration - High-level orchestration layer (ReputationOrchestrator)
• validation - Input validation utilities
• export_import - Data export and import

Performance Considerations

• Use ReputationCache for frequently accessed scores (reduces database load)
• Run batch operations during off-peak hours
• Set appropriate cache TTL based on your update frequency
• Use database indexes (see migrations) for optimal query performance

Error Handling

All operations return Result<T, ReputationError>. See error::ReputationError for comprehensive error types and handling patterns.

Examples

See the examples/ directory for comprehensive usage examples:

• basic_reputation_management - Core concepts and workflows
• commitment_lifecycle - Managing commitments
• caching_integration - Performance optimization
• advanced_analytics - Statistics and insights
• export_import - Data portability

Feature Flags

This crate has no optional features. All functionality is included by default.

Re-exports

pub use cache::CacheCleanupStats;

pub use cache::CacheStats;

pub use cache::CachedScore;

pub use cache::CachedTier;

pub use cache::ReputationCache;

pub use circuit_breaker::CircuitBreaker;

pub use circuit_breaker::CircuitBreakerAction;

pub use circuit_breaker::CircuitBreakerStatus;

pub use commitment::CommitmentService;

pub use commitment::CommitmentStatus;

pub use commitment::CreateCommitmentRequest;

pub use commitment::CreateCommitmentRequestBuilder;

pub use commitment::OutputCommitment;

pub use commitment::SubmitEvidenceRequest;

pub use commitment::VerifyCommitmentRequest;

pub use confidence::ComponentConfidence;

pub use confidence::ConfidenceBreakdown;

pub use confidence::ConfidenceLevel;

pub use confidence::ConfidenceTracker;

pub use confidence::WeightedScore;

pub use error::ReputationError;

pub use events::CreateEventRequest;

pub use events::EventService;

pub use events::EventSummary;

pub use events::EventType;

pub use events::NotificationHandler;

pub use events::NotificationSeverity;

pub use events::RecalculatedScore;

pub use events::ReputationEvent;

pub use events::ScoreNotification;

pub use export_import::BulkReputationExport;

pub use export_import::CommitmentExport;

pub use export_import::EventExport;

pub use export_import::ExportImportService;

pub use export_import::ExportStats;

pub use export_import::RatingExport;

pub use export_import::ScoreHistoryExport;

pub use export_import::TierHistoryExport;

pub use export_import::UserReputationExport;

pub use history::TierHistoryRecord;

pub use history::TierHistoryRepository;

pub use history::TierHistorySummary;

pub use history::TierTracker;

pub use holder_ratings::HolderRating;

pub use holder_ratings::HolderRatingService;

pub use holder_ratings::RatingDistribution;

pub use holder_ratings::RatingRequest;

pub use holder_ratings::RatingStats;

pub use milestone::CreateMilestoneCommitmentRequest;

pub use milestone::Milestone;

pub use milestone::MilestoneCommitment;

pub use milestone::MilestoneService;

pub use milestone::MilestoneStatus;

pub use recurring::CreateRecurringRequest;

pub use recurring::GeneratedCommitment;

pub use recurring::RecurrenceFrequency;

pub use recurring::RecurringCommitment;

pub use recurring::RecurringCommitmentService;

pub use recurring::RecurringSummary;

pub use recurring::UpcomingDeadline;

pub use score_history::ScoreHistoryRepository;

pub use score_history::ScoreSnapshot;

pub use score_history::ScoreTrend;

pub use score_history::TrendDirection;

pub use templates::CategoryCount;

pub use templates::CommitmentTemplate;

pub use templates::CreateFromTemplateRequest;

pub use templates::CreateTemplateRequest;

pub use templates::TemplateCategory;

pub use templates::TemplateService;

pub use templates::TemplateSummary;

pub use templates::TemplateUsage;

pub use time_decay::DecayConfig;

pub use time_decay::TimeDecayService;

pub use ai_scoring::AIScoringService;

pub use ai_scoring::AspectScores;

pub use ai_scoring::DetectFraudRequest;

pub use ai_scoring::EvaluateQualityRequest;

pub use ai_scoring::FraudDetection;

pub use ai_scoring::FraudPattern;

pub use ai_scoring::PredictSuccessRequest;

pub use ai_scoring::PredictionFactor;

pub use ai_scoring::QualityEvaluation;

pub use ai_scoring::QualityFlag;

pub use ai_scoring::SuccessPrediction;

pub use dispute::Appeal;

pub use dispute::AppealStatus;

pub use dispute::CreateAppealRequest;

pub use dispute::CreateDisputeRequest;

pub use dispute::Dispute;

pub use dispute::DisputeOutcome;

pub use dispute::DisputeResults;

pub use dispute::DisputeService;

pub use dispute::DisputeStatus;

pub use dispute::DisputeVote;

pub use dispute::VoteChoice;

pub use dispute::VoteDisputeRequest;

pub use portability::CredentialProof;

pub use portability::CredentialSubject;

pub use portability::ExportReputationRequest;

pub use portability::ExternalReputation;

pub use portability::GitHubReputation;

pub use portability::ImportReputationRequest;

pub use portability::ImportResult;

pub use portability::LinkedInReputation;

pub use portability::Platform;

pub use portability::PortabilityService;

pub use portability::StackOverflowReputation;

pub use portability::VerifiableCredential;

pub use sbt::MintSBTRequest;

pub use sbt::OnChainSBT;

pub use sbt::SBTAttribute;

pub use sbt::SBTMetadata;

pub use sbt::SBTService;

pub use sbt::SoulboundToken;

pub use sbt::UpdateSBTRequest;

pub use analytics::AnalyticsService;

pub use analytics::GrowthMetrics;

pub use analytics::ScoreDistribution;

pub use analytics::SystemStats;

pub use analytics::TierCount;

pub use analytics::UserCommitmentAnalytics;

pub use analytics::UserRanking;

pub use audit::AuditEvent;

pub use audit::AuditEventType;

pub use audit::AuditRecord;

pub use audit::AuditSearch;

pub use audit::AuditService;

pub use audit::AuditSummary;

pub use audit::EntityType;

pub use audit::EventTypeCount;

pub use batch::BatchDecayResult;

pub use batch::BatchExpireResult;

pub use batch::BatchScoreResult;

pub use batch::BatchService;

pub use batch::BatchVerifyResult;

pub use batch::FailedOperation;

pub use batch::FailedVerification;

pub use batch::LowScoreUser;

pub use batch::PendingCommitmentInfo;

pub use batch::ScoreUpdate;

pub use leaderboard::Achievement;

pub use leaderboard::AchievementType;

pub use leaderboard::AwardedAchievement;

pub use leaderboard::Leaderboard;

pub use leaderboard::LeaderboardEntry;

pub use leaderboard::LeaderboardService;

pub use leaderboard::LeaderboardType;

pub use leaderboard::UserRankInfo;

pub use maintenance::HealthCheckReport;

pub use maintenance::MaintenanceReport;

pub use maintenance::MaintenanceService;

pub use integration::AnalyticsDashboard;

pub use integration::BulkVerificationReport;

pub use integration::CompleteReputationProfile;

pub use integration::ComprehensiveUserProfile;

pub use integration::CrisisResponse;

pub use integration::CrisisSeverity;

pub use integration::CrisisType;

pub use integration::DailyMaintenanceReport;

pub use integration::InterventionAction;

pub use integration::InterventionReport;

pub use integration::InterventionType;

pub use integration::PerformanceMetrics;

pub use integration::ReputationOrchestrator;

pub use integration::SystemHealthReport;

pub use integration::UserActivityReport;

pub use integration::UserOnboardingReport;

pub use query_builder::CommitmentQueryBuilder;

pub use query_builder::EventQueryBuilder;

pub use query_builder::LeaderboardQueryBuilder;

pub use query_builder::QueryResult;

pub use statistics::ComponentCorrelation;

pub use statistics::MovingAverage;

pub use statistics::Percentiles;

pub use statistics::Quartiles;

pub use statistics::ScoreStatistics;

pub use statistics::ScoreVolatility;

pub use statistics::Statistics;

pub use statistics::TrendAnalysis;

pub use statistics::TrendMomentum;

pub use score::*;

pub use tier::*;

pub use validation::*;

Modules

ai_scoring

AI-Assisted Scoring for automatic quality evaluation and fraud detection

analytics

Analytics module for reputation system insights

audit

Audit trail module for comprehensive change tracking

batch

Batch operations module for efficient bulk processing

cache

Caching Layer for Reputation Data

circuit_breaker

Circuit breaker for low reputation

commitment

Commitment tracking

confidence

Component confidence tracking

dispute

Dispute Resolution system for commitment verification challenges

error

Reputation error types

events

Reputation events module - event sourcing and notifications

export_import

Bulk export and import utilities for reputation data

history

Tier history tracking

holder_ratings

Holder ratings system

integration

Integration module for coordinating all reputation system features

leaderboard

Leaderboard module for competitive rankings and achievements

maintenance

Maintenance module for automated periodic tasks

milestone

Milestone commitments

portability

Reputation Portability for importing and exporting reputation data

query_builder

Query builders for advanced filtering and searching

recurring

Recurring commitments module

sbt

Soulbound Token (SBT) implementation for on-chain reputation

score

Reputation score calculation

score_history

Score history tracking with daily snapshots

statistics

Statistical analysis module for reputation data

templates

Commitment templates module

tier

Reputation tiers

time_decay

Time-based reputation decay

validation

Input Validation Utilities