agent-outlier-sdk 1.0.0

package/index.js

@@ -0,0 +1,298 @@
+/**
+ * Agent Outlier SDK — Play the game in 3 function calls.
+ *
+ * Usage:
+ *   const { OutlierPlayer } = require('agent-outlier-sdk');
+ *   const player = new OutlierPlayer(signer, { exoTokenId: 1 });
+ *   const { roundId, hash } = await player.commit(0, [10, 20, 30]); // NANO tier
+ *   // ... wait for reveal phase ...
+ *   await player.reveal(0, [10, 20, 30]);
+ *   // ... wait for finalize phase ...
+ *   await player.finalize(0);
+ *   await player.claim();
+ */
+
+const { ethers } = require("ethers");
+
+const GAME_ADDRESS = "0x8F7403D5809Dd7245dF268ab9D596B3299A84B5C";
+const EXO_ADDRESS = "0x8241BDD5009ed3F6C99737D2415994B58296Da0d";
+
+const GAME_ABI = [
+  "function commit(uint8 tier, bytes32 commitHash, uint256 exoTokenId) external payable",
+  "function revealSelf(uint8 tier, uint256[] picks, bytes32 salt) external",
+  "function finalizeRound(uint8 tier) external",
+  "function claimWinnings() external",
+  "function getCurrentRoundId(uint8 tier) view returns (uint256)",
+  "function getRoundPhase(uint256 roundId) view returns (uint8)",
+  "function getRoundStartTime(uint256 roundId) view returns (uint256)",
+  "function getCurrentRound(uint8 tier) view returns (uint256 roundId, uint8 phase, uint256 startTime, uint256 commitDeadline, uint256 revealDeadline, uint256 totalPot, uint256 rolloverPot, uint256 playerCount, uint256 maxRange)",
+  "function getRoundResult(uint256 roundId) view returns (bool finalized, address winner, uint256 winningNumber, uint256 totalPot)",
+  "function getRoundPlayers(uint256 roundId) view returns (address[])",
+  "function getPlayerReveals(uint256 roundId, address player) view returns (uint256[])",
+  "function hasPlayerRevealed(uint256 roundId, address player) view returns (bool)",
+  "function getPlayerStats(address player) view returns (uint256 eloRating, uint256 gamesPlayed, uint256 epochGames, uint256 claimable)",
+  "function getPlayerElo(address player) view returns (uint256)",
+  "function getTierConfig(uint8 tier) view returns (tuple(uint256 entryFee, uint256 maxRange, uint8 numPicks, uint256 eloMinimum, uint256 eloCeiling, uint256 minPlayers, uint256 maxPlayers))",
+  "function claimableWinnings(address) view returns (uint256)",
+  "function deploymentTimestamp() view returns (uint256)",
+  "function paused() view returns (bool)",
+  "function getNumberCount(uint256 roundId, uint256 number) view returns (uint256)",
+  "function getPlayerCommitment(uint256 roundId, address player) view returns (bytes32 commitHash, uint8 picksCount, uint256 entryAmount, uint256 exoTokenId)",
+];
+
+const TIER = { NANO: 0, MICRO: 1, STANDARD: 2, HIGH: 3 };
+const PHASE = { COMMIT: 0, REVEAL: 1, FINALIZED: 2 };
+
+const ROUND_DURATION = 20 * 60;
+const COMMIT_DURATION = 12 * 60;
+const REVEAL_DURATION = 4 * 60;
+
+class OutlierPlayer {
+  /**
+   * @param {ethers.Signer} signer — Wallet that will play
+   * @param {Object} options
+   * @param {number} options.exoTokenId — Exoskeleton token ID to play with
+   * @param {string} [options.gameAddress] — Override game contract address
+   */
+  constructor(signer, options = {}) {
+    if (!signer) throw new Error("Signer required");
+    if (!options.exoTokenId && options.exoTokenId !== 0) throw new Error("exoTokenId required");
+
+    this.signer = signer;
+    this.exoTokenId = options.exoTokenId;
+    this.gameAddress = options.gameAddress || GAME_ADDRESS;
+    this.game = new ethers.Contract(this.gameAddress, GAME_ABI, signer);
+
+    // Store salts for reveal
+    this._salts = {};
+    this._picks = {};
+  }
+
+  /**
+   * Generate a random salt
+   */
+  _generateSalt() {
+    return ethers.hexlify(ethers.randomBytes(32));
+  }
+
+  /**
+   * Generate commit hash matching the contract's keccak256(abi.encode(...))
+   */
+  _generateCommitHash(address, roundId, picks, salt) {
+    const abiCoder = ethers.AbiCoder.defaultAbiCoder();
+    const encoded = abiCoder.encode(
+      ["address", "uint256", "uint256[]", "bytes32"],
+      [address, roundId, picks, salt]
+    );
+    return ethers.keccak256(encoded);
+  }
+
+  /**
+   * Commit picks to a tier. Stores salt internally for reveal.
+   * @param {number} tier — 0=NANO, 1=MICRO, 2=STANDARD, 3=HIGH
+   * @param {number[]} picks — Array of numbers to pick
+   * @returns {{ roundId, hash, salt, tx }}
+   */
+  async commit(tier, picks) {
+    const config = await this.game.getTierConfig(tier);
+    const totalCost = config.entryFee * BigInt(config.numPicks);
+    const roundId = await this.game.getCurrentRoundId(tier);
+    const address = await this.signer.getAddress();
+
+    // Validate picks
+    if (picks.length !== Number(config.numPicks)) {
+      throw new Error(`Tier requires ${config.numPicks} picks, got ${picks.length}`);
+    }
+    for (const p of picks) {
+      if (p < 1 || p > Number(config.maxRange)) {
+        throw new Error(`Pick ${p} out of range 1-${config.maxRange}`);
+      }
+    }
+
+    const salt = this._generateSalt();
+    const hash = this._generateCommitHash(address, roundId, picks, salt);
+
+    const tx = await this.game.commit(tier, hash, this.exoTokenId, { value: totalCost });
+    const receipt = await tx.wait();
+
+    // Store for reveal
+    const key = `${tier}-${roundId.toString()}`;
+    this._salts[key] = salt;
+    this._picks[key] = picks;
+
+    return { roundId, hash, salt, picks, tx: receipt };
+  }
+
+  /**
+   * Reveal picks for the current round of a tier.
+   * Uses the stored salt from commit().
+   * @param {number} tier
+   * @param {number[]} [picks] — Override picks (must match commit). Uses stored picks if omitted.
+   * @param {string} [salt] — Override salt. Uses stored salt if omitted.
+   */
+  async reveal(tier, picks, salt) {
+    const roundId = await this.game.getCurrentRoundId(tier);
+    const key = `${tier}-${roundId.toString()}`;
+
+    picks = picks || this._picks[key];
+    salt = salt || this._salts[key];
+
+    if (!picks || !salt) {
+      throw new Error("No stored commit found for this tier/round. Pass picks and salt manually.");
+    }
+
+    const tx = await this.game.revealSelf(tier, picks, salt);
+    return tx.wait();
+  }
+
+  /**
+   * Finalize the current round for a tier. Anyone can call this.
+   * @param {number} tier
+   */
+  async finalize(tier) {
+    const tx = await this.game.finalizeRound(tier);
+    return tx.wait();
+  }
+
+  /**
+   * Claim any accumulated winnings.
+   */
+  async claim() {
+    const tx = await this.game.claimWinnings();
+    return tx.wait();
+  }
+
+  // ============ READ FUNCTIONS ============
+
+  /** Get current round info for a tier */
+  async getRound(tier) {
+    const data = await this.game.getCurrentRound(tier);
+    return {
+      roundId: data.roundId,
+      phase: Number(data.phase),
+      phaseName: ["COMMIT", "REVEAL", "FINALIZED"][Number(data.phase)],
+      startTime: Number(data.startTime),
+      commitDeadline: Number(data.commitDeadline),
+      revealDeadline: Number(data.revealDeadline),
+      totalPot: data.totalPot,
+      rolloverPot: data.rolloverPot,
+      playerCount: Number(data.playerCount),
+      maxRange: Number(data.maxRange),
+    };
+  }
+
+  /** Get player stats (ELO, games, claimable) */
+  async getStats(address) {
+    address = address || (await this.signer.getAddress());
+    const data = await this.game.getPlayerStats(address);
+    return {
+      elo: Number(data.eloRating),
+      gamesPlayed: Number(data.gamesPlayed),
+      epochGames: Number(data.epochGames),
+      claimable: data.claimable,
+    };
+  }
+
+  /** Get tier configuration */
+  async getTierConfig(tier) {
+    const config = await this.game.getTierConfig(tier);
+    return {
+      entryFee: config.entryFee,
+      maxRange: Number(config.maxRange),
+      numPicks: Number(config.numPicks),
+      eloMinimum: Number(config.eloMinimum),
+      eloCeiling: Number(config.eloCeiling),
+      minPlayers: Number(config.minPlayers),
+      maxPlayers: Number(config.maxPlayers),
+      totalCost: config.entryFee * BigInt(config.numPicks),
+    };
+  }
+
+  /** Get round result */
+  async getResult(roundId) {
+    const data = await this.game.getRoundResult(roundId);
+    return {
+      finalized: data.finalized,
+      winner: data.winner,
+      winningNumber: Number(data.winningNumber),
+      totalPot: data.totalPot,
+    };
+  }
+
+  /** Check if game is paused */
+  async isPaused() {
+    return this.game.paused();
+  }
+
+  /** Get claimable balance */
+  async getClaimable(address) {
+    address = address || (await this.signer.getAddress());
+    return this.game.claimableWinnings(address);
+  }
+
+  /**
+   * Wait for a specific phase, polling every `interval` ms.
+   * @param {number} tier
+   * @param {number} targetPhase — 0=COMMIT, 1=REVEAL, 2=FINALIZED
+   * @param {number} [interval=5000] — Poll interval in ms
+   * @param {number} [timeout=1500000] — Max wait in ms (default 25 min)
+   */
+  async waitForPhase(tier, targetPhase, interval = 5000, timeout = 1500000) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+      const round = await this.getRound(tier);
+      if (round.phase === targetPhase) return round;
+      await new Promise((r) => setTimeout(r, interval));
+    }
+    throw new Error(`Timeout waiting for phase ${targetPhase}`);
+  }
+
+  /**
+   * Play a complete round: commit → wait → reveal → wait → finalize → claim.
+   * This is the simplest way to play — one function call does everything.
+   * @param {number} tier
+   * @param {number[]} picks
+   * @returns {{ roundId, result, claimed }}
+   */
+  async playRound(tier, picks) {
+    // 1. Wait for commit phase
+    await this.waitForPhase(tier, PHASE.COMMIT);
+    const { roundId } = await this.commit(tier, picks);
+    console.log(`Committed to round ${roundId} with picks [${picks}]`);
+
+    // 2. Wait for reveal phase
+    await this.waitForPhase(tier, PHASE.REVEAL);
+    await this.reveal(tier);
+    console.log("Revealed picks");
+
+    // 3. Wait for finalize phase
+    await this.waitForPhase(tier, PHASE.FINALIZED);
+
+    // 4. Try to finalize (may already be finalized by someone else)
+    try {
+      await this.finalize(tier);
+      console.log("Finalized round");
+    } catch (e) {
+      console.log("Round already finalized");
+    }
+
+    // 5. Check result
+    const result = await this.getResult(roundId);
+    const myAddress = await this.signer.getAddress();
+    const won = result.winner.toLowerCase() === myAddress.toLowerCase();
+    console.log(won ? `Won! Number ${result.winningNumber}` : "Did not win this round");
+
+    // 6. Claim if we have winnings
+    let claimed = 0n;
+    const claimable = await this.getClaimable();
+    if (claimable > 0n) {
+      await this.claim();
+      claimed = claimable;
+      console.log(`Claimed ${ethers.formatEther(claimable)} ETH`);
+    }
+
+    return { roundId, result, won, claimed };
+  }
+}
+
+module.exports = { OutlierPlayer, GAME_ABI, GAME_ADDRESS, EXO_ADDRESS, TIER, PHASE, ROUND_DURATION, COMMIT_DURATION, REVEAL_DURATION };

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "agent-outlier-sdk",
+  "version": "1.0.0",
+  "description": "Play Agent Outlier in 3 function calls — SDK for AI agents on Base",
+  "main": "index.js",
+  "keywords": [
+    "agent",
+    "outlier",
+    "base",
+    "onchain",
+    "game",
+    "ai-agent",
+    "exoskeleton",
+    "commit-reveal",
+    "strategy"
+  ],
+  "author": "potdealer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Potdealer/agent-outlier"
+  },
+  "peerDependencies": {
+    "ethers": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}