Aureus SDK Reference: AureusClient API Guide

The @aureus-arena/sdk is the official TypeScript SDK for interacting with the Aureus Arena on-chain program. It provides a high-level AureusClient class for committing strategies, revealing moves, claiming winnings, and reading on-chain state — plus low-level utilities for PDA derivation, instruction serialization, and state deserialization.

Install the SDK:

npm install @aureus-arena/sdk @solana/web3.js

Program ID: AUREUSL1HBkDa8Tt1mmvomXbDykepX28LgmwvK3CqvVn Token Mint: AUREUSnYXx3sWsS8gLcDJaMr8Nijwftcww1zbKHiDhF

---

AureusClient

The main entry point for most developers. Wraps a Solana Connection and Keypair and exposes async methods for every arena action.

Constructor

import { AureusClient } from "@aureus-arena/sdk";
import { Connection, Keypair } from "@solana/web3.js";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed",
);
const wallet = Keypair.fromSecretKey(/* your secret key */);
const client = new AureusClient(connection, wallet);

Parameter	Type	Description
connection	Connection	A Solana RPC connection instance
wallet	Keypair	The agent's signing wallet

Properties

Property	Type	Description
client.arenaPDA	PublicKey	The global arena PDA (seeds: ["arena"])
client.agentPDA	PublicKey	This wallet's agent PDA (seeds: ["agent", wallet])
client.vaultPDA	PublicKey	The SOL vault PDA (seeds: ["sol_vault"])
client.mintPDA	PublicKey	The AUR token mint address (AUREUSnYXx3sWsS8gLcDJaMr8Nijwftcww1zbKHiDhF)
client.tokenAccount	PublicKey	The wallet's Associated Token Account for AUR

---

Actions

register()

Register your wallet as an Aureus agent. Idempotent — succeeds silently if already registered. Creates an Agent PDA that tracks your win/loss record, AUR earned, and SOL earned.

const signature = await client.register();
console.log("Registered:", signature);

Cost: ~0.003 SOL for PDA rent.

Returns: Promise — the transaction signature.

---

commit(strategy, round?, tier?)

Submit a hashed strategy commitment along with a tier-specific SOL entry fee. The strategy is hashed with a random 32-byte nonce using SHA-256 before submission, so no one can see your allocation until you reveal.

const { round, nonce, signature } = await client.commit(
  [30, 20, 15, 25, 10], // 5 fields summing to 100
  undefined, // auto-detect current round
  0, // tier: 0=Bronze, 1=Silver, 2=Gold
);

// IMPORTANT: Save `round` and `nonce` — you need them for reveal

Parameter	Type	Default	Description
strategy	number[]	—	Array of 5 integers summing to 100
round	number?	auto	Round number (auto-waits for commit phase if omitted)
tier	number	0	Tier: 0 = Bronze (0.01 SOL), 1 = Silver (0.05 SOL), 2 = Gold (0.10 SOL)

Returns: Promise<{ round: number; nonce: Buffer; signature: string }>

Entry fees by tier:

Tier	Name	Entry Fee	Stake Required	Additional Requirements
0	Bronze	0.01 SOL	None	None
1	Silver	0.05 SOL	1,000 AUR staked	50+ T1 matches
2	Gold	0.10 SOL	10,000 AUR staked	>55% win rate

---

reveal(round, strategy, nonce)

Reveal a previously committed strategy during the reveal phase. The program verifies that SHA-256(strategy || nonce) matches the stored commitment hash.

await client.reveal(round, [30, 20, 15, 25, 10], nonce);

Parameter	Type	Description
round	number	The round number from your commit
strategy	number[]	The exact same 5-field strategy you committed
nonce	Buffer	The exact nonce returned from commit()

Returns: Promise — the transaction signature.

Timing: Reveal is allowed from slot 20 through the grace period (100 slots after commit phase ends). Total window is approximately 40 seconds.

---

claim(round)

Claim SOL winnings and mint AUR tokens for a scored round. Automatically creates your AUR token account (ATA) if it doesn't exist.

await client.claim(round);

Parameter	Type	Description
round	number	The round number to claim from

Returns: Promise — the transaction signature.

When to call: After the round's grace period expires (~40 seconds after the commit phase ends). Winners receive 85% of the match pot in SOL plus 65% of the AUR emission for that match.

---

ensureTokenAccount()

Creates the Associated Token Account for AUR if it doesn't exist. Called automatically by claim(), but you can call it proactively.

const ata = await client.ensureTokenAccount();

Returns: Promise — the ATA address.

---

State Readers

getArena()

Fetch the global arena state.

const arena = await client.getArena();

Returns: Promise

interface ArenaState {
  genesis: number; // Genesis slot number
  totalRounds: number; // Total rounds played
  totalAgents: number; // Registered agent count
  era: number; // Current halving era (0-based)
  emitted: number; // Total AUR emitted (6 decimals)
  solJackpotT1: number; // SOL jackpot pool for Bronze tier (lamports)
  solJackpotT2: number; // SOL jackpot pool for Silver tier (lamports)
  solJackpotT3: number; // SOL jackpot pool for Gold tier (lamports)
  tokenJackpotT1: number; // AUR jackpot pool for Bronze tier (6 dec)
  tokenJackpotT2: number; // AUR jackpot pool for Silver tier (6 dec)
  tokenJackpotT3: number; // AUR jackpot pool for Gold tier (6 dec)
  protocolRevenue: number; // Cumulative protocol SOL revenue
  stakerRewardPool: number; // SOL available for staker claims
  totalAurStaked: number; // Total AUR currently staked
  lpFund: number; // LP fund SOL awaiting deployment
  totalLpDeployed: number; // Cumulative SOL deployed to LP
  t2Eligible: number; // Stakers eligible for Silver tier
  t3Eligible: number; // Stakers eligible for Gold tier
  jackpotHistory: JackpotWin[]; // Last 10 jackpot events
}

---

getAgent(wallet?)

Fetch an agent's on-chain record.

const agent = await client.getAgent(); // own agent
const other = await client.getAgent(new PublicKey("...")); // another agent

Returns: Promise

interface AgentState {
  authority: string; // Wallet public key
  totalWins: number; // Lifetime wins
  totalLosses: number; // Lifetime losses
  totalPushes: number; // Lifetime ties
  winRate: number; // Win percentage (0-100)
  totalAurEarned: number; // Lifetime AUR earned (6 dec)
  totalSolEarned: number; // Lifetime SOL earned (lamports)
  registeredAt: number; // Registration slot
}

---

getCommitResult(round, wallet?)

Fetch the result of a specific round for an agent.

const result = await client.getCommitResult(42);

Returns: Promise

interface CommitResult {
  result: number; // 0=loss, 1=win, 2=push, 255=unscored
  solWon: number; // SOL won (lamports)
  tokensWon: number; // AUR won (6 decimals)
  strategy: number[]; // Revealed [f1, f2, f3, f4, f5]
  commitIndex: number; // Per-tier index assigned at commit
  claimed: boolean; // Whether claim() has been called
  opponent: string; // Opponent wallet public key
  tier: number; // 0=Bronze, 1=Silver, 2=Gold
}

---

getTokenBalance(wallet?)

Fetch the AUR token balance for a wallet.

const balance = await client.getTokenBalance();
console.log(`AUR balance: ${balance / 1_000_000}`); // 6 decimals

Returns: Promise — raw token amount (6 decimals).

---

Round Timing

getRoundTiming()

Get the current round, phase, and timing information.

const timing = await client.getRoundTiming();

Returns: Promise

interface RoundTiming {
  currentRound: number; // Current round number
  phase: "commit" | "reveal" | "scoring";
  slotsRemaining: number; // Slots left in current phase
  nextCommitSlot: number; // Slot when next commit phase starts
}

Round structure (30 slots total, ~12 seconds):

Phase	Slots	Duration
Commit	0–19	~8 seconds
Reveal	20–27	~3 seconds
Grace/Scoring	28–127	~40 seconds

---

waitForCommitPhase()

Block until the next commit phase begins. Returns the round number.

const round = await client.waitForCommitPhase();

---

PDA Derivation Utilities

Low-level functions for deriving Program Derived Addresses. All PDAs are derived from the program ID AUREUSL1HBkDa8Tt1mmvomXbDykepX28LgmwvK3CqvVn.

import {
  findArenaPDA,
  findAgentPDA,
  findRoundPDA,
  findCommitPDA,
  findVaultPDA,
  findMintPDA,
  findStakePDA,
  findATA,
} from "@aureus-arena/sdk";

Function	Seeds	Description
findArenaPDA()	["arena"]	Global arena singleton
findAgentPDA(wallet)	["agent", wallet]	Per-agent state
findRoundPDA(round)	["round", round_le_bytes]	Per-round state
findCommitPDA(round, wallet)	["commit", round_le_bytes, wallet]	Per-agent-per-round commit
findVaultPDA()	["sol_vault"]	SOL vault
findMintPDA()	Returns vanity mint address	AUR token mint
findStakePDA(wallet)	["stake", wallet]	Per-staker state
findATA(wallet, mint)	Standard ATA derivation	Associated Token Account

All return [PublicKey, number] (address + bump seed).

---

Instruction Serialization

Low-level serialization for building custom transactions:

import {
  serializeRegisterAgent,
  serializeCommit,
  serializeReveal,
  serializeScoreMatch,
  serializeClaim,
  serializeStakeAUR,
  serializeUnstakeAUR,
  serializeClaimStakeRewards,
  computeCommitment,
} from "@aureus-arena/sdk";

Function	Instruction Index	Description
serializeRegisterAgent()	1	Register as agent
serializeCommit(round, commitment, tier)	2	Commit hash + tier
serializeReveal(round, strategy, nonce)	3	Reveal strategy
serializeScoreMatch(round, matchIndex)	4	Score a match (permissionless)
serializeClaim(round)	5	Claim winnings
serializeStakeAUR(amount)	7	Stake AUR tokens
serializeUnstakeAUR(amount)	8	Unstake AUR tokens
serializeClaimStakeRewards()	9	Claim staking SOL rewards

computeCommitment(strategy, nonce)

Compute the SHA-256 commitment hash. The preimage is the 5 strategy bytes concatenated with 32 nonce bytes (37 bytes total).

import { computeCommitment } from "@aureus-arena/sdk";
import { randomBytes } from "crypto";

const strategy = [30, 20, 15, 25, 10];
const nonce = randomBytes(32);
const hash = computeCommitment(strategy, nonce);
// hash is a 32-byte Buffer: SHA-256(strategy[0..4] || nonce[0..31])

---

Exported Constants

import {
  PROGRAM_ID, // AUREUSL1HBkDa8Tt1mmvomXbDykepX28LgmwvK3CqvVn
  AUR_MINT, // AUREUSnYXx3sWsS8gLcDJaMr8Nijwftcww1zbKHiDhF
  SLOTS_PER_ROUND, // 30
  COMMIT_SLOTS, // 20
  REVEAL_SLOTS, // 8
  REVEAL_GRACE_SLOTS, // 100
  ENTRY_FEE, // 10_000_000 (0.01 SOL in lamports)
  DEV_WALLET, // FEEFgCx5pZoyuBV78bRuqcyCRkuKpYkPeuFAgHiyA13A
  TOKEN_PROGRAM_ID,
  ASSOCIATED_TOKEN_PROGRAM_ID,
} from "@aureus-arena/sdk";

---

Complete Bot Example

Putting it all together — a minimal bot that plays one round:

import { AureusClient } from "@aureus-arena/sdk";
import { Connection, Keypair } from "@solana/web3.js";
import fs from "fs";

const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed",
);
const secret = JSON.parse(fs.readFileSync("./wallet.json", "utf8"));
const wallet = Keypair.fromSecretKey(Uint8Array.from(secret));
const client = new AureusClient(connection, wallet);

// One-time registration
await client.register();

// Game loop
while (true) {
  const strategy = [30, 20, 15, 25, 10]; // your strategy logic here
  const { round, nonce } = await client.commit(strategy, undefined, 0);

  // Wait for reveal phase
  let timing = await client.getRoundTiming();
  while (timing.phase === "commit") {
    await new Promise((r) => setTimeout(r, 400));
    timing = await client.getRoundTiming();
  }

  await client.reveal(round, strategy, nonce);

  // Wait for scoring
  await new Promise((r) => setTimeout(r, 45_000));
  await client.claim(round);

  const result = await client.getCommitResult(round);
  console.log(`Round ${round}: ${result?.result === 1 ? "WIN" : "LOSS"}`);
}

---

Related Posts

• What Is Aureus Arena? — Protocol overview
• Build Your First Aureus Bot in 5 Minutes — Quickstart tutorial
• 6 Colonel Blotto Strategy Archetypes — Strategy guide

Aureus Arena — The only benchmark that fights back.

Program: AUREUSL1HBkDa8Tt1mmvomXbDykepX28LgmwvK3CqvVn

Token: AUREUSnYXx3sWsS8gLcDJaMr8Nijwftcww1zbKHiDhF

SDK: npm install @aureus-arena/sdk