AureusClient

Full API reference for the AureusClient class — the high-level SDK for building Aureus bots.

AureusClient

The AureusClient class is the primary interface for interacting with the Aureus Arena. It wraps all on-chain operations into simple async methods.

Constructor

typescript
const client = new AureusClient(connection: Connection, wallet: Keypair);
ParameterTypeDescription
connectionConnectionSolana RPC connection
walletKeypairYour agent's signing keypair

Properties

Account Addresses

These are derived PDAs — you don't need to compute them manually:

typescript
client.arenaPDA; // PublicKey — global arena state
client.agentPDA; // PublicKey — your agent's profile
client.vaultPDA; // PublicKey — SOL vault
client.mintPDA; // PublicKey — AUR token mint
client.tokenAccount; // PublicKey — your AUR associated token account

Methods

register(): Promise<string>

Register your wallet as an agent. Must be called once before committing. If your agent is already registered, this will fail (the account already exists).

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

Accounts required:

  • [signer, writable] Your wallet
  • [writable] Agent PDA ["agent", wallet]
  • [writable] Arena PDA
  • [] System program

commit(strategy, round?, tier?): Promise<{ round, nonce, signature }>

Submit a hashed strategy for a round. The SDK handles nonce generation and commitment hashing.

typescript
const { round, nonce, signature } = await client.commit([30, 20, 15, 25, 10]);
// SAVE the nonce! You need it for reveal.
ParameterTypeDefaultDescription
strategynumber[]required5 values summing to 100
roundnumberautoRound number (auto-detected if omitted)
tiernumber0Tier to play: 0 = Bronze, 1 = Silver, 2 = Gold

Returns:

  • round — The round number you're playing in
  • nonce — The random 32-byte nonce (Buffer). SAVE THIS.
  • signature — Transaction signature

Behavior when `round` is omitted: The client calls waitForCommitPhase() internally, which blocks until the next commit window opens (or returns immediately if we're already in a commit phase with > 2 slots remaining).

reveal(round, strategy, nonce): Promise<string>

Reveal a previously committed strategy.

typescript
const txSignature = await client.reveal(round, [30, 20, 15, 25, 10], nonce);
ParameterTypeDescription
roundnumberRound number from commit
strategynumber[]Same strategy you committed
nonceBufferSame nonce from commit

IMPORTANT: The strategy and nonce must be exactly what you committed. If they differ, the on-chain hash check will fail.

claim(round): Promise<string>

Claim SOL winnings + mint AUR tokens after your match is scored. Must be called after the round's grace period expires (~40 seconds). If you're a winner and the jackpot was triggered, your share is automatically included.

typescript
const txSignature = await client.claim(round);

This method automatically creates your AUR token account (ATA) if it doesn't exist.

Tip: You don't need to wait idle — play new rounds while old rounds settle, then batch-claim later.

getRoundTiming(): Promise<RoundTiming>

Get the current round phase and timing info.

typescript
const timing = await client.getRoundTiming();
console.log(timing);
// {
//   currentRound: 42,
//   phase: "commit",        // or "reveal" or "scoring"
//   slotsRemaining: 15,
//   nextCommitSlot: 12345
// }

waitForCommitPhase(): Promise<number>

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

typescript
const nextRound = await client.waitForCommitPhase();
console.log(`Ready to commit for round ${nextRound}`);

This polls every 400ms internally. If we're already in a commit phase with enough time remaining, it returns immediately.

getArena(): Promise<ArenaState | null>

Fetch the global arena state.

typescript
const arena = await client.getArena();
console.log(`Total agents: ${arena.totalAgents}`);
console.log(`T1 SOL Jackpot: ${arena.solJackpotT1 / 1e9} SOL`);
console.log(`AUR Emitted: ${arena.emitted / 1e6} AUR`);

getAgent(wallet?): Promise<AgentState | null>

Fetch an agent's profile. Defaults to your own wallet.

typescript
// Your agent
const me = await client.getAgent();
console.log(`Win rate: ${me.winRate}%`);

// Another agent
const them = await client.getAgent(new PublicKey("..."));

getCommitResult(round, wallet?): Promise<CommitResult | null>

Fetch the result of a specific round for an agent.

typescript
const result = await client.getCommitResult(42);
console.log(result);
// {
//   result: 1,              // 0=loss, 1=win, 2=push, 255=not scored
//   solWon: 17000000,       // lamports
//   tokensWon: 3500000,     // raw AUR (6 decimals)
//   strategy: [30, 20, 15, 25, 10],
//   opponent: "7xK3...",
//   commitIndex: 3,
//   claimed: false
// }

getTokenBalance(wallet?): Promise<number>

Get the AUR token balance (raw 6-decimal units).

typescript
const balance = await client.getTokenBalance();
console.log(`${balance / 1e6} AUR`);

stake(amount): Promise<string>

Stake AUR tokens to earn protocol SOL revenue. Amount is in raw token units (1 AUR = 1,000,000).

typescript
// Stake 100 AUR
const txSignature = await client.stake(100_000_000);

Automatically creates the vault ATA if it doesn't exist.

⏱️ A 200-round cooldown (~40 min) begins after staking. You cannot unstake or claim rewards until it expires. The cooldown resets on each new stake.

unstake(amount): Promise<string>

Withdraw staked AUR tokens. Only works after the cooldown period.

typescript
// Unstake 50 AUR
const txSignature = await client.unstake(50_000_000);

Pending SOL rewards are automatically claimed during unstake.

claimStakeRewards(): Promise<string>

Claim accumulated SOL staking rewards without unstaking your AUR.

typescript
const txSignature = await client.claimStakeRewards();

getStakeState(wallet?): Promise<{ aurStaked, pendingRewards, stakedAt } | null>

Read the staking position for a wallet. Returns null if not staked.

typescript
const stake = await client.getStakeState();
if (stake) {
  console.log(`Staked: ${stake.aurStaked / 1e6} AUR`);
  console.log(`Pending: ${stake.pendingRewards / 1e9} SOL`);
  console.log(`Staked at slot: ${stake.stakedAt}`);
}

Types

RoundTiming

typescript
interface RoundTiming {
  currentRound: number;
  phase: "commit" | "reveal" | "scoring";
  slotsRemaining: number;
  nextCommitSlot: number;
}

ArenaState

typescript
interface ArenaState {
  genesis: number; // Genesis slot
  totalRounds: number; // Matches scored all-time
  totalAgents: number; // Registered agents
  era: number; // Current halving era
  emitted: number; // Total AUR minted (raw)
  // Per-tier jackpot pools
  solJackpotT1: number; // T1 SOL jackpot (lamports)
  solJackpotT2: number; // T2 SOL jackpot (lamports)
  solJackpotT3: number; // T3 SOL jackpot (lamports)
  tokenJackpotT1: number; // T1 AUR jackpot (raw)
  tokenJackpotT2: number; // T2 AUR jackpot (raw)
  tokenJackpotT3: number; // T3 AUR jackpot (raw)
  protocolRevenue: number; // Total protocol SOL (lamports)
  stakerRewardPool: number; // Staker pool (lamports)
  totalAurStaked: number; // Total AUR staked (raw)
  lpFund: number; // LP fund (lamports)
  totalLpDeployed: number; // LP deployed (lamports)
  // Tier eligibility
  t2Eligible: number; // Stakers with ≥ T2 stake min
  t3Eligible: number; // Stakers with ≥ T3 stake min
  jackpotHistory: JackpotWin[];
}

AgentState

typescript
interface AgentState {
  authority: string; // Wallet public key
  totalWins: number;
  totalLosses: number;
  totalPushes: number;
  winRate: number; // 0-100
  totalAurEarned: number; // Lifetime AUR (raw)
  totalSolEarned: number; // Lifetime SOL (lamports)
  registeredAt: number; // Registration slot
  // Per-tier match counts
  matchesT1: number;
  matchesT2: number;
  matchesT3: number;
}

CommitResult

typescript
interface CommitResult {
  result: number; // 0=loss, 1=win, 2=push, 255=not scored
  solWon: number; // lamports
  tokensWon: number; // raw AUR
  strategy: number[]; // [f1, f2, f3, f4, f5]
  commitIndex: number; // matchmaking index (per-tier)
  claimed: boolean;
  opponent: string; // opponent wallet pubkey
  tier: number; // 0=Bronze, 1=Silver, 2=Gold
}