@marinade.finance/scoring 1.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@marinade.finance/scoring",
+  "version": "1.0.0",
+  "description": "Delegation Strategy Scoring",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:marinade-finance/ds-scoring.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+
+  "files": [
+    "src",
+    "generated",
+    "README.md"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "build": "nest build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "solana",
+    "marinade.finance",
+    "liquid staking",
+    "DeFi"
+  ],
+  "author": "Marinade Finance",
+  "license": "ISC",
+  "dependencies": {
+    "@nestjs/cli": "^10.3.2",
+    "@nestjs/common": "^10.3.3",
+    "axios": "^1.6.7",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.1",
+    "decimal.js": "^10.4.3",
+    "expr-eval": "^2.0.2",
+    "nestjs": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.19"
+  }
+}

package/src/cluster/cluster.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ClusterService } from './cluster.service';
+
+@Module({
+  providers: [ClusterService],
+  exports: [ClusterService],
+})
+export class ClusterModule {}

package/src/cluster/cluster.service.ts

@@ -0,0 +1,108 @@
+import { BlockProductionResult, ClusterInfo } from '../dto/cluster.dto';
+import { ValidatorDto } from '../dto/validators.dto';
+import { mean, stdDev } from '../utils/maths';
+import Decimal from 'decimal.js';
+
+export class ClusterService {
+  computeBlockProduction (validators: ValidatorDto[], startEpoch: number, endEpoch: number): BlockProductionResult {
+    const blockProductions: number[] = [];
+
+    for (const validator of validators) {
+      let leaderSlots = 0;
+      let blocksProduced = 0;
+
+      for (let epoch = startEpoch; epoch <= endEpoch; epoch++) {
+        if (!validator.epochStats) {
+          continue;
+        }
+        const epochStat = validator.epochStats[epoch];
+        if (epochStat) {
+          leaderSlots += epochStat.leader_slots;
+          blocksProduced += epochStat.blocks_produced;
+        }
+      }
+
+      if (leaderSlots) {
+        blockProductions.push(blocksProduced / leaderSlots);
+      }
+    }
+
+    return {
+      mean: mean(blockProductions),
+      stdDev: stdDev(blockProductions),
+    };
+  }
+
+  computeTargetCreditsByEpoch (validators: ValidatorDto[]): Map<number, number> {
+    const sumOfWeightedCreditsPerEpoch = new Map<number, Decimal>();
+    const sumOfWeightsPerEpoch = new Map<number, Decimal>();
+
+    validators.forEach(validator => {
+      validator.epoch_stats.forEach(epochStat => {
+        if (epochStat.epoch_end_at) {
+          const activatedStakeDecimal = new Decimal(epochStat.activated_stake);
+          const stakeInLamports = activatedStakeDecimal.dividedBy(1e9);
+
+          const prevSumOfWeightedCredits = sumOfWeightedCreditsPerEpoch.get(epochStat.epoch) || new Decimal(0);
+          sumOfWeightedCreditsPerEpoch.set(epochStat.epoch, prevSumOfWeightedCredits.plus(new Decimal(epochStat.credits).times(stakeInLamports)));
+
+          const prevSumOfWeightsPerEpoch = sumOfWeightsPerEpoch.get(epochStat.epoch) || new Decimal(0);
+          sumOfWeightsPerEpoch.set(epochStat.epoch, prevSumOfWeightsPerEpoch.plus(stakeInLamports));
+        }
+      });
+    });
+
+    const result = new Map<number, number>();
+    sumOfWeightsPerEpoch.forEach((sumOfWeights, epoch) => {
+      const weightedCredits = sumOfWeightedCreditsPerEpoch.get(epoch) || new Decimal(0);
+      result.set(epoch, weightedCredits.dividedBy(sumOfWeights).toDecimalPlaces(0, Decimal.ROUND_HALF_UP).toNumber());
+    });
+
+    return result;
+  }
+
+  computeConcentrations (validators: ValidatorDto[], epoch: number): { city: Map<string, number>, country: Map<string, number>, aso: Map<string, number> } {
+    let total = 0;
+    const city = new Map<string, number>();
+    const country = new Map<string, number>();
+    const aso = new Map<string, number>();
+
+    for (const validator of validators) {
+      const lastEpochStats = validator.epoch_stats[0];
+      if (lastEpochStats?.epoch === epoch) {
+        const cityKey = validator.dc_full_city ?? '???';
+        const countryKey = validator.dc_country ?? '???';
+        const asoKey = validator.dc_aso ?? '???';
+
+        const stake = Number(validator.activated_stake) / 1e9;
+
+        city.set(cityKey, (city.get(cityKey) ?? 0) + stake);
+        country.set(countryKey, (country.get(countryKey) ?? 0) + stake);
+        aso.set(asoKey, (aso.get(asoKey) ?? 0) + stake);
+
+        total += stake;
+      }
+    }
+
+    if (total > 0) {
+      for (const map of [city, country, aso]) {
+        for (const [key, value] of map) {
+          map.set(key, value / total);
+        }
+      }
+    }
+
+    return { city, country, aso };
+  }
+
+  computeClusterInfo (validators: ValidatorDto[], basicEligibilityEpochs: number, lastEpoch: number): ClusterInfo {
+    const { mean: meanBlockProduction, stdDev: stdDevBlockProduction } = this.computeBlockProduction(validators, lastEpoch - basicEligibilityEpochs, lastEpoch - 1);
+
+    return {
+      targetCreditsByEpoch: this.computeTargetCreditsByEpoch(validators),
+      ...this.computeConcentrations(validators, lastEpoch),
+      meanBlockProductionOverBasicEligibilityPeriod: meanBlockProduction,
+      stdDevBlockProductionOverBasicEligibilityPeriod: stdDevBlockProduction,
+    };
+  }
+}

package/src/config/config.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ConfigService } from './config.service';
+
+@Module({
+  providers: [ConfigService],
+  exports: [ConfigService],
+})
+export class ConfigModule {}

package/src/config/config.service.ts

@@ -0,0 +1,136 @@
+import * as dotenv from 'dotenv';
+import { Injectable } from '@nestjs/common';
+import { Logger } from '../../../../src/logger';
+import { ScoringConfig } from '../dto/scoring.dto';
+import { readFileSync } from 'fs';
+import * as defaultScoringConfig from '../constants/marinade.json';
+
+dotenv.config();
+
+@Injectable()
+export class ConfigService {
+  private readonly logger = new Logger();
+  readonly scoringConfig: ScoringConfig;
+  private getEnvVar (key: string): string {
+    const val = process.env[key];
+    if (!val) {
+      this.logger.error(`Missing environment variable: ${key}`);
+      throw new Error(`Missing environment variable: ${key}`);
+    }
+    return val;
+  }
+
+  getScoringConfig (): ScoringConfig {
+    const scoringConfigPath = process.env['SCORING_CONFIG_PATH'];
+
+    if (!scoringConfigPath) {
+      return {
+        DS_PUBKEY: defaultScoringConfig.DS_PUBKEY,
+        REWARDS_PAST_EPOCHS: defaultScoringConfig.REWARDS_PAST_EPOCHS,
+        CAP_FROM_BOND: defaultScoringConfig.CAP_FROM_BOND,
+        formulaStakeBlockSize: defaultScoringConfig.formulaStakeBlockSize,
+        formulaStakeBlocksFromScore: defaultScoringConfig.formulaStakeBlocksFromScore,
+        formulaVoteCredits: defaultScoringConfig.formulaVoteCredits,
+        formulaBlockProduction: defaultScoringConfig.formulaBlockProduction,
+        formulaInflationCommission: defaultScoringConfig.formulaInflationCommission,
+        formulaMEVCommission: defaultScoringConfig.formulaMEVCommission,
+        formulaStakeConcentrationCountry: defaultScoringConfig.formulaStakeConcentrationCountry,
+        formulaStakeConcentrationCity: defaultScoringConfig.formulaStakeConcentrationCity,
+        formulaStakeConcentrationASO: defaultScoringConfig.formulaStakeConcentrationASO,
+        formulaStakeConcentrationNode: defaultScoringConfig.formulaStakeConcentrationNode,
+        weightTargetSumOfRewards: defaultScoringConfig.weightTargetSumOfRewards,
+        weightMevHeuristic: defaultScoringConfig.weightMevHeuristic,
+        weightVoteCredits: defaultScoringConfig.weightVoteCredits,
+        weightBlockProduction: defaultScoringConfig.weightBlockProduction,
+        weightInflationCommission: defaultScoringConfig.weightInflationCommission,
+        weightMEVCommission: defaultScoringConfig.weightMEVCommission,
+        weightStakeConcentrationCountry: defaultScoringConfig.weightStakeConcentrationCountry,
+        weightStakeConcentrationCity: defaultScoringConfig.weightStakeConcentrationCity,
+        weightStakeConcentrationASO: defaultScoringConfig.weightStakeConcentrationASO,
+        weightStakeConcentrationNode: defaultScoringConfig.weightStakeConcentrationNode,
+        basicEligibilityEpochs: defaultScoringConfig.basicEligibilityEpochs,
+        bonusEligibilityExtraEpochs: defaultScoringConfig.bonusEligibilityExtraEpochs,
+        maxCommission: defaultScoringConfig.maxCommission,
+        voteCreditsWarning: defaultScoringConfig.voteCreditsWarning,
+        voteCreditsLow: defaultScoringConfig.voteCreditsLow,
+        minExternalStake: defaultScoringConfig.minExternalStake,
+        minScore: defaultScoringConfig.minScore,
+        maxStakeShare: defaultScoringConfig.maxStakeShare,
+        maxWarnings: defaultScoringConfig.maxWarnings,
+        mSolControl: defaultScoringConfig.mSolControl,
+        veMndeControl: defaultScoringConfig.veMndeControl,
+        stakeBlocksFromBonus: defaultScoringConfig.stakeBlocksFromBonus,
+        concentrationParams: defaultScoringConfig.concentrationParams,
+      };
+    } else {
+      const scoringConfigData = readFileSync(scoringConfigPath, 'utf8');
+      return JSON.parse(scoringConfigData) as ScoringConfig;
+    }
+  }
+
+  getDataProviderMode (): string {
+    return this.getEnvVar('DATA_PROVIDER_MODE');
+  }
+
+  getMarinadeTvlURL (): string {
+    return this.getEnvVar('MARINADE_TVL_URL');
+  }
+
+  getValidatorsURL (): string {
+    return this.getEnvVar('VALIDATORS_URL');
+  }
+
+  getBlacklistURL (): string {
+    return this.getEnvVar('BLACKLIST_URL');
+  }
+
+  getBondsURL (): string {
+    return this.getEnvVar('BONDS_URL');
+  }
+
+  getVemndeVotesURL (): string {
+    return this.getEnvVar('VEMNDE_VOTES_URL');
+  }
+
+  getMsolVotesURL (): string {
+    return this.getEnvVar('MSOL_VOTES_URL');
+  }
+
+  getRewardsURL (): string {
+    return this.getEnvVar('REWARDS_URL');
+  }
+  getJitoMevURL (): string {
+    return this.getEnvVar('JITO_MEV_URL');
+  }
+  getValidatorsPath (): string {
+    return this.getEnvVar('VALIDATORS_PATH');
+  }
+
+  getBlacklistPath (): string {
+    return this.getEnvVar('BLACKLIST_PATH');
+  }
+
+  getVemndeVotesPath (): string {
+    return this.getEnvVar('VEMNDE_VOTES_PATH');
+  }
+
+  getMsolVotesPath (): string {
+    return this.getEnvVar('MSOL_VOTES_PATH');
+  }
+
+  getRewardsPath (): string {
+    return this.getEnvVar('REWARDS_PATH');
+  }
+
+  getJitoMevPath (): string {
+    return this.getEnvVar('JITO_MEV_PATH');
+  }
+
+  getBondsPath (): string {
+    return this.getEnvVar('JITO_MEV_PATH');
+  }
+
+  getMarinadeTvlPath (): string {
+    return this.getEnvVar('MARINADE_TVL_PATH');
+  }
+}

package/src/constants/marinade.json

@@ -0,0 +1,38 @@
+{
+  "DS_PUBKEY": "MarinadeA1gorithmicDe1egationStrategy111111",
+  "REWARDS_PAST_EPOCHS": 14,
+  "CAP_FROM_BOND": 1000000000,
+  "formulaStakeBlockSize": "tvl / ((6000000 /  30000) * 1.5 ^ (log(tvl / 6000000) / log(2)))",
+  "formulaStakeBlocksFromScore": "1 + ((max(0.94, score) - 0.94) / (1 - 0.94)) ^ 10",
+  "formulaVoteCredits": "min(credits_pct_mean ^ 10, 1)",
+  "formulaBlockProduction": "piecewise((bp_mean - bp_cluster_mean) / bp_cluster_std_dev < -1, bp_mean / (bp_cluster_mean - bp_cluster_std_dev), 1)",
+  "formulaInflationCommission": "piecewise(commission_inflation_max <= 10, (100 - commission_inflation_max) / 100, 0)",
+  "formulaMEVCommission": "(100 - commission_mev) / 100",
+  "formulaStakeConcentrationCountry": "piecewise(country_stake_concentration_last < 1/3, (1 - (3 * country_stake_concentration_last)) ^ (1/3), 0)",
+  "formulaStakeConcentrationCity": "piecewise(city_stake_concentration_last < 1/3, (1 - (3 * city_stake_concentration_last)) ^ (1/3), 0)",
+  "formulaStakeConcentrationASO": "piecewise(aso_stake_concentration_last < 1/3, (1 - (3 * aso_stake_concentration_last)) ^ (1/3), 0)",
+  "formulaStakeConcentrationNode": "piecewise(node_stake_last < 100000, 1, node_stake_last < 4000000, 1 - (node_stake_last - 100000) / (4000000 - 100000), 0)",
+  "weightTargetSumOfRewards": 5,
+  "weightMevHeuristic": 0.1,
+  "weightVoteCredits": 10,
+  "weightBlockProduction": 5,
+  "weightInflationCommission": 4.9,
+  "weightMEVCommission": 0.1,
+  "weightStakeConcentrationCountry": 2,
+  "weightStakeConcentrationCity": 3,
+  "weightStakeConcentrationASO": 4,
+  "weightStakeConcentrationNode": 2,
+  "basicEligibilityEpochs": 14,
+  "bonusEligibilityExtraEpochs": 0,
+  "maxCommission": 7,
+  "voteCreditsWarning": 0,
+  "voteCreditsLow": 80,
+  "minExternalStake": 0,
+  "minScore": 0.8,
+  "maxStakeShare": 0.8,
+  "maxWarnings": 1,
+  "mSolControl": 0.2,
+  "veMndeControl": 0.2,
+  "stakeBlocksFromBonus": 0,
+  "concentrationParams": [4, 5, 6, 7]
+}

package/src/dto/bonds.dto.ts

@@ -0,0 +1,14 @@
+export type BondDto = {
+  pubkey: string;
+  vote_account: string;
+  authority: string;
+  cpmpe: number;
+  updated_at: string;
+  epoch: number;
+}
+
+export type BondsDto = {
+  bonds: BondDto[];
+}
+
+export type Bonds = Record<string, number>;

package/src/dto/cluster.dto.ts

@@ -0,0 +1,13 @@
+export type ClusterInfo = {
+    city: Map<string, number>,
+    country: Map<string, number>,
+    aso: Map<string, number>,
+    targetCreditsByEpoch: Map<number, number>,
+    meanBlockProductionOverBasicEligibilityPeriod: number,
+    stdDevBlockProductionOverBasicEligibilityPeriod: number,
+}
+
+export type BlockProductionResult = {
+  mean: number;
+  stdDev: number;
+}

package/src/dto/eligibility.dto.ts

@@ -0,0 +1,43 @@
+export type EligibilityConfig = {
+    maxCommission: number;
+    voteCreditsWarning: number;
+    voteCreditsLow: number;
+    minExternalStake: number;
+    basicEligibilityEpochs: number;
+    bonusEligibilityExtraEpochs: number;
+    minScore: number;
+    maxStakeShare: number;
+    maxWarnings: number;
+}
+
+export type ValidatorEligibility = {
+    basicEligibility: boolean;
+    bonusEligibility: boolean;
+    issuesCollection: Issue[][];
+    capFromBond: number;
+    capFromExternalStake: number;
+}
+
+export type EvaluationResult = {
+    criticals: number;
+    warnings: number;
+}
+
+export type Issue = {
+    type: IssueType;
+    message: string;
+}
+
+export const enum IssueType {
+    NO_DATA = 'NO_DATA',
+    NO_BOND = 'NO_BOND',
+    SCORE = 'SCORE',
+    BLACKLIST = 'BLACKLIST',
+    COMMISSION = 'COMMISSION',
+    EXTERNAL_STAKE = 'EXTERNAL_STAKE',
+    CENTRALIZATION = 'CENTRALIZATION',
+    VOTE_CREDITS_LOW = 'VOTE_CREDITS_LOW',
+    VOTE_CREDITS_WARNING = 'VOTE_CREDITS_WARNING',
+}
+
+export type ValidatorsEligibilities = Record<string, ValidatorEligibility>

package/src/dto/jito.dto.ts

@@ -0,0 +1,10 @@
+export class JitoValidatorDto {
+  vote_account: string;
+  mev_commission_bps: number;
+  running_jito: boolean;
+  active_stake: number;
+}
+
+export class JitoValidatorsResponseDto {
+  validators: JitoValidatorDto[];
+}

package/src/dto/marinade.dto.ts

@@ -0,0 +1,18 @@
+export type TvlStats = {
+  staked_sol: number;
+  staked_usd: number;
+  msol_directed_stake_sol: number;
+  msol_directed_stake_msol: number;
+  liquidity_sol: number;
+  liquidity_usd: number;
+  total_sol: number;
+  total_usd: number;
+  self_staked_sol: number;
+  self_staked_usd: number;
+  standard_staked_sol: number;
+  standard_staked_usd: number;
+  total_virtual_staked_sol: number;
+  total_virtual_staked_usd: number;
+  marinade_native_stake_sol: number;
+  marinade_native_stake_usd: number;
+}

package/src/dto/rewards.dto.ts

@@ -0,0 +1,21 @@
+export class RewardPairDto {
+  epoch: number;
+  amount: number;
+
+  constructor (pair: [number, number]) {
+    this.epoch = pair[0];
+    this.amount = pair[1];
+  }
+}
+
+export class RewardsResponseDto {
+  rewards_mev: RewardPairDto[];
+  rewards_inflation_est: RewardPairDto[];
+
+  constructor (data: { rewards_mev: [number, number][], rewards_inflation_est: [number, number][] }) {
+    this.rewards_mev = data.rewards_mev.map(pair => new RewardPairDto(pair));
+    this.rewards_inflation_est = data.rewards_inflation_est.map(pair => new RewardPairDto(pair));
+  }
+}
+
+export type Rewards = { inflation: number, mev: number }

package/src/dto/scoring.dto.ts

@@ -0,0 +1,109 @@
+import { ClusterInfo } from './cluster.dto';
+import { AggregatedValidator } from './validators.dto';
+
+export type ScoreDto = {
+    score: number,
+    concentrationScore: number,
+    scores: number[]
+    values: number[]
+    scoreErrors: boolean[]
+    tooltips: string[]
+}
+
+export type Score = {
+    vote_account: string,
+    score: string,
+    score_credits: string,
+    score_block_production: string,
+    score_inflation_commission: string,
+    score_mev_commission: string,
+    score_country_concentration: string,
+    score_city_concentration: string,
+    score_aso_concentration: string,
+    score_node_concentration: string,
+    ui_hints: string,
+    eligible_stake_algo: number;
+    eligible_bonus: number;
+    in_algo_stake_set: number;
+    msol_votes: string;
+    vemnde_votes: string;
+    blacklisted: number,
+    rank: number,
+    version: string,
+    max_commission: number,
+    marinade_stake: string,
+    target_stake_vemnde: string,
+    target_stake_msol: string,
+    target_stake_algo: string,
+    target_stake: string,
+}
+
+export type ScoreConfig = {
+    epochs: number,
+    concentrationParams: number[]
+}
+
+export type ScoringConfig = {
+  DS_PUBKEY: string;
+  REWARDS_PAST_EPOCHS: number;
+  CAP_FROM_BOND: number;
+  formulaStakeBlockSize: string;
+  formulaStakeBlocksFromScore: string;
+  formulaVoteCredits: string;
+  formulaBlockProduction: string;
+  formulaInflationCommission: string;
+  formulaMEVCommission: string;
+  formulaStakeConcentrationCountry: string;
+  formulaStakeConcentrationCity: string;
+  formulaStakeConcentrationASO: string;
+  formulaStakeConcentrationNode: string;
+  weightTargetSumOfRewards: number;
+  weightMevHeuristic: number;
+  weightVoteCredits: number;
+  weightBlockProduction: number;
+  weightInflationCommission: number;
+  weightMEVCommission: number;
+  weightStakeConcentrationCountry: number;
+  weightStakeConcentrationCity: number;
+  weightStakeConcentrationASO: number;
+  weightStakeConcentrationNode: number;
+  basicEligibilityEpochs: number;
+  bonusEligibilityExtraEpochs: number;
+  maxCommission: number;
+  voteCreditsWarning: number;
+  voteCreditsLow: number;
+  minExternalStake: number;
+  minScore: number;
+  maxStakeShare: number;
+  maxWarnings: number;
+  mSolControl: number;
+  veMndeControl: number;
+  stakeBlocksFromBonus: number;
+  concentrationParams: number[];
+};
+
+export type Variables = {
+    bp_cluster_mean: number;
+    bp_cluster_std_dev: number;
+    credits_pct_mean: number;
+    bp_mean: number;
+    commission_inflation_max: number;
+    commission_mev: number;
+    country_stake_concentration_last: number;
+    city_stake_concentration_last: number;
+    aso_stake_concentration_last: number;
+    node_stake_last: number;
+};
+
+export type Scores = Record<string, ScoreDto>
+export type ScoreTooltipBuilder = (validator: AggregatedValidator, clusterInfo: ClusterInfo) => string
+
+export type UnstakeHint = {
+  vote_account: string;
+  marinade_stake: string;
+  hints: string[];
+};
+
+export type UnstakeHints = {
+  unstake_hints: UnstakeHint[];
+};

package/src/dto/snapshots.dto.ts

@@ -0,0 +1,19 @@
+export class RecordDto {
+  amount: string | null;
+  tokenOwner: string;
+  validatorVoteAccount: string;
+}
+
+export class veMNDESnapshotDto {
+  voteRecordsCreatedAt: string;
+  records: RecordDto[];
+}
+
+export class mSolSnapshotDto {
+  mSolSnapshotCreatedAt: string;
+  voteRecordsCreatedAt: string;
+  records: RecordDto[];
+}
+
+export type Votes = Record<string, number>
+

package/src/dto/stakes.dto.ts

@@ -0,0 +1,35 @@
+import { Votes } from './snapshots.dto';
+
+export type StakesConfig = {
+    tvl: number
+    mSolControl: number
+    veMndeControl: number
+    stakeBlocksFromBonus: number
+    formulaStakeBlockSize: string
+    formulaStakeBlocksFromScore: string
+}
+
+export type Stake = {
+    algoStake: number
+    mSolStake: number
+    veMndeStake: number
+    totalStake: number
+    algoStakeFromOverflow: number
+    mSolStakeFromOverflow: number
+    veMndeStakeFromOverflow: number
+    totalStakeFromOverlfow: number
+}
+
+export type ProcessedVotesAndTVLs = {
+    updatedMSolVotes: Votes;
+    updatedVeMndeVotes: Votes;
+    mSolTvl: number;
+    veMndeTvl: number;
+    totalTvl: number;
+};
+
+export type StakingVariables = {
+    tvl: number;
+}
+
+export type Stakes = Record<string, Stake>