@provable-games/metagame-sdk 0.1.0 → 0.1.2

package/dist/prizeAggregation-CHwIJzXr.d.ts

@@ -0,0 +1,325 @@
+interface Token {
+    address: string;
+    name: string;
+    symbol: string;
+    tokenType: "erc20" | "erc721";
+    decimals?: number;
+    logoUrl?: string;
+}
+
+interface Prize {
+    id: string;
+    position: number;
+    tokenAddress: string;
+    tokenType: "erc20" | "erc721";
+    amount: string;
+    sponsorAddress: string;
+}
+
+interface Participant {
+    address: string;
+    rank?: number;
+    score?: number;
+    name?: string;
+    entryNumber?: number;
+}
+
+type StatusVariant = "upcoming" | "registration" | "active" | "submission" | "ended" | "completed" | "locked";
+interface StatusTimestamps {
+    registrationStart?: number | null;
+    registrationEnd?: number | null;
+    start: number;
+    end: number;
+    submissionEnd?: number | null;
+    completed?: boolean;
+    unlocked?: boolean;
+}
+interface StatusResult {
+    label: string;
+    variant: StatusVariant;
+    isActive: boolean;
+    countdown: {
+        targetTimestamp: number;
+        label: string;
+    } | null;
+}
+
+/**
+ * Entry requirement and extension types.
+ *
+ * These types represent the shared entry requirement system used by
+ * EGS metagames. The on-chain extension contracts (tournament validator,
+ * ERC20 balance, Opus Troves, Snapshot) are deployed once and used by
+ * all metagames — the config parsing and qualification logic is the same.
+ */
+/** The type of entry requirement on a metagame event */
+type EntryRequirementVariant = "token" | "extension" | "none";
+/** Known extension types (deployed as shared contracts) */
+type ExtensionType = "tournament" | "erc20Balance" | "opusTroves" | "snapshot" | "zkPassport" | "governance" | "unknown";
+/** Broad category of an extension */
+type ExtensionCategory = "entryRequirement" | "entryFee" | "prize";
+/** Deployed extension contract addresses per chain */
+interface ExtensionAddresses {
+    tournamentValidator?: string;
+    erc20BalanceValidator?: string;
+    opusTrovesValidator?: string;
+    snapshotValidator?: string;
+    zkPassportValidator?: string;
+    governanceValidator?: string;
+}
+/** Parsed config for the tournament validator extension */
+interface TournamentValidatorConfig {
+    /** "won" = must have placed in top N, "participated" = just entered */
+    requirementType: "won" | "participated";
+    /** How tournaments are combined for qualification */
+    qualifyingMode: QualifyingMode;
+    /** Number of top positions that count (0 = all positions) */
+    topPositions: number;
+    /** Tournament IDs that qualify */
+    tournamentIds: string[];
+}
+/** How multiple qualifying tournaments are evaluated */
+declare enum QualifyingMode {
+    /** Qualify in at least one tournament */
+    AtLeastOne = 0,
+    /** Track entry limits separately per tournament */
+    CumulativePerTournament = 1,
+    /** Must qualify in all tournaments */
+    All = 2,
+    /** Track entries per qualifying token ID */
+    CumulativePerEntry = 3,
+    /** Must participate in all, win in any one */
+    AllParticipateAnyWin = 4,
+    /** Must participate in all, entries multiply by count */
+    AllWithCumulative = 5
+}
+/** Human-readable label and description for a qualifying mode */
+interface QualifyingModeInfo {
+    label: string;
+    description: string;
+}
+/** Parsed config for the ERC20 balance validator extension */
+interface ERC20BalanceValidatorConfig {
+    tokenAddress: string;
+    /** Minimum token balance required (raw, in smallest units) */
+    minThreshold: bigint;
+    /** Maximum token balance cap (raw, 0 = unlimited) */
+    maxThreshold: bigint;
+    /** Token amount per entry (raw, 0 = single entry regardless of balance) */
+    valuePerEntry: bigint;
+    /** Maximum entries allowed (0 = unlimited) */
+    maxEntries: number;
+}
+/** Parsed config for the Opus Troves validator extension */
+interface OpusTrovesValidatorConfig {
+    /** Number of specific assets required (0 = wildcard, any asset) */
+    assetCount: number;
+    /** Specific collateral asset addresses (empty if wildcard) */
+    assetAddresses: string[];
+    /** Minimum debt threshold (raw, 18 decimals — CASH is 1:1 USD) */
+    threshold: bigint;
+    /** Debt value per entry (raw, 0 = single entry) */
+    valuePerEntry: bigint;
+    /** Maximum entries allowed (0 = unlimited) */
+    maxEntries: number;
+}
+/** Parsed config for the Snapshot validator extension */
+interface SnapshotValidatorConfig {
+    snapshotId: string;
+}
+/** Result of checking whether a user qualifies to enter */
+interface QualificationResult {
+    /** Whether the user meets the entry requirements */
+    meetsRequirements: boolean;
+    /** The best proof to submit (app-specific format) */
+    bestProof: QualificationProof | null;
+    /** All valid qualification methods with entries remaining */
+    qualifications: QualificationEntry[];
+    /** Total entries remaining across all qualification methods */
+    totalEntriesLeft: number;
+}
+/** A single way the user can qualify */
+interface QualificationEntry {
+    /** Unique ID for this qualification method */
+    id: string;
+    /** Entries remaining via this method */
+    entriesLeft: number;
+    /** The proof data for this qualification */
+    proof: QualificationProof;
+    /** Human-readable label */
+    label?: string;
+    /** Additional metadata for display */
+    metadata?: Record<string, unknown>;
+}
+/** Parsed config for the ZK Passport validator extension */
+interface ZkPassportValidatorConfig {
+    verifierAddress: string;
+    serviceScope: bigint;
+    subscope: bigint;
+    paramCommitment: bigint;
+    maxProofAge: number;
+    nullifierType: number;
+}
+/** Parsed config for the Governance validator extension */
+interface GovernanceValidatorConfig {
+    governorAddress: string;
+    governanceTokenAddress: string;
+    balanceThreshold: bigint;
+    proposalId: bigint;
+    checkVoted: boolean;
+    votesThreshold: bigint;
+    votesPerEntry: bigint;
+}
+/** Generic config placeholder for entry fee extensions */
+interface EntryFeeExtensionConfig {
+    tokenAddress: string;
+    amount: bigint;
+    /** Additional config fields (extension-specific) */
+    extra?: Record<string, unknown>;
+}
+/** Generic config placeholder for prize extensions */
+interface PrizeExtensionConfig {
+    tokenAddress: string;
+    amount: bigint;
+    /** Additional config fields (extension-specific) */
+    extra?: Record<string, unknown>;
+}
+/** Proof data for entering — varies by requirement type */
+interface QualificationProof {
+    type: EntryRequirementVariant;
+    /** For token requirements: the NFT token ID to use */
+    tokenId?: string;
+    /** Raw proof array to pass to the extension contract */
+    extensionProof?: string[];
+}
+
+declare function formatNumber(num: number): string;
+declare function formatPrizeAmount(num: number): string;
+declare function formatUsdValue(value: number): string;
+declare function formatScore(num: number): string;
+declare function formatTime(seconds: number): string;
+declare function getOrdinalSuffix(position: number): string;
+type DistributionType = "linear" | "exponential" | "uniform";
+declare function calculatePayouts(totalPlaces: number, weightingFactor: number): number[];
+declare function calculateDistribution(positions: number, weight: number, creatorFee?: number, gameFee?: number, refundShare?: number, distributionType?: DistributionType): number[];
+
+/**
+ * Entry fee breakdown calculation.
+ *
+ * Takes a total fee pool and share percentages (in basis points, where 10000 = 100%)
+ * and returns the amount allocated to each bucket.
+ *
+ * This is the same math that on-chain metagame contracts use to split entry fees
+ * between creator, game creator, refund pool, and prize pool.
+ */
+interface EntryFeeBreakdown {
+    /** Total fee collected from all entrants */
+    totalCollected: bigint;
+    /** Amount going to the metagame creator */
+    creatorAmount: bigint;
+    /** Amount going to the game creator */
+    gameCreatorAmount: bigint;
+    /** Amount reserved for refunds */
+    refundAmount: bigint;
+    /** Amount available for prize distribution */
+    prizePoolAmount: bigint;
+}
+interface EntryFeeShares {
+    /** Creator share in basis points (0-10000) */
+    creatorShare: number;
+    /** Game creator share in basis points (0-10000) */
+    gameCreatorShare: number;
+    /** Refund share in basis points (0-10000) */
+    refundShare: number;
+}
+/**
+ * Calculate how an entry fee pool is split between creator, game, refund, and prizes.
+ *
+ * @param feePerEntry - Fee amount per entry (in token units, as bigint)
+ * @param entryCount - Number of entries
+ * @param shares - Share percentages in basis points (10000 = 100%)
+ * @returns Breakdown of amounts for each bucket
+ */
+declare function calculateEntryFeeBreakdown(feePerEntry: bigint, entryCount: number, shares: EntryFeeShares): EntryFeeBreakdown;
+/**
+ * Distribute a prize pool across positions using a distribution curve.
+ *
+ * Takes the prize pool amount and distribution percentages (from calculateDistribution),
+ * and returns the actual token amount per position.
+ *
+ * @param prizePoolAmount - Total pool to distribute (bigint, in smallest token units)
+ * @param percentages - Distribution percentages per position (from calculateDistribution)
+ * @returns Array of { position, amount } where position is 1-indexed
+ */
+declare function distributePool(prizePoolAmount: bigint, percentages: number[]): Array<{
+    position: number;
+    amount: bigint;
+}>;
+
+/**
+ * Prize aggregation by position.
+ *
+ * Groups prizes by position, summing ERC20 amounts and collecting ERC721 IDs.
+ * Works with Prize — metagame apps adapt their raw prize data to this
+ * shape before calling these functions.
+ */
+interface PositionPrizeGroup {
+    position: number;
+    erc20: Array<{
+        tokenAddress: string;
+        totalAmount: bigint;
+    }>;
+    erc721: Array<{
+        tokenAddress: string;
+        tokenIds: string[];
+    }>;
+}
+/**
+ * Group prizes by leaderboard position, aggregating ERC20 amounts and
+ * collecting ERC721 token IDs per position.
+ */
+declare function aggregatePrizesByPosition(prizes: Prize[]): PositionPrizeGroup[];
+/**
+ * Sponsor contribution aggregated from prizes.
+ */
+interface SponsorContribution {
+    sponsorAddress: string;
+    tokens: Array<{
+        tokenAddress: string;
+        totalAmount: bigint;
+        prizeCount: number;
+    }>;
+    /** NFT collections grouped by token address, with individual token IDs */
+    nftCollections: Array<{
+        tokenAddress: string;
+        tokenIds: string[];
+    }>;
+    nftCount: number;
+    totalPrizeCount: number;
+}
+/**
+ * Group prizes by sponsor address, aggregating ERC20 contributions and
+ * grouping NFTs by collection. Filters out prizes with no sponsor
+ * (address "0x0" or empty).
+ *
+ * For ERC721 prizes, `prize.amount` is expected to hold the token ID
+ * (this is the convention set by the prize adapter).
+ *
+ * @param prizes - Array of Prize with sponsorAddress populated
+ * @returns Sponsor contributions sorted by total prize count (descending)
+ */
+declare function aggregatePrizesBySponsor(prizes: Prize[]): SponsorContribution[];
+/**
+ * Filter prizes to only those not yet claimed.
+ *
+ * @param prizes - All prizes the user could potentially claim
+ * @param claimedIds - Set of prize IDs already claimed
+ * @returns Prizes not yet claimed
+ */
+declare function filterClaimablePrizes(prizes: Prize[], claimedIds: Set<string>): Prize[];
+/**
+ * Filter out ERC20 prizes with zero amount.
+ */
+declare function filterZeroPrizes(prizes: Prize[]): Prize[];
+
+export { filterZeroPrizes as A, formatNumber as B, formatPrizeAmount as C, type DistributionType as D, type ExtensionAddresses as E, formatScore as F, type GovernanceValidatorConfig as G, formatTime as H, formatUsdValue as I, getOrdinalSuffix as J, type OpusTrovesValidatorConfig as O, type Prize as P, type QualifyingModeInfo as Q, type StatusTimestamps as S, type TournamentValidatorConfig as T, type ZkPassportValidatorConfig as Z, type StatusResult as a, type ExtensionType as b, type ERC20BalanceValidatorConfig as c, type SnapshotValidatorConfig as d, type QualificationResult as e, type EntryRequirementVariant as f, type QualificationProof as g, type EntryFeeBreakdown as h, type EntryFeeExtensionConfig as i, type EntryFeeShares as j, type ExtensionCategory as k, type Participant as l, type PositionPrizeGroup as m, type PrizeExtensionConfig as n, type QualificationEntry as o, QualifyingMode as p, type SponsorContribution as q, type StatusVariant as r, type Token as s, aggregatePrizesByPosition as t, aggregatePrizesBySponsor as u, calculateDistribution as v, calculateEntryFeeBreakdown as w, calculatePayouts as x, distributePool as y, filterClaimablePrizes as z };