Core Concepts

Arena

The Arena is HookOS's PvP wagering system. Users create battles between two tokens and wager on which one will outperform over a set duration. All settlement is on-chain — no oracles, no trust assumptions.

How battles work

Phase	Duration	What happens
Create	Instant	Initiator picks two tokens and a duration (1h, 4h, 24h)
Wager	Until start	Users deposit ETH on their chosen side
Live	1–24 hours	Battle runs — price snapshots taken at start and end
Settle	After end	Winner determined by price performance, payouts distributed

Creating a battle

src/create-battle.ts

const battle = await hookos.arena.create({
  tokenA: "0xToken1...",
  tokenB: "0xToken2...",
  duration: 3600, // 1 hour in seconds
  minWager: ethers.parseEther("0.01"),
});

console.log("Battle ID:", battle.id);
console.log("Starts at:", battle.startTime);

Placing wagers

typescript

await hookos.arena.wager({
  battleId: battle.id,
  side: "tokenA", // or "tokenB"
  amount: ethers.parseEther("0.1"),
});

Wagers are locked until the battle settles. You cannot withdraw a wager once placed.

Settlement

When the battle duration ends, anyone can call settle() to finalize the result. The contract compares the price change of each token over the battle period and distributes the prize pool to the winning side.

typescript

// Settle a completed battle
await hookos.arena.settle(battle.id);

// Claim winnings
const payout = await hookos.arena.claim(battle.id);
console.log("Won:", ethers.formatEther(payout), "ETH");

Fee structure

The Arena takes a 2.5% protocol fee from the total prize pool. This fee is routed through the FeeRouter and split according to the configured shares.

Battle states

solidity

enum BattleStatus {
    Created,    // Accepting wagers
    Active,     // Battle in progress
    Settled,    // Winner determined
    Cancelled   // Cancelled by creator (only before Active)
}

Cancellation

The battle creator can cancel a battle before it goes active. All wagers are refunded in full with no fee deduction.

typescript

// Cancel before battle starts
await hookos.arena.cancel(battle.id);

✓

Battles with higher total wager pools attract more participants. Consider setting a low minimum wager to encourage early participation.

Safety features

Reentrancy protection — All wager and claim functions use OpenZeppelin ReentrancyGuard
Pausable — Admin can pause the Arena contract in emergencies, blocking new wagers
Max wager cap — Battles can set a maximum wager amount (0 = unlimited)
One wager per player — Each address can only wager once per battle
Fee cap — Protocol fee cannot exceed 10% (1000 BPS)

Events and tournaments

Battles can be grouped into tournaments through the Events contract. Tournaments have seasons with leaderboards and prize pools. Seasons can be advanced by admin, and events support configurable entry fees, max players, and multi-tier prize distribution. The Events contract takes a 5% protocol fee on prize pools. See the Smart Contracts page for details.

Quests and social engagement

HookOS supports a quest system powered by X OAuth login — users authenticate with their X account (no manual handle entry required) to participate in community quests, earn points, and climb the leaderboard. Quest progress is tracked on-chain and tied to wallet activity.

Tokens

SDK Reference