theref-sdk 0.1.0

package/dist/index.mjs

@@ -0,0 +1,602 @@
+// src/client/TheRefClient.ts
+import { createClient, createAccount, generatePrivateKey, chains } from "genlayer-js";
+import { TransactionStatus } from "genlayer-js/types";
+
+// src/utils/networks.ts
+var NETWORKS = {
+  bradbury: {
+    id: "bradbury",
+    rpc: "https://rpc-bradbury.genlayer.com",
+    chainId: 4221,
+    addresses: {
+      CORE: "0xA29CfFC83d32fe924cFf1F1bDCf21555CCC96206",
+      LB: "0x5D417F296b17656c9b950236feE66F63E22d8A54",
+      ORG: "0x440b28afc1804fc1E4AA8f5b559C18F7bCf43B3A",
+      FEE: "0x88A0A4d573fD9C63433E457e94d266D7904278C2",
+      TRN: "0xbcc0E82a17491297E0c4938606624Fa04e6abA1B"
+    }
+  },
+  studionet: {
+    id: "studionet",
+    rpc: "https://studio.genlayer.com/api",
+    chainId: 61999,
+    addresses: {
+      CORE: "0x88CAA18419714aA38CdF53c0E603141c48fa3238",
+      LB: "0x8A2d05Df048A64cc6B83682a431ade05030e4BBB",
+      ORG: "0x265ef96A5230F13836c553D7DD2B9D7c3fE14aE1",
+      FEE: "0x0000000000000000000000000000000000000000",
+      TRN: "0x44f7c1bDa293B9cdBD79a6dfb66bD45696dEa4A6"
+    }
+  }
+};
+var DEFAULT_WS_URL = "wss://ws.theref.fun";
+function resolveNetwork(network) {
+  if (typeof network === "string") return NETWORKS[network];
+  return network;
+}
+function gidToNum(gid) {
+  return parseInt(gid.replace(/^0+/, "") || "0", 36) || 1;
+}
+
+// src/adapters/normalizer.ts
+function adaptChess(move) {
+  if (typeof move === "string") {
+    if (/^[a-h][1-8]$|^[NBRQK][a-h]?[1-8]?x?[a-h][1-8][+#]?$|^O-O(-O)?[+#]?$/.test(move)) {
+      return move;
+    }
+  }
+  if (typeof move === "object" && move !== null && !Array.isArray(move)) {
+    const m = move;
+    if (m.from && m.to) {
+      const promo = m.promotion ? `=${String(m.promotion).toUpperCase()}` : "";
+      const piece = m.piece ? `${String(m.piece).toUpperCase()} ` : "";
+      return `${piece}${m.from}${m.promotion ? "" : ""}${m.to}${promo}`.trim();
+    }
+    if (m.piece && m.from && m.to) {
+      const pieceMap = {
+        knight: "N",
+        bishop: "B",
+        rook: "R",
+        queen: "Q",
+        king: "K",
+        pawn: ""
+      };
+      const p = pieceMap[String(m.piece).toLowerCase()] ?? "";
+      return `${p}${m.to}`;
+    }
+    if (m.uci && typeof m.uci === "string") {
+      return `${m.uci.slice(0, 2)}-${m.uci.slice(2, 4)}`;
+    }
+  }
+  if (Array.isArray(move) && move.length === 4 && move.every((n) => typeof n === "number")) {
+    const files = "abcdefgh";
+    return `${files[move[0]]}${move[1] + 1}-${files[move[2]]}${move[3] + 1}`;
+  }
+  return null;
+}
+function adaptRPS(move) {
+  const choices = {
+    rock: "Rock",
+    paper: "Paper",
+    scissors: "Scissors",
+    r: "Rock",
+    p: "Paper",
+    s: "Scissors",
+    "0": "Rock",
+    "1": "Paper",
+    "2": "Scissors",
+    stone: "Rock",
+    shears: "Scissors",
+    lizard: "Lizard",
+    spock: "Spock"
+    // RPSLS variant
+  };
+  if (typeof move === "string") {
+    const normalized = choices[move.toLowerCase().trim()];
+    if (normalized) return normalized;
+  }
+  if (typeof move === "number") {
+    const normalized = choices[String(move)];
+    if (normalized) return normalized;
+  }
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move;
+    const choice = m.choice ?? m.action ?? m.move ?? m.pick;
+    if (choice) return adaptRPS(choice);
+  }
+  return null;
+}
+function adaptCombat(move) {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move;
+    const parts = [];
+    if (m.player || m.character || m.unit) {
+      parts.push(String(m.player ?? m.character ?? m.unit));
+    }
+    const action = m.action ?? m.move ?? m.skill ?? m.ability ?? m.attack ?? m.spell ?? m.card;
+    if (action) parts.push(`uses ${action}`);
+    const target = m.target ?? m.enemy ?? m.opponent;
+    if (target) parts.push(`on ${target}`);
+    if (m.power !== void 0) parts.push(`(power: ${m.power})`);
+    if (m.damage !== void 0) parts.push(`(damage: ${m.damage})`);
+    if (m.mana_cost !== void 0) parts.push(`(mana: ${m.mana_cost})`);
+    if (m.combo) parts.push(`via combo: ${Array.isArray(m.combo) ? m.combo.join("+") : m.combo}`);
+    if (m.type) parts.push(`[${m.type} type]`);
+    if (m.element) parts.push(`[${m.element}]`);
+    if (m.special) parts.push(`special: ${m.special}`);
+    if (m.position) parts.push(`at ${JSON.stringify(m.position)}`);
+    if (parts.length > 0) return parts.join(" ");
+  }
+  return null;
+}
+function adaptStrategy(move) {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move;
+    const parts = [];
+    const action = m.action ?? m.command ?? m.order;
+    if (action) parts.push(String(action));
+    const unit = m.unit ?? m.piece ?? m.troop ?? m.building;
+    if (unit) parts.push(String(unit));
+    if (m.from && m.to) {
+      parts.push(`from ${JSON.stringify(m.from)} to ${JSON.stringify(m.to)}`);
+    } else if (m.position ?? m.target ?? m.location) {
+      parts.push(`at ${JSON.stringify(m.position ?? m.target ?? m.location)}`);
+    }
+    if (m.attack) parts.push(`attacking with ${m.attack}`);
+    if (m.defend) parts.push(`defending with ${m.defend}`);
+    if (m.resource !== void 0) parts.push(`(cost: ${m.resource})`);
+    if (parts.length > 0) return parts.join(" ");
+  }
+  return null;
+}
+function adaptTrivia(move) {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move;
+    const answer = m.answer ?? m.response ?? m.text ?? m.value;
+    if (answer !== void 0) return String(answer);
+  }
+  return null;
+}
+function adaptDebate(move) {
+  if (typeof move === "object" && !Array.isArray(move) && move !== null) {
+    const m = move;
+    const parts = [];
+    if (m.position) parts.push(`Position: ${m.position}`);
+    if (m.argument) parts.push(`Argument: ${m.argument}`);
+    if (m.evidence) parts.push(`Evidence: ${m.evidence}`);
+    if (m.rebuttal) parts.push(`Rebuttal: ${m.rebuttal}`);
+    if (parts.length > 0) return parts.join(". ");
+  }
+  return null;
+}
+function flattenObject(obj, prefix = "") {
+  return Object.entries(obj).map(([key, val]) => {
+    const label = prefix ? `${prefix}.${key}` : key;
+    if (val === null || val === void 0) return null;
+    if (typeof val === "object" && !Array.isArray(val)) {
+      return flattenObject(val, label);
+    }
+    if (Array.isArray(val)) {
+      return `${label}: [${val.map((v) => String(v)).join(", ")}]`;
+    }
+    return `${label}: ${val}`;
+  }).filter(Boolean).join(", ");
+}
+function normalizeMove(move, gameHint) {
+  if (typeof move === "string") {
+    return { raw: move, text: move.trim(), adapter: "passthrough" };
+  }
+  if (typeof move === "number") {
+    return { raw: move, text: String(move), adapter: "number" };
+  }
+  if (typeof move === "boolean") {
+    return { raw: move, text: move ? "Yes" : "No", adapter: "boolean" };
+  }
+  if (move === null || move === void 0) {
+    return { raw: move, text: "No move", adapter: "null" };
+  }
+  const hint = gameHint?.toLowerCase() ?? "";
+  if (hint.includes("chess")) {
+    const result = adaptChess(move);
+    if (result) return { raw: move, text: result, adapter: "chess" };
+  }
+  if (hint.includes("rock") || hint.includes("rps") || hint.includes("scissors")) {
+    const result = adaptRPS(move);
+    if (result) return { raw: move, text: result, adapter: "rps" };
+  }
+  if (hint.includes("trivia") || hint.includes("quiz") || hint.includes("question")) {
+    const result = adaptTrivia(move);
+    if (result) return { raw: move, text: result, adapter: "trivia" };
+  }
+  if (hint.includes("debate") || hint.includes("argument")) {
+    const result = adaptDebate(move);
+    if (result) return { raw: move, text: result, adapter: "debate" };
+  }
+  if (typeof move === "object") {
+    const chess = adaptChess(move);
+    if (chess) return { raw: move, text: chess, adapter: "chess" };
+    const rps = adaptRPS(move);
+    if (rps) return { raw: move, text: rps, adapter: "rps" };
+    const combat = adaptCombat(move);
+    if (combat) return { raw: move, text: combat, adapter: "combat" };
+    const strategy = adaptStrategy(move);
+    if (strategy) return { raw: move, text: strategy, adapter: "strategy" };
+    const trivia = adaptTrivia(move);
+    if (trivia) return { raw: move, text: trivia, adapter: "trivia" };
+    const debate = adaptDebate(move);
+    if (debate) return { raw: move, text: debate, adapter: "debate" };
+    if (Array.isArray(move)) {
+      const text = move.map((m) => normalizeMove(m).text).join(", ");
+      return { raw: move, text, adapter: "array" };
+    }
+    const flat = flattenObject(move);
+    return { raw: move, text: flat, adapter: "generic-object" };
+  }
+  return { raw: move, text: String(move), adapter: "fallback" };
+}
+
+// src/client/TheRefClient.ts
+var TheRefClient = class {
+  constructor(config) {
+    this.network = resolveNetwork(config.network);
+    this.retries = config.retries ?? 300;
+    this.pollInterval = config.pollInterval ?? 5e3;
+    this.wsUrl = config.wsUrl ?? DEFAULT_WS_URL;
+    const chain = this.network.chainId === 4221 ? chains.testnetBradbury : chains.studionet;
+    let account;
+    if (config.privateKey) {
+      account = createAccount(config.privateKey);
+    } else if (config.walletAddress) {
+      account = config.walletAddress;
+    } else {
+      account = createAccount(generatePrivateKey());
+    }
+    this.glClient = createClient({
+      chain,
+      endpoint: this.network.rpc,
+      account
+    });
+  }
+  // ── Internal helpers ────────────────────────────────────────────────────────
+  async write(address, method, args, value = 0n) {
+    const tx = await this.glClient.writeContract({
+      address,
+      functionName: method,
+      args,
+      value
+    });
+    const receipt = await this.glClient.waitForTransactionReceipt({
+      hash: tx,
+      status: TransactionStatus.ACCEPTED,
+      retries: this.retries
+    });
+    const leader = receipt?.consensus_data?.leader_receipt?.[0];
+    const payload = String(
+      leader?.result?.payload?.readable ?? receipt?.data?.result ?? ""
+    ).replace(/^"|"$/g, "");
+    return { payload, txHash: String(tx) };
+  }
+  async read(address, method, args = []) {
+    return this.glClient.readContract({
+      address,
+      functionName: method,
+      args
+    });
+  }
+  get CORE() {
+    return this.network.addresses.CORE;
+  }
+  get LB() {
+    return this.network.addresses.LB;
+  }
+  get TRN() {
+    return this.network.addresses.TRN;
+  }
+  mapGameState(raw) {
+    return {
+      gameId: raw.game_id ?? "",
+      gameName: raw.game_name ?? "",
+      status: raw.status ?? "waiting",
+      player1: raw.player1 ?? "",
+      player2: raw.player2 ?? "",
+      agent1: raw.agent1 ?? "",
+      agent2: raw.agent2 ?? "",
+      maxRounds: Number(raw.max_rounds ?? 0),
+      roundCount: Number(raw.round_count ?? 0),
+      judgedThrough: Number(raw.judged_through ?? 0),
+      rules: raw.rules ?? "",
+      winner: raw.winner ?? "",
+      score: raw.score ?? {},
+      playerTypes: raw.player_types ?? {},
+      caller: raw.caller ?? "",
+      rounds: (raw.rounds ?? []).map((r) => ({
+        roundNumber: r.round_number,
+        movePlayer1: r.move_player1 ?? "",
+        movePlayer2: r.move_player2 ?? "",
+        result: r.result ?? "pending",
+        reasonType: r.reason_type ?? "normal",
+        invalidPlayer: r.invalid_player ?? "none",
+        reasoning: r.reasoning ?? "",
+        confidence: Number(r.confidence ?? 0),
+        status: r.status ?? "pending"
+      }))
+    };
+  }
+  // ── Game API ────────────────────────────────────────────────────────────────
+  /**
+   * Create a new game. Returns the game ID.
+   */
+  async createGame(options) {
+    const { payload } = await this.write(this.CORE, "start_game", [
+      options.name,
+      options.visibility ?? "public",
+      options.maxRounds ?? 3,
+      options.rules ?? "",
+      options.player1,
+      options.player2 ?? "",
+      options.agent1 ?? 0,
+      options.agent2 ?? 0
+    ]);
+    return payload;
+  }
+  /**
+   * Submit a move for a player. Accepts ANY move format — string, object, array, etc.
+   * The SDK automatically normalizes it to a string the AI judge can understand.
+   */
+  async submitMove(gameId, playerName, move, gameHint) {
+    const normalized = normalizeMove(move, gameHint);
+    const { txHash } = await this.write(this.CORE, "submit_move", [
+      gidToNum(gameId),
+      playerName,
+      normalized.text
+    ]);
+    return { txHash, normalizedMove: normalized.text };
+  }
+  /**
+   * Judge the game — triggers AI consensus on all pending rounds.
+   */
+  async judgeGame(gameId) {
+    const { payload, txHash } = await this.write(
+      this.CORE,
+      "judge_game",
+      [gidToNum(gameId)]
+    );
+    const state = await this.getGameState(gameId);
+    return {
+      winner: state.winner,
+      isDraw: state.status === "draw",
+      score: state.score,
+      rounds: state.rounds,
+      txHash,
+      payload
+    };
+  }
+  /**
+   * End an open-ended game (max_rounds = 0). Only callable by the game creator.
+   */
+  async endGame(gameId) {
+    const { payload, txHash } = await this.write(
+      this.CORE,
+      "end_game",
+      [gidToNum(gameId)]
+    );
+    const state = await this.getGameState(gameId);
+    return {
+      winner: state.winner,
+      isDraw: state.status === "draw",
+      score: state.score,
+      rounds: state.rounds,
+      txHash,
+      payload
+    };
+  }
+  /**
+   * Get the full game state.
+   */
+  async getGameState(gameId) {
+    const raw = await this.read(this.CORE, "get_game_state", [gameId]);
+    return this.mapGameState(raw);
+  }
+  /**
+   * Get all active games.
+   */
+  async getActiveGames() {
+    const raw = await this.read(this.CORE, "get_active_games");
+    return (raw ?? []).map(this.mapGameState);
+  }
+  /**
+   * Get total number of games.
+   */
+  async getTotalGames() {
+    const result = await this.read(this.CORE, "get_total_games");
+    return Number(result ?? 0);
+  }
+  // ── Polling helpers ─────────────────────────────────────────────────────────
+  /**
+   * Wait until both players have submitted their move for a given round.
+   * Polls every `pollInterval` ms.
+   */
+  async waitForBothMoves(gameId, roundNumber) {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      const round = state.rounds.find((r) => r.roundNumber === roundNumber);
+      if (round?.movePlayer1 && round?.movePlayer2) return round;
+      await this.sleep(this.pollInterval);
+    }
+  }
+  /**
+   * Wait until the opponent has submitted their move for a round.
+   * isPlayer1: true if you are player1, false if player2.
+   */
+  async waitForOpponentMove(gameId, roundNumber, isPlayer1) {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      const round = state.rounds.find((r) => r.roundNumber === roundNumber);
+      const opponentMove = isPlayer1 ? round?.movePlayer2 : round?.movePlayer1;
+      if (opponentMove) return opponentMove;
+      await this.sleep(this.pollInterval);
+    }
+  }
+  /**
+   * Wait until the game reaches a specific status.
+   */
+  async waitForStatus(gameId, status) {
+    while (true) {
+      const state = await this.getGameState(gameId);
+      if (state.status === status) return state;
+      if (state.status === "completed" || state.status === "draw") return state;
+      await this.sleep(this.pollInterval);
+    }
+  }
+  /**
+   * Play a full game automatically.
+   * moveFn is called for each round — return your move in any format.
+   */
+  async playGame(gameId, playerName, isPlayer1, moveFn, gameHint) {
+    let state = await this.getGameState(gameId);
+    const maxRounds = state.maxRounds || 999;
+    for (let round = 1; round <= maxRounds; round++) {
+      state = await this.getGameState(gameId);
+      if (state.status !== "active") break;
+      if (!isPlayer1) {
+        await this.waitForOpponentMove(gameId, round, false);
+      }
+      state = await this.getGameState(gameId);
+      const move = await moveFn(state, round);
+      await this.submitMove(gameId, playerName, move, gameHint);
+      if (isPlayer1) {
+        await this.waitForOpponentMove(gameId, round, true);
+      }
+      state = await this.getGameState(gameId);
+      if (state.roundCount >= maxRounds) break;
+    }
+    return this.judgeGame(gameId);
+  }
+  // ── Leaderboard API ─────────────────────────────────────────────────────────
+  async getLeaderboard(gameName, playerType = "all") {
+    const raw = await this.read(this.LB, "get_leaderboard", [gameName, playerType]);
+    return (raw ?? []).map((e) => ({
+      player: e.player ?? "",
+      wins: Number(e.wins ?? 0),
+      losses: Number(e.losses ?? 0),
+      draws: Number(e.draws ?? 0),
+      score: Number(e.score ?? 0),
+      playerType: e.player_type ?? "human"
+    }));
+  }
+  async getTopPlayers(gameName, n = 10) {
+    const raw = await this.read(this.LB, "get_top_players", [gameName, n]);
+    return (raw ?? []).map((e) => ({
+      player: e.player ?? "",
+      wins: Number(e.wins ?? 0),
+      losses: Number(e.losses ?? 0),
+      draws: Number(e.draws ?? 0),
+      score: Number(e.score ?? 0),
+      playerType: e.player_type ?? "human"
+    }));
+  }
+  async getPlayerStats(gameName, playerName, playerType = "all") {
+    try {
+      const raw = await this.read(this.LB, "get_player_stats", [gameName, playerName, playerType]);
+      if (!raw) return null;
+      return {
+        player: raw.player ?? playerName,
+        wins: Number(raw.wins ?? 0),
+        losses: Number(raw.losses ?? 0),
+        draws: Number(raw.draws ?? 0),
+        score: Number(raw.score ?? 0),
+        games: Number(raw.games ?? 0),
+        playerType: raw.player_type ?? playerType
+      };
+    } catch {
+      return null;
+    }
+  }
+  // ── Tournament API ──────────────────────────────────────────────────────────
+  async createTournament(options) {
+    const { payload } = await this.write(this.TRN, "create_tournament", [
+      options.name,
+      options.gameName,
+      options.format,
+      options.maxPlayers,
+      0,
+      // entry fee — always free
+      options.prizeSplit ?? [70, 30],
+      options.rules ?? "",
+      options.roundsPerMatch ?? 1
+    ]);
+    return payload;
+  }
+  async joinTournament(tid, playerName, playerType = "human") {
+    await this.write(this.TRN, "join_tournament", [tid, playerName, playerType]);
+  }
+  async startTournament(tid) {
+    await this.write(this.TRN, "start_tournament", [tid]);
+  }
+  async getTournament(tid) {
+    try {
+      const raw = await this.read(this.TRN, "get_tournament", [tid]);
+      if (!raw) return null;
+      return {
+        tid: raw.tid ?? tid,
+        name: raw.name ?? "",
+        gameName: raw.game_name ?? "",
+        format: raw.format ?? "",
+        maxPlayers: Number(raw.max_players ?? 0),
+        status: raw.status ?? "",
+        players: raw.players ?? [],
+        bracket: (raw.bracket ?? []).map((m) => ({
+          matchId: m.match_id,
+          round: m.round,
+          player1: m.player1,
+          player2: m.player2,
+          gameId: m.game_id,
+          winner: m.winner,
+          status: m.status
+        })),
+        winner: raw.winner ?? ""
+      };
+    } catch {
+      return null;
+    }
+  }
+  async listTournaments() {
+    const raw = await this.read(this.TRN, "list_tournaments");
+    return (raw ?? []).map((t) => ({
+      tid: t.tid ?? "",
+      name: t.name ?? "",
+      gameName: t.game_name ?? "",
+      format: t.format ?? "",
+      maxPlayers: Number(t.max_players ?? 0),
+      status: t.status ?? "",
+      players: t.players ?? [],
+      bracket: [],
+      winner: t.winner ?? ""
+    }));
+  }
+  async recordMatchResult(tid, matchId, winner) {
+    await this.write(this.TRN, "record_match_result", [tid, matchId, winner]);
+  }
+  // ── Utils ───────────────────────────────────────────────────────────────────
+  /** Normalize any move to a string without submitting */
+  normalizeMove(move, gameHint) {
+    return normalizeMove(move, gameHint);
+  }
+  /** Sleep helper */
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+};
+
+// src/index.ts
+function createTheRef(config) {
+  return new TheRefClient(config);
+}
+export {
+  NETWORKS,
+  TheRefClient,
+  createTheRef,
+  gidToNum,
+  normalizeMove,
+  resolveNetwork
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "theref-sdk",
+  "version": "0.1.0",
+  "description": "Universal SDK for TheRef — the decentralized AI game referee on GenLayer",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "jest"
+  },
+  "keywords": ["genlayer", "theref", "ai", "gaming", "blockchain", "sdk", "agent"],
+  "author": "0xZaid10",
+  "license": "MIT",
+  "dependencies": {
+    "genlayer-js": "latest",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "@types/ws": "^8.5.0",
+    "@types/node": "^20.0.0"
+  },
+  "peerDependencies": {
+    "genlayer-js": "latest"
+  }
+}