@provable-games/metagame-sdk 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,489 @@
+import { P as Prize, S as StatusTimestamps, a as StatusResult, E as ExtensionAddresses, Q as QualifyingModeInfo, b as ExtensionType, c as ERC20BalanceValidatorConfig, T as TournamentValidatorConfig, O as OpusTrovesValidatorConfig, d as SnapshotValidatorConfig, Z as ZkPassportValidatorConfig, G as GovernanceValidatorConfig, e as QualificationResult, f as EntryRequirementVariant, g as QualificationProof } from './prizeAggregation-CHwIJzXr.js';
+export { D as DistributionType, h as EntryFeeBreakdown, i as EntryFeeExtensionConfig, j as EntryFeeShares, k as ExtensionCategory, l as Participant, m as PositionPrizeGroup, n as PrizeExtensionConfig, o as QualificationEntry, p as QualifyingMode, q as SponsorContribution, r as StatusVariant, s as Token, t as aggregatePrizesByPosition, u as aggregatePrizesBySponsor, v as calculateDistribution, w as calculateEntryFeeBreakdown, x as calculatePayouts, y as distributePool, z as filterClaimablePrizes, A as filterZeroPrizes, B as formatNumber, C as formatPrizeAmount, F as formatScore, H as formatTime, I as formatUsdValue, J as getOrdinalSuffix } from './prizeAggregation-CHwIJzXr.js';
+import { CairoOption, CairoCustomEnum } from 'starknet';
+
+interface EntryFee {
+    tokenAddress: string;
+    amount: string;
+    tournamentCreatorShare?: number;
+    gameCreatorShare?: number;
+    refundShare?: number;
+    distribution?: Distribution | null;
+    distributionCount?: number;
+}
+interface EntryRequirement {
+    requirementType: "token" | "extension";
+    tokenAddress?: string;
+    entryLimit?: number;
+    extensionConfig?: Record<string, unknown>;
+}
+type Distribution = {
+    Linear: number;
+} | {
+    Exponential: number;
+} | {
+    Uniform: Record<string, never>;
+} | {
+    Custom: [number, ...number[]];
+};
+
+declare function indexAddress(address: string): string;
+declare function padAddress(address: string): string;
+declare function displayAddress(address: string): string;
+declare function bigintToHex(v: bigint | string | number): string;
+
+interface GroupedTokenPrize {
+    type: "erc20" | "erc721";
+    address: string;
+    totalAmount: string;
+}
+declare function groupPrizesByToken(prizes: Prize[]): Record<string, GroupedTokenPrize>;
+declare function calculatePrizeValue(amount: string, decimals: number, price: number): number;
+
+declare function computeStatus(timestamps: StatusTimestamps, now?: number): StatusResult;
+
+declare function isBefore(date1: Date, date2: Date): boolean;
+
+/**
+ * NFT bulk input parsing for prize creation forms.
+ *
+ * Metagame UIs often need a textarea where users can paste multiple NFT
+ * token IDs with positions. This parser handles two common formats:
+ *
+ * 1. JSON array: [{ "tokenId": 1, "position": 1 }, ...]
+ * 2. Key-value: "tokenId:position" per line or comma-separated
+ */
+interface NftPrizeInput {
+    tokenId: string;
+    position: number;
+}
+interface NftParseResult {
+    entries: NftPrizeInput[];
+    errors: string[];
+}
+/**
+ * Parse bulk NFT input text into structured entries.
+ *
+ * Supports:
+ * - JSON array: `[{"tokenId": 1, "position": 1}]`
+ * - Key-value lines: `123:1` (tokenId:position)
+ * - Comma-separated: `123:1, 456:2, 789:3`
+ *
+ * @param input - Raw text from a textarea
+ * @returns Parsed entries and any validation errors
+ */
+declare function parseNFTBulkInput(input: string): NftParseResult;
+
+/**
+ * Extension utilities for EGS entry requirements.
+ *
+ * The EGS ecosystem has shared extension contracts that any metagame can use
+ * for gating entry. These utilities handle:
+ * - Identifying which extension type an address corresponds to
+ * - Parsing the on-chain config arrays into structured objects
+ * - Providing deployed addresses per chain
+ *
+ * The extension contracts are deployed once and shared across metagames.
+ * The config format is defined by each extension's Cairo contract — these
+ * parsers match that format exactly.
+ */
+
+/**
+ * Get deployed extension addresses for a chain.
+ */
+declare function getExtensionAddresses(chainId: string): ExtensionAddresses;
+/**
+ * Get supported Opus collateral asset addresses for a chain.
+ */
+declare function getOpusSupportedAssets(chainId: string): string[];
+/**
+ * Get all whitelisted extension addresses for a chain (normalized).
+ */
+declare function getWhitelistedExtensionAddresses(chainId: string): Set<string>;
+/**
+ * Check if an extension address is whitelisted for a chain.
+ */
+declare function isWhitelistedExtension(extensionAddress: string, chainId: string): boolean;
+/**
+ * Identify which extension type a contract address corresponds to.
+ *
+ * @param extensionAddress - The extension contract address from the entry requirement
+ * @param chainId - The chain ID (e.g., "SN_MAIN", "SN_SEPOLIA")
+ * @returns The extension type, or "unknown" if not a recognized preset
+ */
+declare function identifyExtensionType(extensionAddress: string, chainId: string): ExtensionType;
+/**
+ * Parse a tournament validator extension config array.
+ *
+ * Config format: [qualifier_type, qualifying_mode, top_positions, ...tournament_ids]
+ * - qualifier_type: "0" = participated, "1" = won
+ * - qualifying_mode: 0-5 (see QualifyingMode enum)
+ * - top_positions: 0 = all positions, or N = top N
+ * - remaining values: tournament IDs
+ */
+declare function parseTournamentValidatorConfig(config: Array<string | number | bigint>): TournamentValidatorConfig | null;
+/**
+ * Parse an ERC20 balance validator extension config array.
+ *
+ * Config format: [token_address, min_low, min_high, max_low, max_high, vpe_low, vpe_high, max_entries]
+ * Values are u256 split into low (128-bit) and high (128-bit) parts.
+ */
+declare function parseERC20BalanceValidatorConfig(config: Array<string | number | bigint>): ERC20BalanceValidatorConfig | null;
+/**
+ * Parse an Opus Troves validator extension config array.
+ *
+ * Config format: [asset_count, ...asset_addresses, threshold, value_per_entry, max_entries]
+ * - asset_count: 0 = wildcard (any collateral), N = specific assets
+ * - asset_addresses: N addresses following asset_count
+ * - threshold: minimum debt in CASH (18 decimals, 1:1 USD)
+ * - value_per_entry: debt per additional entry
+ * - max_entries: cap on entries (0 = unlimited)
+ */
+declare function parseOpusTrovesValidatorConfig(config: Array<string | number | bigint>): OpusTrovesValidatorConfig | null;
+/**
+ * Parse a Snapshot validator extension config array.
+ *
+ * Config format: [snapshot_space_id]
+ */
+declare function parseSnapshotValidatorConfig(config: Array<string | number | bigint>): SnapshotValidatorConfig | null;
+/**
+ * Parse a ZK Passport validator extension config array.
+ *
+ * Config format: [verifier_address, service_scope, subscope, param_commitment, max_proof_age, nullifier_type]
+ */
+declare function parseZkPassportValidatorConfig(config: Array<string | number | bigint>): ZkPassportValidatorConfig | null;
+/**
+ * Parse a Governance validator extension config array.
+ *
+ * Config format: [governor_address, governance_token_address, balance_threshold_low, balance_threshold_high,
+ *                 proposal_id_low, proposal_id_high, check_voted, votes_threshold_low, votes_threshold_high,
+ *                 votes_per_entry_low, votes_per_entry_high]
+ */
+declare function parseGovernanceValidatorConfig(config: Array<string | number | bigint>): GovernanceValidatorConfig | null;
+/**
+ * Parse any extension config by first identifying its type.
+ *
+ * Returns the parsed config along with the identified type. Useful when
+ * you have a raw extension config and need to determine both what it is
+ * and what its parameters are in one call.
+ */
+declare function parseExtensionConfig(extensionAddress: string, config: Array<string | number | bigint>, chainId: string): {
+    type: "tournament";
+    config: TournamentValidatorConfig;
+} | {
+    type: "erc20Balance";
+    config: ERC20BalanceValidatorConfig;
+} | {
+    type: "opusTroves";
+    config: OpusTrovesValidatorConfig;
+} | {
+    type: "snapshot";
+    config: SnapshotValidatorConfig;
+} | {
+    type: "zkPassport";
+    config: ZkPassportValidatorConfig;
+} | {
+    type: "governance";
+    config: GovernanceValidatorConfig;
+} | {
+    type: "unknown";
+    config: null;
+} | null;
+/**
+ * Get a human-readable label and description for a qualifying mode.
+ */
+declare function getQualifyingModeInfo(mode: number): QualifyingModeInfo;
+/**
+ * Format a raw token amount (bigint) to a human-readable string with decimals.
+ * Removes trailing zeros from the decimal part.
+ */
+declare function formatTokenAmount(value: bigint, decimals: number): string;
+/**
+ * Format a CASH value (18 decimals, 1:1 USD) to a USD string.
+ */
+declare function formatCashToUSD(value: bigint): string;
+
+/**
+ * Entry qualification evaluation.
+ *
+ * Pure functions that determine whether a user qualifies to enter a metagame
+ * event based on pre-fetched data. Each metagame fetches the data through
+ * their own SDK, then passes it here for evaluation.
+ *
+ * The evaluation logic is the same across metagames because the entry
+ * requirement system (token gating, extensions) is shared.
+ */
+
+interface TokenQualificationInput {
+    /** NFT token IDs owned by the player */
+    ownedTokenIds: string[];
+    /** Number of times each token has been used to enter (tokenId → count) */
+    usedEntryCounts: Record<string, number>;
+    /** Max entries per token (0 = unlimited) */
+    entryLimit: number;
+}
+/**
+ * Evaluate token-based entry qualification.
+ *
+ * Checks if the player owns any qualifying NFTs and how many entries
+ * remain for each. Selects the token with the most entries remaining
+ * as the best proof.
+ */
+declare function evaluateTokenQualification(input: TokenQualificationInput): QualificationResult;
+interface ExtensionQualificationInput {
+    /** Results from checking each qualification method against the extension contract */
+    checkedQualifications: Array<{
+        id: string;
+        entriesLeft: number;
+        proof: string[];
+        label?: string;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Evaluate extension-based entry qualification from pre-checked results.
+ *
+ * Each metagame calls the extension contract's `entries_left` function
+ * for each potential qualification proof, then passes the results here.
+ * This function aggregates and selects the best qualification.
+ */
+declare function evaluateExtensionQualification(input: ExtensionQualificationInput): QualificationResult;
+/**
+ * Evaluate entry qualification based on requirement variant.
+ *
+ * This is the top-level function — pass in the requirement type and
+ * the appropriate input, get back a unified QualificationResult.
+ */
+declare function evaluateQualification(variant: EntryRequirementVariant, input: {
+    type: "token";
+    data: TokenQualificationInput;
+} | {
+    type: "extension";
+    data: ExtensionQualificationInput;
+} | {
+    type: "none";
+}): QualificationResult;
+
+/**
+ * Qualification proof construction for EGS entry requirements.
+ *
+ * Builds the on-chain proof calldata that metagames pass when entering
+ * an event. The proof format matches the Cairo `QualificationProof` enum:
+ *
+ *   enum QualificationProof {
+ *     NFT: NFTQualification,    // { token_id: u256 }
+ *     Extension: Span<felt252>,
+ *   }
+ *
+ * Extension-specific data (tournament IDs, positions, addresses, etc.)
+ * is encoded into the `Extension` variant's felt252 array by the
+ * extension's own logic.
+ */
+
+/**
+ * Build the on-chain qualification proof from a QualificationProof object.
+ *
+ * Returns a `CairoOption<CairoCustomEnum>` ready to pass to a metagame
+ * contract's entry function. Returns `None` if no proof is needed.
+ *
+ * @param proof - The qualification proof from evaluateQualification()
+ * @returns CairoOption wrapping the proof enum, ready for contract call
+ */
+declare function buildQualificationProof(proof: QualificationProof | null): CairoOption<CairoCustomEnum>;
+/**
+ * Build an NFT ownership proof.
+ * Used when entry requires holding a specific NFT collection.
+ */
+declare function buildNFTProof(tokenId: string): CairoOption<CairoCustomEnum>;
+/**
+ * Build a tournament validator extension proof.
+ * Used when entry requires participation/winning in a prior tournament.
+ *
+ * The proof array is: [tournament_id, token_id, position]
+ */
+declare function buildTournamentExtensionProof(tournamentId: string, tokenId: string, position: number): CairoOption<CairoCustomEnum>;
+/**
+ * Build a generic extension proof.
+ * Used for any extension validator (ERC20 balance, Opus Troves, Snapshot, etc.).
+ *
+ * @param proofData - Array of felt252 values to pass to the extension contract
+ */
+declare function buildExtensionProof(proofData: string[]): CairoOption<CairoCustomEnum>;
+
+/**
+ * Tournament validator qualification resolution.
+ *
+ * The tournament validator extension requires players to have participated
+ * in (or won) specific prior tournaments. This module resolves which of
+ * a player's game tokens can serve as proof of qualification.
+ *
+ * Every metagame that uses the tournament validator extension needs this
+ * same logic — cross-referencing the player's registrations and leaderboard
+ * positions against the validator's required tournaments.
+ */
+
+/** A registration record — player entered a tournament with a game token */
+interface TournamentRegistration {
+    tournamentId: string;
+    gameTokenId: string;
+}
+/** A leaderboard — ordered list of token IDs for a finalized tournament */
+interface TournamentLeaderboard {
+    tournamentId: string;
+    /** Token IDs in rank order (index 0 = 1st place) */
+    tokenIds: string[];
+    /** Whether this tournament has finalized */
+    isFinalized: boolean;
+}
+/** A resolved qualification proof for the tournament validator */
+interface TournamentQualificationInput {
+    tournamentId: string;
+    tokenId: string;
+    position: number;
+    tournamentName?: string;
+}
+/**
+ * Build a map of tournament ID → game token IDs the player used to enter.
+ *
+ * @param registrations - All registrations for the required tournaments
+ * @param requiredTournamentIds - Tournament IDs from the validator config
+ * @returns Map of tournamentId → array of game token IDs the player registered with
+ */
+declare function buildParticipationMap(registrations: TournamentRegistration[], requiredTournamentIds: string[]): Record<string, string[]>;
+/**
+ * Build a map of tournament ID → winning token positions the player holds.
+ *
+ * Cross-references finalized leaderboards with the player's owned game tokens
+ * to find which tokens placed on which leaderboards.
+ *
+ * @param leaderboards - Leaderboards for the required tournaments
+ * @param ownedGameTokenIds - Game token IDs the player currently owns
+ * @param topPositions - Only count positions within top N (0 = all positions)
+ * @returns Map of tournamentId → array of { tokenId, position }
+ */
+declare function buildWinMap(leaderboards: TournamentLeaderboard[], ownedGameTokenIds: string[], topPositions?: number): Record<string, Array<{
+    tokenId: string;
+    position: number;
+}>>;
+/**
+ * Resolve tournament validator qualification inputs from player data.
+ *
+ * Takes the validator config, the player's registrations/leaderboard positions,
+ * and returns the list of proofs to check against the extension contract.
+ *
+ * @param config - Parsed tournament validator config
+ * @param participationMap - From buildParticipationMap()
+ * @param winMap - From buildWinMap()
+ * @param tournamentNames - Optional map of tournamentId → display name
+ * @returns Array of qualification inputs to pass to the extension contract
+ */
+declare function resolveTournamentQualifications(config: TournamentValidatorConfig, participationMap: Record<string, string[]>, winMap: Record<string, Array<{
+    tokenId: string;
+    position: number;
+}>>, tournamentNames?: Record<string, string>): TournamentQualificationInput[];
+
+/**
+ * Opus Troves entry calculation.
+ *
+ * The Opus Troves extension gates entry based on the player's CASH debt
+ * in the Opus Protocol. This module contains the pure math for determining
+ * how many entries a given debt level allows, and which entries are bannable
+ * if a player's debt drops below the threshold.
+ *
+ * The trove debt fetching (getUserTroveIds, getTroveHealth) is RPC-specific
+ * and stays in each app. This module handles the calculation once you have
+ * the debt value.
+ */
+
+/**
+ * Calculate how many entries a player's total debt allows.
+ *
+ * Two modes based on config:
+ * - Proportional (valuePerEntry > 0): entries = (debt - threshold) / valuePerEntry
+ * - Fixed (valuePerEntry == 0): if debt >= threshold → maxEntries
+ *
+ * @param debt - Player's total CASH debt across all troves (18 decimals)
+ * @param config - Parsed Opus Troves validator config
+ * @returns Number of entries allowed (0 if below threshold)
+ */
+declare function calculateOpusTrovesEntries(debt: bigint, config: OpusTrovesValidatorConfig): number;
+/**
+ * Determine which entries should be banned based on debt vs allowed entries.
+ *
+ * When a player's debt drops below what their entries require, the excess
+ * entries (sorted by token ID ascending — oldest first) become bannable.
+ *
+ * @param registeredTokenIds - Token IDs the player registered with
+ * @param entriesAllowed - From calculateOpusTrovesEntries()
+ * @returns Set of token IDs that should be banned
+ */
+declare function findBannableEntries(registeredTokenIds: string[], entriesAllowed: number): Set<string>;
+/**
+ * Batch calculate bannable entries for multiple players.
+ *
+ * Takes a map of player → { debt, registeredTokenIds } and returns
+ * the set of all bannable token IDs across all players.
+ *
+ * @param players - Map of player address → their debt and registered entries
+ * @param config - Parsed Opus Troves validator config
+ * @returns Set of all bannable token IDs
+ */
+declare function findAllBannableEntries(players: Map<string, {
+    debt: bigint;
+    registeredTokenIds: string[];
+}>, config: OpusTrovesValidatorConfig): Set<string>;
+
+/**
+ * Entry fee configuration as provided by metagame contracts (e.g. Budokan SDK).
+ */
+interface EntryFeeConfig {
+    tokenAddress: string;
+    amount: string;
+    tournamentCreatorShare: number;
+    gameCreatorShare: number;
+    refundShare: number;
+    distribution: unknown;
+    distributionCount: number;
+}
+/**
+ * Build Prize[] from entry fee configuration and entry count.
+ *
+ * Calculates the total entry fee pool, subtracts creator/game/refund shares,
+ * then distributes the remaining prize pool across positions using the
+ * configured distribution curve.
+ *
+ * @param entryFee - Entry fee configuration from the tournament
+ * @param entryCount - Number of entries in the tournament
+ * @returns Array of Prize objects representing entry fee prizes per position
+ */
+declare function buildEntryFeePrizes(entryFee: EntryFeeConfig, entryCount: number): Prize[];
+/**
+ * Token price lookup: normalized address → USD price.
+ */
+type TokenPriceLookup = Record<string, number>;
+/**
+ * Token decimals lookup: normalized address → decimals.
+ */
+type TokenDecimalsLookup = Record<string, number>;
+/**
+ * Calculate total USD value of a set of prizes.
+ *
+ * @param prizes - Array of Prize objects (sponsored + entry fee)
+ * @param prices - Token price lookup (normalized address → USD price)
+ * @param decimals - Token decimals lookup (normalized address → decimals, defaults to 18)
+ * @param normalizeAddress - Function to normalize addresses for lookup (e.g. indexAddress)
+ * @returns Total USD value, or 0 if any required price is missing
+ */
+declare function calculateTotalPrizeValueUSD(prizes: Prize[], prices: TokenPriceLookup, decimals: TokenDecimalsLookup, normalizeAddress?: (addr: string) => string): number;
+/**
+ * Calculate the number of paid positions (places that receive prizes).
+ *
+ * Takes the maximum of sponsored prize positions and entry fee distribution count.
+ *
+ * @param sponsoredPrizes - Array of sponsored Prize objects
+ * @param entryFeeDistributionCount - Number of positions from entry fee distribution
+ * @returns Number of paid places
+ */
+declare function calculatePaidPlaces(sponsoredPrizes: Prize[], entryFeeDistributionCount: number): number;
+
+export { type Distribution, ERC20BalanceValidatorConfig, type EntryFee, type EntryFeeConfig, type EntryRequirement, EntryRequirementVariant, ExtensionAddresses, type ExtensionQualificationInput, ExtensionType, GovernanceValidatorConfig, type GroupedTokenPrize, type NftParseResult, type NftPrizeInput, OpusTrovesValidatorConfig, Prize, QualificationProof, QualificationResult, QualifyingModeInfo, SnapshotValidatorConfig, StatusResult, StatusTimestamps, type TokenDecimalsLookup, type TokenPriceLookup, type TokenQualificationInput, type TournamentLeaderboard, type TournamentQualificationInput, type TournamentRegistration, TournamentValidatorConfig, ZkPassportValidatorConfig, bigintToHex, buildEntryFeePrizes, buildExtensionProof, buildNFTProof, buildParticipationMap, buildQualificationProof, buildTournamentExtensionProof, buildWinMap, calculateOpusTrovesEntries, calculatePaidPlaces, calculatePrizeValue, calculateTotalPrizeValueUSD, computeStatus, displayAddress, evaluateExtensionQualification, evaluateQualification, evaluateTokenQualification, findAllBannableEntries, findBannableEntries, formatCashToUSD, formatTokenAmount, getExtensionAddresses, getOpusSupportedAssets, getQualifyingModeInfo, getWhitelistedExtensionAddresses, groupPrizesByToken, identifyExtensionType, indexAddress, isBefore, isWhitelistedExtension, padAddress, parseERC20BalanceValidatorConfig, parseExtensionConfig, parseGovernanceValidatorConfig, parseNFTBulkInput, parseOpusTrovesValidatorConfig, parseSnapshotValidatorConfig, parseTournamentValidatorConfig, parseZkPassportValidatorConfig, resolveTournamentQualifications };