DenshokanClient

import { DenshokanClient } from "@provable-games/denshokan-sdk";
 
const client = new DenshokanClient({
  chain: "mainnet",           // "mainnet" | "sepolia"
  apiUrl: "https://...",      // Override API URL
  wsUrl: "wss://...",         // Override WebSocket URL
  rpcUrl: "https://...",      // Override RPC URL
  primarySource: "api",       // "api" | "rpc" (default: "api")
  viewerAddress: "0x...",     // Viewer contract for batch filter queries
  denshokanAddress: "0x...",  // Denshokan ERC721 contract address
  registryAddress: "0x...",   // Minigame registry contract address
  fetch: {
    timeout: 10000,           // Request timeout (ms)
    maxRetries: 3,            // Max retry attempts
    baseBackoff: 1000,        // Base backoff delay (ms)
    maxBackoff: 30000,        // Max backoff delay (ms)
    tokenUriConcurrency: 0,   // Max concurrent URI fetches (0 = unlimited)
  },
  ws: {
    maxReconnectAttempts: 10, // Max reconnect attempts
    reconnectBaseDelay: 1000, // Base reconnect delay (ms)
  },
  health: {
    initialCheckDelay: 1000,  // ms before first health check
    checkInterval: 30000,     // ms between health checks
    checkTimeout: 5000,       // ms timeout for health check
  },
});

// List games with pagination
const games = await client.getGames({ limit: 20, offset: 0 });
// Returns: PaginatedResult<Game>
 
// Get a single game (API with RPC fallback)
const game = await client.getGame("0x1234...");
// Returns: Game
 
// Get game statistics
const stats = await client.getGameStats("0x1234...");
// Returns: GameStats

// List tokens with filtering
const tokens = await client.getTokens({
  gameAddress: "0x1234...",
  owner: "0x5678...",
  settingsId: 2,
  gameOver: true,
  playable: false,
  soulbound: false,
  includeUri: true,    // Fetch token URIs via batch RPC
  limit: 50,
  offset: 0,
});
// Returns: PaginatedResult<Token>
 
// Get a single token (API with RPC fallback)
const token = await client.getToken("0xabc...");
// Returns: Token
 
// Get score history
const scores = await client.getTokenScores("0xabc...", 10);
// Returns: TokenScoreEntry[]

// Get player's tokens
const tokens = await client.getPlayerTokens("0x5678...", {
  gameAddress: "0x1234...",  // Optional: filter by game
  includeUri: true,          // Optional: fetch token URIs
});
// Returns: PaginatedResult<Token>
 
// Get player statistics
const stats = await client.getPlayerStats("0x5678...");
// Returns: PlayerStats

// List minters with pagination
const minters = await client.getMinters({ limit: 20, offset: 0 });
// Returns: PaginatedResult<Minter>
 
// Get a single minter
const minter = await client.getMinter("minter-id");
// Returns: Minter

// List activity events
const activity = await client.getActivity({
  type: "score_update",  // Optional: filter by event type
  limit: 50,
  offset: 0,
});
// Returns: PaginatedResult<ActivityEvent>
 
// Get aggregate activity stats
const stats = await client.getActivityStats(1); // Optional: gameId filter
// Returns: ActivityStats

// Get settings for a game
const settings = await client.getSettings({
  gameAddress: "0x1234...",
  limit: 10,
  offset: 0,
});
// Returns: PaginatedResult<GameSettingDetails>
 
// Get a specific setting
const setting = await client.getSetting(2, "0x1234...");
// Returns: GameSettingDetails
 
// Get objectives for a game
const objectives = await client.getObjectives({
  gameAddress: "0x1234...",
  settingsId: 1,  // Optional: filter by settings
});
// Returns: PaginatedResult<GameObjectiveDetails>
 
// Get a specific objective
const objective = await client.getObjective(1, "0x1234...");
// Returns: GameObjectiveDetails

const balance = await client.balanceOf("0x5678...");   // bigint
const owner = await client.ownerOf("0xabc...");        // string
const uri = await client.tokenUri("0xabc...");         // string
const name = await client.name();                       // string
const sym = await client.symbol();                      // string
const supply = await client.totalSupply();              // bigint
 
// Batch URI fetch
const uris = await client.tokenUriBatch(["0xa..", "0xb.."]);
// Returns: string[]
 
// ERC-2981 royalty info
const royalty = await client.royaltyInfo("0xabc..", salePrice);
// Returns: RoyaltyInfo { receiver, amount }

// Get token ID by global index
const tokenId = await client.tokenByIndex(0n);
 
// Get token ID by owner index
const tokenId = await client.tokenOfOwnerByIndex("0x5678...", 0n);
 
// Enumerate all token IDs (paginated)
const ids = await client.enumerateTokenIds({ limit: 100, offset: 0 });
 
// Enumerate token IDs owned by address
const ids = await client.enumerateTokenIdsByOwner("0x5678...", {
  limit: 100,
  offset: 0,
});

// Single
const metadata = await client.tokenMetadata("0xabc...");
const playable = await client.isPlayable("0xabc...");
const name = await client.playerName("0xabc...");
 
// Batch
const metadatas = await client.tokenMetadataBatch(["0xa..", "0xb.."]);
const names = await client.playerNameBatch(["0xa..", "0xb.."]);

const score = await client.score("0xabc...", "0x1234...");   // bigint
const over = await client.gameOver("0xabc...", "0x1234..."); // boolean
 
// Batch
const scores = await client.scoreBatch(["0xa..", "0xb.."], "0x1234...");
const overs = await client.gameOverBatch(["0xa..", "0xb.."], "0x1234...");

const name = await client.tokenName("0xabc..", "0x1234..");
const desc = await client.tokenDescription("0xabc..", "0x1234..");
const details = await client.gameDetails("0xabc..", "0x1234..");
// Returns: GameDetail[] — array of { key, value } pairs
 
// Batch variants
const names = await client.tokenNameBatch(["0xa..", "0xb.."], "0x1234..");
const descs = await client.tokenDescriptionBatch(["0xa..", "0xb.."], "0x1234..");
const allDetails = await client.gameDetailsBatch(["0xa..", "0xb.."], "0x1234..");

const count = await client.objectivesCount("0x1234..");             // number
const exists = await client.objectiveExists(1, "0x1234..");         // boolean
const completed = await client.completedObjective(
  "0xabc..", 1, "0x1234.."
);  // boolean
const details = await client.objectivesDetails(1, "0x1234..");      // GameObjectiveDetails
 
// Batch variants
const existsAll = await client.objectiveExistsBatch([1, 2, 3], "0x1234..");
const completedAll = await client.completedObjectiveBatch(
  ["0xa..", "0xb.."], 1, "0x1234.."
);
const detailsAll = await client.objectivesDetailsBatch([1, 2, 3], "0x1234..");

const count = await client.settingsCount("0x1234..");              // number
const exists = await client.settingsExists(1, "0x1234..");         // boolean
const details = await client.settingsDetails(1, "0x1234..");       // GameSettingDetails
 
// Batch variants
const existsAll = await client.settingsExistsBatch([1, 2, 3], "0x1234..");
const detailsAll = await client.settingsDetailsBatch([1, 2, 3], "0x1234..");

// Get full on-chain game metadata from registry
const meta = await client.gameMetadata(1);       // GameMetadata
const addr = await client.gameAddress(1);        // string

// Mint a new game token
const calls = client.mint({
  gameId: 1,
  settingsId: 2,
  objectiveId: 0,
  playerName: "Player1",
  skillsAddress: undefined,   // Optional: AI agent skills provider
  to: playerAddress,
  soulbound: false,
});
 
// Batch mint (auto-assigns salts)
const calls = client.mintBatch([
  { gameId: 1, settingsId: 1, objectiveId: 0, playerName: "P1", to: addr, soulbound: false },
  { gameId: 1, settingsId: 2, objectiveId: 0, playerName: "P2", to: addr, soulbound: false },
]);
 
// Update game state (sync score/game_over from game contract)
const calls = client.updateGame(tokenId);
const calls = client.updateGameBatch([tokenId1, tokenId2]);
 
// Update player name
const calls = client.updatePlayerName(tokenId, "NewName");
const calls = client.updatePlayerNameBatch([
  { tokenId: "0xa..", name: "Name1" },
  { tokenId: "0xb..", name: "Name2" },
]);

import { Account, RpcProvider } from "starknet";
 
const provider = new RpcProvider({ nodeUrl: "https://..." });
const account = new Account(provider, accountAddress, privateKey);
 
// Execute a mint
const mintCalls = client.mint({
  gameId: 1,
  settingsId: 1,
  objectiveId: 0,
  playerName: "MyPlayer",
  to: account.address,
  soulbound: false,
});
const { transaction_hash } = await account.execute(mintCalls);
await provider.waitForTransaction(transaction_hash);

import { useAccount } from "@starknet-react/core";
 
function MintButton({ client }) {
  const { account } = useAccount();
 
  const handleMint = async () => {
    const calls = client.mint({
      gameId: 1,
      settingsId: 1,
      objectiveId: 0,
      playerName: "Player",
      to: account.address,
      soulbound: false,
    });
    await account.execute(calls);
  };
 
  return <button onClick={handleMint}>Mint Token</button>;
}

const decoded = client.decodeTokenId("0x123...");
// Returns: DecodedTokenId {
//   tokenId: bigint,
//   gameId: number,
//   mintedBy: bigint,
//   settingsId: number,
//   mintedAt: Date,
//   startDelay: number,
//   endDelay: number,
//   objectiveId: number,
//   soulbound: boolean,
//   hasContext: boolean,
//   paymaster: boolean,
//   txHash: number,
//   salt: number,
//   metadata: number,
// }

import { decodeCoreToken } from "@provable-games/denshokan-sdk";
 
const core = decodeCoreToken("0x123...");
// Returns: CoreToken — no RPC, no client needed

import { MintSaltCounter } from "@provable-games/denshokan-sdk";
 
const counter = new MintSaltCounter();    // starts at 0
const salt1 = counter.next();             // 0
const salt2 = counter.next();             // 1
const peeked = counter.peek();            // 2 (without advancing)
counter.reset();                          // back to 0

import { assignSalts } from "@provable-games/denshokan-sdk";
 
const params = [
  { gameId: 1, settingsId: 1, objectiveId: 0, playerName: "P1", to: addr, soulbound: false },
  { gameId: 1, settingsId: 2, objectiveId: 0, playerName: "P2", to: addr, soulbound: false },
];
 
const withSalts = assignSalts(params);
// withSalts[0].salt === 0
// withSalts[1].salt === 1

import { normalizeAddress, toHexTokenId } from "@provable-games/denshokan-sdk";
 
// Normalize to 0x-prefixed, 64-char hex (strips leading zeros, pads)
normalizeAddress("0x00123");
// "0x0000000000000000000000000000000000000000000000000000000000000123"
 
// Convert bigint/hex/decimal to 0x-prefixed hex (no padding)
toHexTokenId(255n);
// "0xff"

// Check WebSocket connection
const connected = client.wsConnected; // boolean
 
// Listen for connection changes
const unsub = client.onWsConnectionChange((connected) => {
  console.log("WebSocket:", connected ? "up" : "down");
});
 
// Later: stop listening
unsub();

// ConnectionStatus modes
type ConnectionMode = "api" | "rpc-fallback" | "offline";

import {
  DenshokanError,
  ApiError,
  RpcError,
  TokenNotFoundError,
  DataSourceError,
} from "@provable-games/denshokan-sdk";
 
try {
  const token = await client.getToken(id);
} catch (error) {
  if (error instanceof TokenNotFoundError) {
    console.log(`Token ${error.tokenId} not found`);
  } else if (error instanceof ApiError) {
    console.log(`API error: ${error.statusCode}`);
  } else if (error instanceof DataSourceError) {
    console.log("Both API and RPC failed");
  }
}

// Disconnect WebSocket and cleanup
client.disconnect();