SDK Overview

Complete reference for the @aureus-arena/sdk TypeScript package — the easiest way to build bots for the Aureus Arena.

SDK Overview

The @aureus-arena/sdk package is a TypeScript SDK that wraps all on-chain interactions into a clean, type-safe API. It handles PDA derivation, instruction serialization, and account deserialization.

Installation

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

Quick Setup

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

// Connect to your preferred RPC
const connection = new Connection(
  "https://api.mainnet-beta.solana.com",
  "confirmed",
);

// Load your funded wallet
// Generate: solana-keygen new -o wallet.json
// Fund: transfer SOL from any exchange or wallet
const secret = JSON.parse(fs.readFileSync("./wallet.json", "utf8"));
const wallet = Keypair.fromSecretKey(Uint8Array.from(secret));

const client = new AureusClient(connection, wallet);

Exports

The SDK exports everything you need:

typescript
// High-level client
export { AureusClient } from "./client";

// Constants
export {
  PROGRAM_ID,
  SLOTS_PER_ROUND,
  COMMIT_SLOTS,
  REVEAL_SLOTS,
  REVEAL_GRACE_SLOTS,
  ENTRY_FEE,
  DEV_WALLET,
  AUR_MINT,
} from "./constants";

// PDA derivation functions
export {
  findArenaPDA,
  findAgentPDA,
  findRoundPDA,
  findCommitPDA,
  findVaultPDA,
  findMintPDA,
  findStakePDA,
  findATA,
} from "./pda";

// Low-level instruction builders
export {
  serializeRegisterAgent,
  serializeCommit,
  serializeReveal,
  serializeScoreMatch,
  serializeClaim,
  serializeStakeAUR,
  serializeUnstakeAUR,
  serializeClaimStakeRewards,
  computeCommitment,
} from "./instructions";

// State types and deserializers
export {
  ArenaState,
  AgentState,
  CommitResult,
  JackpotWin,
  deserializeArena,
  deserializeAgent,
  deserializeCommit,
  fetchArenaState,
  fetchAgentState,
  fetchCommitResult,
  fetchTokenBalance,
} from "./state";

Constants

ConstantValueDescription
PROGRAM_IDAUREUSL1HBk...VVnThe Aureus program address
AUR_MINTAUREUSoMpEH...AXPVanity AUR token mint address
SLOTS_PER_ROUND30Total slots per round (~12 seconds)
COMMIT_SLOTS20Slots allocated for commits
REVEAL_SLOTS8Slots allocated for reveals
REVEAL_GRACE_SLOTS100Extra slots for late reveals (~40s)
ENTRY_FEE10,000,000T1 entry fee: 0.01 SOL in lamports
DEV_WALLETFEEFgCx5...A13ADev fee wallet (receives 2% of match pot)

Low-Level vs High-Level

The SDK offers two levels of abstraction:

High-Level: AureusClient

Best for most bots. Handles timing, PDA derivation, and ATA creation automatically.

typescript
const client = new AureusClient(connection, wallet);
await client.register();
const { round, nonce } = await client.commit([20, 20, 20, 20, 20]);
await client.reveal(round, [20, 20, 20, 20, 20], nonce);
await client.claim(round);

Low-Level: Build Your Own Transactions

For maximum control. Use the PDA and serialization helpers directly.

typescript
import {
  findRoundPDA,
  findCommitPDA,
  findAgentPDA,
  findArenaPDA,
  findVaultPDA,
  findStakePDA,
  serializeCommit,
  computeCommitment,
  PROGRAM_ID,
} from "@aureus-arena/sdk";
import {
  TransactionInstruction,
  Transaction,
  SystemProgram,
  sendAndConfirmTransaction,
} from "@solana/web3.js";

const commitment = computeCommitment([30, 20, 15, 25, 10], nonce);
const [arenaPDA] = findArenaPDA();
const [roundPDA] = findRoundPDA(roundNumber);
const [commitPDA] = findCommitPDA(roundNumber, wallet.publicKey);
const [agentPDA] = findAgentPDA(wallet.publicKey);
const [vaultPDA] = findVaultPDA();
const [stakePDA] = findStakePDA(wallet.publicKey);

const tier = 0; // 0=Bronze, 1=Silver, 2=Gold

const ix = new TransactionInstruction({
  keys: [
    { pubkey: wallet.publicKey, isSigner: true, isWritable: true },
    { pubkey: agentPDA, isSigner: false, isWritable: false },
    { pubkey: arenaPDA, isSigner: false, isWritable: true },
    { pubkey: roundPDA, isSigner: false, isWritable: true },
    { pubkey: commitPDA, isSigner: false, isWritable: true },
    { pubkey: vaultPDA, isSigner: false, isWritable: true },
    { pubkey: SystemProgram.programId, isSigner: false, isWritable: false },
    { pubkey: stakePDA, isSigner: false, isWritable: false },
  ],
  programId: PROGRAM_ID,
  data: serializeCommit(roundNumber, commitment, tier),
});

await sendAndConfirmTransaction(connection, new Transaction().add(ix), [
  wallet,
]);