Skip to main content

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

function calculateSeniority(accountCreatedAt: Date): number {
  const monthsActive = differenceInMonths(new Date(), accountCreatedAt);
  return Math.min(monthsActive, 12); // Cap at 12 points
}
MonthsPoints
11
66
12+12 (max)

2. Repayment Score

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 RepaymentsPoints
510
1020
20+40 (max)

3. Volume Score

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

function calculateSocialScore(guardians: Guardian[]): number {
  const activeGuardians = guardians.filter(g => g.status === 'ACTIVE');
  return Math.min(activeGuardians.length * 5, 15); // Cap at 15 points
}
GuardiansPoints
15
210
3+15 (max)

5. Level Bonus

function calculateLevelBonus(xp: number): number {
  const level = getLevel(xp);

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

  return bonusMap[level];
}
LevelXP RequiredBonus Points
Bronze0-4990
Silver500-1,9993
Gold2,000-4,9996
Platinum5,000-9,99910
Diamond10,000+13

Modifiers

Modifiers are applied after the base score calculation:
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)));
}
Modifiers are multiplicative and applied in chronological order. Multiple defaults can severely impact your score.

Complete Implementation

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

TriggerUpdate Time
New repaymentImmediate
Guardian changeImmediate
XP level upImmediate
Monthly seniorityDaily batch
Volume recalculationHourly

Smart Contract Integration

The Trust Score is also stored on-chain for use in smart contract operations:
// 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);
}

View Contract

See how Trust Scores are used in the Trust Vault contract

The algorithm is open source and can be verified in our GitHub repository.