@provable-games/budokan-sdk 0.1.23 → 0.1.25

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-BUynfv7D.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-BUynfv7D.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 } 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 { 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;
@@ -189,5 +264,542 @@ interface ChainConfig {
 }
 declare const CHAINS: Record<string, ChainConfig>;
 declare function getChainConfig(chain: string): ChainConfig | undefined;
+/**
+ * Voyager block-explorer base URL for the chain. Used to build
+ * shareable links for tx hashes and contracts in chat / Discord / CLI
+ * surfaces. Unknown chains fall back to mainnet — Voyager 404s
+ * gracefully and the caller can still click the link.
+ */
+declare function explorerBaseUrl(chain: string): string;
+/** Voyager URL for a transaction hash. */
+declare function explorerTxUrl(chain: string, txHash: string): string;
+/** Voyager URL for a contract / account address. */
+declare function explorerAddressUrl(chain: string, address: string): string;
+/**
+ * Canonical budokan.gg URL for a tournament. The `network` query param
+ * tells the client which chain to load — important when sharing sepolia
+ * tournaments since the site defaults to mainnet.
+ */
+declare function tournamentPageUrl(chain: string, tournamentId: string | number | bigint): string;
+
+/** Subset of chain identifiers the whitelist covers. */
+type WhitelistChain = "mainnet" | "sepolia";
+interface WhitelistedGame {
+    /** Canonical 0x-prefixed, 66-char lowercase contract address. */
+    contractAddress: string;
+    /** Display name. */
+    name: string;
+    /** Optional remote logo URL. The SDK never bundles binary assets — host externally. */
+    imageUrl?: string;
+    /** Game's homepage / landing URL. */
+    url?: string;
+    /** Direct-play URL template. May include `{tokenId}`. */
+    playUrl?: string;
+    /** Optional spectator URLs. */
+    watchLink?: string;
+    replayLink?: string;
+    /** True if the game requires a Cartridge Controller to play. */
+    controllerOnly?: boolean;
+    /** Hide from default listings while keeping the metadata around. */
+    disabled?: boolean;
+    /** Minimum entry fee floor in USD, used as a UX hint at tournament-create time. */
+    minEntryFeeUsd?: number;
+    /** Recommended ERC-20 token for entry fee on this chain. */
+    defaultEntryFeeToken?: string;
+    /** Game-creator share of entry fee (basis-points-style — `5` means 5%). */
+    defaultGameFeePercentage?: number;
+    /** Approximate gas cost per entry, in USD — UX hint only. */
+    averageGasCostUsd?: number;
+    /** Some game tokens use animated SVG that needs `<object>` rather than `<img>`. */
+    objectImage?: boolean;
+    /**
+     * Score ordering. `true` = lower-is-better (golf-style), `false` = higher-
+     * is-better (points-style). Defaults to false when omitted — most games
+     * are points-based.
+     */
+    leaderboardAscending?: boolean;
+    /**
+     * Whether the game's score is only valid once the game is in a completed
+     * (e.g. dead, finished) state. Tournament-creation UIs hide this question
+     * when the property of the game is known. Defaults to false.
+     */
+    leaderboardGameMustBeOver?: boolean;
+}
+/**
+ * Whitelisted games for a chain, sorted by name with disabled entries last.
+ *
+ * Returns a frozen copy — mutations don't bleed back into the module state.
+ */
+declare function getWhitelistedGames(chain: WhitelistChain): WhitelistedGame[];
+/**
+ * Look up a single whitelisted game by contract address. Address is normalized
+ * before comparison so callers can pass any padding.
+ */
+declare function findWhitelistedGame(chain: WhitelistChain, contractAddress: string): WhitelistedGame | undefined;
+/** True if the given game is on the whitelist. */
+declare function isGameWhitelisted(chain: WhitelistChain, contractAddress: string): boolean;
+/**
+ * Defaults block — what UI surfaces should pre-fill when the user picks this
+ * game. Falls back to per-chain sensible defaults (STRK as fee token, 1% fee,
+ * $0.25 minimum) when the game isn't whitelisted, so callers don't have to
+ * special-case missing entries.
+ */
+interface GameDefaults {
+    minEntryFeeUsd: number;
+    defaultEntryFeeToken: string;
+    defaultGameFeePercentage: number;
+    averageGasCostUsd: number | undefined;
+    /** Inherited leaderboard ordering (true = lower wins, false = higher wins). */
+    leaderboardAscending: boolean;
+    /** Inherited "must finish game before submitting" flag. */
+    leaderboardGameMustBeOver: boolean;
+}
+declare function getGameDefaults(chain: WhitelistChain, contractAddress: string): GameDefaults;
+
+/**
+ * Calldata builders for Budokan's on-chain entrypoints.
+ *
+ * Each builder is a pure function that returns a starknet.js `Call` —
+ * `{ contractAddress, entrypoint, calldata }` — without signing or
+ * executing anything. Callers pass the returned Call to
+ * `account.execute([...])` themselves so this module is decoupled from
+ * how an integrator obtains an account (controller, sessions, agent
+ * wallets, signing servers).
+ *
+ * Cairo encoding gotchas this module hides from callers:
+ *   - Option<T> and custom enums must be wrapped in `CairoOption` /
+ *     `CairoCustomEnum`. Plain `{ type, variant }` objects look right but
+ *     CallData.compile treats them as generic structs and serializes the
+ *     type-name string as a ByteArray — i.e. produces garbage calldata.
+ *   - `Metadata.description` is a ByteArray (3+ felts). A plain JS
+ *     string becomes a single felt and the deserializer reverts with
+ *     "Failed to deserialize param".
+ *   - Cairo enum variant tags are 0-indexed in declaration order; the
+ *     manually-built calldata in enter/claim/submit follows this order
+ *     exactly. References:
+ *       contracts/packages/interfaces/src/budokan.cairo (RewardType,
+ *         EntryFeeRewardType, EntryRequirementType, Distribution)
+ *       game-components/.../prize.cairo (PrizeType)
+ *
+ * Used today by the Telegram bot in
+ * `examples/telegram-controller-bot/`. Any other integration that needs
+ * to drive the same contract (a Discord bot, a CLI, agent code) should
+ * import from here so we don't fork the encoding logic again.
+ */
+interface Call {
+    contractAddress: string;
+    entrypoint: string;
+    calldata: string[];
+}
+/**
+ * Shape of the entry-fee distribution. Mirrors the Cairo `Distribution`
+ * enum (Linear / Exponential / Uniform / Custom). The integer `weight`
+ * is in client units — the encoder scales it ×10 to match the on-chain
+ * convention the budokan client uses, so distributions created via this
+ * SDK and via budokan.gg render identically.
+ */
+type DistributionSpec = {
+    kind: "linear";
+    weight: number;
+} | {
+    kind: "exponential";
+    weight: number;
+} | {
+    kind: "uniform";
+};
+interface EntryFeeArgs {
+    tokenAddress: string;
+    /** Raw u128 amount in smallest token units (decimal string). */
+    amount: string;
+    /** All shares are basis points (0–10000). Sum + leaderboard pool = 10000. */
+    tournamentCreatorShare: number;
+    gameCreatorShare: number;
+    refundShare: number;
+    distribution: DistributionSpec;
+    /** Number of top placements that share the leaderboard pool. */
+    distributionCount: number;
+}
+/**
+ * Entry-requirement gating. Two variants on the chain's
+ * EntryRequirementType enum:
+ *   - token: ContractAddress — must own a token from this contract
+ *   - extension: ExtensionConfig — validator contract + config Span
+ *
+ * For "extension" callers build the `config` Span<felt252> in the exact
+ * felt order the target validator's `add_config` expects (see
+ * `src/extensions` for preset builders that produce this for the
+ * shared deployed validators).
+ */
+type EntryRequirementSpec = {
+    kind: "token";
+    tokenAddress: string;
+} | {
+    kind: "extension";
+    address: string;
+    config: string[];
+};
+interface EntryRequirementArgs {
+    /** Max entries per qualifying token / extension match. */
+    entryLimit: number;
+    type: EntryRequirementSpec;
+}
+interface EnterTournamentArgs {
+    tournamentId: string;
+    /**
+     * Mint recipient. Encoded as `Option<ContractAddress>` — omit for
+     * `None` (the contract defaults the mint to the caller).
+     */
+    playerAddress?: string;
+    /** Optional felt252 short string (≤31 ASCII bytes). Omit → Option::None. */
+    playerName?: string;
+    /**
+     * Third-party qualifier to claim, as `Option<ContractAddress>`. Omit for
+     * `None` (caller is the qualifier — the common path). Only needed for
+     * sponsor flows against gated tournaments.
+     */
+    qualifier?: string;
+    /**
+     * `entry_fee_pay_params` (`Option<Span<felt252>>`). Required only for
+     * tournaments with an `EntryFeeKind::Extension` fee — the felts the fee
+     * extension expects. Omit for the built-in fee flow (Option::None).
+     */
+    entryFeePayParams?: string[];
+    salt?: number;
+    metadataValue?: number;
+}
+interface CreateTournamentArgs {
+    creatorRewardsAddress: string;
+    /** ≤31 ASCII bytes (felt252 short string). */
+    name: string;
+    description: string;
+    gameAddress: string;
+    settingsId: number;
+    schedule: {
+        registrationStartDelay: number;
+        registrationEndDelay: number;
+        gameStartDelay: number;
+        gameEndDelay: number;
+        submissionDuration: number;
+    };
+    leaderboard: {
+        ascending: boolean;
+        gameMustBeOver: boolean;
+    };
+    /** Encoded as Option::Some(EntryFeeKind::BuiltIn(EntryFee)) when set. */
+    entryFee?: EntryFeeArgs;
+    /** Encoded as Option::Some(EntryRequirement) on chain when set. */
+    entryRequirement?: EntryRequirementArgs;
+    salt?: number;
+    metadataValue?: number;
+}
+/**
+ * Token prize payload. Mirrors the Cairo `TokenTypeData` enum.
+ *
+ * - `erc20` — fungible. `amount` is required; `distribution` optional
+ *   (undefined → single winner-takes-all payout). When `distribution`
+ *   is set, `distributionCount` is required (number of paid positions).
+ * - `erc721` — single NFT. `tokenId` is the u128 id of the token the
+ *   sponsor is escrowing.
+ */
+type TokenTypeSpec = {
+    kind: "erc20";
+    /** Raw u128 amount (decimal string). */
+    amount: string;
+    distribution?: DistributionSpec;
+    distributionCount?: number;
+} | {
+    kind: "erc721";
+    tokenId: string;
+};
+/**
+ * Tagged union mirroring the on-chain `Prize` enum.
+ *
+ * - `config` — built-in path: sponsor escrows an ERC20/ERC721 prize via
+ *   the budokan PrizeComponent; `position` selects a leaderboard slot
+ *   for non-distributed prizes (ignored for distributed ERC20).
+ * - `extension` — external `IPrizeExtension`: budokan forwards the
+ *   `config` blob to `IPrizeExtension.add_prize`. `position` is ignored
+ *   (the extension owns position semantics).
+ */
+type PrizeSpec = {
+    kind: "token";
+    tokenAddress: string;
+    tokenType: TokenTypeSpec;
+    /** Leaderboard slot for single (non-distributed) prizes. Omit for distributed. */
+    position?: number;
+} | {
+    kind: "extension";
+    /** Address of the contract implementing `IPrizeExtension`. */
+    address: string;
+    /** Opaque payload forwarded to `IPrizeExtension.add_prize`. */
+    config: string[];
+};
+interface AddPrizeArgs {
+    tournamentId: string;
+    prize: PrizeSpec;
+}
+/**
+ * Tagged union mirroring the Cairo `RewardType` enum hierarchy:
+ *
+ *   variant 0: Prize(PrizeClaim)
+ *     PrizeClaim variant 0: Token(PrizeType)
+ *       PrizeType variant 0: Single(u64)
+ *       PrizeType variant 1: Distributed((u64, u8))
+ *     PrizeClaim variant 1: Extension({prize_id, position, payout_params})
+ *   variant 1: EntryFee(EntryFeeClaim)
+ *     EntryFeeClaim variant 0: Token(EntryFeeRewardType)
+ *       EntryFeeRewardType variant 0: Position(u32)
+ *       EntryFeeRewardType variant 1: TournamentCreator
+ *       EntryFeeRewardType variant 2: GameCreator
+ *       EntryFeeRewardType variant 3: Refund(felt252)
+ *     EntryFeeClaim variant 1: Extension(ExtensionEntryFeeClaim)
+ *
+ * Extension claims are pure pass-through on the host: budokan forwards
+ * `(token_id, payout_params)` to the extension and lets it resolve
+ * recipient + eligibility from its own state. Callers don't supply
+ * recipient or position — the extension derives them.
+ *
+ * Conventions:
+ *   - `tokenId` is the game token claiming. Positional extensions
+ *     (NFTPrize, NFTEntryFee) use it to look up the leaderboard
+ *     position; ownership-based extensions use it to derive the
+ *     recipient via `owner_of`.
+ *   - `tokenId: undefined` signals a non-claim flow (sponsor refund,
+ *     dao distribution, raffle draw). The extension extracts whatever
+ *     it needs from `payoutParams` / `claimParams` — e.g. NFTPrize
+ *     reads `payoutParams[0]` as the slot index to refund.
+ */
+type RewardType = {
+    kind: "prize_single";
+    prizeId: string;
+} | {
+    kind: "prize_distributed";
+    prizeId: string;
+    payoutPosition: number;
+} | {
+    kind: "prize_extension";
+    prizeId: string;
+    /**
+     * Game token claiming the prize, or undefined for non-claim flows
+     * (sponsor refunds, raffle draws, etc.).
+     */
+    tokenId?: string;
+    payoutParams: string[];
+} | {
+    kind: "entry_fee_position";
+    position: number;
+} | {
+    kind: "entry_fee_tournament_creator";
+} | {
+    kind: "entry_fee_game_creator";
+} | {
+    kind: "entry_fee_protocol_fee";
+} | {
+    kind: "entry_fee_refund";
+    tokenId: string;
+} | {
+    kind: "entry_fee_extension";
+    /**
+     * Game token claiming the fee-pool share, or undefined for
+     * non-claim flows (sponsor refunds, creator shares, etc.).
+     */
+    tokenId?: string;
+    claimParams: string[];
+};
+/** Standard ERC20 `approve(spender, amount)` call. */
+declare function buildErc20ApproveCall(tokenAddress: string, spender: string, amount: string): Call;
+/**
+ * `enter_tournament(tournament_id: u64, player_name: Option<felt252>,
+ *                   player_address: Option<ContractAddress>,
+ *                   qualifier: Option<ContractAddress>,
+ *                   qualification: Option<QualificationProof>,
+ *                   entry_fee_pay_params: Option<Span<felt252>>,
+ *                   salt: u16, metadata_value: u16)`
+ *
+ * Targets the current budokan contract (#264/#269). `qualification` and
+ * `entry_fee_pay_params` are always `None` here — gated/extension-fee
+ * tournaments need a real proof / pay-params payload, which depend on the
+ * validator and the caller's runtime state.
+ *
+ * Returns `(felt252, u32)` on-chain — game_token_id and entry_number — but
+ * `execute()` surfaces only the tx hash. Callers can fetch the receipt
+ * and parse events if they need the values.
+ *
+ * Tournaments with a non-trivial entry_requirement (NFT-gated or
+ * extension-validator) need a real `QualificationProof` and shouldn't go
+ * through this entrypoint — route those via the budokan client UI or
+ * implement a qualification-proof builder.
+ */
+declare function buildEnterTournamentCall(budokanAddress: string, args: EnterTournamentArgs): Call;
+/** `submit_score(tournament_id: u64, token_id: felt252, position: u32)` */
+declare function buildSubmitScoreCall(budokanAddress: string, args: {
+    tournamentId: string;
+    tokenId: string;
+    position: number;
+}): Call;
+/** `claim_reward(tournament_id: u64, reward_type: RewardType)` */
+declare function buildClaimRewardCall(budokanAddress: string, args: {
+    tournamentId: string;
+    reward: RewardType;
+}): Call;
+/**
+ * `create_tournament(creator_rewards_address, metadata, schedule,
+ *                    game_config, entry_fee, entry_requirement,
+ *                    leaderboard_config, salt, metadata_value)`
+ *
+ * Schedule fields are durations (`registration_end_delay`,
+ * `game_end_delay` measured from their respective starts) — *not*
+ * absolute offsets from creation. Callers are responsible for the
+ * arithmetic; the contract validates min/max bounds itself.
+ *
+ * Pass `entryFee` / `entryRequirement` as `undefined` for free / open
+ * tournaments. Both fields are wrapped in `CairoOption` so
+ * `CallData.compile` emits the correct variant tag.
+ */
+declare function buildCreateTournamentCall(budokanAddress: string, args: CreateTournamentArgs): Call;
+/**
+ * `add_prize(tournament_id: u64, prize: Prize, position: Option<u32>) -> u64`
+ *
+ * The `Prize` sum type discriminates between the built-in
+ * (ERC20/ERC721) flow and an external `IPrizeExtension` integration —
+ * see `PrizeSpec` for the variants.
+ *
+ * The on-chain entrypoint returns the minted `prize_id` (u64); callers
+ * wanting the full payload should subscribe to the `PrizeAdded` event.
+ */
+declare function buildAddPrizeCall(budokanAddress: string, args: AddPrizeArgs): Call;
+/**
+ * Minimal receipt shape — `events: Array<{ from_address, keys, ... }>`
+ * is all `parseTournamentIdFromReceipt` needs and matches what every
+ * Starknet RPC / starknet.js `waitForTransaction` returns.
+ */
+interface ReceiptWithEvents {
+    events?: Array<{
+        from_address?: string;
+        keys?: string[];
+    }>;
+}
+/**
+ * Extract the new tournament's id from a `create_tournament` tx receipt
+ * by scanning for the `TournamentCreated` event emitted by the budokan
+ * contract. The event has the tournament id in its first indexed key
+ * (`keys[1]` — `keys[0]` is the selector).
+ *
+ * Returns the id as a `bigint` (the on-chain type is `u64`, which exceeds
+ * JS `Number.MAX_SAFE_INTEGER`, so a lossless type is required — callers
+ * deep-linking to a tournament page should `.toString()` it). Returns
+ * `undefined` if no matching event is found (e.g. the receipt came from a
+ * different call, or the budokan address didn't match).
+ *
+ * Caller is responsible for fetching the receipt — typically via
+ * `account.waitForTransaction(hash)` or `provider.waitForTransaction(hash)`.
+ */
+declare function parseTournamentIdFromReceipt(receipt: ReceiptWithEvents, budokanAddress: string): bigint | undefined;
+
+/**
+ * Entry-requirement validator extensions.
+ *
+ * Thin wrappers on top of @provable-games/metagame-sdk for the four
+ * validator presets we recommend for chat / bot integrations:
+ *
+ *   - merkle           — Allowlist of addresses via a pre-built merkle tree
+ *   - erc20Balance     — Player must hold ≥ X of some ERC-20
+ *   - opusTroves       — Player must have borrowed ≥ $X CASH on Opus
+ *   - tournament       — Player must have entered / placed in a prior tournament
+ *
+ * Each `buildXxxConfig` function emits the `Span<felt252>` config array
+ * the on-chain validator's `add_config` expects. Pair the array with the
+ * validator address (via `extensionAddressFor`) when building an
+ * `EntryRequirementArgs` of kind `"extension"`.
+ *
+ * Authoritative on-chain layouts:
+ *   metagame-extensions/packages/presets/src/entry_requirement/*.cairo
+ *
+ * u256 values (ERC-20 balance thresholds) are split into low/high felt
+ * pairs to match those layouts. CASH amounts for Opus are passed as
+ * single felts because they're u128-range in practice.
+ */
+
+type ExtensionPresetKind = "merkle" | "erc20Balance" | "opusTroves" | "tournament";
+/**
+ * Lookup the deployed validator address for a given preset on a given
+ * chain. Throws if the metagame-sdk address table doesn't have one — the
+ * preset isn't usable on that chain.
+ */
+declare function extensionAddressFor(chain: WhitelistChain, kind: ExtensionPresetKind): string;
+/** Split a u256 (as bigint) into [low_128, high_128] felt strings. */
+declare function u256ToLowHigh(value: bigint): [string, string];
+interface Erc20BalanceConfig {
+    tokenAddress: string;
+    /** Raw u256, smallest units. */
+    minThreshold: bigint;
+    /** Raw u256, smallest units; 0 = no max. */
+    maxThreshold: bigint;
+    /** Raw u256, smallest units; 0 = single entry, regardless of balance. */
+    valuePerEntry: bigint;
+    /** 0 = unlimited (only meaningful when valuePerEntry > 0). */
+    maxEntries: number;
+    bannable: boolean;
+}
+/**
+ * Build the felt-string config array.
+ *
+ * Layout (from erc20_balance_validator.cairo):
+ *   [token, min_low, min_high, max_low, max_high, vpe_low, vpe_high,
+ *    max_entries, bannable]
+ */
+declare function buildErc20BalanceConfig(cfg: Erc20BalanceConfig): string[];
+interface OpusTrovesConfig {
+    /** Specific collateral filters; empty = wildcard (any trove qualifies). */
+    assetAddresses: string[];
+    /** Min CASH borrowed (raw, 18 decimals). CASH is 1:1 USD. */
+    threshold: bigint;
+    /** CASH per additional entry; 0 = single entry per qualifying trove. */
+    valuePerEntry: bigint;
+    /** 0 = unlimited (only meaningful with proportional valuePerEntry > 0). */
+    maxEntries: number;
+    bannable: boolean;
+}
+/**
+ * Layout (from opus_troves_validator):
+ *   [asset_count, ...asset_addresses, threshold, value_per_entry,
+ *    max_entries, bannable]
+ *
+ * threshold / value_per_entry are CASH amounts (18 decimals, ≤ u128 range
+ * for any reasonable USD value) — passed as single felts, not low/high
+ * pairs. This matches the validator's parse (parseOpusTrovesValidatorConfig
+ * in metagame-sdk reads them as bigints directly).
+ */
+declare function buildOpusTrovesConfig(cfg: OpusTrovesConfig): string[];
+interface MerkleConfig {
+    /** On-chain tree ID from the merkle-validator's create_tree. */
+    treeId: number;
+}
+/** Layout: [tree_id]. */
+declare function buildMerkleConfig(cfg: MerkleConfig): string[];
+/** 0 = participated (any entry counts), 1 = won (placed in top N). */
+type TournamentRequirementType = "participated" | "won";
+/**
+ * How to combine multiple qualifying tournaments. Matches QualifyingMode
+ * in metagame-sdk: 0=AtLeastOne, 1=CumulativePerTournament, 2=All,
+ * 3=CumulativePerEntry, 4=AllParticipateAnyWin, 5=AllWithCumulative.
+ */
+interface TournamentValidatorConfig {
+    requirement: TournamentRequirementType;
+    /** Tournament IDs whose history qualifies. */
+    tournamentIds: string[];
+    /** Top N positions that count (only used when requirement = "won"). */
+    topPositions: number;
+    /** Default 0 (= AtLeastOne). */
+    qualifyingMode?: number;
+}
+/**
+ * Layout (from tournament_validator):
+ *   [qualifier_type, qualifying_mode, top_positions, ...tournament_ids]
+ *   - qualifier_type: 0 = participated, 1 = won
+ *   - qualifying_mode: 0–5 enum
+ *   - top_positions: 0 for "all positions" (used with participated)
+ */
+declare function buildTournamentValidatorConfig(cfg: TournamentValidatorConfig): string[];
 
-export { BudokanApiError, BudokanConnectionError, BudokanError, BudokanTimeoutError, CHAINS, type ChainConfig, DataSourceError, PaginatedResult, PlatformStats, Prize, PrizeAggregation, PrizeStats, QualificationEntry, Registration, RewardClaim, RewardClaimSummary, RpcError, Tournament, TournamentListParams, TournamentNotFoundError, WSEventHandler, WSManager, WSSubscribeOptions, camelToSnake, getActivityStats, getChainConfig, getGameStats, getGameTournaments, getPrizeStats, getTournament, getTournamentPrizeAggregation, getTournamentPrizes, getTournamentQualifications, getTournamentRegistrations, getTournamentRewardClaims, getTournamentRewardClaimsSummary, getTournaments, normalizeAddress, snakeToCamel, withRetry };
+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 };