> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usmewe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trust Score Algorithm

> Technical specification of the Trust Score calculation

# Trust Score Algorithm

This document provides the complete technical specification for how Trust Scores are calculated.

## Formula

The Trust Score is calculated using the following formula:

```
TrustScore = BaseScore + Modifiers

Where:
  BaseScore = Seniority + Repayments + Volume + Social + LevelBonus

Constraints:
  - Minimum: 0
  - Maximum: 100
```

## Component Calculations

### 1. Seniority Score

```typescript theme={null}
function calculateSeniority(accountCreatedAt: Date): number {
  const monthsActive = differenceInMonths(new Date(), accountCreatedAt);
  return Math.min(monthsActive, 12); // Cap at 12 points
}
```

| Months | Points   |
| ------ | -------- |
| 1      | 1        |
| 6      | 6        |
| 12+    | 12 (max) |

### 2. Repayment Score

```typescript theme={null}
function calculateRepaymentScore(repayments: Repayment[]): number {
  const onTimeCount = repayments.filter(r => r.status === 'ON_TIME').length;
  return Math.min(onTimeCount * 2, 40); // Cap at 40 points
}
```

| On-Time Repayments | Points   |
| ------------------ | -------- |
| 5                  | 10       |
| 10                 | 20       |
| 20+                | 40 (max) |

### 3. Volume Score

```typescript theme={null}
function calculateVolumeScore(totalVolume: number): number {
  if (totalVolume <= 0) return 0;

  // Logarithmic scaling with normalization
  const logVolume = Math.log10(totalVolume + 1);
  const normalized = (logVolume / Math.log10(100000)) * 20;

  return Math.min(Math.floor(normalized), 20); // Cap at 20 points
}
```

| Total Volume (USDC) | Points   |
| ------------------- | -------- |
| \$100               | \~8      |
| \$1,000             | \~12     |
| \$10,000            | \~16     |
| \$100,000+          | 20 (max) |

### 4. Social Score

```typescript theme={null}
function calculateSocialScore(guardians: Guardian[]): number {
  const activeGuardians = guardians.filter(g => g.status === 'ACTIVE');
  return Math.min(activeGuardians.length * 5, 15); // Cap at 15 points
}
```

| Guardians | Points   |
| --------- | -------- |
| 1         | 5        |
| 2         | 10       |
| 3+        | 15 (max) |

### 5. Level Bonus

```typescript theme={null}
function calculateLevelBonus(xp: number): number {
  const level = getLevel(xp);

  const bonusMap = {
    'Bronze': 0,
    'Silver': 3,
    'Gold': 6,
    'Platinum': 10,
    'Diamond': 13
  };

  return bonusMap[level];
}
```

| Level    | XP Required | Bonus Points |
| -------- | ----------- | ------------ |
| Bronze   | 0-499       | 0            |
| Silver   | 500-1,999   | 3            |
| Gold     | 2,000-4,999 | 6            |
| Platinum | 5,000-9,999 | 10           |
| Diamond  | 10,000+     | 13           |

## Modifiers

Modifiers are applied after the base score calculation:

```typescript theme={null}
function applyModifiers(baseScore: number, events: Event[]): number {
  let score = baseScore;

  for (const event of events) {
    switch (event.type) {
      case 'ON_TIME_REPAYMENT':
        score *= 1.01; // +1%
        break;
      case 'LATE_PAYMENT':
        score *= 0.95; // -5%
        break;
      case 'DEFAULT':
        score *= 0.70; // -30%
        break;
    }
  }

  return Math.max(0, Math.min(100, Math.floor(score)));
}
```

<Warning>
  Modifiers are multiplicative and applied in chronological order. Multiple defaults can severely impact your score.
</Warning>

## Complete Implementation

```typescript theme={null}
interface TrustScoreInput {
  accountCreatedAt: Date;
  repayments: Repayment[];
  totalVolume: number;
  guardians: Guardian[];
  xp: number;
  events: Event[];
}

function calculateTrustScore(input: TrustScoreInput): number {
  // Calculate base components
  const seniority = calculateSeniority(input.accountCreatedAt);
  const repaymentScore = calculateRepaymentScore(input.repayments);
  const volumeScore = calculateVolumeScore(input.totalVolume);
  const socialScore = calculateSocialScore(input.guardians);
  const levelBonus = calculateLevelBonus(input.xp);

  // Sum base score
  const baseScore = seniority + repaymentScore + volumeScore + socialScore + levelBonus;

  // Apply modifiers
  const finalScore = applyModifiers(baseScore, input.events);

  return finalScore;
}
```

## Score Update Frequency

| Trigger              | Update Time |
| -------------------- | ----------- |
| New repayment        | Immediate   |
| Guardian change      | Immediate   |
| XP level up          | Immediate   |
| Monthly seniority    | Daily batch |
| Volume recalculation | Hourly      |

## Smart Contract Integration

The Trust Score is also stored on-chain for use in smart contract operations:

```solidity theme={null}
// TrustScore.sol (simplified)
mapping(address => uint8) public trustScores;

function updateTrustScore(address user, uint8 score) external onlyOracle {
    require(score <= 100, "Score exceeds maximum");
    trustScores[user] = score;
    emit TrustScoreUpdated(user, score);
}
```

<Card title="View Contract" icon="file-contract" href="/smart-contracts/trust-vault">
  See how Trust Scores are used in the Trust Vault contract
</Card>

***

<Info>
  The algorithm is open source and can be verified in our [GitHub repository](https://github.com/Topxl/UsMeWe/tree/main/apps/api/src/modules/trust-score).
</Info>