Budokan: Key Functions

This section details the primary functions exposed by the Budokan tournament system and its core data structures.

Component Architecture

Budokan is built by composing reusable Cairo components from the open-source game-components library:

These components are not Budokan-specific — they are general-purpose building blocks from the Metagame Extensions package. Anyone can compose them to build their own tournament or competition system with custom prize logic, entry fee handling, or scoring rules.

For example, you could build a platform that uses the same PrizeComponent and LeaderboardComponent but with entirely different entry mechanics, or extend the EntryFeeComponent with a custom distribution strategy.

IBudokan Interface

create_tournament

fn create_tournament(
    ref self: TState,
    creator_rewards_address: ContractAddress,
    metadata: Metadata,
    schedule: Schedule,
    game_config: GameConfig,
    entry_fee: Option<EntryFee>,
    entry_requirement: Option<EntryRequirement>,
    leaderboard_config: LeaderboardConfig,
    salt: u16,
    metadata_value: u16,
) -> Tournament;

Purpose: Create a new tournament with specified metadata, schedule, game configuration, entry fee, and requirements. Mints a game token to the creator for reward distribution.

• creator_rewards_address: Address to receive the creator's game token.
• metadata: Tournament metadata (name, description).
• schedule: Delay-based schedule (registration, game, and submission durations).
• game_config: Game configuration (game address, settings, soulbound, paymaster, etc.).
• entry_fee: Optional entry fee with distribution rules.
• entry_requirement: Optional qualification requirement (token gating, tournament qualification, or extension).
• leaderboard_config: Leaderboard scoring rules (ascending/descending, game_must_be_over).
• salt: Salt for token ID packing.
• metadata_value: Additional metadata value for token ID packing.

Returns: Tournament struct.

enter_tournament

fn enter_tournament(
    ref self: TState,
    tournament_id: u64,
    player_name: felt252,
    player_address: ContractAddress,
    qualification: Option<QualificationProof>,
    salt: u16,
    metadata_value: u16,
) -> (felt252, u32);

Purpose: Register a player for a tournament, minting a game token and assigning an entry number.

• tournament_id: ID of the tournament to enter.
• player_name: Name of the player (felt252).
• player_address: Address to mint the game token to.
• qualification: Optional qualification proof (NFT ownership or extension data).
• salt: Salt for token ID packing.
• metadata_value: Additional metadata value for token ID packing.

Returns: Tuple of (game token ID as felt252, entry number as u32).

submit_score

fn submit_score(
    ref self: TState,
    tournament_id: u64,
    token_id: felt252,
    position: u32,
);

Purpose: Submit a score/position for a tournament entry. Updates the leaderboard and marks the score as submitted.

• tournament_id: ID of the tournament.
• token_id: Game token ID for the entry (felt252).
• position: Leaderboard position (1-based index).

claim_reward

fn claim_reward(
    ref self: TState,
    tournament_id: u64,
    reward_type: RewardType,
);

Purpose: Claim a reward for a tournament after it is finalized. Handles both entry fee distributions and custom prizes.

• tournament_id: ID of the tournament.
• reward_type: Type of reward to claim — either a Prize(PrizeType) or EntryFee(EntryFeeRewardType).

add_prize

fn add_prize(
    ref self: TState,
    tournament_id: u64,
    token_address: ContractAddress,
    token_type: TokenTypeData,
    position: Option<u32>,
) -> PrizeData;

Purpose: Add a new prize to a tournament. Specify a leaderboard position or None for an unpositioned prize.

• tournament_id: ID of the tournament.
• token_address: Address of the prize token contract.
• token_type: Token type data (ERC20Data or ERC721Data).
• position: Optional leaderboard position for the prize.

Returns: PrizeData struct.

ban_entry

fn ban_entry(
    ref self: TState,
    tournament_id: u64,
    game_token_id: felt252,
    proof: Span<felt252>,
);

Purpose: Permissionlessly ban a tournament entry that no longer meets the extension validator's requirements. Anyone can call this — it delegates to the tournament's extension validator to confirm the ban via should_ban.

• tournament_id: ID of the tournament.
• game_token_id: Token ID of the entry to ban.
• proof: Proof data passed to the validator (validator-specific).

See Entry Requirements: Banning Mechanism for details on how this works with extension validators.

View Functions

fn total_tournaments(self: @TState) -> u64;
fn tournament(self: @TState, tournament_id: u64) -> Tournament;
fn tournament_entries(self: @TState, tournament_id: u64) -> u32;
fn get_leaderboard(self: @TState, tournament_id: u64) -> Array<felt252>;
fn current_phase(self: @TState, tournament_id: u64) -> Phase;

• total_tournaments: Returns the total number of tournaments created.
• tournament: Returns the Tournament struct for a given ID.
• tournament_entries: Returns the number of entries for a tournament.
• get_leaderboard: Returns an array of game token IDs ordered by position.
• current_phase: Returns the current phase of a tournament.

Data Structures

Schedule

Tournament phases are calculated from cumulative delays relative to the creation timestamp:

pub struct Schedule {
    pub registration_start_delay: u32,
    pub registration_end_delay: u32,
    pub game_start_delay: u32,
    pub game_end_delay: u32,
    pub submission_duration: u32,
}

For example, if a tournament is created at time T:

• Registration opens at T + registration_start_delay
• Registration closes at T + registration_end_delay
• Game starts at T + game_start_delay
• Game ends at T + game_start_delay + game_end_delay
• Submission ends at T + game_start_delay + game_end_delay + submission_duration

A delay of 0 for registration means no registration period.

Phase

pub enum Phase {
    Scheduled,
    Registration,
    Staging,
    Live,
    Submission,
    Finalized,
}

LeaderboardConfig

pub struct LeaderboardConfig {
    pub ascending: bool,          // true = lower scores better, false = higher scores better
    pub game_must_be_over: bool,  // true = game_over() must return true before submission
}

GameConfig

pub struct GameConfig {
    pub game_address: ContractAddress,
    pub settings_id: u32,
    pub soulbound: bool,
    pub paymaster: bool,
    pub client_url: Option<ByteArray>,
    pub renderer: Option<ContractAddress>,
}

EntryFee

Budokan enforces that game_creator_share is >= the fee declared by the game via game_fee_info in the game registry (default 5% / 500 bps). Tournament creation will revert if the share is too low.

pub struct EntryFee {
    pub token_address: ContractAddress,
    pub amount: u128,
    pub tournament_creator_share: u16,  // basis points
    pub game_creator_share: u16,        // basis points (must be >= game's declared fee)
    pub refund_share: u16,              // basis points returned to each depositor
    pub distribution: Distribution,
    pub distribution_count: u32,
}

RewardType

pub enum RewardType {
    Prize: PrizeType,
    EntryFee: EntryFeeRewardType,
}
 
pub enum EntryFeeRewardType {
    Position: u32,
    TournamentCreator,
    GameCreator,
    Refund: felt252,
}

Tournament

pub struct Tournament {
    pub id: u64,
    pub created_at: u64,
    pub created_by: ContractAddress,
    pub creator_token_id: felt252,
    pub metadata: Metadata,
    pub schedule: Schedule,
    pub game_config: GameConfig,
    pub entry_fee: Option<EntryFee>,
    pub entry_requirement: Option<EntryRequirement>,
    pub leaderboard_config: LeaderboardConfig,
}

Metadata

pub struct Metadata {
    pub name: felt252,
    pub description: ByteArray,
}