Skip to content
BranchesTags

Repository files navigation

Kaspa Arena

中文 | English

Kaspa Arena 是一个用于验证 Kaspa 最新 covenant / SilverScript 能力的实验项目。当前版本实现了一个基于 Kaspa Testnet 10 的五子棋对战网站：两位玩家使用 TN10 钱包入座、签名锁定押注，胜负产生后通过 kascov-lab 的 covenant escrow 结算路径把测试币释放给胜方。

这个项目不是生产级博彩、游戏或钱包产品。它的目标是让更多开发者可以直观看到 Kaspa covenant 在真实对局中的资金锁定、胜负触发和链上释放流程。欢迎大家 fork、测试、改进、审计和提出更好的实现方式。

当前能力

  • 五子棋 1v1 房间。
  • 基于钱包地址的黑白双方座位。
  • 房间链接分享。
  • 创建者可以删除无人入座的空房间。
  • TN10 测试币领取到玩家钱包。
  • 两位玩家各自用钱包签名，把押注锁入 TN10 SilverScript escrow。
  • 五连胜负触发链上结算。
  • 胜方/败方弹窗和音效。
  • 链上托管、结算交易、Kascov covenant story 链接展示。
  • 中英双语，并按浏览器语言自动选择默认语言。
  • 主网接口保留，但默认只面向 TN10 测试网。

实现路径

1. 房间与对局

服务端使用 Node.js 原生 HTTP 服务维护当前房间状态。玩家连接钱包后进入房间，服务端按入座顺序分配：

  • seat 0: 黑棋
  • seat 1: 白棋

棋盘状态包括：

  • roundId
  • board
  • turn
  • moves
  • winner
  • winnerAddress
  • settlementId

每一局都有独立 roundId，避免旧一局的 escrow 状态污染新一局。

2. 钱包与测试币

前端优先连接兼容 Kasware 接口的钱包。项目也配套使用过一个 TN10 signer 插件，用于测试 getPublicKey 和 signPskt 之类的钱包能力。

测试币领取逻辑由后端热钱包广播 TN10 转账到用户钱包：

  • 每次最多领取 200 TN10 KAS
  • 每个钱包最多领取 2000 TN10 KAS

注意：这是测试网资金，只用于验证流程。

3. Covenant escrow 草案

合约设计草案位于：

contracts/gomoku_escrow.sil

核心思路：

  • 黑棋、白棋分别锁定同额押注。
  • escrow 持有双方押注总额。
  • 胜负产生后走 winner release path。
  • 当前站点使用 kascov-lab 的 escrow settle 命令完成实际 TN10 covenant 结算验证。
  • refund 思路在合约草案中保留，但当前站点没有把双方退款路径作为已完成生产功能暴露。

4. 玩家签名锁仓

当前流程是：

  1. 两位玩家进入同一房间。
  2. 玩家点击确认锁定押注。
  3. 前端请求服务端生成 player-funded covenant draft。
  4. 钱包对各自输入签名。
  5. 服务端收集双方签名。
  6. 双方签名合并完成后，广播 TN10 Toccata v1 covenant transaction。
  7. 交易广播成功后，房间进入可落子状态，黑棋先手。

为了避免第一手计时提前开始，倒计时只在链上托管广播成功后启动。

5. 胜负与结算

服务端检测五连：

  1. 玩家落子。
  2. 服务端验证是否五连。
  3. 如果胜负产生，记录 transcript / winner。
  4. 调用 kascov-lab 走 escrow release path。
  5. 结算交易广播到 TN10。
  6. 前端刷新钱包余额、托管状态、结算凭证和 Kascov story 链接。

前端展示的凭证包括：

  • Covenant ID
  • 托管交易
  • 结算交易
  • 释放路径：buyer / seller
  • 释放金额
  • 胜方钱包地址
  • Kascov Explorer story

技术结构

.
├── contracts/
│   └── gomoku_escrow.sil        # SilverScript escrow design draft
├── public/
│   ├── index.html               # UI shell
│   ├── app.js                   # wallet, room, board, i18n, game UI
│   └── styles.css               # Kaspa-inspired visual style
├── kascov-blake2b.js            # local helper from kascov tooling
├── kascov-disasm.js             # local helper from kascov tooling
├── server.js                    # HTTP API, TN10 tx, covenant draft/settle
├── package.json
└── README.md

本地运行

要求：

  • Node.js 20+
  • TN10 测试钱包
  • 可选：本地或服务器上的 kascov-lab

安装依赖：

npm install

启动：

npm start

默认监听：

http://0.0.0.0:3000

关键环境变量

PORT=3000
HOST=0.0.0.0
KASPA_NETWORK=tn10
KASPA_TN10_REST_API=https://api-tn10.kaspa.org
KASCOV_LAB_BIN=/path/to/kascov-lab
KASCOV_LAB_KEY_FILE=/path/to/kascov-lab-key.hex
KASPA_TN10_DEPOSIT_ADDRESS=kaspatest:...
KASPA_MAINNET_DEPOSIT_ADDRESS=kaspa:...

运行时还会使用：

  • tn10-wallet.json：测试币发放热钱包。
  • data/kascov-lab-key.hex：kascov-lab 使用的私钥文件。
  • data/ledger.json：本地运行记录、测试领取、结算摘要等。

这些文件不应该提交到 GitHub。

API 摘要

房间：

GET    /api/rooms
POST   /api/rooms
DELETE /api/rooms/:roomId
POST   /api/rooms/:roomId/join
POST   /api/rooms/:roomId/leave
GET    /api/rooms/:roomId/gomoku
POST   /api/rooms/:roomId/gomoku/move
POST   /api/rooms/:roomId/gomoku/reset
POST   /api/rooms/:roomId/gomoku/timeout

Covenant：

GET  /api/covenants/status
GET  /api/covenants/escrows
GET  /api/covenants/source/gomoku
GET  /api/covenants/rooms/:roomId/escrow-intent
GET  /api/covenants/rooms/:roomId/escrow/player-deploy-draft
POST /api/covenants/rooms/:roomId/escrow/player-signature
POST /api/covenants/rooms/:roomId/escrow/player-signature/cancel

测试币：

GET  /api/faucet
POST /api/faucet/claim

当前限制

  • 这是实验项目，不建议直接用于主网资金。
  • 当前主要验证五子棋 1v1 covenant escrow。
  • 当前链上退款路径没有作为完整用户功能发布。
  • 钱包端对 Toccata / covenant transaction JSON / PSKT 的支持仍是关键依赖。
  • 结算由服务端根据游戏 transcript 触发，仍需要更严谨的审计和去信任化设计。
  • 主网接口保留，但主网上线前需要重新审计合约、钱包交互和广播路径。

欢迎参与

欢迎大家：

  • 测试不同钱包和浏览器。
  • 改进 SilverScript 合约。
  • 增加更完整的 refund / timeout claim。
  • 优化去中心化裁决方式。
  • 改进前端 UX。
  • 提交 issue / PR。

这个项目的意义不是宣称“已经生产可用”，而是提供一个可以实际触摸、实际签名、实际观察链上 covenant 生命周期的实验场。

致谢

感谢这些项目和社区提供的基础设施与灵感：

Kaspa Arena

Kaspa Arena is an experimental project for validating Kaspa's latest covenant / SilverScript capabilities. The current version implements a Gomoku game website on Kaspa Testnet 10: two players join with TN10 wallets, sign to lock their stakes into an escrow, and after a five-in-a-row result the locked test coins are released to the winner through the kascov-lab covenant escrow path.

This is not a production gambling, gaming, or wallet product. The purpose is to make the Kaspa covenant flow visible and testable: funding, locking, gameplay, winner detection, on-chain release, and proof display. Everyone is welcome to fork it, test it, improve it, audit it, and propose better approaches.

Current Features

  • 1v1 Gomoku rooms.
  • Wallet-address based black/white seats.
  • Shareable room links.
  • Empty rooms can be deleted by their creator.
  • TN10 test coin claims directly to player wallets.
  • Player-funded wallet signatures lock stakes into a TN10 SilverScript escrow.
  • Five-in-a-row triggers on-chain settlement.
  • Victory/defeat dialogs and sounds.
  • Escrow, settlement transaction, and Kascov covenant story links.
  • Chinese and English UI with browser-language default detection.
  • Mainnet interfaces are reserved, while the default deployment targets TN10 only.

Implementation Path

1. Room and Game State

The server is a Node.js HTTP service that keeps active room state in memory. After wallet connection, players enter a room and are assigned by seat order:

  • seat 0: black
  • seat 1: white

Each game round stores:

  • roundId
  • board
  • turn
  • moves
  • winner
  • winnerAddress
  • settlementId

Each round has an independent roundId, so stale escrow records from previous rounds do not affect the next game.

2. Wallets and Test Coins

The frontend connects to wallets that expose Kasware-compatible APIs. During development, a TN10 signer extension was also used to test wallet capabilities such as getPublicKey and signPskt.

The faucet flow sends TN10 test coins from a backend hot wallet to the user's wallet:

  • Maximum 200 TN10 KAS per claim.
  • Maximum 2000 TN10 KAS per wallet.

These are testnet coins only.

3. Covenant Escrow Draft

The contract design draft is located at:

contracts/gomoku_escrow.sil

The core idea:

  • Black and white lock equal stakes.
  • The escrow holds the combined pot.
  • Once a winner is determined, the release follows the winner path.
  • The current website validates real TN10 covenant settlement through kascov-lab's escrow settle command.
  • A refund idea is kept in the contract draft, but a full user-facing mutual refund path is not shipped as a completed production feature.

4. Player-Funded Locking

The current flow:

  1. Two players enter the same room.
  2. Each player confirms stake locking.
  3. The frontend asks the server for a player-funded covenant draft.
  4. Each wallet signs its own input.
  5. The server collects both signatures.
  6. After both signatures are merged, the server broadcasts a TN10 Toccata v1 covenant transaction.
  7. After broadcast succeeds, the game becomes playable and black moves first.

To avoid the first move timing out before the game really starts, the move timer starts only after the on-chain escrow is broadcast successfully.

5. Winner Detection and Settlement

The server detects five-in-a-row:

  1. A player places a stone.
  2. The server checks whether the move creates five in a row.
  3. If there is a winner, the transcript and winner are recorded.
  4. kascov-lab is called to spend the escrow through the release path.
  5. The settlement transaction is broadcast to TN10.
  6. The frontend refreshes wallet balance, escrow status, settlement proof, and Kascov story links.

The proof UI includes:

  • Covenant ID
  • Escrow transaction
  • Settlement transaction
  • Release path: buyer / seller
  • Released amount
  • Winner wallet address
  • Kascov Explorer story

Project Structure

.
├── contracts/
│   └── gomoku_escrow.sil        # SilverScript escrow design draft
├── public/
│   ├── index.html               # UI shell
│   ├── app.js                   # wallet, room, board, i18n, game UI
│   └── styles.css               # Kaspa-inspired visual style
├── kascov-blake2b.js            # local helper from kascov tooling
├── kascov-disasm.js             # local helper from kascov tooling
├── server.js                    # HTTP API, TN10 tx, covenant draft/settle
├── package.json
└── README.md

Local Run

Requirements:

  • Node.js 20+
  • TN10 test wallet
  • Optional: local or server-side kascov-lab

Install dependencies:

npm install

Start:

npm start

Default listen address:

http://0.0.0.0:3000

Important Environment Variables

PORT=3000
HOST=0.0.0.0
KASPA_NETWORK=tn10
KASPA_TN10_REST_API=https://api-tn10.kaspa.org
KASCOV_LAB_BIN=/path/to/kascov-lab
KASCOV_LAB_KEY_FILE=/path/to/kascov-lab-key.hex
KASPA_TN10_DEPOSIT_ADDRESS=kaspatest:...
KASPA_MAINNET_DEPOSIT_ADDRESS=kaspa:...

Runtime files:

  • tn10-wallet.json: test coin hot wallet.
  • data/kascov-lab-key.hex: private key used by kascov-lab.
  • data/ledger.json: local runtime records, test claims, settlement summaries.

Do not commit these files.

API Summary

Rooms:

GET    /api/rooms
POST   /api/rooms
DELETE /api/rooms/:roomId
POST   /api/rooms/:roomId/join
POST   /api/rooms/:roomId/leave
GET    /api/rooms/:roomId/gomoku
POST   /api/rooms/:roomId/gomoku/move
POST   /api/rooms/:roomId/gomoku/reset
POST   /api/rooms/:roomId/gomoku/timeout

Covenants:

GET  /api/covenants/status
GET  /api/covenants/escrows
GET  /api/covenants/source/gomoku
GET  /api/covenants/rooms/:roomId/escrow-intent
GET  /api/covenants/rooms/:roomId/escrow/player-deploy-draft
POST /api/covenants/rooms/:roomId/escrow/player-signature
POST /api/covenants/rooms/:roomId/escrow/player-signature/cancel

Test coins:

GET  /api/faucet
POST /api/faucet/claim

Current Limitations

  • This is an experiment and should not be used directly with mainnet funds.
  • The current validation target is 1v1 Gomoku covenant escrow.
  • A full user-facing refund path is not shipped yet.
  • Wallet support for Toccata / covenant transaction JSON / PSKT remains a key dependency.
  • Settlement is triggered by the server after game transcript validation; more trust-minimized or fully decentralized arbitration is future work.
  • Mainnet hooks are reserved, but mainnet deployment requires a full audit of the contract, wallet interaction, and broadcast path.

Contributions Welcome

You are welcome to:

  • Test more wallets and browsers.
  • Improve the SilverScript contract.
  • Add complete refund / timeout claim support.
  • Improve decentralized result verification.
  • Improve the frontend UX.
  • Open issues and pull requests.

The project does not claim to be production-ready. Its value is that it provides a tangible playground where developers can sign, lock, settle, and inspect the covenant lifecycle on Kaspa TN10.

Acknowledgements

Thanks to these projects and communities:

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages