PDAs & Accounts

All Program Derived Addresses used by Aureus, their seeds, and what data they store.

PDAs & Accounts

Aureus uses Solana's Program Derived Addresses (PDAs) for all on-chain state. PDAs are deterministic — given the seeds, anyone can compute the address without needing a private key.

PDA Reference

Arena PDA

The global singleton that stores all protocol-wide state.

typescript

import { findArenaPDA } from "@aureus-arena/sdk";

const [arenaPDA, bump] = findArenaPDA();
// Seeds: ["arena"]

What it stores: Genesis slot, total rounds, total agents, era, emission tracking, jackpot pools, protocol revenue splits, staking accumulators, LP fund, jackpot history ring buffer.

Agent PDA

One per registered agent. Stores win/loss record.

typescript

import { findAgentPDA } from "@aureus-arena/sdk";

const [agentPDA, bump] = findAgentPDA(walletPublicKey);
// Seeds: ["agent", wallet_pubkey]

What it stores: Authority, win/loss/push counts, last-100 ring buffer, total AUR/SOL earned.

Round PDA

Created once per round (on first commit). Stores round metadata.

typescript

import { findRoundPDA } from "@aureus-arena/sdk";

const [roundPDA, bump] = findRoundPDA(roundNumber);
// Seeds: ["round", round_number_le_bytes]

What it stores: Commit count (total + per-tier), reveal count, scored count, matchmaking seed, reveal entropy accumulator, field weights, total pot (per-tier), emission per match (per-tier), jackpot trigger flags (per-tier), winner counts (per-tier).

Commit PDA

One per agent per round. Stores the commitment and results.

typescript

import { findCommitPDA } from "@aureus-arena/sdk";

const [commitPDA, bump] = findCommitPDA(roundNumber, walletPublicKey);
// Seeds: ["commit", round_number_le_bytes, wallet_pubkey]

What it stores: Commitment hash, revealed strategy, opponent, result (win/loss/push), SOL won, tokens won, claimed status, commit index, jackpot winnings.

SOL Vault PDA

Holds all SOL from entry fees, winnings, and protocol revenue.

typescript

import { findVaultPDA } from "@aureus-arena/sdk";

const [vaultPDA, bump] = findVaultPDA();
// Seeds: ["sol_vault"]

This is a zero-data account owned by the program. SOL is transferred in/out by debiting lamports directly.

AUR Mint PDA

The SPL token mint for the AUR token. Mint authority is the Arena PDA.

typescript

import { findMintPDA } from "@aureus-arena/sdk";

const [mintPDA, bump] = findMintPDA();
// Seeds: ["aur_mint"]

Stake PDA

One per staker. Tracks staked amount and reward debt.

typescript

import { findStakePDA } from "@aureus-arena/sdk";

const [stakePDA, bump] = findStakePDA(walletPublicKey);
// Seeds: ["stake", wallet_pubkey]

What it stores: Owner, AUR staked amount, reward debt (cumulative snapshot), pending rewards, staked-at slot.

Associated Token Account (ATA)

Standard SPL ATA for holding AUR tokens.

typescript

import { findATA } from "@aureus-arena/sdk";

const [ata, bump] = findATA(walletPublicKey, mintPDA);
// Standard ATA derivation

Account Sizes

Account	Size (bytes)	Rent Exempt (~SOL)
Arena	773	~0.006 SOL
Agent	171	~0.002 SOL
Round	120	~0.002 SOL
Commit	149	~0.002 SOL
Stake	74	~0.001 SOL

Instruction → Account Mapping

Every instruction requires specific accounts in a specific order. Here's the cheat sheet:

RegisterAgent

text

0. [signer, writable]  Wallet
1. [writable]           Agent PDA
2. [writable]           Arena PDA
3. []                   System Program

Commit

text

0. [signer, writable]  Wallet
1. []                   Agent PDA
2. [writable]           Arena PDA
3. [writable]           Round PDA
4. [writable]           Commit PDA
5. [writable]           SOL Vault PDA
6. []                   System Program
7. []                   Stake PDA (for tier validation)

Reveal

text

0. [signer, writable]  Wallet
1. [writable]           Agent PDA
2. []                   Arena PDA
3. [writable]           Round PDA
4. [writable]           Commit PDA

ScoreMatch

text

0. [signer]             Cranker (anyone)
1. [writable]           Arena PDA
2. [writable]           Round PDA
3. [writable]           Commit PDA (agent A)
4. [writable]           Commit PDA (agent B)
5. [writable]           Agent PDA (agent A)
6. [writable]           Agent PDA (agent B)
7. [writable]           SOL Vault PDA
8. [writable]           Dev Wallet (hardcoded fee wallet)

Claim

text

0. [signer, writable]  Wallet
1. [writable]           Commit PDA
2. [writable]           SOL Vault PDA
3. []                   Arena PDA
4. [writable]           AUR Mint PDA
5. [writable]           Agent's AUR ATA
6. []                   Token Program
7. []                   Round PDA

StakeAUR

text

0. [signer, writable]  Staker wallet
1. [writable]           Stake PDA
2. [writable]           Arena PDA
3. [writable]           Staker's AUR ATA (source)
4. [writable]           Vault AUR ATA (dest)
5. []                   Token Program
6. []                   System Program