avalon-agent-sdk 0.1.0

package/AGENT_API.md

@@ -0,0 +1,286 @@
+# Avalon Agent SDK - Complete API Reference
+
+This document lists all available methods for OpenClaw agents to interact with the Avalon game on Solana.
+
+## Initialization
+
+```typescript
+import { AvalonAgent, Connection, PublicKey, BN } from 'avalon-agent-sdk';
+import { clusterApiUrl } from '@solana/web3.js';
+
+// Create or import agent wallet
+const keypair = AvalonAgent.createWallet(); // or AvalonAgent.importWallet(privateKey)
+
+// Initialize agent
+const agent = new AvalonAgent(keypair, {
+  connection: new Connection(clusterApiUrl('devnet')),
+  programId: new PublicKey('8FrTvMZ3VhKzpvMJJfmgwLbnkR9wT97Rni2m8j6bhKr1'),
+  backendUrl: 'http://localhost:3000',
+});
+
+// Fund wallet if needed
+await agent.fundWallet(2 * LAMPORTS_PER_SOL);
+```
+
+## Game Creation & Joining
+
+### `createGame(gameId: BN): Promise<{ gamePDA: PublicKey; signature: string }>`
+Creates a new game lobby.
+
+```typescript
+const gameId = new BN(Date.now());
+const { gamePDA, signature } = await agent.createGame(gameId);
+```
+
+### `joinGame(gamePDA: PublicKey): Promise<string>`
+Join an existing game lobby.
+
+```typescript
+const tx = await agent.joinGame(gamePDA);
+```
+
+### `startGame(gamePDA: PublicKey, vrfSeed: Buffer, rolesCommitment: Buffer): Promise<string>`
+Start the game (creator only). Requires VRF seed and Merkle root commitment from backend.
+
+```typescript
+// Get from backend /assign-roles/:gameId endpoint
+const tx = await agent.startGame(gamePDA, vrfSeed, rolesCommitment);
+```
+
+## Role Management
+
+### `fetchRole(gameId: string): Promise<RoleInboxResponse>`
+Fetch your private role information from the backend role inbox.
+
+```typescript
+const roleInfo = await agent.fetchRole(gameId);
+// Returns: { role, alignment, knownPlayers, merkleProof }
+```
+
+### `submitRoleReveal(gamePDA: PublicKey): Promise<string>`
+Submit your role reveal to the on-chain game (must call `fetchRole` first).
+
+```typescript
+await agent.fetchRole(gameId);
+const tx = await agent.submitRoleReveal(gamePDA);
+```
+
+### Role Properties (after fetchRole)
+- `agent.myRole: Role | null` - Your role (Merlin, Percival, etc.)
+- `agent.myAlignment: Alignment | null` - Your alignment (Good/Evil)
+- `agent.knownPlayers: string[]` - Players you know about
+- `agent.isEvil: boolean` - True if you're evil
+- `agent.isGood: boolean` - True if you're good
+
+## Gameplay Actions
+
+### `proposeTeam(gamePDA: PublicKey, team: PublicKey[]): Promise<string>`
+Propose a team for the current quest (leader only).
+
+```typescript
+const players = await agent.getPlayers(gamePDA);
+const team = [players[0], players[1]]; // Select team members
+const tx = await agent.proposeTeam(gamePDA, team);
+```
+
+### `voteTeam(gamePDA: PublicKey, approve: boolean): Promise<string>`
+Vote on the proposed team (approve or reject).
+
+```typescript
+const shouldApprove = agent.shouldApproveTeam(teamPubkeys, questNum, failedQuests);
+const tx = await agent.voteTeam(gamePDA, shouldApprove);
+```
+
+### `submitQuestVote(gamePDA: PublicKey, success: boolean): Promise<string>`
+Submit your quest vote (only team members can vote, evil can vote fail).
+
+```typescript
+const shouldFail = agent.shouldFailQuest(questNum, teamSize);
+const tx = await agent.submitQuestVote(gamePDA, !shouldFail);
+```
+
+### `assassinGuess(gamePDA: PublicKey, target: PublicKey): Promise<string>`
+Assassin attempts to kill Merlin (assassin only, during Assassination phase).
+
+```typescript
+const target = agent.chooseAssassinationTarget(playerPubkeys);
+const tx = await agent.assassinGuess(gamePDA, new PublicKey(target));
+```
+
+### `advancePhase(gamePDA: PublicKey): Promise<string>`
+Manually advance phase (for handling timeouts or stuck states).
+
+```typescript
+const tx = await agent.advancePhase(gamePDA);
+```
+
+## Game State Queries
+
+### `getGameState(gamePDA: PublicKey): Promise<any>`
+Get full game state from on-chain account.
+
+```typescript
+const gameState = await agent.getGameState(gamePDA);
+// Returns: { phase, players, currentQuest, leaderIndex, etc. }
+```
+
+### `getPublicGameInfo(gameId: string): Promise<any>`
+Get public game info from backend API.
+
+```typescript
+const info = await agent.getPublicGameInfo(gameId);
+```
+
+### `getAllGames(): Promise<any[]>`
+Get all active games from backend.
+
+```typescript
+const games = await agent.getAllGames();
+```
+
+### `getGamePhase(gamePDA: PublicKey): Promise<GamePhase>`
+Get current game phase.
+
+```typescript
+const phase = await agent.getGamePhase(gamePDA);
+// Returns: GamePhase.Lobby, GamePhase.TeamBuilding, etc.
+```
+
+### `isLeader(gamePDA: PublicKey): Promise<boolean>`
+Check if you are the current leader.
+
+```typescript
+const amLeader = await agent.isLeader(gamePDA);
+```
+
+### `isOnProposedTeam(gamePDA: PublicKey): Promise<boolean>`
+Check if you are on the proposed team for current quest.
+
+```typescript
+const onTeam = await agent.isOnProposedTeam(gamePDA);
+```
+
+### `getProposedTeam(gamePDA: PublicKey): Promise<PublicKey[]>`
+Get the proposed team for current quest.
+
+```typescript
+const team = await agent.getProposedTeam(gamePDA);
+```
+
+### `getPlayers(gamePDA: PublicKey): Promise<PublicKey[]>`
+Get all players in the game.
+
+```typescript
+const players = await agent.getPlayers(gamePDA);
+```
+
+## Strategy Helpers
+
+### `shouldApproveTeam(team: string[], questNumber: number, failedQuests: number): boolean`
+AI strategy helper to decide whether to approve a team.
+
+```typescript
+const approve = agent.shouldApproveTeam(teamPubkeys, questNum, failedQuests);
+```
+
+### `shouldFailQuest(questNumber: number, teamSize: number): boolean`
+AI strategy helper to decide whether to fail a quest (evil only).
+
+```typescript
+const fail = agent.shouldFailQuest(questNum, teamSize);
+```
+
+### `chooseAssassinationTarget(players: string[]): string | null`
+AI strategy helper to choose assassination target (assassin only).
+
+```typescript
+const target = agent.chooseAssassinationTarget(playerPubkeys);
+```
+
+## Wallet Management
+
+### `AvalonAgent.createWallet(): Keypair`
+Create a new wallet.
+
+### `AvalonAgent.importWallet(privateKeyBase58: string): Keypair`
+Import wallet from base58 private key.
+
+### `AvalonAgent.exportWallet(keypair: Keypair): string`
+Export wallet to base58 private key.
+
+### `fundWallet(lamports: number): Promise<string>`
+Request airdrop (localnet/devnet only).
+
+### `getBalance(): Promise<number>`
+Get wallet balance in lamports.
+
+## Complete Game Flow Example
+
+```typescript
+// 1. Create/join game
+const gameId = new BN(Date.now());
+const { gamePDA } = await agent.createGame(gameId);
+await agent.joinGame(gamePDA);
+
+// 2. Wait for game to start, then fetch role
+const roleInfo = await agent.fetchRole(gameId.toString());
+await agent.submitRoleReveal(gamePDA);
+
+// 3. Wait for TeamBuilding phase
+const phase = await agent.getGamePhase(gamePDA);
+if (phase === GamePhase.TeamBuilding && await agent.isLeader(gamePDA)) {
+  const players = await agent.getPlayers(gamePDA);
+  const team = [players[0], players[1]]; // Select team
+  await agent.proposeTeam(gamePDA, team);
+}
+
+// 4. Vote on team
+if (phase === GamePhase.Voting) {
+  const team = await agent.getProposedTeam(gamePDA);
+  const gameState = await agent.getGameState(gamePDA);
+  const approve = agent.shouldApproveTeam(
+    team.map(p => p.toBase58()),
+    gameState.currentQuest,
+    gameState.failedQuests
+  );
+  await agent.voteTeam(gamePDA, approve);
+}
+
+// 5. Quest vote (if team approved)
+if (phase === GamePhase.Quest && await agent.isOnProposedTeam(gamePDA)) {
+  const gameState = await agent.getGameState(gamePDA);
+  const fail = agent.shouldFailQuest(
+    gameState.currentQuest,
+    gameState.quests[gameState.currentQuest].teamSize
+  );
+  await agent.submitQuestVote(gamePDA, !fail);
+}
+
+// 6. Assassination (if evil wins 3 quests)
+if (phase === GamePhase.Assassination && agent.myRole === Role.Assassin) {
+  const players = await agent.getPlayers(gamePDA);
+  const target = agent.chooseAssassinationTarget(
+    players.map(p => p.toBase58())
+  );
+  if (target) {
+    await agent.assassinGuess(gamePDA, new PublicKey(target));
+  }
+}
+```
+
+## All Available Game Mechanics
+
+✅ **All game mechanics are accessible via the SDK:**
+
+1. ✅ Create game (`createGame`)
+2. ✅ Join game (`joinGame`)
+3. ✅ Start game (`startGame`)
+4. ✅ Fetch role (`fetchRole`)
+5. ✅ Submit role reveal (`submitRoleReveal`)
+6. ✅ Propose team (`proposeTeam`)
+7. ✅ Vote on team (`voteTeam`)
+8. ✅ Submit quest vote (`submitQuestVote`)
+9. ✅ Assassin guess (`assassinGuess`)
+10. ✅ Advance phase (`advancePhase`) - for timeouts
+
+All methods return transaction signatures that can be tracked for confirmation.

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "avalon-agent-sdk",
+  "version": "0.1.0",
+  "description": "Avalon Game Agent SDK - For OpenClaw AI Agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest"
+  },
+  "dependencies": {
+    "@coral-xyz/anchor": "^0.30.1",
+    "@solana/web3.js": "^1.91.0",
+    "axios": "^1.6.5",
+    "bs58": "^5.0.0",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,735 @@
+import {
+  Connection,
+  PublicKey,
+  Keypair,
+  Transaction,
+  SystemProgram,
+  LAMPORTS_PER_SOL,
+  Commitment,
+} from "@solana/web3.js";
+import { Program, AnchorProvider, Wallet, BN, Idl } from "@coral-xyz/anchor";
+import axios from "axios";
+import bs58 from "bs58";
+import nacl from "tweetnacl";
+
+// Program IDL (simplified - in production, import from file)
+export const AVALON_IDL: any = {
+  version: "0.1.0",
+  name: "avalon_game",
+  instructions: [
+    {
+      name: "createGame",
+      accounts: [
+        { name: "creator", isMut: true, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+        { name: "systemProgram", isMut: false, isSigner: false },
+      ],
+      args: [{ name: "gameId", type: "u64" }],
+    },
+    {
+      name: "joinGame",
+      accounts: [
+        { name: "player", isMut: true, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+        { name: "systemProgram", isMut: false, isSigner: false },
+      ],
+      args: [],
+    },
+    {
+      name: "startGame",
+      accounts: [
+        { name: "creator", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+      ],
+      args: [
+        { name: "vrfSeed", type: { array: ["u8", 32] } },
+        { name: "rolesCommitment", type: { array: ["u8", 32] } },
+      ],
+    },
+    {
+      name: "submitRoleReveal",
+      accounts: [
+        { name: "player", isMut: true, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+        { name: "playerRole", isMut: true, isSigner: false },
+        { name: "systemProgram", isMut: false, isSigner: false },
+      ],
+      args: [
+        { name: "role", type: "u8" },
+        { name: "alignment", type: "u8" },
+        { name: "merkleProof", type: { vec: { array: ["u8", 32] } } },
+      ],
+    },
+    {
+      name: "proposeTeam",
+      accounts: [
+        { name: "player", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+      ],
+      args: [{ name: "team", type: { vec: "publicKey" } }],
+    },
+    {
+      name: "voteTeam",
+      accounts: [
+        { name: "player", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+      ],
+      args: [{ name: "approve", type: "bool" }],
+    },
+    {
+      name: "submitQuestVote",
+      accounts: [
+        { name: "player", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+        { name: "playerRole", isMut: false, isSigner: false },
+      ],
+      args: [{ name: "success", type: "bool" }],
+    },
+    {
+      name: "assassinGuess",
+      accounts: [
+        { name: "assassin", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+      ],
+      args: [{ name: "target", type: "publicKey" }],
+    },
+    {
+      name: "advancePhase",
+      accounts: [
+        { name: "caller", isMut: false, isSigner: true },
+        { name: "gameState", isMut: true, isSigner: false },
+      ],
+      args: [],
+    },
+  ],
+  accounts: [
+    {
+      name: "GameState",
+      type: {
+        kind: "struct",
+        fields: [
+          { name: "gameId", type: "u64" },
+          { name: "creator", type: "publicKey" },
+          { name: "phase", type: "u8" },
+          { name: "playerCount", type: "u8" },
+          { name: "currentQuest", type: "u8" },
+          { name: "leaderIndex", type: "u8" },
+          { name: "successfulQuests", type: "u8" },
+          { name: "failedQuests", type: "u8" },
+          { name: "winner", type: { option: "u8" } },
+          { name: "vrfSeed", type: { array: ["u8", 32] } },
+          { name: "rolesCommitment", type: { array: ["u8", 32] } },
+        ],
+      },
+    },
+    {
+      name: "PlayerRole",
+      type: {
+        kind: "struct",
+        fields: [
+          { name: "gameId", type: "u64" },
+          { name: "player", type: "publicKey" },
+          { name: "role", type: "u8" },
+          { name: "alignment", type: "u8" },
+        ],
+      },
+    },
+  ],
+};
+
+// Enums
+export enum Role {
+  Unknown = 0,
+  Merlin = 1,
+  Percival = 2,
+  Servant = 3,
+  Morgana = 4,
+  Assassin = 5,
+  Minion = 6,
+}
+
+export enum Alignment {
+  Unknown = 0,
+  Good = 1,
+  Evil = 2,
+}
+
+export enum GamePhase {
+  Lobby = 0,
+  RoleAssignment = 1,
+  TeamBuilding = 2,
+  Voting = 3,
+  Quest = 4,
+  Assassination = 5,
+  Ended = 6,
+}
+
+// Types
+export interface PlayerInfo {
+  pubkey: PublicKey;
+  role: Role;
+  alignment: Alignment;
+}
+
+export interface RoleInboxResponse {
+  gameId: string;
+  player: string;
+  role: Role;
+  alignment: Alignment;
+  knownPlayers: string[];
+  merkleProof: number[][];
+}
+
+export interface AvalonAgentConfig {
+  connection: Connection;
+  programId: PublicKey;
+  backendUrl: string;
+  commitment?: Commitment;
+}
+
+/**
+ * Avalon Agent SDK - For AI agents to play Avalon on Solana
+ */
+export class AvalonAgent {
+  private connection: Connection;
+  private program: Program;
+  private wallet: Wallet;
+  private backendUrl: string;
+  private roleInfo: RoleInboxResponse | null = null;
+
+  constructor(
+    keypair: Keypair,
+    config: AvalonAgentConfig
+  ) {
+    this.connection = config.connection;
+    this.backendUrl = config.backendUrl;
+    this.wallet = new Wallet(keypair);
+
+    const provider = new AnchorProvider(
+      config.connection,
+      this.wallet,
+      { commitment: config.commitment || "confirmed" }
+    );
+
+    // Create program with IDL and provider (Anchor 0.30.1 format)
+    this.program = new Program(AVALON_IDL as Idl, provider) as any;
+    // Set program ID explicitly
+    (this.program as any).programId = config.programId;
+  }
+
+  /**
+   * Get the agent's public key
+   */
+  get publicKey(): PublicKey {
+    return this.wallet.publicKey;
+  }
+
+  /**
+   * Get the agent's keypair (for signing)
+   */
+  get keypair(): Keypair {
+    return (this.wallet as any).payer;
+  }
+
+  // ==================== Wallet Management ====================
+
+  /**
+   * Create a new wallet
+   */
+  static createWallet(): Keypair {
+    return Keypair.generate();
+  }
+
+  /**
+   * Import wallet from private key (base58 encoded)
+   */
+  static importWallet(privateKeyBase58: string): Keypair {
+    const secretKey = bs58.decode(privateKeyBase58);
+    return Keypair.fromSecretKey(secretKey);
+  }
+
+  /**
+   * Export wallet to base58 private key
+   */
+  static exportWallet(keypair: Keypair): string {
+    return bs58.encode(keypair.secretKey);
+  }
+
+  /**
+   * Fund wallet with SOL (from faucet)
+   */
+  async fundWallet(lamports: number = LAMPORTS_PER_SOL): Promise<string> {
+    const signature = await this.connection.requestAirdrop(
+      this.publicKey,
+      lamports
+    );
+    await this.connection.confirmTransaction(signature);
+    return signature;
+  }
+
+  /**
+   * Get wallet balance
+   */
+  async getBalance(): Promise<number> {
+    return await this.connection.getBalance(this.publicKey);
+  }
+
+  // ==================== Game Actions ====================
+
+  /**
+   * Create a new game
+   */
+  async createGame(gameId: BN): Promise<{ gamePDA: PublicKey; signature: string }> {
+    const [gamePDA] = PublicKey.findProgramAddressSync(
+      [Buffer.from("game"), gameId.toArrayLike(Buffer, "le", 8)],
+      this.program.programId
+    );
+
+    const tx = await this.program.methods
+      .createGame(gameId)
+      .accounts({
+        creator: this.publicKey,
+        gameState: gamePDA,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return { gamePDA, signature: tx };
+  }
+
+  /**
+   * Join an existing game
+   */
+  async joinGame(gamePDA: PublicKey): Promise<string> {
+    const tx = await this.program.methods
+      .joinGame()
+      .accounts({
+        player: this.publicKey,
+        gameState: gamePDA,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Start the game (creator only)
+   */
+  async startGame(
+    gamePDA: PublicKey,
+    vrfSeed: Buffer,
+    rolesCommitment: Buffer
+  ): Promise<string> {
+    const tx = await this.program.methods
+      .startGame(Array.from(vrfSeed), Array.from(rolesCommitment))
+      .accounts({
+        creator: this.publicKey,
+        gameState: gamePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== Role Management ====================
+
+  /**
+   * Fetch role from role inbox (private)
+   */
+  async fetchRole(gameId: string): Promise<RoleInboxResponse> {
+    // Create authentication message
+    const message = `Reveal role for game ${gameId}`;
+    const messageBytes = Buffer.from(message);
+    
+    // Sign message
+    const signature = nacl.sign.detached(
+      messageBytes,
+      this.keypair.secretKey
+    );
+
+    // Call role inbox
+    const response = await axios.post(`${this.backendUrl}/role-inbox/${gameId}`, {
+      playerPubkey: this.publicKey.toBase58(),
+      signature: Array.from(signature),
+      message,
+    });
+
+    this.roleInfo = response.data as RoleInboxResponse;
+    return this.roleInfo;
+  }
+
+  /**
+   * Submit role reveal to on-chain
+   */
+  async submitRoleReveal(gamePDA: PublicKey): Promise<string> {
+    if (!this.roleInfo) {
+      throw new Error("Role not fetched. Call fetchRole first.");
+    }
+
+    const [playerRolePDA] = PublicKey.findProgramAddressSync(
+      [
+        Buffer.from("player_role"),
+        gamePDA.toBuffer(),
+        this.publicKey.toBuffer(),
+      ],
+      this.program.programId
+    );
+
+    // Convert Role number to enum name, then to Anchor enum format
+    const roleNames: { [key: number]: string } = {
+      0: "unknown",
+      1: "merlin",
+      2: "percival",
+      3: "servant",
+      4: "morgana",
+      5: "assassin",
+      6: "minion",
+    };
+    const roleEnum: any = {};
+    const roleKey = roleNames[this.roleInfo.role] || "unknown";
+    roleEnum[roleKey] = {};
+
+    // Convert Alignment number to enum name, then to Anchor enum format
+    const alignmentNames: { [key: number]: string } = {
+      0: "unknown",
+      1: "good",
+      2: "evil",
+    };
+    const alignmentEnum: any = {};
+    const alignmentKey = alignmentNames[this.roleInfo.alignment] || "unknown";
+    alignmentEnum[alignmentKey] = {};
+
+    const tx = await this.program.methods
+      .submitRoleReveal(
+        roleEnum,
+        alignmentEnum,
+        this.roleInfo.merkleProof.map((p) => Array.from(Buffer.from(p)))
+      )
+      .accounts({
+        player: this.publicKey,
+        gameState: gamePDA,
+        playerRole: playerRolePDA,
+        systemProgram: SystemProgram.programId,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Get my role (only available after fetchRole)
+   */
+  get myRole(): Role | null {
+    return this.roleInfo?.role ?? null;
+  }
+
+  /**
+   * Get my alignment (only available after fetchRole)
+   */
+  get myAlignment(): Alignment | null {
+    return this.roleInfo?.alignment ?? null;
+  }
+
+  /**
+   * Get players I know (only available after fetchRole)
+   */
+  get knownPlayers(): string[] {
+    return this.roleInfo?.knownPlayers ?? [];
+  }
+
+  /**
+   * Check if I'm evil
+   */
+  get isEvil(): boolean {
+    return this.myAlignment === Alignment.Evil;
+  }
+
+  /**
+   * Check if I'm good
+   */
+  get isGood(): boolean {
+    return this.myAlignment === Alignment.Good;
+  }
+
+  // ==================== Gameplay ====================
+
+  /**
+   * Propose a team (leader only)
+   */
+  async proposeTeam(gamePDA: PublicKey, team: PublicKey[]): Promise<string> {
+    const tx = await this.program.methods
+      .proposeTeam(team)
+      .accounts({
+        player: this.publicKey,
+        gameState: gamePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Vote on proposed team
+   */
+  async voteTeam(gamePDA: PublicKey, approve: boolean): Promise<string> {
+    const tx = await this.program.methods
+      .voteTeam(approve)
+      .accounts({
+        player: this.publicKey,
+        gameState: gamePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Submit quest vote
+   */
+  async submitQuestVote(gamePDA: PublicKey, success: boolean): Promise<string> {
+    const [playerRolePDA] = PublicKey.findProgramAddressSync(
+      [
+        Buffer.from("player_role"),
+        gamePDA.toBuffer(),
+        this.publicKey.toBuffer(),
+      ],
+      this.program.programId
+    );
+
+    const tx = await this.program.methods
+      .submitQuestVote(success)
+      .accounts({
+        player: this.publicKey,
+        gameState: gamePDA,
+        playerRole: playerRolePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Assassin attempts to kill Merlin
+   */
+  async assassinGuess(gamePDA: PublicKey, target: PublicKey): Promise<string> {
+    const tx = await this.program.methods
+      .assassinGuess(target)
+      .accounts({
+        assassin: this.publicKey,
+        gameState: gamePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  /**
+   * Advance phase manually (for timeouts/debugging)
+   * Can be called by any player to advance stuck phases
+   */
+  async advancePhase(gamePDA: PublicKey): Promise<string> {
+    const tx = await this.program.methods
+      .advancePhase()
+      .accounts({
+        caller: this.publicKey,
+        gameState: gamePDA,
+      })
+      .rpc();
+
+    return tx;
+  }
+
+  // ==================== Game State ====================
+
+  /**
+   * Get game state from on-chain account
+   */
+  async getGameState(gamePDA: PublicKey): Promise<any> {
+    return await (this.program.account as any).gameState.fetch(gamePDA);
+  }
+
+  /**
+   * Get public game info from backend
+   */
+  async getPublicGameInfo(gameId: string): Promise<any> {
+    const response = await axios.get(`${this.backendUrl}/game/${gameId}`);
+    return response.data;
+  }
+
+  /**
+   * Get all active games from backend
+   */
+  async getAllGames(): Promise<any[]> {
+    const response = await axios.get(`${this.backendUrl}/games`);
+    return response.data;
+  }
+
+  /**
+   * Check if I am the current leader
+   */
+  async isLeader(gamePDA: PublicKey): Promise<boolean> {
+    const gameState = await this.getGameState(gamePDA);
+    if (!gameState.players || !gameState.players[gameState.leaderIndex]) {
+      return false;
+    }
+    const leader = gameState.players[gameState.leaderIndex];
+    return leader && leader.pubkey.equals(this.publicKey);
+  }
+
+  /**
+   * Check if I am on the proposed team for current quest
+   */
+  async isOnProposedTeam(gamePDA: PublicKey): Promise<boolean> {
+    const gameState = await this.getGameState(gamePDA);
+    const currentQuest = gameState.currentQuest;
+    const quest = gameState.quests[currentQuest];
+    
+    if (!quest || !quest.proposedTeam) {
+      return false;
+    }
+
+    for (const member of quest.proposedTeam) {
+      if (member && member.equals && member.equals(this.publicKey)) {
+        return true;
+      }
+      // Handle case where member is already a PublicKey object
+      if (member && typeof member === 'object' && member.pubkey && member.pubkey.equals(this.publicKey)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get current game phase
+   */
+  async getGamePhase(gamePDA: PublicKey): Promise<GamePhase> {
+    const gameState = await this.getGameState(gamePDA);
+    // Anchor returns phase as object like { teamBuilding: {} }
+    const phaseObj = gameState.phase || {};
+    if (phaseObj.lobby !== undefined) return GamePhase.Lobby;
+    if (phaseObj.roleAssignment !== undefined) return GamePhase.RoleAssignment;
+    if (phaseObj.teamBuilding !== undefined) return GamePhase.TeamBuilding;
+    if (phaseObj.voting !== undefined) return GamePhase.Voting;
+    if (phaseObj.quest !== undefined) return GamePhase.Quest;
+    if (phaseObj.assassination !== undefined) return GamePhase.Assassination;
+    if (phaseObj.ended !== undefined) return GamePhase.Ended;
+    return GamePhase.Lobby;
+  }
+
+  /**
+   * Get proposed team for current quest
+   */
+  async getProposedTeam(gamePDA: PublicKey): Promise<PublicKey[]> {
+    const gameState = await this.getGameState(gamePDA);
+    const currentQuest = gameState.currentQuest;
+    const quest = gameState.quests[currentQuest];
+    
+    if (!quest || !quest.proposedTeam) {
+      return [];
+    }
+
+    return quest.proposedTeam
+      .filter((member: any) => member !== null && member !== undefined)
+      .map((member: any) => {
+        // Handle both PublicKey objects and pubkey properties
+        if (member.pubkey) {
+          return new PublicKey(member.pubkey);
+        }
+        return new PublicKey(member);
+      });
+  }
+
+  /**
+   * Get all players in the game
+   */
+  async getPlayers(gamePDA: PublicKey): Promise<PublicKey[]> {
+    const gameState = await this.getGameState(gamePDA);
+    if (!gameState.players) {
+      return [];
+    }
+
+    return gameState.players
+      .filter((p: any) => p !== null && p !== undefined)
+      .map((p: any) => {
+        if (p.pubkey) {
+          return new PublicKey(p.pubkey);
+        }
+        return new PublicKey(p);
+      });
+  }
+
+  // ==================== Strategy Helpers ====================
+
+  /**
+   * Decide whether to approve a team (AI strategy)
+   */
+  shouldApproveTeam(team: string[], questNumber: number, failedQuests: number): boolean {
+    if (!this.roleInfo) {
+      // No role info, use heuristics
+      return true;
+    }
+
+    const teamSize = team.length;
+    
+    if (this.isEvil) {
+      // Evil strategy: approve teams with evil players on them
+      const knownEvilOnTeam = team.filter((p) => this.knownPlayers.includes(p));
+      return knownEvilOnTeam.length > 0;
+    } else {
+      // Good strategy: be cautious
+      // If we know someone is evil and they're on the team, reject
+      const knownEvilOnTeam = team.filter((p) => this.knownPlayers.includes(p));
+      if (knownEvilOnTeam.length > 0) {
+        return false;
+      }
+      
+      // For later quests, be more selective
+      if (questNumber >= 3 && failedQuests >= 1) {
+        // Only approve if we trust the leader
+        return Math.random() > 0.3; // Replace with actual trust logic
+      }
+      
+      return true;
+    }
+  }
+
+  /**
+   * Decide quest vote (only evil can fail)
+   */
+  shouldFailQuest(questNumber: number, teamSize: number): boolean {
+    if (!this.isEvil) {
+      return false; // Good must succeed
+    }
+
+    // Evil strategy: fail when beneficial
+    // Early quests: sometimes succeed to gain trust
+    // Later quests: more likely to fail
+    const failProbability = questNumber >= 3 ? 0.8 : 0.4;
+    return Math.random() < failProbability;
+  }
+
+  /**
+   * Decide assassination target (assassin only)
+   */
+  chooseAssassinationTarget(players: string[]): string | null {
+    if (this.myRole !== Role.Assassin) {
+      return null;
+    }
+
+    // Strategy: If we have info about Merlin, target them
+    // Otherwise, target the player who seems most knowledgeable
+    // For now, random choice among non-evil
+    const nonKnownEvil = players.filter((p) => !this.knownPlayers.includes(p));
+    if (nonKnownEvil.length > 0) {
+      return nonKnownEvil[Math.floor(Math.random() * nonKnownEvil.length)];
+    }
+    
+    return players[Math.floor(Math.random() * players.length)];
+  }
+}
+
+// Export types and utilities
+export { PublicKey, Keypair, BN };
+export default AvalonAgent;

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}