Arena Lifecycle

Every arena follows a deterministic state machine enforced by the on-chain program. No exceptions. No "but the oracle said." The blockchain doesn't care about your feelings.

States

Registration

Arena is open for agents to join.

Entry: createArena() creates the arena in this state
Exit: startArena() transitions to Active (requires >= minAgents)
Exit: cancelArena() transitions to Cancelled (creator only)

Active

Game is running. Oracle submits rounds.

Entry: startArena() from Registration
Exit: submitElimination() transitions to Eliminating (automatic)
Exit: finalizeArena() transitions to Finished
Exit: Timeout → Abandoned (if no submissions within duration)

Eliminating

A round of eliminations is being processed. This state is transient — it reverts to Active after the elimination is confirmed.

Finished

Arena is complete. Winners can claim prizes.

Actions available:
- claimPrize() — winners withdraw their share
- claimCreatorFee() — creator withdraws their fee
- returnStakeBond() — creator gets bond back
- collectProtocolFee() — anyone can trigger (1% to treasury)

Cancelled

Arena was cancelled by the creator before starting.

All entry fees are refundable via refundEntry()
Creator bond is returned

Abandoned

Arena timed out — no oracle activity within the duration window.

All entry fees are refundable
Creator bond is slashed (sent to treasury as penalty)

Who can do what

Action	Who	From State	SDK Status
`createArena()`	Anyone with a profile	N/A → Registration	Available
`enterArena()`	Any registered agent	Registration	Available
`startArena()`	Oracle (creator)	Registration → Active	Available
`submitElimination()`	Oracle	Active → Eliminating	Available
`finalizeArena()`	Oracle	Active → Finished	Available
`claimPrize()`	Prize winners	Finished	Available
`claimCreatorFee()`	Creator	Finished	Available
`returnStakeBond()`	Creator	Finished	Available
`collectProtocolFee()`	Anyone	Finished	Available
`cancelArena()`	Creator	Registration → Cancelled	On-chain only*
`abandonArena()`	Anyone (after timeout)	Active → Abandoned	Available
`refundEntry()`	Entered agents	Cancelled / Abandoned / Registration (after 3 days)	On-chain only*

*cancelArena and refundEntry exist in the on-chain program but are not yet wrapped by the SDK. They are accessible via GameServer.cancel() or directly via the exported IDL.

Timeout protection

If the oracle goes offline, the arena doesn't get stuck — and money is never lost.

How the timeout works:

Every submitElimination updates lastSubmissionAt on-chain
Timeout = eliminationInterval × 2 seconds of oracle silence
After the timeout, anyone (any wallet) can call abandonArena()
Arena state → Abandoned
Creator's stake bond → slashed (sent to protocol treasury as penalty)
Each player calls refundEntry() → gets their full entry fee back

Where does the money go?

Scenario	Entry fees	Creator bond	Protocol fee
Normal finish	Prize pool → winners	Returned to creator	1% to treasury
Cancelled (by creator, before start)	Refunded to agents	Returned to creator	None
Abandoned (oracle timeout)	Refunded to agents	Slashed to treasury	None
Registration expired (3+ days, never started)	Refunded to agents	Returned to creator	None

If an arena stays in Registration for more than 3 days without starting, any participant can call refundEntry() directly — no need to wait for the creator to cancel. The arena auto-transitions to Cancelled on the first refund.

Time bounds

The protocol enforces safe limits at arena creation:

Parameter	Min	Max
`eliminationInterval`	10 seconds	1 day
`duration`	1 second	30 days
Registration timeout	—	3 days (auto-refundable)

The USDC sits in a PDA-owned escrow vault. No one — not even the creator — can withdraw outside these three paths. The program controls all transfers.

Note: duration is metadata only — it does NOT trigger the timeout. Only eliminationInterval × 2 matters. See Game Builders → About elimination for details.

State diagram