Skip to main content

​
What is IOTA Repstation?

IOTA Repstation is a decentralized reputation system built on IOTA’s MoveVM that enables applications to create and manage transparent, portable reputation scores. Unlike traditional centralized rating systems, IOTA Repstation provides:
  • Deal-bound ratings - All ratings are tied to actual transactions
  • Cross-platform portability - Reputation follows users across all integrated platforms
  • App-scoped isolation - Each app maintains its own reputation namespace
  • Blockchain transparency - All ratings are publicly verifiable on IOTA

​
System Architecture

graph TB A[User A] —>|Creates| D[Deal] B[User B] —>|Accepts| D D —>|Completion| R[Ratings] R —>|Aggregates to| G[Global Reputation] R —>|Aggregates to| AS[App-Scoped Reputation]subgraph “IOTA Blockchain” D R G AS end

​
Key Components

​
1. Applications & Namespaces

Each platform that integrates IOTA Repstation registers as an Application with its own unique namespace: 
// Register your platform
await client.registerApp({
  appId: 'com.mynftmarket.platform',
  metadataUri: 'ipfs://app-metadata-hash'
});
Benefits:
  • Isolated reputation scoring per application
  • Prevents cross-app rating manipulation
  • Enables app-specific reputation policies

​
2. Deals

A Deal represents an agreement between two parties (party_a and party_b) within your application: 
const { dealId } = await client.openDeal({
  partyB: buyerWallet,
  subjectRef: { type: 'NFT', id: 'token123' },
  amount: 1000 // Price in your app's units
});
Deal Properties:
  • Subject Reference: What the deal is about (NFT, service, loan, etc.)
  • Amount: Deal value (for reputation weighting)
  • Parties: The two participants in the transaction
  • Status: PENDING → ACTIVE → CLOSED

​
3. Deal Lifecycle

Deals follow a strict three-state lifecycle:
1

PENDING

Deal Created: Party A creates a deal and invites Party B
const deal = await client.openDeal({
  partyB: '0xBUYER_ADDRESS',
  subjectRef: { type: 'NFT', id: 'token123' },
  amount: 1000
});
// Status: PENDING
2

ACTIVE

Deal Accepted: Party B accepts the deal terms
await client.acceptDeal({
  dealId: deal.dealId
});
// Status: ACTIVE
3

CLOSED

Deal Completed: Either party closes the deal after completion
await client.closeDeal({
  dealId: deal.dealId
});
// Status: CLOSED - ratings now possible
Deals must be CLOSED before either party can submit ratings. This ensures ratings are only given after actual deal completion.

​
4. Ratings & Endorsements

Once a deal is closed, both parties can rate each other by creating Endorsements: 
const { endorsementId } = await client.rate({
  dealId: 'deal123',
  score: 85,           // 1-100 rating score
  category: 'communication' // Custom category
});
Rating Features:
  • Score Range: 1-100 (100 being the best)
  • Categories: Custom categories like ‘quality’, ‘speed’, ‘communication’
  • Mutability: Ratings can be updated or revoked by the rater
  • Deal-Bound: Each rating is tied to a specific deal

​
5. Reputation Aggregation

All ratings are automatically aggregated into two types of reputation:

​
Global Reputation

Cross-platform reputation that follows users everywhere: 
const profile = await client.getReputationProfile({
  walletAddress: userAddress
});

console.log(profile.global.average); // 0-100
console.log(profile.global.count);   // Total ratings received

​
App-Scoped Reputation

Platform-specific reputation for each integrated application: 
profile.appScoped.forEach(app => {
  console.log(`App: ${app.appOwner}`);
  console.log(`Average: ${app.stats.average}`);
  console.log(`Count: ${app.stats.count}`);
});

​
Reputation Calculation

Reputation scores are calculated using a weighted average: 
Average Score = Total Score Points / Total Ratings Count

Where each rating contributes:
- Score points: The 1-100 rating value
- Weight: Currently 1 (equal weight for all ratings)
Future Enhancements:
  • Deal amount weighting (larger deals count more)
  • Time decay (recent ratings matter more)
  • Category-specific averages
  • Platform-specific weighting policies

​
Security Model

IOTA Repstation uses a capability-based security model:

​
Admin Capabilities

  • AppAdminCap: Allows app registration and management
  • Full Control: Can mint client capabilities, manage app settings

​
Client Capabilities

  • AppClientCap: Time-limited capability for users
  • Deal Creation: Can open deals on behalf of the app
  • Expiration: Capabilities can expire for added security

​
Party Rights

  • Deal Participation: Only invited parties can accept deals
  • Rating Authority: Only deal participants can rate each other
  • Rating Ownership: Only the rater can update/revoke their ratings

​
Integration Patterns

​
Pattern 1: Marketplace Integration

  1. Pre-Transaction: Check user reputation before allowing high-value deals
  2. Deal Creation: Create deal when buyer initiates purchase
  3. Deal Execution: Handle normal marketplace flow (payment, delivery)
  4. Deal Completion: Close deal after successful transaction
  5. Post-Transaction: Enable mutual rating between buyer and seller

​
Pattern 2: Service Platform Integration

  1. Service Booking: Create deal when service is booked
  2. Service Delivery: Handle normal service fulfillment
  3. Service Completion: Close deal after service delivery
  4. Mutual Rating: Both client and provider rate each other

​
Pattern 3: DeFi Protocol Integration

  1. Loan Application: Check borrower’s reputation
  2. Loan Agreement: Create deal when loan is approved
  3. Loan Execution: Handle normal lending flow
  4. Loan Completion: Close deal when loan is repaid
  5. Credit Rating: Lender rates borrower’s payment behavior

​
Best Practices

  • Always validate deal participants match your platform users
  • Store deal IDs securely with your transaction records
  • Implement proper access controls for rating submissions
  • Use time-limited client capabilities for enhanced security
  • Only close deals after actual completion/delivery
  • Allow reasonable time for users to submit ratings
  • Consider automatic deal closure after extended periods
  • Handle failed transactions by not closing deals
  • Display both global and app-specific reputation
  • Show rating counts alongside averages for context
  • Make rating submission optional but encouraged
  • Provide clear feedback on reputation benefits
  • Cache reputation data for better performance
  • Handle network failures gracefully with retries
  • Use mock clients for development and testing
  • Monitor deal completion rates for platform health

​
Next Steps

Deal Management

Deep dive into deal creation and lifecycle management.

Rating System

Learn about creating, updating, and managing ratings.

Reputation Queries

Understand reputation calculation and querying.

Integration Guide

Start integrating IOTA Repstation into your platform.