Leaderboards
Off-chain ranking authority for competitive play, with on-chain settlement handoff at finalization.
Overview
Leaderboards in Monsuta Core are intentionally off-chain.
They are designed to support:
- high-frequency match updates
- real-time standings and rank movement
- configurable scoring logic per game mode
- season/event-specific ranking contexts
The blockchain is not used for live leaderboard updates.
Instead, chain interaction happens only when finalized standings must drive prize settlement.
Why Leaderboards Are Off-Chain
Updating leaderboard state on every match on-chain would be expensive, slow, and operationally rigid.
By keeping rankings off-chain, games can:
- process thousands of updates efficiently
- tune scoring formulas without contract redeploys
- support richer anti-abuse and dispute logic
- maintain better UX with real-time ranking refreshes
On-chain contracts are reserved for what they do best: escrow, immutable settlement, claims, and refunds.
Boundary: Off-Chain Ranking vs On-Chain Settlement
Off-chain responsibilities (Competition module)
- ingest and validate match results
- update ratings/points/win-loss stats
- apply tie-break rules
- generate standings snapshots
- finalize leaderboard ordering at event/season close
On-chain responsibilities (Economy / Prize Pools)
- hold prize funds in escrow
- accept finalized winners + payout amounts (
submitResults) - enforce claim/refund rules
- enforce lifecycle constraints
Leaderboard Types
| Type | Scope | Typical Use |
|---|---|---|
| Event Leaderboard | Single tournament/event | Cup and bracket outcomes |
| Season Leaderboard | Full season window | Promotion/relegation and seasonal rewards |
| League Leaderboard | Tier-specific slice | Skill bucket competition |
| Global Leaderboard | Cross-league summary | Broad engagement and visibility |
Scoring Models (Off-Chain)
| Model | Description | Best For |
|---|---|---|
| ELO | Rating shift based on opponent strength | Skill-based 1v1 |
| Points | Rule-driven points per result | Team or objective modes |
| Win Count | Total wins over period | Sprint events |
| Composite | Weighted blend of metrics | Custom competitive ecosystems |
Example model config (off-chain):
{
"scoringModel": "elo",
"initialRating": 1200,
"kFactor": 32,
"newPlayerKFactor": 64,
"newPlayerGames": 20,
"ratingFloor": 100
}
Finalization and Settlement Handoff
At event or season end:
- Leaderboard is frozen off-chain.
- Final ranks are computed deterministically.
- Payout calculator derives exact winner amounts.
- Settlement payload is prepared (and ideally attested/signed).
- Authorized server/worker submits to Prize Pool contract.
- Winners claim on-chain.
Settlement Payload Shape (Recommended)
{
"eventId": "weekly-cup-042",
"poolAddress": "0xPoolAddress...",
"winners": [
"0xWinner1...",
"0xWinner2...",
"0xWinner3..."
],
"amounts": [
"3040000000000000000",
"1824000000000000000",
"1216000000000000000"
],
"resultHash": "0xResultHash...",
"signedAt": "2026-03-02T12:00:00Z"
}
Required Validation Before On-Chain Submit
Before settlement submission, leaderboard output should satisfy:
- winner list and payout list are same length and non-empty
- winner addresses are unique
- payout amounts are non-zero
- sum of payouts is within distributable pool bounds
- payload references the expected pool/event context
- payload integrity hash/signature checks pass (if attested flow enabled)
If any validation fails, no on-chain settlement should be attempted.
Trust Model
What players trust off-chain for
- fair match processing and scoring policy
- anti-cheat and dispute handling
- correctness of finalized ranking output
What players do not have to trust operators for
- manual custody and manual payout distribution of prize funds
(escrow + claims are contract-enforced on-chain)
Operational Guidance
- Keep leaderboard updates idempotent and replay-safe.
- Persist immutable finalization snapshots.
- Use deterministic tie-break policy and document it publicly.
- Keep an audit trail from match results -> final standings -> settlement bundle.
- Alert on settlement delays after leaderboard finalization.
Summary
Leaderboards are an off-chain performance layer.
Prize Pools are an on-chain settlement layer.
That separation is deliberate and central to Monsuta Core’s architecture:
off-chain ranking velocity + on-chain payout finality.