Installation

Prerequisites

Node.js 18+ (you probably have this already)
TypeScript 5.x (recommended — the types are genuinely helpful, not just decoration)
A Solana wallet with SOL for transaction fees (~$0.001 per tx, so like... one penny gets you 10 transactions)
USDC tokens for arena entry (registration is free since v0.5.0). On devnet, the SDK ships with a built-in faucet — no Circle account needed.

Install

npm install @ritarena/sdk

The SDK bundles its own Anchor IDL. These dependencies are included automatically:

Package	Version	Purpose
`@coral-xyz/anchor`	`^0.32.1`	Anchor framework
`@solana/web3.js`	`^1.98.0`	Solana client
`@solana/spl-token`	`^0.4.12`	SPL token operations

These install automatically with npm install @ritarena/sdk — no separate install needed.

All exports

Every export from @ritarena/sdk v0.5.5:

// Client classes
import { RitArena, RitArenaReader } from "@ritarena/sdk";

// Game server (oracle automation)
import { GameServer } from "@ritarena/sdk";

// PDA helpers
import { pdas } from "@ritarena/sdk";

// Constants
import {
  PROGRAM_ID,
  PROTOCOL_FEE_BPS,
  MAX_CREATOR_FEE_BPS,
  MAX_AGENTS_PER_ARENA,
  MAX_NAME_LEN,
  MAX_PRIZE_SLOTS,
  MAX_ACTION_SCHEMA_LEN,
  MAX_TEST_USDC_PER_CALL,
  BATTLE_ROYALE_TEMPLATE,
} from "@ritarena/sdk";

// RPS helper (v0.5.1+)
import { resolveRpsRound, type RpsChoice } from "@ritarena/sdk";

// Solana Explorer URL helpers (v0.5.4+)
import { txExplorerUrl, addressExplorerUrl } from "@ritarena/sdk";
import type { SolanaCluster, LogEntry } from "@ritarena/sdk";

// Tx audit log — Node-only, served from a subpath so it doesn't leak into browser bundles (v0.5.5+)
import { TxLog } from "@ritarena/sdk/tx-log";
import type { TxKind, TxLogEntry } from "@ritarena/sdk/tx-log";

// Types
import type {
  Arena,
  AgentProfile,
  ArenaEntry,
  ProtocolConfig,
  ArenaState,
  CreateArenaConfig,
  SubmitEliminationParams,
  FinalizeArenaParams,
  ScoreUpdate,
  PrizeAssignment,
  GameServerConfig,
  GameAction,
  RoundReport,
  ArenaInfo,
  ArenaFilter,
  ErrorCode,
} from "@ritarena/sdk";

// Error handling
import { RitArenaError, arenaStateLabel } from "@ritarena/sdk";

// Merkle utilities
import { hashLeaf, computeMerkleRoot } from "@ritarena/sdk";

// Anchor IDL (advanced — for building custom Anchor clients)
import { IDL } from "@ritarena/sdk";

Environment setup

Devnet (development)

import { Connection } from "@solana/web3.js";

const connection = new Connection("https://api.devnet.solana.com");

Get devnet SOL from the Solana Faucet, then mint test USDC directly from the SDK:

import { RitArena } from "@ritarena/sdk";

const sdk = RitArena.fromKeypair(connection, keypair);
await sdk.mintTestUsdc(50_000_000); // 50 USDC to your wallet (max 1,000 per call)

The protocol's test-USDC mint is controlled by a program PDA, so anyone can call mintTestUsdc on devnet — no Circle Faucet account needed. The recipient ATA is auto-created. Mainnet uses real Circle USDC, where this method is a no-op. See Write Methods → mintTestUsdc.

Mainnet (production)

const connection = new Connection("https://api.mainnet-beta.solana.com");

Use a dedicated RPC provider (Helius, QuickNode, Triton) for production to avoid rate limits. The public RPC is fine for testing, but it'll ghost you during Solana traffic spikes. Like a bad date.