@provable-games/budokan-sdk 0.1.24 → 0.1.26

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { T as Tournament, P as PrizeAggregation, a as Prize, b as PaginatedResult, Q as QualificationEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, e as TournamentListParams, f as PlatformStats, g as PrizeStats, W as WSSubscribeOptions, h as WSEventHandler } from './player-C2GE9Lop.js';
-export { B as BudokanClient, i as BudokanClientConfig, C as ConnectionMode, j as ConnectionStatus, k as ConnectionStatusState, D as DataSource, G as GameConfig, L as LeaderboardConfig, l as LeaderboardEntry, m as Phase, n as PlayerPlacement, o as PlayerRewards, S as Schedule, p as WSChannel, q as WSEventMessage, r as WSMessage, s as WSSubscribeMessage, t as WSUnsubscribeMessage, u as createBudokanClient } from './player-C2GE9Lop.js';
+import { T as Tournament, P as PrizeAggregation, a as Prize, b as PaginatedResult, Q as QualificationEntry, R as Registration, c as RewardClaim, d as RewardClaimSummary, e as TournamentListParams, f as PlatformStats, g as PrizeStats, W as WSSubscribeOptions, h as WSEventHandler, i as TokenPrize, E as ExtensionPrize$1, j as PlayerPlacement, k as Phase } from './player-CbAYHoW8.js';
+export { B as BudokanClient, l as BudokanClientConfig, C as ConnectionMode, m as ConnectionStatus, n as ConnectionStatusState, D as DataSource, o as Erc20Prize, p as Erc721Prize, G as GameConfig, L as LeaderboardConfig, q as LeaderboardEntry, r as PlayerRewards, S as Schedule, s as WSChannel, t as WSEventMessage, u as WSMessage, v as WSSubscribeMessage, w as WSUnsubscribeMessage, x as createBudokanClient } from './player-CbAYHoW8.js';
+import { ExtensionPrize, PrizeLike, Prize as Prize$1 } from '@provable-games/metagame-sdk';
 export { EntryFee } from '@provable-games/metagame-sdk';
 import 'starknet';
 
@@ -180,6 +181,80 @@ declare function camelToSnake<T>(obj: unknown): T;
 
 declare function withRetry<T>(fn: () => Promise<T>, attempts?: number, delay?: number): Promise<T>;
 
+type MetagameTokenPrize = Prize$1;
+type MetagameExtensionPrize = ExtensionPrize;
+type MetagamePrizeLike = PrizeLike;
+declare function isRawTokenPrize(prize: Prize): prize is TokenPrize;
+declare function isRawExtensionPrize(prize: Prize): prize is ExtensionPrize$1;
+declare function isTokenPrize(prize: Prize): prize is TokenPrize;
+declare function isExtensionPrize(prize: Prize): prize is ExtensionPrize$1;
+/**
+ * Returns true when a prize is a valid Budokan token/extension prize and has a
+ * hydrated leaderboard position suitable for the metagame prize shape.
+ */
+declare function isMetagameAdaptablePrize(prize: Prize): prize is TokenPrize | ExtensionPrize$1;
+/**
+ * Returns validated raw token prizes. Extension records are skipped without
+ * validation; malformed `erc20`/`erc721` records throw instead of being
+ * silently dropped. RPC records with `payoutPosition === 0` are returned here
+ * for raw token-prize visibility.
+ */
+declare function getRawTokenPrizes(prizes: readonly Prize[]): TokenPrize[];
+/**
+ * Returns validated hydrated token prizes. Extension records are skipped
+ * without validation, and valid raw token prizes with `payoutPosition === 0`
+ * are skipped; malformed `erc20`/`erc721` records throw instead of being
+ * silently dropped.
+ */
+declare function getTokenPrizes(prizes: readonly Prize[]): TokenPrize[];
+/**
+ * Converts a guard-validated Budokan token prize into the Metagame SDK token
+ * prize shape. Metagame token prizes do not carry Budokan distribution fields,
+ * so distributed ERC20 prizes are represented by their aggregate `amount` at
+ * `payoutPosition`; use the original Budokan `Prize` for payout-split math.
+ * For ERC721 prizes, metagame-sdk@0.1.13 uses `amount` to carry the token ID.
+ * Throws when `payoutPosition` is zero because the RPC path uses zero for
+ * unhydrated token-prize positions and metagame positions are leaderboard slots.
+ */
+declare function toMetagameTokenPrize(prize: TokenPrize): MetagameTokenPrize;
+/**
+ * Converts a guard-validated Budokan extension prize into the Metagame SDK
+ * extension-prize shape. Throws when `payoutPosition` is zero because metagame
+ * positions are leaderboard slots and the RPC path uses zero for unhydrated
+ * prize positions.
+ */
+declare function toMetagameExtensionPrize(prize: ExtensionPrize$1): MetagameExtensionPrize;
+/**
+ * Converts supported Budokan prize variants into Metagame SDK prize shapes.
+ * Throws when a prize has malformed fields or an unhydrated payout position.
+ * Raw-but-valid zero-position prizes throw the unhydrated-position error.
+ * See `toMetagameTokenPrize` for token prize distribution behavior.
+ */
+declare function toMetagamePrize(prize: Prize): MetagamePrizeLike;
+/**
+ * Non-throwing metagame adapter. Returns null for malformed prize records and
+ * for valid RPC-sourced prizes whose `payoutPosition` is not hydrated yet.
+ */
+declare function tryToMetagamePrize(prize: Prize): MetagamePrizeLike | null;
+/**
+ * Converts supported Budokan prize variants into Metagame SDK prize shapes.
+ * Throws when any prize has malformed fields or an unhydrated payout position.
+ * See `toMetagameTokenPrize` for token prize distribution behavior.
+ */
+declare function toMetagamePrizes(prizes: readonly Prize[]): MetagamePrizeLike[];
+/**
+ * Non-throwing batch metagame adapter. Skips malformed records and valid
+ * RPC-sourced prizes whose `payoutPosition` is not hydrated yet.
+ */
+declare function tryToMetagamePrizes(prizes: readonly Prize[]): MetagamePrizeLike[];
+/**
+ * Converts Budokan token prizes into Metagame SDK token prize shapes. Extension
+ * records are skipped without validation. Throws for malformed token records
+ * and unhydrated token positions. See `toMetagameTokenPrize` for distribution
+ * behavior.
+ */
+declare function toMetagameTokenPrizes(prizes: readonly Prize[]): MetagameTokenPrize[];
+
 interface ChainConfig {
     rpcUrl: string;
     apiBaseUrl: string;
@@ -517,6 +592,8 @@ type RewardType = {
     kind: "entry_fee_tournament_creator";
 } | {
     kind: "entry_fee_game_creator";
+} | {
+    kind: "entry_fee_protocol_fee";
 } | {
     kind: "entry_fee_refund";
     tokenId: string;
@@ -619,6 +696,233 @@ interface ReceiptWithEvents {
  */
 declare function parseTournamentIdFromReceipt(receipt: ReceiptWithEvents, budokanAddress: string): bigint | undefined;
 
+/**
+ * Pure distribution + entry-fee math for Budokan.
+ *
+ * This module is the single source of truth for "how much does position N
+ * get?" — the same arithmetic the budokan client used to duplicate in
+ * `computeEntryFeeAmount` / `computePrizePercentages` / `processEntryFeePrizes`.
+ *
+ * All functions are pure: no I/O, no contract calls, no `Date.now()`. Token
+ * amounts are `bigint` in smallest token units; basis-point shares are plain
+ * numbers (0–10000). USD conversion, decimals, and formatting stay in the
+ * consumer.
+ *
+ * Distribution percentages are computed with the shared `calculateDistribution`
+ * from `@provable-games/metagame-sdk` — the *exact* function the budokan client
+ * renders payouts with — so amounts match between the SDK, budokan.gg, and any
+ * third-party integration. (The final on-chain claim amount is computed by the
+ * contract's fixed-point math; these values are the canonical client-side
+ * estimate, suitable for display and for filtering unclaimable zero slices.)
+ *
+ * Entry-fee split semantics follow the contract
+ * (`packages/rewards/src/budokan_rewards.cairo::_claim_entry_fee_position`):
+ * the position pool is the entry-fee pool **minus** the tournament-creator,
+ * game-creator, refund, *and protocol-fee* shares. The client historically
+ * omitted the protocol fee here and over-counted the position pool — this
+ * module fixes that by taking `protocolFeeShare` as an explicit input.
+ */
+
+type DistributionKind = "linear" | "exponential" | "uniform" | "custom" | "unknown";
+interface ParsedDistribution {
+    type: DistributionKind;
+    /**
+     * Raw weight as stored on-chain (scaled ×10 — e.g. `10` = 1.0). `0` for
+     * Uniform/Custom. `distributionPercentages` divides by 10 internally.
+     */
+    weight: number;
+    /** For Custom distributions, the raw u16 basis-point shares (one per paid position). */
+    customWeights?: number[];
+}
+/**
+ * Normalize the many wire shapes of the Cairo `Distribution` enum into a flat
+ * `{ type, weight, customWeights }`. Handles:
+ *   - starknet.js v9 CairoCustomEnum: `{ variant: { Exponential: 100 } }`
+ *   - SDK / PascalCase: `{ Exponential: 100 }`
+ *   - lower-cased JSON (indexer/API): `{ exponential: 100 }`
+ *   - explicit `{ type, weight }`
+ *   - `Option`-wrapped weights (`{ Some: n }`)
+ *
+ * Unknown / missing input → `{ type: "unknown", weight: 0 }`, which
+ * `distributionPercentages` treats as Uniform.
+ */
+declare function parseDistribution(dist: unknown): ParsedDistribution;
+/**
+ * Build a `ParsedDistribution` from the flat fields the SDK carries on a
+ * sponsored `Prize` (`distributionType` / `distributionWeight` /
+ * `distributionShares`).
+ */
+declare function prizeDistribution(prize: Pick<Prize, "distributionType" | "distributionWeight" | "distributionShares">): ParsedDistribution;
+/**
+ * Per-position percentages (each 0–100, summing to ~100) for a distribution
+ * across `count` paid positions. Generalizes the client's
+ * `computeEntryFeePercentages` / `computePrizePercentages`.
+ *
+ * - linear/exponential: delegates to metagame-sdk's `calculateDistribution`
+ *   (weight is divided by 10 to undo the on-chain ×10 scaling).
+ * - uniform / unknown: equal split.
+ * - custom: raw basis-point shares ÷ 100; falls back to uniform when the
+ *   shares array length doesn't match `count`.
+ */
+declare function distributionPercentages(dist: ParsedDistribution, count: number): number[];
+/** Input shape for entry-fee split math. Mirrors the on-chain built-in `EntryFee`
+ *  plus the per-tournament protocol-fee snapshot (carried on `Tournament`). */
+interface EntryFeeSplitInput {
+    /** Per-entry fee in smallest token units (decimal string or bigint). */
+    amount: string | bigint;
+    /** Number of paid entries collected. */
+    entryCount: number;
+    /** Basis-point shares (0–10000). Omitted / null → 0. */
+    tournamentCreatorShare?: number | null;
+    gameCreatorShare?: number | null;
+    refundShare?: number | null;
+    /** Protocol-fee bps snapshotted for the tournament (`Tournament.protocolFeeShare`). */
+    protocolFeeShare?: number | null;
+}
+interface EntryFeeSplit {
+    /** Total fee pool = amount × entryCount. */
+    total: bigint;
+    /** Pool shared across leaderboard positions = floor(availableShare × total / 10000). */
+    positionPool: bigint;
+    tournamentCreator: bigint;
+    gameCreator: bigint;
+    refund: bigint;
+    protocolFee: bigint;
+    /** Basis points left for positions after fixed shares (clamped ≥ 0). */
+    availableShareBps: number;
+}
+/**
+ * Split a built-in entry-fee pool into its on-chain components. The position
+ * pool reserves the tournament-creator, game-creator, refund, *and* protocol
+ * fee — matching `_claim_entry_fee_position`'s `available_share`.
+ *
+ * Note: each component is floored independently (sub-wei dust may not sum to
+ * `total`, exactly as on-chain).
+ */
+declare function entryFeeSplit(input: EntryFeeSplitInput): EntryFeeSplit;
+/** The on-chain `EntryFee` distribution shape this module needs to size a
+ *  position payout. A superset of `EntryFeeSplitInput`. */
+interface EntryFeePositionInput extends EntryFeeSplitInput {
+    /** Raw on-chain `Distribution` (any wire shape — parsed internally). */
+    distribution: unknown;
+    /** Number of paid positions (`distribution_count`). */
+    distributionCount: number;
+}
+/**
+ * Amount a single leaderboard `position` (1-indexed) claims from the entry-fee
+ * pool. Generalizes the client's `computeEntryFeeAmount` — and fixes its
+ * protocol-fee over-count by reserving `protocolFeeShare`.
+ *
+ * Returns `0n` when the position is outside the paid range, the pool is empty,
+ * or the share rounds to zero (the contract makes such positions unclaimable).
+ */
+declare function entryFeePositionPayout(input: EntryFeePositionInput, position: number): bigint;
+/**
+ * Amount a single `position` (1-indexed) claims from a distributed sponsored
+ * ERC20 prize. Generalizes the client's per-position `computePrizePercentages`
+ * + amount slicing. Returns `0n` for non-distributed / non-ERC20 prizes, a
+ * position outside the paid range, or a zero slice.
+ */
+declare function sponsorPrizePayout(prize: Prize, position: number): bigint;
+
+/**
+ * Player reward resolution — "which rewards can this player still claim, and
+ * what `claim_reward` calls assemble them?"
+ *
+ * Generalizes the budokan client's `buildPlayerClaimCalls` + `computeEarnings`
+ * + `getClaimablePrizes`. Pure: walks placements + prize/entry-fee data +
+ * existing claims and returns not-yet-claimed, non-zero rewards plus the
+ * `Call`s to claim them (via the tested `buildClaimRewardCall` encoder — so
+ * the claim-encoding bug class the SDK was created to kill can't recur).
+ *
+ * Scope (matches the client): the connected player's own placements only —
+ * entry-fee position prizes + sponsored prizes. Creator shares, protocol fee,
+ * and per-token refunds are pool/owner concerns, not placement-derived, and
+ * are intentionally excluded.
+ */
+
+type ClaimableRewardSource = "entry_fee_position" | "sponsor_single" | "sponsor_distributed";
+interface ClaimableReward {
+    tournamentId: string;
+    /** Human label for UI/telemetry (`tournament.name` or `#id`). */
+    tournamentName: string;
+    /** Reward descriptor — feed straight to `buildClaimRewardCall` / `buildClaimCalls`. */
+    reward: RewardType;
+    /** Where the reward comes from (UI grouping / telemetry). */
+    source: ClaimableRewardSource;
+    /** 1-indexed leaderboard position the reward is for. */
+    position: number;
+    /** Token contract (ERC20/ERC721). */
+    tokenAddress: string | null;
+    tokenType: "erc20" | "erc721";
+    /** ERC20 amount in smallest units; `undefined` for ERC721 (one NFT). */
+    amount?: bigint;
+    /** ERC721 token id, when applicable. */
+    tokenId?: string | null;
+}
+interface GetClaimableRewardsInput {
+    placements: PlayerPlacement[];
+    tournaments: Tournament[];
+    prizes: Prize[];
+    /** Existing reward-claim records. Only those with `claimed === true` filter rewards out. */
+    existingClaims: RewardClaim[];
+}
+/**
+ * The not-yet-claimed, non-zero rewards across the player's placements.
+ *
+ * Skips:
+ * - already-claimed rewards (would revert),
+ * - 0-amount ERC20 slices (contract truncation makes them unclaimable),
+ * - creator/protocol/refund shares (not placement-derived).
+ */
+declare function getClaimableRewards(input: GetClaimableRewardsInput): ClaimableReward[];
+/**
+ * Turn resolved {@link ClaimableReward}s into `claim_reward` `Call`s for
+ * `account.execute([...])`. Order is preserved.
+ */
+declare function buildClaimCalls(rewards: ClaimableReward[], budokanAddress: string): Call[];
+
+/**
+ * Tournament phase derivation — the single source of truth for "what phase is
+ * this tournament in right now?", mirroring the contract exactly
+ * (`packages/budokan/src/libs/schedule.cairo::current_phase`).
+ *
+ * The client used to recompute this inline (`isStarted/isEnded/isSubmitted`);
+ * this generalizes it so the client, bot, and any integration agree with the
+ * chain on phase boundaries (all comparisons are strict `<`, so a boundary
+ * second belongs to the *later* phase, matching the Cairo `if` ladder).
+ */
+
+/** Minimal schedule + creation-time shape needed to derive a phase. Matches
+ *  the relevant subset of `Tournament` (top-level delay fields + on-chain
+ *  created-at), so a full `Tournament` satisfies it directly. */
+interface PhaseInput {
+    /** Unix seconds (string or number) the tournament was created on-chain. */
+    createdAtOnchain?: string | number | null;
+    registrationStartDelay?: number | null;
+    registrationEndDelay?: number | null;
+    gameStartDelay?: number | null;
+    gameEndDelay?: number | null;
+    submissionDuration?: number | null;
+    /** Fallback structured schedule (used when top-level delays are absent). */
+    schedule?: {
+        registrationStartDelay: number;
+        registrationEndDelay: number;
+        gameStartDelay: number;
+        gameEndDelay: number;
+        submissionDuration: number;
+    } | null;
+}
+/**
+ * Derive the current {@link Phase}. Returns `null` when the on-chain
+ * creation time is unknown (can't anchor the schedule).
+ *
+ * @param t - tournament schedule + `createdAtOnchain`
+ * @param nowSeconds - Unix seconds to evaluate at (defaults to wall-clock now).
+ *   Pass an explicit value for deterministic/testable derivation.
+ */
+declare function tournamentPhase(t: PhaseInput, nowSeconds?: number): Phase | null;
+
 /**
  * Entry-requirement validator extensions.
  *
@@ -725,4 +1029,4 @@ interface TournamentValidatorConfig {
  */
 declare function buildTournamentValidatorConfig(cfg: TournamentValidatorConfig): string[];
 
-export { type AddPrizeArgs, BudokanApiError, BudokanConnectionError, BudokanError, BudokanTimeoutError, CHAINS, type Call, type ChainConfig, type CreateTournamentArgs, DataSourceError, type DistributionSpec, type EnterTournamentArgs, type EntryFeeArgs, type EntryRequirementArgs, type EntryRequirementSpec, type Erc20BalanceConfig, type ExtensionPresetKind, type GameDefaults, type MerkleConfig, type OpusTrovesConfig, PaginatedResult, PlatformStats, Prize, PrizeAggregation, type PrizeSpec, PrizeStats, QualificationEntry, type ReceiptWithEvents, Registration, RewardClaim, RewardClaimSummary, type RewardType, RpcError, type TokenTypeSpec, Tournament, TournamentListParams, TournamentNotFoundError, type TournamentRequirementType, type TournamentValidatorConfig, WSEventHandler, WSManager, WSSubscribeOptions, type WhitelistChain, type WhitelistedGame, buildAddPrizeCall, buildClaimRewardCall, buildCreateTournamentCall, buildEnterTournamentCall, buildErc20ApproveCall, buildErc20BalanceConfig, buildMerkleConfig, buildOpusTrovesConfig, buildSubmitScoreCall, buildTournamentValidatorConfig, camelToSnake, explorerAddressUrl, explorerBaseUrl, explorerTxUrl, extensionAddressFor, findWhitelistedGame, getActivityStats, getChainConfig, getGameDefaults, getGameStats, getGameTournaments, getPrizeStats, getTournament, getTournamentPrizeAggregation, getTournamentPrizes, getTournamentQualifications, getTournamentRegistrations, getTournamentRewardClaims, getTournamentRewardClaimsSummary, getTournaments, getWhitelistedGames, isGameWhitelisted, normalizeAddress, parseTournamentIdFromReceipt, snakeToCamel, tournamentPageUrl, u256ToLowHigh, withRetry };
+export { type AddPrizeArgs, BudokanApiError, BudokanConnectionError, BudokanError, BudokanTimeoutError, CHAINS, type Call, type ChainConfig, type ClaimableReward, type ClaimableRewardSource, type CreateTournamentArgs, DataSourceError, type DistributionKind, type DistributionSpec, type EnterTournamentArgs, type EntryFeeArgs, type EntryFeePositionInput, type EntryFeeSplit, type EntryFeeSplitInput, type EntryRequirementArgs, type EntryRequirementSpec, type Erc20BalanceConfig, type ExtensionPresetKind, ExtensionPrize$1 as ExtensionPrize, type GameDefaults, type GetClaimableRewardsInput, type MerkleConfig, type MetagameExtensionPrize, type MetagamePrizeLike, type MetagameTokenPrize, type OpusTrovesConfig, PaginatedResult, type ParsedDistribution, Phase, type PhaseInput, PlatformStats, PlayerPlacement, Prize, PrizeAggregation, type PrizeSpec, PrizeStats, QualificationEntry, type ReceiptWithEvents, Registration, RewardClaim, RewardClaimSummary, type RewardType, RpcError, TokenPrize, type TokenTypeSpec, Tournament, TournamentListParams, TournamentNotFoundError, type TournamentRequirementType, type TournamentValidatorConfig, WSEventHandler, WSManager, WSSubscribeOptions, type WhitelistChain, type WhitelistedGame, buildAddPrizeCall, buildClaimCalls, buildClaimRewardCall, buildCreateTournamentCall, buildEnterTournamentCall, buildErc20ApproveCall, buildErc20BalanceConfig, buildMerkleConfig, buildOpusTrovesConfig, buildSubmitScoreCall, buildTournamentValidatorConfig, camelToSnake, distributionPercentages, entryFeePositionPayout, entryFeeSplit, explorerAddressUrl, explorerBaseUrl, explorerTxUrl, extensionAddressFor, findWhitelistedGame, getActivityStats, getChainConfig, getClaimableRewards, getGameDefaults, getGameStats, getGameTournaments, getPrizeStats, getRawTokenPrizes, getTokenPrizes, getTournament, getTournamentPrizeAggregation, getTournamentPrizes, getTournamentQualifications, getTournamentRegistrations, getTournamentRewardClaims, getTournamentRewardClaimsSummary, getTournaments, getWhitelistedGames, isExtensionPrize, isGameWhitelisted, isMetagameAdaptablePrize, isRawExtensionPrize, isRawTokenPrize, isTokenPrize, normalizeAddress, parseDistribution, parseTournamentIdFromReceipt, prizeDistribution, snakeToCamel, sponsorPrizePayout, toMetagameExtensionPrize, toMetagamePrize, toMetagamePrizes, toMetagameTokenPrize, toMetagameTokenPrizes, tournamentPageUrl, tournamentPhase, tryToMetagamePrize, tryToMetagamePrizes, u256ToLowHigh, withRetry };