@provable-games/budokan-sdk 0.1.25 → 0.1.26

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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 } from './player-P6Dd1lNb.cjs';
-export { B as BudokanClient, j as BudokanClientConfig, C as ConnectionMode, k as ConnectionStatus, l as ConnectionStatusState, D as DataSource, m as Erc20Prize, n as Erc721Prize, G as GameConfig, L as LeaderboardConfig, o as LeaderboardEntry, p as Phase, q as PlayerPlacement, 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-P6Dd1lNb.cjs';
+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.cjs';
+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.cjs';
 import { ExtensionPrize, PrizeLike, Prize as Prize$1 } from '@provable-games/metagame-sdk';
 export { EntryFee } from '@provable-games/metagame-sdk';
 import 'starknet';
@@ -696,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.
  *
@@ -802,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, ExtensionPrize$1 as ExtensionPrize, type GameDefaults, type MerkleConfig, type MetagameExtensionPrize, type MetagamePrizeLike, type MetagameTokenPrize, type OpusTrovesConfig, PaginatedResult, PlatformStats, 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, buildClaimRewardCall, buildCreateTournamentCall, buildEnterTournamentCall, buildErc20ApproveCall, buildErc20BalanceConfig, buildMerkleConfig, buildOpusTrovesConfig, buildSubmitScoreCall, buildTournamentValidatorConfig, camelToSnake, explorerAddressUrl, explorerBaseUrl, explorerTxUrl, extensionAddressFor, findWhitelistedGame, getActivityStats, getChainConfig, getGameDefaults, getGameStats, getGameTournaments, getPrizeStats, getRawTokenPrizes, getTokenPrizes, getTournament, getTournamentPrizeAggregation, getTournamentPrizes, getTournamentQualifications, getTournamentRegistrations, getTournamentRewardClaims, getTournamentRewardClaimsSummary, getTournaments, getWhitelistedGames, isExtensionPrize, isGameWhitelisted, isMetagameAdaptablePrize, isRawExtensionPrize, isRawTokenPrize, isTokenPrize, normalizeAddress, parseTournamentIdFromReceipt, snakeToCamel, toMetagameExtensionPrize, toMetagamePrize, toMetagamePrizes, toMetagameTokenPrize, toMetagameTokenPrizes, tournamentPageUrl, tryToMetagamePrize, tryToMetagamePrizes, 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 };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 } from './player-P6Dd1lNb.js';
-export { B as BudokanClient, j as BudokanClientConfig, C as ConnectionMode, k as ConnectionStatus, l as ConnectionStatusState, D as DataSource, m as Erc20Prize, n as Erc721Prize, G as GameConfig, L as LeaderboardConfig, o as LeaderboardEntry, p as Phase, q as PlayerPlacement, 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-P6Dd1lNb.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';
@@ -696,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.
  *
@@ -802,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, ExtensionPrize$1 as ExtensionPrize, type GameDefaults, type MerkleConfig, type MetagameExtensionPrize, type MetagamePrizeLike, type MetagameTokenPrize, type OpusTrovesConfig, PaginatedResult, PlatformStats, 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, buildClaimRewardCall, buildCreateTournamentCall, buildEnterTournamentCall, buildErc20ApproveCall, buildErc20BalanceConfig, buildMerkleConfig, buildOpusTrovesConfig, buildSubmitScoreCall, buildTournamentValidatorConfig, camelToSnake, explorerAddressUrl, explorerBaseUrl, explorerTxUrl, extensionAddressFor, findWhitelistedGame, getActivityStats, getChainConfig, getGameDefaults, getGameStats, getGameTournaments, getPrizeStats, getRawTokenPrizes, getTokenPrizes, getTournament, getTournamentPrizeAggregation, getTournamentPrizes, getTournamentQualifications, getTournamentRegistrations, getTournamentRewardClaims, getTournamentRewardClaimsSummary, getTournaments, getWhitelistedGames, isExtensionPrize, isGameWhitelisted, isMetagameAdaptablePrize, isRawExtensionPrize, isRawTokenPrize, isTokenPrize, normalizeAddress, parseTournamentIdFromReceipt, snakeToCamel, toMetagameExtensionPrize, toMetagamePrize, toMetagamePrizes, toMetagameTokenPrize, toMetagameTokenPrizes, tournamentPageUrl, tryToMetagamePrize, tryToMetagamePrizes, 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 };