Metafide Winnings Computation Module

This module computes player winnings for Metafide Range and Spot games based on their performance predictions, using a normalized variance-based distribution model.

It includes:

• Pot distribution calculation
• Player variance computation
• Winnings and returns ranking
• Top streak player detection

Installation

Using npm:

npm i metafide-surge

Usage

import { computeRangeWinnings, computeSpotWinnings, calculateSpotPotDistribution, calculateRangePotDistribution } from "metafide-surge"

// Example
const range_players = []
const range_game = {}
const distribution = calculateRangePotDistribution(range_players)
const computed_range_winnings = computeRangeWinnings(range_players, range_game, distribution)
console.log(computed_range_winnings)

Features

Range Game Computation:

Calculates player performance based on how well their predicted price ranges covered the actual asset movement.

Spot Game Computation:

Calculates player performance based on proximity and timing of their spot price prediction versus the actual asset close.

Pot Distribution:

Allocates the total game pot into metafide rake, reward streak pots (5, 10, 25 wins), daily/monthly rewards, burns, and winning pools.

Top Player Selection:

Identifies the top 2% of players by total winnings and percent returns in each game.

Range Functions

| Function | Description | |:---|:---| | calculateRangePotDistribution(players, allocations?) | Computes how the total pot is distributed in Range games. | | computeRangePlayerVariance(players, game) | Calculates player variance based on predicted vs. actual price range. | | computeRangeWinnings(players, games) | Calculates player winnings and ranks top players based on variance and contributions. |

Spot Functions

| Function | Description | |:---|:---| | calculateSpotPotDistribution(players, allocations?) | Computes how the total pot is distributed in Spot games. | | computeSpotPlayerVariance(players, game) | Calculates player variance based on spot price and closing time accuracy. | | computeSpotWinnings(players, game) | Calculates player winnings and ranks top players based on variance and contributions. |

Pot Allocations and Defaults

Each game’s total prize pool ("pot") is divided into several categories based on predefined allocation percentages. These allocations ensure that a portion of the pot is distributed toward operational costs, player rewards for streak achievements, daily/monthly competitions, and token burns for long-term ecosystem health.

There are default allocation percentages defined for both Range and Spot games:

Range Game Allocations (DEFAULT_RANGE_ALLOCATION_PERCENTAGES):

• 1.9875% → Metafide Rake
• 1.43% → Streak Pot (5 wins)
• 0.95% → Streak Pot (10 wins)
• 0.238% → Streak Pot (25 wins)
• 0.35% → Daily Reward Pot
• 0.15% → Monthly Reward Pot
• 2.5% → Burn Pool

Spot Game Allocations (DEFAULT_SPOT_ALLOCATION_PERCENTAGES):

• 1.9875% → Metafide Rake
• 1.5% → Range Rake (specific to Spot games)
• 1.43% → Streak Pot (5 wins)
• 0.95% → Streak Pot (10 wins)
• 0.238% → Streak Pot (25 wins)
• 0.35% → Daily Reward Pot
• 0.15% → Monthly Reward Pot
• 2.5% → Burn Pool

By default, these allocations are applied automatically when calculating pot distributions. However, custom allocation percentages can also be passed manually to override the defaults if needed for special events or game types.

Running Tests

This module includes unit tests to validate the accuracy of pot distribution, variance calculation, and winnings computation for both Range and Spot games.

To run the tests locally:

# Install dependencies if not already done
npm install

# Run the tests using Vitest
npx vitest run

Tests are organized to cover:

• Pot distribution correctness based on given allocations.
• Player variance calculations (Range and Spot games).
• Final winnings and top player ranking logic.

Test files are located alongside the main source files for easy maintenance and extension.

Response Structure

Each main computation function — computeRangeWinnings and computeSpotWinnings — returns a structured, predictable response format designed for easy integration into frontends, leaderboards, or further analytics.

The standard response structure is:

{
  players: UpdatedPlayer[], // List of players with computed winnings and returns
  streak: {
    winnings: TopPlayer[],  // Top players by total winnings
    returns: TopPlayer[]    // Top players by percent return
  }
}

players: An array of all participating players, each updated with:

• w: the computed winnings (scaled down for user display)
• r: the computed percent return relative to their initial stake

streak.winnings: The top 2% of players ranked by highest absolute winnings.

streak.returns: The top 2% of players ranked by highest percent return on their wager.

If no players are available or no valid variance is computed, the functions safely return empty arrays for all fields, ensuring graceful handling on the consuming side.