Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Types Reference

Complete TypeScript type definitions for the @provable-games/denshokan-sdk package.

import type {
  Token, CoreToken, DecodedTokenId, TokenMetadata,
  TokenMutableState, TokenScoreEntry, PaginatedResult,
  TokensFilterParams, Game, GameStats, // ... etc
} from "@provable-games/denshokan-sdk";

Core Token Types

Token

The full token representation returned by API and RPC queries. See DenshokanClient for query methods.

interface Token {
  tokenId: string;
  gameId: number;
  owner: string;
  score: number;
  gameOver: boolean;
  playerName: string;
  /** 40-bit truncated minter address from token ID (not full address) */
  mintedBy: number;
  mintedAt: string;
  settingsId: number;
  objectiveId: number;
  soulbound: boolean;
  isPlayable: boolean;
  gameAddress: string;
  clientUrl?: string;
  rendererAddress?: string;
  skillsAddress?: string;
  startDelay: number;
  endDelay: number;
  hasContext: boolean;
  paymaster: boolean;
  /** Only populated when includeUri option is passed to getTokens/useTokens */
  tokenUri?: string;
}

CoreToken

Decoded purely from the packed token ID — no RPC calls required. Returned by useDecodeToken and decodeCoreToken().

interface CoreToken {
  tokenId: string;
  gameId: number;
  settingsId: number;
  objectiveId: number;
  mintedAt: string;
  soulbound: boolean;
  startDelay: number;
  endDelay: number;
  hasContext: boolean;
  paymaster: boolean;
  /** 40-bit truncated minter address (not full address) */
  mintedByTruncated: bigint;
  txHash: number;
  salt: number;
  metadata: number;
}

DecodedTokenId

Raw bigint decode of the packed token ID. Returned by client.decodeTokenId(). See Packed Token IDs for the bit layout.

interface 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;
}

TokenMetadata

Immutable on-chain token metadata returned by client.tokenMetadata().

interface TokenMetadata {
  gameId: number;
  settingsId: number;
  objectiveId: number;
  playerName: string;
  mintedBy: string;
  isPlayable: boolean;
  isSoulbound: boolean;
  rendererAddress: string;
  gameAddress: string;
}

TokenMutableState

Mutable token state that can change after minting. Returned by client.tokenMutableState().

interface TokenMutableState {
  gameOver: boolean;
  completedObjective: boolean;
}

TokenScoreEntry

A single score history entry. Returned by client.getTokenScores().

interface TokenScoreEntry {
  score: number;
  timestamp: string;
}

PaginatedResult<T>

Wrapper for paginated API responses. All list queries return this shape.

interface PaginatedResult<T> {
  data: T[];
  total: number;
}

TokensFilterParams

Filter parameters for client.getTokens() and useTokens().

interface TokensFilterParams {
  gameId?: number;
  gameAddress?: string;
  owner?: string;
  settingsId?: number;
  objectiveId?: number;
  minterAddress?: string;
  soulbound?: boolean;
  playable?: boolean;
  gameOver?: boolean;
  mintedAfter?: number;
  mintedBefore?: number;
  limit?: number;
  offset?: number;
  /** When true, fetches token URIs via batch RPC */
  includeUri?: boolean;
}

Game Types

Game

A registered game in the EGS ecosystem.

interface Game {
  gameId: number;
  name: string;
  description: string;
  contractAddress: string;
  imageUrl?: string;
  developer?: string;
  publisher?: string;
  genre?: string;
  color?: string;
  clientUrl?: string;
  rendererAddress?: string;
  royaltyFraction?: string;
  skillsAddress?: string;
  version?: number;
  createdAt: string;
}

GameStats

Aggregate statistics for a game. Returned by client.getGameStats().

interface GameStats {
  gameId: number;
  totalTokens: number;
  completedGames: number;
  activeGames: number;
  uniquePlayers: number;
}

GameDetail

A key-value pair from game-specific detail data. Returned by client.gameDetails().

interface GameDetail {
  key: string;
  value: string;
}

GameSettingDetails

A complete settings configuration for a game.

interface GameSettingDetails {
  id: number;
  gameAddress: string;
  creatorAddress: string;
  name: string;
  description: string;
  settings: Record<string, string>;
  blockNumber: string;
  createdAt: string;
}

GameObjectiveDetails

A complete objective definition for a game.

interface GameObjectiveDetails {
  id: number;
  settingsId: number;
  gameAddress: string;
  creatorAddress: string;
  name: string;
  description: string;
  objectives: Record<string, string>;
  blockNumber: string;
  createdAt: string;
}

SettingsParams

Parameters for querying settings lists.

interface SettingsParams {
  limit?: number;
  offset?: number;
  gameAddress?: string;
}

ObjectivesParams

Parameters for querying objectives lists.

interface ObjectivesParams {
  limit?: number;
  offset?: number;
  gameAddress?: string;
}

Player Types

PlayerStats

Aggregate player statistics. Returned by client.getPlayerStats().

interface PlayerStats {
  address: string;
  totalTokens: number;
  gamesPlayed: number;
  completedGames: number;
  activeGames: number;
  totalScore: string;
}

PlayerTokensParams

Parameters for querying a player's tokens.

interface PlayerTokensParams {
  gameId?: number;
  limit?: number;
  offset?: number;
  /** When true, fetches token URIs via batch RPC */
  includeUri?: boolean;
}

Minter Types

Minter

A registered minter contract. Returned by client.getMinters().

interface Minter {
  id: string;
  minterId: string;
  name: string;
  contractAddress: string;
  createdAt: string;
  blockNumber: string;
}

Activity Types

ActivityEvent

A single activity event in the system.

interface ActivityEvent {
  id: string;
  type: string;
  tokenId: string;
  gameId: number;
  player: string;
  data: Record<string, unknown>;
  timestamp: string;
}

ActivityParams

Parameters for querying activity.

interface ActivityParams {
  type?: string;
  limit?: number;
  offset?: number;
}

ActivityStats

Aggregate activity statistics.

interface ActivityStats {
  gameId: number;
  totalTokens: number;
  completedGames: number;
  activeGames: number;
  uniquePlayers: number;
}

RPC Types

MintParams

Parameters for client.mint(). All fields are required except salt and metadata.

interface MintParams {
  gameId: number;
  settingsId: number;
  objectiveId: number;
  playerName: string;
  skillsAddress?: string;
  soulbound: boolean;
  to: string;
  salt?: number;
  metadata?: number;
}

RoyaltyInfo

ERC-2981 royalty information. Returned by client.royaltyInfo().

interface RoyaltyInfo {
  receiver: string;
  amount: bigint;
}

GameMetadata

On-chain game metadata from the registry RPC.

interface GameMetadata {
  gameId: number;
  contractAddress: string;
  name: string;
  description: string;
  developer: string;
  publisher: string;
  genre: string;
  image: string;
  color: string;
  clientUrl: string;
  rendererAddress: string;
  skillsAddress: string;
  version: number;
  royaltyFraction: bigint;
  createdAt: number;
}

PlayerNameUpdate

Used with client.updatePlayerNameBatch().

interface PlayerNameUpdate {
  tokenId: string;
  name: string;
}

FilterResult

Result from viewer contract filter queries.

interface FilterResult {
  tokenIds: string[];
  total: number;
}

TokenFullState

Full on-chain token state from the viewer contract.

interface TokenFullState {
  tokenId: string;
  owner: string;
  playerName: string;
  isPlayable: boolean;
  gameAddress: string;
  gameOver: boolean;
  completedObjective: boolean;
  lifecycle: Lifecycle;
}

Lifecycle

Start and end timestamps for token playability windows.

interface Lifecycle {
  start: number;
  end: number;
}

WebSocket Event Types

For subscription hooks usage, see WebSocket Subscriptions and React Hooks.

WSChannel

type WSChannel =
  | "tokens"
  | "scores"
  | "game_over"
  | "mints"
  | "games"
  | "minters"
  | "settings"
  | "objectives";

WSMessage

interface WSMessage {
  channel: string;
  data: unknown;
  _timing?: { serverTs: number };
}

WSSubscribeOptions

interface WSSubscribeOptions {
  channels: WSChannel[];
  gameIds?: number[];
}

WSEventHandler

type WSEventHandler = (message: WSMessage) => void;

ScoreEvent

Emitted on the scores channel when a token's score changes.

interface ScoreEvent {
  tokenId: string;
  gameId: number;
  score: number;
  ownerAddress: string;
  playerName: string;
}

GameOverEvent

Emitted on the game_over channel when a game ends.

interface GameOverEvent {
  tokenId: string;
  gameId: number;
  score: number;
  ownerAddress: string;
  playerName: string;
  completedAllObjectives: boolean;
}

MintEvent

Emitted on the mints channel when a new token is minted.

interface MintEvent {
  tokenId: string;
  gameId: number;
  ownerAddress: string;
  mintedBy: string;
  settingsId: number;
}

TokenUpdateEvent

Union type emitted on the tokens channel for any token state change.

type TokenUpdateEvent =
  | { type: "scoreUpdate"; tokenId: string; gameId: number; score: number }
  | { type: "gameOver"; tokenId: string; gameId: number; score: number }
  | { type: "minted"; tokenId: string; gameId: number; ownerAddress: string };

NewGameEvent

interface NewGameEvent {
  gameId: number;
  contractAddress: string;
  name: string;
}

NewMinterEvent

interface NewMinterEvent {
  minterId: string;
  contractAddress: string;
  name: string;
  blockNumber: string;
}

NewSettingEvent

interface NewSettingEvent {
  gameAddress: string;
  settingsId: number;
  creatorAddress: string;
  settingsData: string | null;
}

NewObjectiveEvent

interface NewObjectiveEvent {
  gameAddress: string;
  objectiveId: number;
  settingsId: number;
  creatorAddress: string;
  objectiveData: string | null;
}

WSChannelPayloadMap

Maps each channel name to its typed payload. Used by subscription hooks for type safety.

interface WSChannelPayloadMap {
  scores: ScoreEvent;
  game_over: GameOverEvent;
  mints: MintEvent;
  tokens: TokenUpdateEvent;
  games: NewGameEvent;
  minters: NewMinterEvent;
  settings: NewSettingEvent;
  objectives: NewObjectiveEvent;
}

Configuration Types

DenshokanClientConfig

Configuration for creating a DenshokanClient.

interface DenshokanClientConfig {
  chain?: "mainnet" | "sepolia";
  apiUrl?: string;
  wsUrl?: string;
  rpcUrl?: string;
  provider?: unknown;
  /** Denshokan ERC721 contract address (defaults to chain address) */
  denshokanAddress?: string;
  /** Minigame registry contract address (defaults to chain address) */
  registryAddress?: string;
  /** Viewer contract address for batch filter queries (defaults to chain address) */
  viewerAddress?: string;
  primarySource?: DataSource;
  fetch?: FetchConfig;
  ws?: WSConfig;
  health?: HealthConfig;
}

DataSource

type DataSource = "api" | "rpc";

FetchConfig

interface FetchConfig {
  timeout?: number;
  maxRetries?: number;
  baseBackoff?: number;
  maxBackoff?: number;
  /** Max concurrent token URI RPC calls (0 = unlimited) */
  tokenUriConcurrency?: number;
}

WSConfig

interface WSConfig {
  maxReconnectAttempts?: number;
  reconnectBaseDelay?: number;
}

HealthConfig

interface HealthConfig {
  /** Delay before first health check in ms (default: 1000) */
  initialCheckDelay?: number;
  /** Interval between health checks in ms (default: 30000) */
  checkInterval?: number;
  /** Timeout for each health check in ms (default: 5000) */
  checkTimeout?: number;
}

Error Types

All errors extend DenshokanError. See Error Handling for usage examples.

class DenshokanError extends Error {}
 
class ApiError extends DenshokanError {
  statusCode: number;
}
 
class RpcError extends DenshokanError {
  contractAddress?: string;
}
 
class RateLimitError extends DenshokanError {
  retryAfter: number | null;
}
 
class TimeoutError extends DenshokanError {}
 
class AbortError extends DenshokanError {}
 
class TokenNotFoundError extends DenshokanError {
  tokenId: string;
}
 
class GameNotFoundError extends DenshokanError {
  gameId: string | number;
}
 
class InvalidChainError extends DenshokanError {
  chain: string;
}
 
class DataSourceError extends DenshokanError {
  primaryError: Error;
  fallbackError: Error;
}

Hook Return Types

UseAsyncResult<T>

Standard return type for all data React hooks.

interface UseAsyncResult<T> {
  data: T | null;
  isLoading: boolean;
  error: Error | null;
  refetch: () => void;
}

UseTokensResult

Extended return type for useTokens and usePlayerTokens. Adds isLoadingUri for background URI fetching.

interface UseTokensResult extends UseAsyncResult<PaginatedResult<Token>> {
  /** True while token URIs are being fetched (when includeUri: true) */
  isLoadingUri: boolean;
}

UseChannelOptions<C>

Options for subscription hooks.

interface UseChannelOptions<C extends WSChannel> {
  gameIds?: number[];
  bufferSize?: number;
  enabled?: boolean;
  onEvent?: (event: WSChannelPayloadMap[C]) => void;
}

UseChannelResult<C>

Return type for subscription hooks.

interface UseChannelResult<C extends WSChannel> {
  lastEvent: WSChannelPayloadMap[C] | null;
  events: WSChannelPayloadMap[C][];
  isConnected: boolean;
  clear: () => void;
}