@block52/poker-vm-sdk


TypeScript SDK for Block52 Poker VM - A blockchain-based poker platform built on Cosmos.

Features

- 🎮 Complete Poker Game Logic - Card dealing, hand evaluation, and game state management
- 🔐 Cosmos Blockchain Integration - Transaction signing, querying, and wallet management
- 🎲 Deck Management - Shuffle, deal, and track card states with blockchain-verified randomness
- 🤝 Type-Safe - Full TypeScript support with generated types from protobuf definitions
- 🔄 Real-time Updates - WebSocket support for live game state synchronization
- 💰 Token Operations - Built-in USDC token handling and conversions

Installation

``bash
npm install @block52/poker-vm-sdk
`

or with yarn:

`bash
yarn add @block52/poker-vm-sdk
`

Quick Start

$3

`typescript
import { createSigningClientFromMnemonic, getDefaultCosmosConfig } from '@block52/poker-vm-sdk';

// Connect to the blockchain
const config = getDefaultCosmosConfig("mainnet"); // or "testnet", "localhost"
const mnemonic = "your twelve word mnemonic phrase here...";

const client = await createSigningClientFromMnemonic(config, mnemonic);
const walletAddress = await client.getWalletAddress();
console.log("Wallet Address:", walletAddress);
`

$3

`typescript
// Define game parameters
const gameParams = {
gameFormat: "cash", // or "tournament"
gameVariant: "texas-holdem",
minPlayers: 2,
maxPlayers: 6,
minBuyIn: client.usdcToB52usdc(10), // 10 USDC minimum
maxBuyIn: client.usdcToB52usdc(100), // 100 USDC maximum
smallBlind: client.usdcToB52usdc(0.5), // 0.5 USDC small blind
bigBlind: client.usdcToB52usdc(1), // 1 USDC big blind
timeout: 60 // 60 seconds per action
};

// Create the game on-chain
const txHash = await client.createGame(
gameParams.gameFormat,
gameParams.gameVariant,
gameParams.minPlayers,
gameParams.maxPlayers,
gameParams.minBuyIn,
gameParams.maxBuyIn,
gameParams.smallBlind,
gameParams.bigBlind,
gameParams.timeout
);

console.log("Game created! Transaction:", txHash);
`

$3

`typescript
import { Deck, PokerSolver } from '@block52/poker-vm-sdk';

// Create and shuffle a deck
const deck = new Deck();
deck.shuffle([1, 2, 3, 4, 5]); // Seed for deterministic shuffle

// Deal cards
const playerHand = deck.deal(2); // Deal 2 cards to player
const communityCards = deck.deal(5); // Deal 5 community cards

// Evaluate hand strength
const allCards = [...playerHand, ...communityCards];
const evaluation = PokerSolver.evaluateSevenCardHand(allCards);
console.log("Hand type:", evaluation.type);
console.log("Hand rank:", evaluation.rank);

// Compare two hands
const player1Evaluation = PokerSolver.evaluateSevenCardHand(player1Cards);
const player2Evaluation = PokerSolver.evaluateSevenCardHand(player2Cards);
const result = PokerSolver.compareHands(player1Evaluation, player2Evaluation);
// result > 0: player1 wins, < 0: player2 wins, 0: tie
`

$3

`typescript
import { CosmosClient, getDefaultCosmosConfig } from '@block52/poker-vm-sdk';

// Create a query-only client (no signing required)
const config = getDefaultCosmosConfig("mainnet");
const queryClient = new CosmosClient(config);

// Query a game by ID
const game = await queryClient.getGame(gameId);
console.log("Game options:", game);

// Get game state
const gameState = await queryClient.getGameState(gameId);
console.log("Game state:", gameState);

// List all games
const allGames = await queryClient.listGames();
console.log("Active games:", allGames.length);

// Get games for a specific player
const playerGames = await queryClient.getPlayerGames(playerAddress);
console.log("Player games:", playerGames.length);
`

$3

`typescript
// Convert between USDC and b52usdc (blockchain representation)
const usdcAmount = 100; // 100 USDC
const b52usdcAmount = client.usdcToB52usdc(usdcAmount);

// Convert back
const usdcValue = client.b52usdcToUsdc(b52usdcAmount);

// Check balance
const balance = await client.getB52USDCBalance(walletAddress);
console.log("Balance:", client.b52usdcToUsdc(balance), "USDC");
`

API Reference

$3

The main client for interacting with the poker blockchain with signing capabilities.

#### Methods

- createGame(gameFormat, gameVariant, minPlayers, maxPlayers, minBuyIn, maxBuyIn, smallBlind, bigBlind, timeout, rakeConfig?, sngConfig?) - Create a new poker game
- joinGame(gameId, seat, buyInAmount) - Join an existing game at a specific seat
- performAction(gameId, action, amount?, data?) - Perform a poker action (fold, call, raise, check)
- leaveGame(gameId) - Leave a game and cash out
- getWalletAddress() - Get the current wallet address
- getB52USDCBalance(address) - Get USDC balance for an address
- getTx(hash) - Get transaction details by hash
- disconnect() - Close the client connection

$3

Query-only client for reading blockchain state.

#### Methods

- getGame(gameId) - Get game options/configuration by ID
- getGameState(gameId) - Get current game state by ID
- listGames() - Get all games
- findGames(min?, max?) - Find games by blind range
- getPlayerGames(playerAddress) - Get games for a specific player
- getLegalActions(gameId, playerAddress?) - Get legal actions for a game
- getBalance(address, denom?) - Query token balance
- getAllBalances(address) - Get all token balances
- getAccount(address) - Get account information
- getHeight() - Get current block height
- getTx(txHash) - Get transaction by hash

$3

Card deck management with blockchain integration.

#### Methods

- constructor(deck?: string) - Create deck from mnemonic string or new ordered deck
- getNext() - Draw next card
- deal(amount) - Deal multiple cards
- toString() - Serialize deck to string
- shuffle(seed) - Shuffle deck (testing only, production uses blockchain randomness)

#### Constants

- Deck.DECK_SIZE - Number of cards in a standard deck (52)
- Deck.RANK_MAP - Map of rank values to strings (A, T, J, Q, K)
- Deck.SUIT_MAP - Map of suit values to strings (C, D, H, S)

$3

Hand evaluation and poker logic.

#### Static Methods

- evaluatePartialHand(cards) - Evaluate poker hand strength (partial or complete hand)
- evaluateSevenCardHand(cards) - Evaluate best 5-card hand from 7 cards
- compareHands(hand1, hand2) - Compare two hands to determine winner

$3

Utilities for wallet management.

- generateWallet(prefix?, wordCount?) - Generate a new wallet with random mnemonic (12 or 24 words)
- createWalletFromMnemonic(mnemonic, prefix?) - Create wallet from existing mnemonic
- getAddressFromMnemonic(mnemonic, prefix?) - Derive address from mnemonic
- isValidMnemonic(mnemonic) - Validate mnemonic phrase
- BLOCK52_HD_PATH - Standard Cosmos HD derivation path for Block52

Configuration

$3

`typescript
import { getDefaultCosmosConfig } from '@block52/poker-vm-sdk';

// Mainnet
const mainnetConfig = getDefaultCosmosConfig("mainnet");

// Testnet
const testnetConfig = getDefaultCosmosConfig("testnet");

// Local development
const localConfig = getDefaultCosmosConfig("localhost");

// Custom configuration
const customConfig = {
rpcEndpoint: "https://your-node.example.com:26657",
restEndpoint: "https://your-node.example.com:1317",
chainId: "pokerchain-1",
prefix: "poker"
};
`

Examples

Check out the examples directory for complete working examples:

- create-game-example.ts - Complete example of creating a poker game
- wallet-example.ts - Wallet creation and management

To run the examples:

`bash
git clone https://github.com/block52/poker-vm.git
cd poker-vm/sdk
yarn install
yarn build
npx ts-node examples/create-game-example.ts
`

Development

$3

`bash


Clone the repository

git clone https://github.com/block52/poker-vm.git
cd poker-vm/sdk

Install dependencies

yarn install

Build the SDK

yarn build

Run tests

yarn test

Lint code

yarn lint
`

$3

`
sdk/
├── src/
│ ├── index.ts # Main entry point
│ ├── client.ts # Base client implementation
│ ├── cosmosClient.ts # Query client
│ ├── signingClient.ts # Signing client
│ ├── deck.ts # Deck class
│ ├── pokerSolver.ts # Hand evaluation
│ ├── walletUtils.ts # Wallet utilities
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ └── pokerchain.poker.v1/ # Generated protobuf types
├── examples/ # Usage examples
├── tests/ # Test files
└── dist/ # Built output (after yarn build)
`

TypeScript Support

This SDK is written in TypeScript and includes full type definitions. No additional @types packages are needed.

`typescript
import type { GameStateResponseDTO, PlayerDTO, ActionDTO } from '@block52/poker-vm-sdk';
`

$3

The SDK defines the single source of truth for all game types:

- GameStateResponseDTO - Root type for game data over the wire
- TexasHoldemStateDTO - Game state (contains players, communityCards, etc.)
- GameOptionsDTO - Game configuration (NO format or owner - use root fields)
- PlayerDTO - Player information

See CLAUDE.md for complete type rules.

Browser Support

The SDK works in both Node.js and browser environments. For browser usage, you may need to configure polyfills for Node.js built-ins:

`javascript
// Example webpack config
module.exports = {
resolve: {
fallback: {
"stream": require.resolve("stream-browserify"),
"crypto": require.resolve("crypto-browserify"),
"buffer": require.resolve("buffer/")
}
}
};
``

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

MIT License - see LICENSE file for details.

Support

- 📚 Documentation: CLAUDE.md - Detailed SDK documentation
- 🐛 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions
- 🌐 Website: Block52

Related Projects

- Poker VM - Main repository
- Poker UI - Web-based poker client
- Poker Bot - AI poker bot

Changelog

See Releases for version history and changes.