metafide-surge/lib/src/types.d.ts

Metafide Surge Game Computation

/**
 * Represents a numeric value that may be returned as either a string or a number.
 *
 * This is commonly used when interfacing with PostgreSQL, where `numeric` fields
 * are returned as strings to preserve precision. Consumers of this type should
 * handle both formats accordingly.
 *
 * @typedef {string | number} Numeric
 */
export declare type Numeric = string | number;
/**
 * Represents the possible statuses a game can have in the system.
 *
 * @typedef {'OPEN' | 'LIVE' | 'CANCELLED' | 'EXPIRED'} GameStatus
 *
 * - `OPEN`: The game is created.
 * - `LIVE`: The game is currently active and in progress.
 * - `CANCELLED`: The game was cancelled before completion.
 * - `EXPIRED`: The game ended due to an error during creation or price feeds.
 */
export declare type GameStatus = 'OPEN' | 'LIVE' | 'CANCELLED' | 'EXPIRED';
/**
 * Base interface for common game data fields shared across different game types.
 *
 * @property {number} gid - Unique game ID.
 * @property {Numeric} t1 - Game start time (block or timestamp).
 * @property {Numeric} t2 - Game lock time (block or timestamp).
 * @property {Numeric | null} ha - Highest price during the game (nullable).
 * @property {Numeric | null} la - Lowest price during the game (nullable).
 * @property {GameStatus} st - Game status (e.g., "PENDING", "LIVE", "EXPIRED").
 * @property {Numeric | null} oa - Opening price at game start (nullable).
 * @property {Numeric | null} ca - Closing price at game end (nullable).
 */
export interface BaseGameData {
    gid: number;
    t1: Numeric;
    t2: Numeric;
    t3: Numeric;
    t4: Numeric;
    ha: Numeric | null;
    la: Numeric | null;
    st: GameStatus;
    oa: Numeric | null;
    ca: Numeric | null;
    it: number;
    a: string;
}
/**
 * Represents a range-based game, using only the base game data structure.
 *
 * @typedef {BaseGameData} RangeGame
 *
 */
export declare type RangeGame = BaseGameData;
/**
 * Represents a spot-based game, which extends the base game data
 * with an additional AI-generated price prediction field.
 *
 * @interface SpotGame
 * @extends BaseGameData
 *
 * @property {Numeric | null} ai - AI-generated price prediction (nullable).
 */
export interface SpotGame extends BaseGameData {
    ai: Numeric | null;
}
/**
 * Represents the PostgreSQL enum type `status_enum`.
 *
 * @typedef {'pending' | 'failed' | 'success' | 'error'} StatusEnum
 *
 * - `pending`: The operation is in progress or awaiting processing.
 * - `failed`: The operation encountered an error and did not complete.
 * - `success`: The operation completed successfully.
 * - `error`: A critical issue occurred (used interchangeably with `failed` in some systems).
 */
export declare type StatusEnum = 'pending' | 'failed' | 'success' | 'error';
/**
 * Base fields shared across all player types.
 *
 * @property {number} gid - Game ID this player participated in.
 * @property {string} c - Chain ID (e.g., 'Mantle').
 * @property {string} a - Asset eg (BTC_USDT | NVIDIA).
 * @property {Numeric} f - Amount committed by the player in FIDE.
 * @property {boolean} cm - Whether the player has been sent winnings.
 * @property {Numeric} t - This is the timestamp a player placed a position
 * @property {Numeric} w - Player winnings (if any).
 * @property {Numeric} r - Refund amount (if applicable).
 * @property {string} pw - Player wallet address.
 * @property {boolean} win - Whether the player won the game.
 * @property {string} [tx] - Optional transaction hash.
 * @property {string} [createdat] - When the record was created in the database.
 * @property {StatusEnum} [st] - Game status (eg "pending", "failed").
 */
export interface BasePlayerData {
    gid: number;
    c: string;
    a: string;
    f: Numeric;
    cm: boolean;
    t: Numeric;
    w: Numeric;
    r: Numeric;
    pw: string;
    win: boolean;
    tx?: string;
    createdat?: string;
    st?: StatusEnum;
}
/**
 * Player data for range-based games.
 *
 * @interface RangePlayer
 * @extends BasePlayerData
 *
 * @property {string | number} id - Player identifier.
 * @property {Numeric} hp - High price selected by the player.
 * @property {Numeric} lp - Low price selected by the player.
 * @property {Numeric | null} cmt - Player comment or metadata (nullable).
 * @property {Numeric} p - Amount won by the player points.
 * @property {boolean} ex - Whether the player exited the game manually.
 * @property {Numeric | null} ex_ha - High price at exit (nullable).
 * @property {Numeric | null} ex_la - Low price at exit (nullable).
 * @property {Numeric | null} ex_t - Timestamp or block number at exit (nullable).
 */
export interface RangePlayer extends BasePlayerData {
    id: string | number;
    hp: Numeric;
    lp: Numeric;
    cmt: Numeric | null;
    ex: boolean;
    ex_ha: Numeric | null;
    ex_la: Numeric | null;
    ex_t: Numeric | null;
    p?: Numeric;
}
/**
 * Player data for spot-based games.
 *
 * @interface SpotPlayer
 * @extends BasePlayerData
 *
 * @property {string | number} id - Player identifier.
 * @property {Numeric} sp - Price selected by the player.
 * @property {Numeric | null} cmt - Timestamp when winnings were sent
 * @property {string} [txid] - Optional secondary transaction ID.
 * @property {Numeric} p - Player winning points.
 */
export interface SpotPlayer extends BasePlayerData {
    id: string | number;
    sp: Numeric;
    cmt: Numeric | null;
    txid?: string;
    p?: Numeric;
}
/**
 * Input data used for calculating spot game player variance.
 *
 * @property {number} actual_price - The actual price at the end of the game.
 * @property {number} abs_spot_var - Absolute variance between predicted and actual price.
 * @property {number} token_milliseconds - Time-weighted token amount.
 * @property {number} share_tkm_to_var - Share of player's token-milliseconds relative to variance.
 * @property {number} sum_share_tkm_to_var - Sum of all players' shares used for proportional reward distribution.
 */
export declare type SpotVarianceInput = {
    actual_price: number;
    abs_spot_var: number;
    token_milliseconds: number;
    share_tkm_to_var: number;
    sum_share_tkm_to_var: number;
};
/**
 * Input data used for calculating range game player variance.
 *
 * @property {number} high_actual - Actual highest price during the game.
 * @property {number} low_actual - Actual lowest price during the game.
 * @property {number} total_variance - Player's total variance from their selected high/low range.
 * @property {number} sum_total_variance - Sum of total variances across all players.
 */
export declare type RangeVarianceInput = {
    high_actual: number;
    low_actual: number;
    total_variance: number;
    sum_total_variance: number;
};
/**
 * A spot game player combined with their variance calculation data.
 *
 * @property {SpotVarianceInput} varianceInput - The input values used to compute the player's variance.
 */
export declare type SpotPlayerVarianceResult = SpotPlayer & {
    varianceInput: SpotVarianceInput;
};
/**
 * A range game player combined with their variance calculation data.
 *
 * @property {RangeVarianceInput} varianceInput - The input values used to compute the player's variance.
 */
export declare type RangePlayerVarianceResult = RangePlayer & {
    varianceInput: RangeVarianceInput;
};
/**
 * The breakdown of how the total pot is distributed among different allocations.
 *
 * @property {number} total_pot - The full amount of tokens available for distribution.
 * @property {number} metafide_rake - Fee taken by Metafide.
 * @property {number} streak_pot_5 - Portion reserved for 5-win streak rewards.
 * @property {number} streak_pot_10 - Portion reserved for 10-win streak rewards.
 * @property {number} streak_pot_25 - Portion reserved for 25-win streak rewards.
 * @property {number} daily_reward_pot - Portion allocated for daily rewards.
 * @property {number} monthly_reward_pot - Portion allocated for monthly rewards.
 * @property {number} burn - Portion permanently removed from circulation.
 * @property {number} winning_pot - Remaining pot for winners.
 * @property {number} [range_rake] - Optional fee taken for range-specific logic.
 */
export interface PotDistribution {
    total_pot: number;
    metafide_rake: number;
    streak_pot_5: number;
    streak_pot_10: number;
    streak_pot_25: number;
    daily_reward_pot: number;
    monthly_reward_pot: number;
    burn: number;
    winning_pot: number;
    range_rake?: number;
}
/**
 * Percentage allocation for how the pot is split across categories.
 * Values are expected to sum to 100%.
 *
 * @property {number} metafide_rake - Percentage for Metafide fee.
 * @property {number} streak_pot_5 - Percentage for 5-win streak rewards.
 * @property {number} streak_pot_10 - Percentage for 10-win streak rewards.
 * @property {number} streak_pot_25 - Percentage for 25-win streak rewards.
 * @property {number} daily_reward_pot - Percentage for daily rewards.
 * @property {number} monthly_reward_pot - Percentage for monthly rewards.
 * @property {number} burn - Percentage to be burned.
 * @property {number} [range_rake] - Optional percentage for range-specific rake.
 */
export interface AllocationPercentages {
    metafide_rake: number;
    streak_pot_5: number;
    streak_pot_10: number;
    streak_pot_25: number;
    daily_reward_pot: number;
    monthly_reward_pot: number;
    burn: number;
    range_rake?: number;
}
/**
 * Computed results from a completed game round, including all players
 * and top streak performers by winnings and returns.
 *
 * @property {(RangePlayer | SpotPlayer)[]} players - List of all participating players with computed data.
 * @property {{
 *   winnings: (RangePlayer | SpotPlayer)[];
 *   returns: (RangePlayer | SpotPlayer)[];
 * }} streak - Top players by total winnings and percent returns.
 */
export interface ComputedData {
    players: (RangePlayer | SpotPlayer)[];
    streak: {
        winnings: (RangePlayer | SpotPlayer)[];
        returns: (RangePlayer | SpotPlayer)[];
    };
}