# @block52/poker-vm-sdk 中文文档

规范地址：https://npmcn.com/package/%40block52/poker-vm-sdk/

版本：1\.24\.0
npm 元数据更新时间：2026-11-05T01:56:04.695Z
中文译文更新时间：2026-11-08T07:08:02.988Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40block52/poker-vm-sdk
原文对照：https://npmcn.com/package/%40block52/poker-vm-sdk/?lang=original
项目主页：https://github.com/block52/poker-vm#readme
源码仓库：https://github.com/block52/poker-vm

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：26.3 MB，1174 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- 首次发布：2025-12-14T04:31:57.836Z
- 最新版本发布：2026-11-05T01:56:04.524Z
- 近 30 天下载量：3038（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 69 个）

## 中文简介

Block52 扑克VM 的脚本 SDK

## 安装

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

也可以使用：`pnpm add @block52/poker-vm-sdk`、`yarn add @block52/poker-vm-sdk`、`bun add @block52/poker-vm-sdk`

## README

# @ block52/ poker-vm- sdk (英语)

[![npm version](https://img.shields.io/npm/v/@block52/poker-vm-sdk.svg)](https://www.npmjs.com/package/@block52/poker-vm-sdk) [![SDK Tests](https://github.com/block52/poker-vm/actions/workflows/sdk-test.yml/badge.svg)](https://github.com/block52/poker-vm/actions/workflows/sdk-test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

TypeScript SDK for Block52 Poker VM - 一个以Cosmos为主的以块链为主的扑克平台.

## 特征

-   🎮 **完成扑克游戏逻辑** - 卡片交易、手评价、游戏状态管理
-   🔐 **Cosmos 区块链集成** - 交易签名、查询和钱包管理
-   🎲 **舱面管理** - 摇摆、交易和追踪卡状态 以区块链验证随机性
-   🤝 **类型安全** - 完整类型脚本支持,并用原生生物定义生成的类型
-   🔄 **实时更新** - 对游戏状态同步的WebSocket支持
-   💰 **调试操作** - 安装在USDC信号处理和转换中

## 安装

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

或带线:

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

## 快速启动

### 创建签名客户端

```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);
```

### 创建扑克游戏

```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);
```

### 与牌和德克牌合作

```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
```

### 查询游戏状态

```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);
```

### 调试操作

```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 参考

### 签名空间

扩展 `CosmosClient` 具有交易签名能力。 包括所有查询方法 `CosmosClient` 加:

#### 交易方法

-   `createGame(gameFormat, gameVariant, minPlayers, maxPlayers, minBuyIn, maxBuyIn, smallBlind, bigBlind, timeout, rakeConfig?, sngConfig?)` - 创建新的扑克游戏
-   `joinGame(gameId, seat, buyInAmount)` - 在一个特定位置加入已有的游戏
-   `leaveGame(gameId)` - 留下游戏和现金
-   `performAction(gameId, action, amount?, data?)` - 实施扑克动作(倍数、呼叫、提升、检查、全入、交易)
-   `topUp(gameId, amount)` - 将芯片添加到桌子上
-   `sendTokens(fromAddress, toAddress, amount, denom?, memo?)` - 向另一个地址发送签名
-   `sendB52USDC(fromAddress, toAddress, amount, memo?)` - 发送b52USDC令牌

#### 桥梁方法

-   `processDeposit(depositIndex)` - 按指数处理伊特鲁姆的桥梁存款
-   `initiateWithdrawal(baseAddress, amount)` - 开始撤回基地
-   `getWithdrawalRequest(nonce)` - 询问非ce提出的具体退出请求
-   `listWithdrawalRequests(cosmosAddress?)` - 除名请求

#### 钱包方法

-   `getWalletAddress()` - 获取当前钱包地址
-   `setWallet(wallet)` - 为签名设置一个新的钱包
-   `getWallet()` - 获取当前钱包实例
-   `disconnect()` - 关闭客户端连接

### 宇宙线

通过 REST API 读取块链状态的查询客户端 .

#### 块链查询方法

-   `getAccount(address)` - 获取账户信息
-   `getAllBalances(address)` - 获得所有象征性余额的地址
-   `getBalance(address, denom?)` - 获得具体符号余额(默认:b52USDC)
-   `getHeight()` - 获取当前块高
-   `getTx(txHash)` -通过散列交易
-   `getBlock(height)` - 按高度逐个街区
-   `getLatestBlock()` - 获取最新块
-   `getBlocks(startHeight, count?)` - 从高处开始多块块
-   `getLatestBlocks(count?)` - 获取最新的N区块

#### 游戏查询方法

-   `getGame(gameId)` - 通过ID获取游戏选项/配置
-   `getGameState(gameId)` - 通过 ID 获取当前游戏状态
-   `listGames()` - 获得所有活跃的游戏
-   `findGames(min?, max?)` - 按玩家容量查找游戏(minPlayers/maxPlayers)
-   `getPlayerGames(playerAddress)` - 为特定玩家获得所有游戏
-   `getLegalActions(gameId, playerAddress?)` - 为游戏中的玩家争取法律行动

#### 调试方法( U)

-   `getB52USDCBalance(address)` - 获得B52USDC的地址余额
-   `b52usdcToUsdc(amount)` - 将b52USDC(微单位)转换为USDC显示格式
-   `usdcToB52usdc(amount)` - 将USDC转换为b52USDC(微单位)
-   `calculateEquity(hands, board?, dead?, simulations?)` - 通过Monte Carlo计算手股
-   `calculateEquityFull(hands, board?, dead?, simulations?)` - 用完整的元数据计算公平
-   `listWithdrawalRequests(cosmosAddress?)` - 除名请求(全部或具体地址)

### 地标

采用区块链集成的牌甲板管理.

#### 方法

-   `constructor(deck?: string)` - 从元音字符串或新订购的甲板创建甲板
-   `getNext()` - 绘制下一张牌
-   `deal(amount)` - 发多张牌
-   `toString()` - 将甲板串起
-   `shuffle(seed)` - Shuffle甲板(仅测试,生产使用区块链随机性)

#### 常数

-   `Deck.DECK_SIZE` - 标准甲板上的牌数(52)
-   `Deck.RANK_MAP` - 排序值图到字符串(A、T、J、Q、K)
-   `Deck.SUIT_MAP` - 服饰值图到字符串(C、D、H、S)

### 扑克索尔

手评和扑克逻辑.

#### 静态方法

-   `evaluatePartialHand(cards)` - 评估扑克手力(部分或完整的手)
-   `evaluateSevenCardHand(cards)` - 从7张牌上评估最好的5张牌手
-   `compareHands(hand1, hand2)` - 用两只手来决定赢家

### 钱包公用事业

钱包管理费.

-   `generateWallet(prefix?, wordCount?)` - 生成一个带有随机元件的新钱包( 12或24个字)
-   `createWalletFromMnemonic(mnemonic, prefix?)` - 从现有元件创建钱包
-   `getAddressFromMnemonic(mnemonic, prefix?)` - 来自元音的衍生地址
-   `isValidMnemonic(mnemonic)` - 验证元音短语
-   `BLOCK52_HD_PATH` - Block52的标准Cosmos HD衍生路径

## 配置

### 网络终点

```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"
};
```

## 实例

看看这个 [实例](https://npmcn.com/package/%40block52/poker-vm-sdk/examples) 完整工作示例目录 :

-   **[创建游戏实例( t)](https://npmcn.com/package/%40block52/poker-vm-sdk/examples/create-game-example.ts)** - 制作扑克游戏的完整实例
-   **[钱包示例.ts](https://npmcn.com/package/%40block52/poker-vm-sdk/examples/wallet-example.ts)** - 钱包的建立和管理

举例来说:

```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
```

## 发展

### 来源建筑

```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
```

### 发布到 npm

SDK在创建发行时通过GitHub Actions自动发布到npm.

#### 自动出版程序

1.  **更新版本** 内 `package.json`数字 :
    
    ```bash
    cd sdk
    # Edit package.json to update version (e.g., "1.1.9")
    ```
    
2.  **提交和推** 版本更改 :
    
    ```bash
    git add package.json
    git commit -m "chore: update SDK version to 1.1.9"
    git push
    ```
    
3.  **创建 GitHub 发布** 带有标签匹配 `sdk-v*`数字 :
    
    ```bash
    gh release create sdk-v1.1.9 --title "SDK v1.1.9" --notes "Release notes here"
    ```
    

GitHub 动作工作流程将自动:

-   安装依赖关系
-   运行测试
-   构建 SDK
-   校验软件包。 json 版本匹配发行标记
-   向 npm 公开发布

**重要注释 :**

-   释放标签必须从 `sdk-v` (例如, `sdk-v1.1.9`(中文(简体) )
-   版本在 `package.json` 必须匹配标签版本(例如, `1.1.9` 标记 `sdk-v1.1.9`(中文(简体) )
-   这个 `NPM_TOKEN` 密钥必须在 GitHub 仓库设置中配置
-   工作流程使用 `--ignore-scripts` 跳过 `prepublishOnly` 脚本已构建 SDK

### 项目结构

```
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)
```

## 类型脚本支持

这个SDK被用TypeScript来写,包括了完整的类型定义. 无额外 `@types` 需要软件包.

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

### 光圈类型

SDK定义了 **单一真相来源** 所有游戏类型:

-   **`GameStateResponseDTO`** - 线上游戏数据的根类型
-   **`TexasHoldemStateDTO`** - 游戏状态( 包含) `players`, (中文(简体) ), `communityCards`页:1
-   **`GameOptionsDTO`** - 游戏配置( 无) `format` 或者说 `owner` - 使用根字段)
-   **`PlayerDTO`** - 玩家资讯

见 [克劳德·姆德](https://npmcn.com/package/%40block52/poker-vm-sdk/CLAUDE.md) 为完整的类型规则.

## 浏览器支持

SDK同时在Node.js和浏览器环境中工作. 对于浏览器的使用,可能需要为节点.js内置配置多填充:

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

## 捐款

欢迎捐款! 请看 [主要仓库](https://github.com/block52/poker-vm) 捐款准则.

## 许可证

麻省理工学院执照 - 看 [自由主义](https://npmcn.com/package/%40block52/LICENSE) 详细文件.

## 支助

-   📚 **文档**数字 : [克劳德·姆德](https://npmcn.com/package/%40block52/poker-vm-sdk/CLAUDE.md) - 详细的SDK文档
-   🐛 **问题**数字 : [GitHub 问题](https://github.com/block52/poker-vm/issues)
-   💬 **讨论情况**数字 : [GitHub 讨论](https://github.com/block52/poker-vm/discussions)
-   🌐 **网站**数字 : [块52](https://block52.xyz/)

## 相关项目

-   [扑克车VM](https://github.com/block52/poker-vm) - 主要仓库
-   [扑克机UI](https://github.com/block52/poker-vm/tree/main/ui) - 网上扑克客户端
-   [扑克瓶](https://github.com/block52/poker-vm/tree/main/bot) -AI扑克机器人

## 更改日志

见 [释放](https://github.com/block52/poker-vm/releases) 用于版本历史和更改.

## 常见问题

### @block52/poker-vm-sdk 是什么？

Block52 扑克VM 的脚本 SDK

### 如何安装 @block52/poker-vm-sdk？

在项目目录运行 npm install @block52/poker-vm-sdk，或使用 pnpm add / yarn add / bun add。

### @block52/poker-vm-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @block52/poker-vm-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @block52/poker-vm-sdk 可以商用吗？

@block52/poker-vm-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @block52/poker-vm-sdk 的下载量有多少？

根据 npm 官方下载统计，@block52/poker-vm-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 3,038 次，日均约 101 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @block52/poker-vm-sdk 还在维护吗？

最新版本 1\.24\.0 发布于 2026/11/05（3 天前）；至今共发布 69 个版本，其中过去 12 个月发布了 69 个；首次发布于 2025/12/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。