Feature: User Reputation System
Relevant source files
The following files were used as context for generating this wiki page:
- apps/backend/src/reputation/reputation.service.ts
- apps/backend/src/reputation/reputation.controller.ts
- apps/backend/src/reputation/entities/reputation.entity.ts
- apps/backend/src/reputation/entities/vote.entity.ts
- apps/backend/src/reputation/reputation.module.ts
- ARCHITECTURE.md
- apps/backend/src/social-engagement-analytics/enagagemanet-analytics/services/reputation-weighting.service.ts
The User Reputation System is a core component of the OnChain Sage platform, designed to quantify user credibility based on their participation in community-driven signal validation. By analyzing a user's voting history, stake, and accuracy, the system calculates a reputation score. This score is crucial for weighting user votes on signal credibility, influencing signal rankings, and fostering a trustworthy ecosystem.
The system is implemented within the backend service and interacts with data derived from on-chain activities, such as votes and stakes on trading signals. It provides functionalities to calculate individual user reputation, generate a public leaderboard, and retrieve detailed user profiles. This reputation score is also used in other parts of the application, such as the social engagement analytics module, to weight the impact of user actions.
Sources: ARCHITECTURE.md, apps/backend/src/reputation/reputation.service.ts, apps/backend/src/social-engagement-analytics/enagagemanet-analytics/services/reputation-weighting.service.ts
Architecture and Core Components
The reputation system is encapsulated within the ReputationModule in the NestJS backend. It consists of a controller for handling HTTP requests, a service for business logic, and TypeORM entities for database interaction.
This diagram shows the components of the ReputationModule and their interactions.
Sources: apps/backend/src/reputation/reputation.module.ts:9-12
Components
ReputationController: Exposes API endpoints for clients to access reputation data, such as the leaderboard and user profiles.
Sources: apps/backend/src/reputation/reputation.controller.tsReputationService: Contains the core logic for calculating reputation, fetching leaderboard data, and retrieving user profiles. It interacts directly with the database via repositories.
Sources: apps/backend/src/reputation/reputation.service.tsVoteEntity: Represents a user's vote on a signal, storing their address, the stake amount, and the result of the vote.
Sources: apps/backend/src/reputation/entities/vote.entity.tsReputationAdjustmentEntity: Represents a manual or systemic adjustment to a user's reputation score.
Sources: apps/backend/src/reputation/entities/reputation.entity.ts
Data Model
The reputation system relies on two primary database entities: Vote and ReputationAdjustment. These tables store the necessary data to calculate a user's reputation score over time.
This ER diagram illustrates the schema for the Vote and ReputationAdjustment entities.
Sources: apps/backend/src/reputation/entities/vote.entity.ts, apps/backend/src/reputation/entities/reputation.entity.ts
Vote Entity
This entity stores records of votes cast by users.
| Column | Type | Description |
|---|---|---|
id | string | Primary key (UUID). |
address | string | The user's wallet address. |
stake | numeric | The amount staked on the vote. |
voteResult | boolean | The outcome of the vote (e.g., win/loss). |
timestamp | Date | When the vote was recorded. |
Sources: apps/backend/src/reputation/entities/vote.entity.ts:6-23
ReputationAdjustment Entity
This entity stores manual or automated adjustments to a user's reputation.
| Column | Type | Description |
|---|---|---|
id | string | Primary key (UUID). |
address | string | The user's wallet address. |
adjustment | numeric | The value to adjust the reputation by. |
reason | string | The reason for the adjustment. |
timestamp | Date | When the adjustment was made. |
Sources: apps/backend/src/reputation/entities/reputation.entity.ts:6-22
Reputation Calculation
The reputation score is calculated in the calculateReputation method of the ReputationService. It is a function of the user's voting accuracy, the total amount they have staked, and any manual adjustments.
The formula is: (accuracy * totalStake) + totalAdjustments
Sources: apps/backend/src/reputation/reputation.service.ts:28-31
// apps/backend/src/reputation/reputation.service.ts:15-31
async calculateReputation(address: string): Promise<number> {
const votes = await this.voteRepo.find({ where: { address } });
const adjustments = await this.adjustRepo.find({ where: { address } });
const totalStake = votes.reduce((sum, v) => sum + Number(v.stake), 0);
const wins = votes.filter((v) => v.voteResult).length;
const accuracy = votes.length > 0 ? wins / votes.length : 0;
const totalAdjustments = adjustments.reduce(
(sum, a) => sum + Number(a.adjustment),
0,
);
return accuracy * totalStake + totalAdjustments;
}
The following diagram illustrates the flow of this calculation.
Reputation-Based Weighting
In addition to the core reputation score, a ReputationWeightingService exists within the social engagement analytics module. This service calculates a userReputationMultiplier to weight the significance of user actions like "likes" or "comments". While separate from the main ReputationService, it demonstrates a key application of user reputation.
The multiplier is calculated based on several factors:
- Account Age
- Previous Engagement Quality
- Content Quality
- Community Standing
The service also defines default weights for different engagement types.
| Engagement Type | Default Weight |
|---|---|
LIKE | 1.0 |
DISLIKE | 1.2 |
COMMENT | 2.0 |
SHARE | 3.0 |
VIEW | 0.1 |
The final weight of an engagement is typeWeight * userMultiplier.
API Endpoints
The ReputationController provides endpoints to query reputation data.
| Method | Path | Description |
|---|---|---|
GET | /reputation/leaderboard | Returns the top 100 users sorted by reputation score. |
GET | /reputation/profile/:address | Returns a detailed profile for a user, including reputation, vote counts, accuracy, and stake history. |
Sources: apps/backend/src/reputation/reputation.controller.ts:11-23
Get Leaderboard Flow
This sequence diagram shows the process for retrieving the reputation leaderboard.
Conclusion
The User Reputation System is a foundational feature for ensuring data quality and rewarding knowledgeable community members in OnChain Sage. By creating a transparent and quantifiable measure of user credibility, it underpins the community-driven validation of trading signals. The system's design is modular, allowing for future enhancements to the calculation logic and broader integration across the platform.