Rating System

Overview

The rating system in IOTA Repstation allows parties to rate each other after completing a deal. Ratings are permanent, blockchain-recorded assessments that build into reputation profiles over time.

Rating Requirements

Deal-Bound Ratings

All ratings must be tied to a specific deal:

Deal must be in CLOSED state
Only deal participants can rate each other
Each participant can rate the other party once per deal
Ratings reference the specific deal and subject

Score Range

Ratings use a standardized 1-100 score system:

1-20: Very Poor
21-40: Poor
41-60: Average
61-80: Good
81-100: Excellent

Rating Categories

Categories help organize different aspects of performance:

Common Categories

reliability - Did they deliver as promised?
communication - How well did they communicate?
quality - Was the work/product high quality?
speed - How quickly did they complete the work?
professionalism - Were they professional throughout?

Custom Categories

Applications can define their own categories:

// NFT Marketplace
const categories = [
  'artwork_quality',
  'authenticity',
  'shipping_speed',
  'packaging'
];

// Service Platform  
const categories = [
  'technical_skill',
  'deadline_adherence', 
  'code_quality',
  'project_management'
];

Creating Ratings

Basic Rating

const { endorsement_id } = await client.rate({
  signer: raterWallet,
  deal_id: completedDealId,
  score: 85,
  category: 'reliability'
});

Multiple Category Ratings

Rate different aspects separately:

// Rate communication
await client.rate({
  signer: buyerWallet,
  deal_id: dealId,
  score: 92,
  category: 'communication'
});

// Rate delivery speed
await client.rate({
  signer: buyerWallet,
  deal_id: dealId,
  score: 78,
  category: 'speed'
});

// Rate product quality
await client.rate({
  signer: buyerWallet,
  deal_id: dealId,
  score: 95,
  category: 'quality'
});

Rating Management

Updating Ratings

Ratings can be updated using the endorsement capability:

await client.updateRating({
  signer: raterWallet,
  endorsement_id: endorsementId,
  endorsement_cap_id: endorsementCapId,
  new_score: 90, // Updated score
});

Revoking Ratings

Ratings can be completely revoked:

await client.revokeRating({
  signer: raterWallet,
  endorsement_id: endorsementId,
  endorsement_cap_id: endorsementCapId
});

Revoked ratings are permanently removed and cannot be restored. Use updates instead of revocation when possible.

Rating Aggregation

Global Reputation

All ratings for a user are aggregated globally:

const profile = await client.getReputationProfile({
  walletAddress: userWallet
});

console.log(`Global average: ${profile.global.average}/100`);
console.log(`Total ratings: ${profile.global.count}`);

App-Scoped Reputation

Ratings are also tracked per application:

// Each app namespace maintains separate stats
profile.appScoped.forEach(app => {
  console.log(`App: ${app.appOwner}`);
  console.log(`Average: ${app.stats.average}/100`);
  console.log(`Count: ${app.stats.count}`);
});

Rating Data Structure

Endorsement Object

interface Endorsement {
  id: string;
  rater: string;           // Wallet address of rater
  deal_id: string;         // Associated deal
  score: number;           // 1-100 rating score
  category: string;        // Rating category
  timestamp: string;       // When rating was created
  last_updated?: string;   // When rating was last modified
}

Rating Statistics

interface RatingStats {
  average: number;         // Average of all ratings
  count: number;          // Total number of ratings
  distribution?: {        // Optional score distribution
    excellent: number;    // 81-100 scores
    good: number;        // 61-80 scores  
    average: number;     // 41-60 scores
    poor: number;        // 21-40 scores
    very_poor: number;   // 1-20 scores
  };
}

Best Practices

1. Meaningful Categories

Use categories that matter to your use case:

// Good for marketplaces
const marketplaceCategories = [
  'product_quality',
  'shipping_speed', 
  'customer_service',
  'value_for_money'
];

// Good for freelancing
const freelanceCategories = [
  'skill_level',
  'communication',
  'deadline_compliance',
  'work_quality'
];

2. Encourage Honest Ratings

Design your UI to promote fair ratings:

function RatingComponent({ onSubmit }) {
  const [scores, setScores] = useState({});
  
  return (
    <div className="rating-form">
      <h3>Rate Your Experience</h3>
      
      <RatingSlider
        label="Communication (How well did they communicate?)"
        value={scores.communication || 50}
        onChange={(score) => setScores({...scores, communication: score})}
        helpText="Consider responsiveness, clarity, and professionalism"
      />
      
      <RatingSlider
        label="Quality (How was the work quality?)"  
        value={scores.quality || 50}
        onChange={(score) => setScores({...scores, quality: score})}
        helpText="Consider attention to detail and meeting requirements"
      />
      
      <button onClick={() => submitRatings(scores)}>
        Submit Ratings
      </button>
    </div>
  );
}

3. Rating Timing

Prompt for ratings at the right time:

class OrderService {
  async markOrderDelivered(orderId: string) {
    const order = await this.getOrder(orderId);
    
    // Close the deal first
    await this.reputation.closeDeal({
      signer: this.adminWallet,
      deal_id: order.reputationDealId
    });
    
    // Send rating reminders after short delay
    setTimeout(() => {
      this.sendRatingReminder(order.buyerId, order.id);
      this.sendRatingReminder(order.sellerId, order.id);
    }, 24 * 60 * 60 * 1000); // 24 hours
  }
}

Error Handling

Common rating errors:

try {
  await client.rate({
    signer: wallet,
    deal_id: dealId,
    score: score,
    category: category
  });
} catch (error) {
  switch (error.code) {
    case 'DEAL_NOT_CLOSED':
      showError('Deal must be completed before rating');
      break;
    case 'ALREADY_RATED':
      showError('You have already rated this deal. Use update instead.');
      break;
    case 'NOT_DEAL_PARTICIPANT':
      showError('Only deal participants can rate each other');
      break;
    case 'INVALID_SCORE':
      showError('Rating must be between 1 and 100');
      break;
    case 'CANNOT_RATE_SELF':
      showError('You cannot rate yourself');
      break;
  }
}

Integration Examples

E-commerce Rating Flow

class EcommerceRatings {
  async handleOrderCompletion(orderId: string) {
    const order = await this.db.orders.findById(orderId);
    
    // Close reputation deal
    await this.reputation.closeDeal({
      signer: this.adminWallet,
      deal_id: order.reputationDealId
    });
    
    // Enable rating UI for both parties
    await this.enableRatings(order.buyerId, order.sellerId, order.id);
  }
  
  async submitBuyerRating(buyerId: string, orderId: string, ratings: any) {
    const order = await this.db.orders.findById(orderId);
    
    // Rate seller on multiple categories
    for (const [category, score] of Object.entries(ratings)) {
      await this.reputation.rate({
        signer: buyerId,
        deal_id: order.reputationDealId,
        score: score as number,
        category
      });
    }
  }
}

Service Platform Ratings

class ServiceRatings {
  async completeProject(projectId: string, clientId: string, providerId: string) {
    const project = await this.getProject(projectId);
    
    // Close deal
    await this.reputation.closeDeal({
      signer: clientId,
      deal_id: project.dealId
    });
    
    // Client rates provider
    await this.reputation.rate({
      signer: clientId,
      deal_id: project.dealId,
      score: project.clientRating.skill,
      category: 'technical_skill'
    });
    
    // Provider rates client
    await this.reputation.rate({
      signer: providerId,
      deal_id: project.dealId,
      score: project.providerRating.clarity,
      category: 'requirements_clarity'
    });
  }
}

Next Steps

Reputation Profiles

Learn how ratings build into comprehensive reputation profiles.

Rating API

Explore the complete rating management API.

Deal Management

Understand the deal lifecycle that enables ratings.

Integration Guide

Build rating interfaces for your application.

Getting Started

Core Concepts

Integration Guide

Examples

Overview

Rating Requirements

Deal-Bound Ratings

Score Range

Rating Categories

Common Categories

Custom Categories

Creating Ratings

Basic Rating

Multiple Category Ratings

Rating Management

Updating Ratings

Revoking Ratings

Rating Aggregation

Global Reputation

App-Scoped Reputation

Rating Data Structure

Endorsement Object

Rating Statistics

Best Practices

1. Meaningful Categories

2. Encourage Honest Ratings

3. Rating Timing

Error Handling

Integration Examples

E-commerce Rating Flow

Service Platform Ratings

Next Steps

Reputation Profiles

Rating API

Deal Management

Integration Guide

​Overview

​Rating Requirements

​Deal-Bound Ratings

​Score Range

​Rating Categories

​Common Categories

​Custom Categories

​Creating Ratings

​Basic Rating

​Multiple Category Ratings

​Rating Management

​Updating Ratings

​Revoking Ratings

​Rating Aggregation

​Global Reputation

​App-Scoped Reputation

​Rating Data Structure

​Endorsement Object

​Rating Statistics

​Best Practices

​1. Meaningful Categories

​2. Encourage Honest Ratings

​3. Rating Timing

​Error Handling

​Integration Examples

​E-commerce Rating Flow

​Service Platform Ratings

​Next Steps

Reputation Profiles

Rating API

Deal Management

Integration Guide

Overview

Rating Requirements

Deal-Bound Ratings

Score Range

Rating Categories

Common Categories

Custom Categories

Creating Ratings

Basic Rating

Multiple Category Ratings

Rating Management

Updating Ratings

Revoking Ratings

Rating Aggregation

Global Reputation

App-Scoped Reputation

Rating Data Structure

Endorsement Object

Rating Statistics

Best Practices

1. Meaningful Categories

2. Encourage Honest Ratings

3. Rating Timing

Error Handling

Integration Examples

E-commerce Rating Flow

Service Platform Ratings

Next Steps