Skip to main content

Competition Module

Tournament-first competitive engine built for a hybrid stack: off-chain execution, on-chain settlement.

Overview​

The Competition module is the off-chain authority for competitive play in Monsuta Core.

It is responsible for:

  • tournament orchestration (registration, brackets, rounds, finals)
  • match result ingestion and validation
  • rankings, standings, and leaderboard updates
  • season and league progression logic
  • generating final settlement-ready winner outputs

It is not responsible for custodial fund management.

When a tournament is finalized, this module emits a deterministic result payload that is passed to the Economy module’s Prize Pool contracts for trust-minimized on-chain payout settlement.

Hybrid Architecture (Tournament-Focused)​

Monsuta’s competition architecture is intentionally hybrid.

Off-chain domain (Competition module)​

  • Bracket computation (single elimination, double elimination, Swiss-style variants)
  • Match processing and anti-abuse checks
  • Tie-breakers and ranking policies
  • Real-time leaderboard updates
  • Final standings and payout amount calculation
  • Operational workflows (retries, audit trails, dispute windows)

On-chain domain (Economy module)​

  • Prize escrow custody
  • Finalized winner payout execution
  • Claim/refund logic
  • Lifecycle state guarantees
  • Treasury fee accounting

This split keeps tournament logic fast and flexible while preserving trust where funds move.

Core Tournament Model​

The module is organized around tournament entities:

  • Tournament — high-level lifecycle and configuration
  • Stage — groups, rounds, knockout phases
  • Match — result-bearing atomic competition unit
  • Participant — player/team competitive identity
  • Standing — ranking state at any point in time
  • SettlementBundle — winner addresses + exact payout amounts for settlement

Tournament Lifecycle​

Draft
  -> Registration Open
  -> Registration Closed
  -> Active
  -> Finalizing
  -> Finalized

Typical transitions:

  1. Tournament configured and published
  2. Participants register
  3. Bracket/stage progression runs off-chain
  4. Final standings computed deterministically
  5. Settlement bundle generated for prize pool submission

Settlement Pipeline​

Match servers
  -> Competition engine
  -> Final standings
  -> Payout calculator
  -> Settlement bundle (winners + amounts)
  -> Distributor / backend signer
  -> PrizePool.submitResults(...)
  -> Winners claim on-chain

Contract alignment requirements before submission​

The competition output should satisfy settlement constraints:

  • pool expected in Active state
  • winner list has no duplicates
  • payout amounts are non-zero and aligned with winners
  • total payout does not exceed distributable pool budget
  • payload is auditable (result hash / metadata tracked off-chain)

Why This Module Exists​

Games need competitive logic that is:

  • high-throughput
  • easy to iterate
  • cheap to run
  • deterministic at finalization

Putting full tournament computation on-chain is expensive and operationally rigid.
Keeping it off-chain enables scale and rapid iteration, while the Economy module ensures outcome settlement remains verifiable and non-custodial.

Integration Pattern​

At integration time, your game backend typically:

  1. Uses Competition APIs to run the tournament
  2. Calls tournament finalization to obtain ordered standings
  3. Builds payout amounts from standings
  4. Submits results to the associated prize pool via the authorized server path
  5. Notifies winners to claim directly from contract

Security Boundaries​

Competition module guarantees​

  • deterministic tournament finalization logic
  • replay-safe match/result processing
  • auditable progression and output artifacts

Economy module guarantees​

  • no arbitrary prize withdrawal path
  • winner-only claims (post-finalization)
  • cancellation/refund behavior enforced by contract state

Current Direction​

The module is evolving with a tournament-first focus, then generalized season/league overlays.

Planned emphasis:

  • robust bracket/state machine primitives
  • deterministic tie-break and ranking policies
  • settlement bundle standardization
  • stronger result attestation interoperability with payout workers

Summary​

The Competition module is the execution brain for competitive gameplay.
The Economy module is the settlement trust anchor.

Together they implement Monsuta’s target model:

off-chain heavy competition + on-chain payout finality.