Feat: Round Configuration & Utilities Implementation

[manlikeHB]

Overview

Implement configuration and utility methods for Round instances. This issue covers card management, duration calculation, and summary generation.

Requirements

Functions to Implement

set_cards() - Assign Cards to Round

fn set_cards(
    self: @Round, 
    cards: Span<u64>, 
    question_cards: Span<QuestionCard>
) -> Result<Round, RoundValidation>

• Assign card IDs and question cards to round
• Validate card count matches cards_per_round configuration
• Validate both arrays have matching lengths
• Return updated round instance
• Used during round setup phase

get_duration() - Calculate Round Duration

fn get_duration(self: @Round) -> Option<u64>

• Calculate round duration in seconds
• Only available for completed rounds
• Return Some(duration) if valid, None otherwise
• Duration = end_time - start_time
• Validate end_time > start_time

get_summary() - Generate Round Summary

fn get_summary(self: @Round) -> RoundSummary

• Create lightweight summary for display/listing
• Include essential round information
• Convert enums to proper types

Business Logic

Card Assignment Rules

• Cards can only be set for valid rounds
• Card count must exactly match cards_per_round
• Question cards array must match cards array length
• Both arrays must be non-empty if cards_per_round > 0

Duration Calculation Rules

• Only completed rounds have duration
• Both start_time and end_time must be > 0
• end_time must be > start_time for valid duration
• Return None for invalid or incomplete rounds

Summary Generation Rules

• Always succeeds (no validation failures)
• Convert felt252 enums to proper enum types
• Include current joinability status

Acceptance Criteria

• All 3 configuration/utility methods implemented correctly
• Card assignment validation works properly
• Duration calculation handles all edge cases
• Summary generation is accurate and complete
• Comprehensive error handling with descriptive messages
• Complete test coverage
• All edge cases tested and handled

Dependencies

• Uses existing Round struct and helper methods(get_mode(), get_state(), is_joinable())
• Feat: Round State Queries Implementation #127

---

Note

Target Branch

• refac/modular-architecture

File Location

• src/models/round.cairo

Target Trait

• RoundTrait

[emarc99]

Would love to do this!

[Henrichy]

Implementation Plan

1. set_cards()

Purpose: Assign card IDs and question cards to a round.

Validation:

Ensure round is in a valid setup state (depends on your RoundState).

Check that:

cards.len() == self.cards_per_round

question_cards.len() == self.cards_per_round

cards.len() == question_cards.len()

Non-empty if cards_per_round > 0.

On success → return updated Round.

On failure → return RoundValidation error (descriptive).

2. get_duration()

Purpose: Calculate duration of completed round.

Logic:

Only valid if round is in Completed state (or similar).

Ensure:

start_time > 0

end_time > start_time

Duration = end_time - start_time.

Return:

Some(duration) if valid.

None otherwise.

3. get_summary()

Purpose: Return lightweight RoundSummary for UI/listing.

Content:

Round ID

Mode (converted from felt252 → enum type)

State (converted properly)

Cards_per_round

Current joinability (self.is_joinable())

Optional metadata (start/end times, players count, etc.)

Always succeeds (no validation).

📝 Example Cairo Implementation
#[derive(Drop, Serde)]
struct RoundSummary {
id: u64,
mode: RoundMode,
state: RoundState,
cards_per_round: u64,
joinable: bool,
start_time: u64,
end_time: u64,
}

trait RoundTrait {
fn set_cards(
self: @round,
cards: Span,
question_cards: Span
) -> Result<Round, RoundValidation>;

fn get_duration(self: @Round) -> Option<u64>;

fn get_summary(self: @Round) -> RoundSummary;

}

impl RoundImpl of RoundTrait {
fn set_cards(
self: @round,
cards: Span,
question_cards: Span
) -> Result<Round, RoundValidation> {
// Validation
if cards.len() != self.cards_per_round {
return Err(RoundValidation::InvalidCardCount);
}
if question_cards.len() != self.cards_per_round {
return Err(RoundValidation::InvalidQuestionCardCount);
}
if cards.len() != question_cards.len() {
return Err(RoundValidation::MismatchedCardLengths);
}
if self.cards_per_round > 0 && cards.len() == 0 {
return Err(RoundValidation::EmptyCardsNotAllowed);
}

    // Update round
    let mut updated = self;
    updated.cards = cards.into();
    updated.question_cards = question_cards.into();

    Ok(updated)
}

fn get_duration(self: @Round) -> Option<u64> {
    if self.state != RoundState::Completed {
        return None;
    }
    if self.start_time == 0 || self.end_time == 0 {
        return None;
    }
    if self.end_time <= self.start_time {
        return None;
    }
    Some(self.end_time - self.start_time)
}

fn get_summary(self: @Round) -> RoundSummary {
    RoundSummary {
        id: self.id,
        mode: self.get_mode(),
        state: self.get_state(),
        cards_per_round: self.cards_per_round,
        joinable: self.is_joinable(),
        start_time: self.start_time,
        end_time: self.end_time,
    }
}

}

✅ Acceptance Criteria Coverage

set_cards() ensures validation with descriptive errors.

get_duration() covers edge cases.

get_summary() generates consistent display-friendly summary.

Trait-based → clean modular structure.

Can extend with more fields without breaking API.

[wheval]

Hello @manlikeHB , I would love to work on this. I worked on the State queries!