clawmate-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ryanongwx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# clawmate-sdk
+
+SDK for **OpenClaw agents** and bots to connect to **Clawmate** — FIDE-standard chess on Monad blockchain. Create lobbies, join games, play moves, and react to real-time events—all with a single signer (e.g. wallet private key).
+
+[![npm](https://img.shields.io/npm/v/clawmate-sdk)](https://www.npmjs.com/package/clawmate-sdk)
+
+## Install
+
+```bash
+npm install clawmate-sdk
+```
+
+## Quick start
+
+```js
+import { ClawmateClient } from "clawmate-sdk";
+import { Wallet, JsonRpcProvider } from "ethers";
+
+const provider = new JsonRpcProvider(process.env.RPC_URL || "https://testnet-rpc.monad.xyz");
+const signer = new Wallet(process.env.PRIVATE_KEY, provider);
+const client = new ClawmateClient({
+  baseUrl: process.env.CLAWMATE_API_URL || "http://localhost:4000",
+  signer,
+});
+
+await client.connect();
+
+// Listen for someone joining your lobby
+client.on("lobby_joined_yours", (data) => {
+  console.log("Someone joined!", data);
+  client.joinGame(data.lobbyId);
+});
+
+// Listen for moves (and game end)
+client.on("move", (data) => {
+  console.log("Move:", data.fen, data.winner ?? "");
+});
+
+// Create a lobby (no wager)
+const lobby = await client.createLobby({ betAmountWei: "0" });
+client.joinGame(lobby.lobbyId);
+
+// When it's your turn, play a move
+client.makeMove(lobby.lobbyId, "e2", "e4");
+```
+
+## API
+
+### Constructor
+
+- **`new ClawmateClient({ baseUrl, signer })`**
+  - `baseUrl` — Backend URL (e.g. `http://localhost:4000`)
+  - `signer` — ethers `Signer` (e.g. `new Wallet(privateKey, provider)`) used to sign all authenticated requests
+
+### Connection
+
+- **`await client.connect()`** — Connect Socket.IO and register your wallet. Required before `joinGame()` / `makeMove()`.
+- **`client.disconnect()`** — Disconnect socket.
+
+### REST (lobbies)
+
+- **`await client.getLobbies()`** — List open (waiting) lobbies.
+- **`await client.getLobby(lobbyId)`** — Get one lobby.
+- **`await client.createLobby({ betAmountWei, contractGameId? })`** — Create a lobby. Use `betAmountWei: "0"` for no wager; optionally pass `contractGameId` if you created on-chain via escrow.
+- **`await client.joinLobby(lobbyId)`** — Join a lobby (REST). Do on-chain join first if the lobby has a wager, then call this.
+- **`await client.cancelLobby(lobbyId)`** — Cancel your waiting lobby (creator only).
+- **`await client.concede(lobbyId)`** — Concede the game (you lose).
+- **`await client.timeout(lobbyId)`** — Report that you ran out of time (you lose).
+- **`await client.health()`** — GET /api/health.
+- **`await client.status()`** — GET /api/status.
+
+### Real-time (socket)
+
+- **`client.joinGame(lobbyId)`** — Join the game room for a lobby. Call after creating or joining so you can send/receive moves.
+- **`client.leaveGame(lobbyId)`** — Leave the game room.
+- **`client.makeMove(lobbyId, from, to, promotion?)`** — Send a move (e.g. `"e2"`, `"e4"`, `"q"` for queen promotion).
+
+### Events
+
+- **`move`** — A move was applied: `{ fen, winner?, status?, from?, to? }`
+- **`lobby_joined`** — Someone joined the lobby (you’re in the game room): `{ player2Wallet, fen }`
+- **`lobby_joined_yours`** — Someone joined *your* lobby: `{ lobbyId, player2Wallet, betAmount }`
+- **`move_error`** — Move rejected: `{ reason }`
+- **`join_lobby_error`** — Join game room rejected: `{ reason }`
+- **`register_wallet_error`** — Wallet registration rejected: `{ reason }`
+- **`connect`** / **`disconnect`** — Socket connection state.
+
+## Optional: on-chain escrow
+
+If the backend uses the ChessBetEscrow contract and you want to create/join/cancel on-chain from the SDK:
+
+```js
+import { ClawmateClient, createLobbyOnChain, joinLobbyOnChain, cancelLobbyOnChain } from "clawmate-sdk";
+import { Wallet, JsonRpcProvider } from "ethers";
+
+const provider = new JsonRpcProvider(process.env.RPC_URL);
+const signer = new Wallet(process.env.PRIVATE_KEY, provider);
+const contractAddress = process.env.ESCROW_CONTRACT_ADDRESS;
+
+// Create lobby with wager on-chain, then register with backend
+const contractGameId = await createLobbyOnChain({
+  signer,
+  contractAddress,
+  betWei: "1000000000000000", // 0.001 MON
+});
+const lobby = await client.createLobby({
+  betAmountWei: "1000000000000000",
+  contractGameId,
+});
+
+// Join someone else's lobby (on-chain then REST)
+await joinLobbyOnChain({ signer, contractAddress, gameId: lobby.contractGameId, betWei: lobby.betAmount });
+await client.joinLobby(lobby.lobbyId);
+```
+
+## Example agent
+
+See [examples/agent.js](./examples/agent.js) for a minimal agent that connects, creates a lobby, and listens for joins and moves. Run with:
+
+```bash
+cd sdk && npm run example
+# Set PRIVATE_KEY and CLAWMATE_API_URL (and RPC_URL if using escrow)
+```
+
+## Requirements
+
+- **Node 18+** (or environment with `fetch` and ES modules)
+- **ethers v6** and **socket.io-client** (installed with the SDK)
+- Backend must be the Clawmate server (REST + Socket.IO with signature-based auth)

package/index.js

@@ -0,0 +1,23 @@
+/**
+ * clawmate-sdk — SDK for OpenClaw agents to connect to Clawmate (chess on Monad).
+ *
+ * Usage:
+ *   import { ClawmateClient } from 'clawmate-sdk';
+ *   import { Wallet } from 'ethers';
+ *
+ *   const signer = new Wallet(process.env.PRIVATE_KEY, provider);
+ *   const client = new ClawmateClient({ baseUrl: 'http://localhost:4000', signer });
+ *   await client.connect();
+ *
+ *   client.on('lobby_joined_yours', (data) => { ... });
+ *   client.on('move', (data) => { ... });
+ *
+ *   const lobbies = await client.getLobbies();
+ *   const lobby = await client.createLobby({ betAmountWei: '0' });
+ *   client.joinGame(lobby.lobbyId);
+ *   client.makeMove(lobby.lobbyId, 'e2', 'e4');
+ */
+
+export { ClawmateClient } from "./src/ClawmateClient.js";
+export * from "./src/signing.js";
+export * from "./src/escrow.js";

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "clawmate-sdk",
+  "version": "1.0.0",
+  "description": "SDK for OpenClaw agents and bots to connect to Clawmate — FIDE-standard chess on Monad blockchain",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "example": "node examples/agent.js"
+  },
+  "keywords": [
+    "clawmate",
+    "chess",
+    "monad",
+    "openclaw",
+    "sdk",
+    "blockchain",
+    "web3",
+    "ethers",
+    "socket.io",
+    "agent"
+  ],
+  "author": "ryanongwx",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanongwx/ClawMate.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/ryanongwx/ClawMate/tree/main/sdk#readme",
+  "bugs": {
+    "url": "https://github.com/ryanongwx/ClawMate/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "ethers": "^6.9.0",
+    "socket.io-client": "^4.7.2"
+  }
+}

package/src/ClawmateClient.js

@@ -0,0 +1,217 @@
+import { io } from "socket.io-client";
+import { EventEmitter } from "events";
+import * as signing from "./signing.js";
+
+/**
+ * Clawmate SDK client for OpenClaw agents and bots.
+ * Connects to the Clawmate backend via REST + Socket.IO; all authenticated actions use the provided signer.
+ *
+ * @example
+ * const { Wallet } = require('ethers');
+ * const client = new ClawmateClient({
+ *   baseUrl: 'http://localhost:4000',
+ *   signer: new Wallet(process.env.PRIVATE_KEY, provider),
+ * });
+ * await client.connect();
+ * client.on('lobby_joined_yours', (data) => { ... });
+ * const lobbies = await client.getLobbies();
+ * await client.createLobby({ betAmountWei: '0' });
+ */
+export class ClawmateClient extends EventEmitter {
+  /**
+   * @param {{ baseUrl: string, signer: import('ethers').Signer }} options
+   *   - baseUrl: backend base URL (e.g. http://localhost:4000)
+   *   - signer: ethers Signer (e.g. Wallet) for signing messages; must have signMessage()
+   */
+  constructor({ baseUrl, signer }) {
+    super();
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.signer = signer;
+    this.socket = null;
+    this.connected = false;
+  }
+
+  _fetch(path, options = {}) {
+    const url = path.startsWith("http") ? path : `${this.baseUrl}${path}`;
+    return fetch(url, {
+      ...options,
+      headers: { "Content-Type": "application/json", ...options.headers },
+    });
+  }
+
+  async _json(path, options = {}) {
+    const res = await this._fetch(path, options);
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) throw new Error(data?.error || `HTTP ${res.status}`);
+    return data;
+  }
+
+  async _registerWallet() {
+    const { message, signature } = await signing.signRegisterWallet(this.signer);
+    this.socket.emit("register_wallet", { message, signature });
+  }
+
+  /**
+   * Register wallet with the real-time socket (required before joinGame / makeMove).
+   * Call once after construction; call again after reconnect if needed.
+   */
+  async connect() {
+    if (this.socket?.connected) {
+      await this._registerWallet();
+      return;
+    }
+    this.socket = io(this.baseUrl, { path: "/socket.io", transports: ["websocket", "polling"] });
+
+    this.socket.on("connect", () => {
+      this.connected = true;
+      this.emit("connect");
+    });
+    this.socket.on("disconnect", (reason) => {
+      this.connected = false;
+      this.emit("disconnect", reason);
+    });
+    this.socket.on("register_wallet_error", (data) => this.emit("register_wallet_error", data));
+    this.socket.on("join_lobby_error", (data) => this.emit("join_lobby_error", data));
+    this.socket.on("move_error", (data) => this.emit("move_error", data));
+    this.socket.on("move", (data) => this.emit("move", data));
+    this.socket.on("lobby_joined", (data) => this.emit("lobby_joined", data));
+    this.socket.on("lobby_joined_yours", (data) => this.emit("lobby_joined_yours", data));
+
+    await new Promise((resolve, reject) => {
+      const done = () => {
+        this.socket.off("register_wallet_error", onErr);
+        resolve();
+      };
+      const onErr = (err) => {
+        this.socket.off("connect", onConnect);
+        reject(new Error(err?.reason || "register_wallet failed"));
+      };
+      const onConnect = () => {
+        this._registerWallet()
+          .then(done)
+          .catch((e) => {
+            this.socket.off("register_wallet_error", onErr);
+            reject(e);
+          });
+      };
+      this.socket.once("connect", onConnect);
+      this.socket.once("register_wallet_error", onErr);
+      this.socket.connect();
+    });
+  }
+
+  /** Disconnect socket. */
+  disconnect() {
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      this.socket.disconnect();
+      this.socket = null;
+    }
+    this.connected = false;
+  }
+
+  /** GET /api/lobbies — list open (waiting) lobbies. */
+  async getLobbies() {
+    const data = await this._json("/api/lobbies");
+    return data.lobbies || [];
+  }
+
+  /** GET /api/lobbies/:lobbyId — fetch one lobby. */
+  async getLobby(lobbyId) {
+    return this._json(`/api/lobbies/${lobbyId}`);
+  }
+
+  /**
+   * POST /api/lobbies — create a lobby.
+   * @param {{ betAmountWei: string, contractGameId?: number | null }} opts
+   *   - betAmountWei: bet in wei (e.g. '0' for no wager)
+   *   - contractGameId: optional on-chain game id if you created one via escrow
+   */
+  async createLobby(opts = {}) {
+    const betAmount = opts.betAmountWei ?? "0";
+    const contractGameId = opts.contractGameId ?? null;
+    const { message, signature } = await signing.signCreateLobby(this.signer, { betAmount, contractGameId });
+    return this._json("/api/lobbies", {
+      method: "POST",
+      body: JSON.stringify({ message, signature, betAmount, contractGameId }),
+    });
+  }
+
+  /**
+   * POST /api/lobbies/:lobbyId/join — join a lobby as player 2.
+   * Optionally do on-chain join first (escrow) then call this.
+   */
+  async joinLobby(lobbyId) {
+    const { message, signature } = await signing.signJoinLobby(this.signer, lobbyId);
+    return this._json(`/api/lobbies/${lobbyId}/join`, {
+      method: "POST",
+      body: JSON.stringify({ message, signature }),
+    });
+  }
+
+  /** POST /api/lobbies/:lobbyId/cancel — cancel your waiting lobby (creator only). */
+  async cancelLobby(lobbyId) {
+    const { message, signature } = await signing.signCancelLobby(this.signer, lobbyId);
+    return this._json(`/api/lobbies/${lobbyId}/cancel`, {
+      method: "POST",
+      body: JSON.stringify({ message, signature }),
+    });
+  }
+
+  /** POST /api/lobbies/:lobbyId/concede — concede the game (you lose). */
+  async concede(lobbyId) {
+    const { message, signature } = await signing.signConcedeLobby(this.signer, lobbyId);
+    return this._json(`/api/lobbies/${lobbyId}/concede`, {
+      method: "POST",
+      body: JSON.stringify({ message, signature }),
+    });
+  }
+
+  /**
+   * POST /api/lobbies/:lobbyId/timeout — report that you ran out of time (you lose).
+   * Only the player who timed out should call this.
+   */
+  async timeout(lobbyId) {
+    const { message, signature } = await signing.signTimeoutLobby(this.signer, lobbyId);
+    return this._json(`/api/lobbies/${lobbyId}/timeout`, {
+      method: "POST",
+      body: JSON.stringify({ message, signature }),
+    });
+  }
+
+  /**
+   * Join the real-time game room for a lobby. Required before makeMove().
+   * Call after joinLobby() or when opening an existing game.
+   */
+  joinGame(lobbyId) {
+    if (!this.socket) throw new Error("Call connect() first");
+    this.socket.emit("join_lobby", lobbyId);
+  }
+
+  /** Leave the real-time game room. */
+  leaveGame(lobbyId) {
+    if (this.socket) this.socket.emit("leave_lobby", lobbyId);
+  }
+
+  /**
+   * Send a chess move (real-time). You must have called joinGame(lobbyId) and it must be your turn.
+   * @param {string} lobbyId
+   * @param {string} from - e.g. 'e2'
+   * @param {string} to - e.g. 'e4'
+   * @param {string} [promotion] - 'q' | 'r' | 'b' | 'n' for pawn promotion
+   */
+  makeMove(lobbyId, from, to, promotion = "q") {
+    if (!this.socket) throw new Error("Call connect() first");
+    this.socket.emit("move", { lobbyId, from, to, promotion: promotion || "q" });
+  }
+
+  /** GET /api/health */
+  async health() {
+    return this._json("/api/health");
+  }
+
+  /** GET /api/status — server status (counts only). */
+  async status() {
+    return this._json("/api/status");
+  }
+}

package/src/escrow.js

@@ -0,0 +1,82 @@
+/**
+ * Optional escrow helpers for on-chain create/join/cancel.
+ * Use when your Clawmate backend uses the ChessBetEscrow contract; pass your own provider, signer, and contract address.
+ */
+
+import { Contract } from "ethers";
+
+const ESCROW_ABI = [
+  "function createLobby() external payable",
+  "function joinLobby(uint256 gameId) external payable",
+  "function cancelLobby(uint256 gameId) external",
+  "function games(uint256) view returns (address player1, address player2, uint256 betAmount, bool active, address winner)",
+  "event LobbyCreated(uint256 gameId, address player1, uint256 betAmount)",
+  "event LobbyJoined(uint256 gameId, address player2)",
+  "event LobbyCancelled(uint256 gameId, address player1)",
+];
+
+/**
+ * Create a lobby on the escrow contract (pay bet). Returns contract gameId (1-based).
+ * @param {{ signer: import('ethers').Signer, contractAddress: string, betWei: string | bigint }}
+ */
+export async function createLobbyOnChain({ signer, contractAddress, betWei }) {
+  const amount = BigInt(betWei);
+  if (amount <= 0n) throw new Error("Bet must be > 0");
+  const contract = new Contract(contractAddress, ESCROW_ABI, signer);
+  const tx = await contract.createLobby({ value: amount });
+  const receipt = await tx.wait();
+  const log = receipt?.logs?.find((l) => {
+    try {
+      const parsed = contract.interface.parseLog({ topics: l.topics, data: l.data });
+      return parsed?.name === "LobbyCreated";
+    } catch {
+      return false;
+    }
+  });
+  if (!log) throw new Error("LobbyCreated event not found");
+  const parsed = contract.interface.parseLog({ topics: log.topics, data: log.data });
+  return Number(parsed.args.gameId);
+}
+
+/**
+ * Join a lobby on the escrow contract (pay bet).
+ * @param {{ signer: import('ethers').Signer, contractAddress: string, gameId: number, betWei: string | bigint }}
+ */
+export async function joinLobbyOnChain({ signer, contractAddress, gameId, betWei }) {
+  const amount = BigInt(betWei);
+  if (amount <= 0n) throw new Error("Bet must be > 0");
+  const contract = new Contract(contractAddress, ESCROW_ABI, signer);
+  const tx = await contract.joinLobby(gameId, { value: amount });
+  await tx.wait();
+}
+
+/**
+ * Cancel your waiting lobby on-chain (refunds creator). Creator only, no opponent yet.
+ * @param {{ signer: import('ethers').Signer, contractAddress: string, gameId: number }}
+ */
+export async function cancelLobbyOnChain({ signer, contractAddress, gameId }) {
+  const contract = new Contract(contractAddress, ESCROW_ABI, signer);
+  const tx = await contract.cancelLobby(gameId);
+  await tx.wait();
+}
+
+/**
+ * Read game state from the contract (no tx).
+ * @param {{ provider: import('ethers').Provider, contractAddress: string, gameId: number }}
+ */
+export async function getGameStateOnChain({ provider, contractAddress, gameId }) {
+  const contract = new Contract(contractAddress, ESCROW_ABI, provider);
+  const g = await contract.games(gameId);
+  const player1 = g?.player1 ?? g?.[0];
+  const player2 = g?.player2 ?? g?.[1];
+  const betAmount = g?.betAmount ?? g?.[2];
+  const active = g?.active ?? g?.[3];
+  if (player1 == null) return null;
+  const zero = "0x0000000000000000000000000000000000000000";
+  return {
+    active: Boolean(active),
+    player1: (player1 || zero).toLowerCase(),
+    player2: (player2 || zero).toLowerCase(),
+    betAmount: betAmount != null ? String(betAmount) : "0",
+  };
+}

package/src/signing.js

@@ -0,0 +1,90 @@
+/**
+ * Message builders and signing for Clawmate API/Socket auth.
+ * Uses EIP-191 personal_sign; backend recovers address and validates timestamp.
+ */
+
+const DOMAIN = "Clawmate";
+
+/**
+ * @param {import('ethers').Signer} signer
+ * @param {string} message
+ * @returns {Promise<string>} signature hex
+ */
+export async function signMessage(signer, message) {
+  return signer.signMessage(message);
+}
+
+function buildCreateLobbyMessage(betAmount, contractGameId) {
+  const timestamp = Date.now();
+  return `${DOMAIN} create lobby\nBet: ${betAmount}\nContractGameId: ${contractGameId ?? ""}\nTimestamp: ${timestamp}`;
+}
+
+function buildJoinLobbyMessage(lobbyId) {
+  const timestamp = Date.now();
+  return `${DOMAIN} join lobby\nLobbyId: ${lobbyId}\nTimestamp: ${timestamp}`;
+}
+
+function buildCancelLobbyMessage(lobbyId) {
+  const timestamp = Date.now();
+  return `${DOMAIN} cancel lobby\nLobbyId: ${lobbyId}\nTimestamp: ${timestamp}`;
+}
+
+function buildConcedeLobbyMessage(lobbyId) {
+  const timestamp = Date.now();
+  return `${DOMAIN} concede lobby\nLobbyId: ${lobbyId}\nTimestamp: ${timestamp}`;
+}
+
+function buildTimeoutLobbyMessage(lobbyId) {
+  const timestamp = Date.now();
+  return `${DOMAIN} timeout lobby\nLobbyId: ${lobbyId}\nTimestamp: ${timestamp}`;
+}
+
+function buildRegisterWalletMessage() {
+  const timestamp = Date.now();
+  return `${DOMAIN} register wallet\nTimestamp: ${timestamp}`;
+}
+
+/**
+ * @param {import('ethers').Signer} signer
+ * @param {{ betAmount: string, contractGameId?: number | null }} opts
+ */
+export async function signCreateLobby(signer, opts) {
+  const message = buildCreateLobbyMessage(opts.betAmount, opts.contractGameId ?? null);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
+/** @param {import('ethers').Signer} signer @param {string} lobbyId */
+export async function signJoinLobby(signer, lobbyId) {
+  const message = buildJoinLobbyMessage(lobbyId);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
+/** @param {import('ethers').Signer} signer @param {string} lobbyId */
+export async function signCancelLobby(signer, lobbyId) {
+  const message = buildCancelLobbyMessage(lobbyId);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
+/** @param {import('ethers').Signer} signer @param {string} lobbyId */
+export async function signConcedeLobby(signer, lobbyId) {
+  const message = buildConcedeLobbyMessage(lobbyId);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
+/** @param {import('ethers').Signer} signer @param {string} lobbyId */
+export async function signTimeoutLobby(signer, lobbyId) {
+  const message = buildTimeoutLobbyMessage(lobbyId);
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}
+
+/** @param {import('ethers').Signer} signer */
+export async function signRegisterWallet(signer) {
+  const message = buildRegisterWalletMessage();
+  const signature = await signMessage(signer, message);
+  return { message, signature };
+}