> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repstation.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Core Concepts
> Understanding the fundamental concepts of IOTA Repstation
## 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:
```javascript theme={null}
// 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:
```javascript theme={null}
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:
**Deal Created**: Party A creates a deal and invites Party B
```javascript theme={null}
const deal = await client.openDeal({
partyB: '0xBUYER_ADDRESS',
subjectRef: { type: 'NFT', id: 'token123' },
amount: 1000
});
// Status: PENDING
```
**Deal Accepted**: Party B accepts the deal terms
```javascript theme={null}
await client.acceptDeal({
dealId: deal.dealId
});
// Status: ACTIVE
```
**Deal Completed**: Either party closes the deal after completion
```javascript theme={null}
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**:
```javascript theme={null}
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:
```javascript theme={null}
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:
```javascript theme={null}
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
Deep dive into deal creation and lifecycle management.
Learn about creating, updating, and managing ratings.
Understand reputation calculation and querying.
Start integrating IOTA Repstation into your platform.