跳到主要内容

Developers Guide

Early beta

This is an early beta of the Chia Gaming system. It works, but bugs are still likely. Compatibility is best-effort: wire formats, persistence, and APIs can still change. Use this system for development and testing.

Intro​

This guide covers development, testing, and deployment for the Chia Gaming system.

The player app is one React + WASM bundle (front-end/). It contains the wallet connection, game engine, and all game UIs. No server-side logic, no cookies, no server-side sessions. That same bundle ships two ways:

Hosted player appElectron desktop
What it isStatic HTML/JS/CSS/WASM on any web serverNative installer wrapping that same bundle in a hardened Electron shell (desktop/)
How players open itBrowser URL (local demo: http://localhost:3002)Installed app (chiagaming://app)
SimulatorAvailable in the local/web buildHidden — use Link Wallet for live play
HubStill required (iframe + WebSocket on a different origin)Same hub; the shell allowlists hub origins
Build./run-local-demo.sh or ./tools/build-deploy.sh./tools/build-electron.sh --platform=mac (or win / linux), or download 0.4.0-beta.1

A hub is a separate service: matchmaking UI (iframe inside the player app) and a WebSocket relay between peers. Hubs are third-party code; anyone can run one. The desktop app does not replace the hub — you still run or join one.

Details of the desktop shell (CSP, network allowlist, config.json) are in desktop/README.md. The 0.4.0-beta.1 macOS and Windows installers are unsigned; macOS Gatekeeper and Windows SmartScreen warnings are expected. Verify downloads against the SHA-256 checksum files on the same release.

A Cloud Wallet connection option is under development and is not ready for use. For live testing, use Link Wallet (WalletConnect).

To follow this guide, you will need:

  • Linux, macOS, or Windows with Git Bash / WSL (the local demo scripts are bash)
  • Rust (stable; pinned in the repo’s rust-toolchain.toml) with the wasm32-unknown-unknown target
  • Node.js 22+ and pnpm 10.33
  • wasm-pack 0.15.0
  • Chia wallet 2.7.1 or later (required minimum for live WalletConnect; earlier wallet versions are not supported)
  • Access to the chia-gaming repository
Reference games

California Poker, Space Poker, and Krunk are the beta reference games. On-chain Chialisp, rules, and UI may still change.

For game rules and mechanics, see:

To add a game, start from GAME_WRITING_GUIDE.md in the chia-gaming repository. Games live in games/<key>/{clsp,ui} (optional rust/ for tests) and register in games/registry.json.

For information about becoming a gaming partner, see the Gaming Partner RFP.

Dependencies and Setup​

Developer Dependencies​

  • Operating System: Linux, macOS, or Windows with Git Bash / WSL for ./run-local-demo.sh and the other bash build scripts
  • Rust (stable) with wasm32-unknown-unknown target: the chia-gaming rust-toolchain.toml pins the channel and targets when you build from a clone: 
    rustup target add wasm32-unknown-unknown
  • wasm-pack 0.15.0: 
    cargo install wasm-pack --version 0.15.0
  • Node.js 22+ and pnpm 10.33: 
    corepack enable
    corepack prepare [email protected] --activate
  • macOS only: Homebrew LLVM for WASM builds (brew install llvm). Build scripts automatically detect and use it.
  • Chia Wallet: Chia 2.7.1 or later (only needed for live WalletConnect testing, not required for simulator testing)
  • Codebase: Access to the chia-gaming repository or the release artifacts

User Dependencies​

  • Chia wallet: 2.7.1 or later (light wallet is sufficient; a local full node is not required for players)
  • WalletConnect (live play): Each player connects their wallet via Link Wallet. The player app uses wallet RPC methods (for example chia_getCoinRecordsByNames, chia_createOfferForIds, chia_cancelOffer, chia_pushTransactions) through that connection (front-end/src/hooks/RealBlockchainInterface.ts). Set a transaction fee in the Wallet tab for live spends; the default is 100,000,000 mojos (0.0001 XCH). You can set 0 for a free transaction. A nonzero fee below 100,000,000 mojos is treated as zero (front-end/src/constants/fees.ts) and can be rejected by the mempool. Reconnect the same wallet account that funded the session; a different account is treated as a mismatch and is not used for funding or cleanup.
  • Simulator (development): For testing without real XCH, use simulator mode and the chia-gaming-sim binary started by run-local-demo.sh (single port 5800: HTTP /health and WebSocket /ws; see front-end/src/settings.ts).
  • Cloud Wallet: Integration is in progress but not complete. Do not rely on the Cloud Wallet button for testing yet.
Common Issues

For common setup issues and solutions, see the Known Issues document.

Development Workflow​

Quick Start (Local Demo)​

The fastest way to get started is run-local-demo.sh, which builds everything (including tools/build-chialisp.sh and a --dev WASM build for faster iteration) and starts three services:

git clone https://github.com/Chia-Network/chia-gaming.git
cd chia-gaming
./run-local-demo.sh
ServiceDefault URLOverride env var
Player apphttp://localhost:3002GAME_PORT
Hubhttp://localhost:3003HUB_PORT
Simulatorhttp://localhost:5800 (HTTP and /ws)(hardcoded)

Flags:

  • --skip-build: skip all build steps, use existing artifacts
  • --force-build: cargo clean before building

Press Ctrl-C to stop all services.

You can play on the simulator or on live chain with the files hosted locally. Live WalletConnect play needs Chia Wallet 2.7.1 or later with spendable funds (the repository documents a practical minimum of 1000 mojos for mainnet smoke tests). To try the same player bundle as a desktop app instead of :3002, keep the hub (and simulator, if you need it) from this script and launch Electron from desktop/README.md — the desktop UI hides the simulator.

Using Release Artifacts​

Local development: ./run-local-demo.sh builds everything, assembles the nonce-based staging trees (build-meta.json, assets under app/<nonce>/), and starts the player app, hub, and simulator.

Release binaries: The current cut is 0.4.0-beta.1. Hosted player and hub archives come from tools/build-deploy.sh (.zip and .tgz with the same contents):

  • chia-gaming-0.4.0-beta.1.zip / .tgz: hosted player app (index.html, build-meta.json, app/<nonce>/ with JS, CSS, WASM, and compiled CLVM)
  • chia-gaming-hub-0.4.0-beta.1.zip / .tgz: hub (same staging layout, plus service.js at the archive root)

Those archives are what you extract onto a web server. They are not the Electron installers. Local builds that omit --release-version still use a date-and-hash stamp instead of the tag name.

Build the hosted archives with ./tools/build-deploy.sh (see DEVELOPMENT.md). Pass --release-version=<tag> when you want tag-named archives. The staged layout matches what run-local-demo.sh assembles locally (file copies under front-end/serve and hub/hub-frontend/serve).

Electron desktop: Installers are on the same release, or you can build them with ./tools/build-electron.sh --platform=mac (or win / linux). That packages the same player bundle under desktop/release/. The hub is still a separate process.

0.4.0-beta.1 desktop files:

  • macOS: chia-gaming-0.4.0-beta.1-mac-universal.dmg and .zip
  • Windows: chia-gaming-0.4.0-beta.1-win-x64.exe
  • Linux: chia-gaming-0.4.0-beta.1-linux-x86_64.AppImage and chia-gaming-0.4.0-beta.1-linux-amd64.deb

The macOS and Windows installers in this beta are unsigned. macOS Gatekeeper and Windows SmartScreen warnings are expected. Verify downloads against SHA256SUMS-mac.txt, SHA256SUMS-win.txt, SHA256SUMS-linux.txt, or SHA256SUMS-web.txt on the same release. See desktop/README.md.

To run the hub from a release zip:

PORT=3003 node service.js --self 'https://your-hub.example' --dir /path/to/extracted-hub-archive

Building Step by Step​

For production packaging or partial rebuilds. Run commands from the repo root. The full sequence is documented in DEVELOPMENT.md and mirrored in tools/build-deploy.sh.

1. Chialisp:

./tools/build-chialisp.sh

This is the sole entry point for compiling .clsp sources. The compiler emits .hex, then the build decodes those into .clvm.bin artifacts. For each game it also prepares the runtime factory. Ordinary Cargo commands do not compile Chialisp.

2. WASM (browser target):

cd wasm && wasm-pack build --out-dir=../front-end/dist --release --target=web

For development, use --dev instead of --release (faster builds, larger output).

3. Player app (frontend JS/CSS):

pnpm install --frozen-lockfile
pnpm --filter chia-gaming-fe run build

4. Hub frontend:

pnpm --filter chia-gaming-hub-frontend run build

5. Hub service:

pnpm --filter chia-gaming-hub-service run build

If pnpm install warns about ignored build scripts, that is expected (see Known Issues).

6. Simulator (development only):

cargo build --features sim-server --bin chia-gaming-sim

Listens on port 5800, serving GET|POST /health over HTTP and the simulator API over WebSocket at /ws.

Making Code Changes​

  1. Edit Source Code: Make your changes to the codebase.

  2. Rebuild: After making changes, rebuild the affected components. For quick iteration, use --skip-build with run-local-demo.sh if you only changed frontend code, or rebuild individual steps as needed.

  3. Test Changes: Use the simulator (recommended) or live WalletConnect to test your modifications.

Testing​

Simulator Recommended

For development, it is recommended to use the simulator for testing game logic without interacting with a real Chia wallet.

Using Simulator (Recommended for Development):

  1. Start the local demo with ./run-local-demo.sh
  2. Navigate to the player app URL (http://localhost:3002)
  3. Choose Continue with Simulator
  4. Connect both browsers to the same hub (http://localhost:3003 in the local demo)
  5. Open a different web browser, user profile, or incognito/private window
  6. Challenge the other player from the hub UI and accept the challenge

Using Live WalletConnect (Advanced Testing):

Two Separate Wallet Instances Required

When testing with live WalletConnect (not simulator), you must use two different Chia wallet instances. You cannot use the same wallet or installation for both players. The easiest approach is to deploy the gaming system to a URL accessible by both computers and use two different systems with separate wallet installations.

  1. Deploy the gaming system to a URL accessible by both computers (does not need to be publicly accessible; local network, VPN, or other private network setup is sufficient)
  2. Use two different computers or systems, each with its own Chia wallet installation (2.7.1 or later)
  3. Each player connects their separate wallet via WalletConnect and, for live chain, sets a transaction fee in the Wallet tab (default 100,000,000 mojos; see Manual Configuration)
  4. Both players connect to the same hub, then one player challenges the other

Viewing Logs​

View service logs for debugging:

# Logs appear in the terminal where run-local-demo.sh is running
# For more control, run services separately (see Building Step by Step)

Verification​

After building and launching the system, verify it's working correctly:

  1. Check Services: Ensure all three services are accessible:

    curl http://localhost:3002  # Player app
    curl http://localhost:3003  # Hub
    curl http://localhost:5800/health  # Simulator

  2. Test with Simulator:

    • Navigate to http://localhost:3002
    • Choose Continue with Simulator
    • Connect to the local hub and challenge a second browser

  3. Test with Live WalletConnect:

    • Connect a Chia wallet (2.7.1 or later) via WalletConnect
    • Confirm the player-app network setting matches the wallet (mainnet or testnet11)
    • Connect to a hub and test a challenge

  4. Check WalletConnect (live play only): Confirm each test wallet is connected, synced, and approving pending requests in the Chia wallet UI.

Deploy to Production​

For detailed deployment instructions including asset layout, caching rules, and production configuration, see DEVELOPMENT.md in the chia-gaming repository.

Key points:

  • The hosted player app and hub must be served from different origins (the hub UI loads inside an iframe)
  • WASM files and compiled CLVM artifacts must be under the same basePath as index.js
  • No simulator in a production hosted deploy or in the Electron app: players connect a Chia wallet via WalletConnect (Link Wallet)
  • Cloud Wallet integration is not complete; do not require it for a production deploy yet
  • Use tools/build-deploy.sh for hosted zip/tgz archives; use tools/build-electron.sh for desktop installers. Both wrap the same front-end/ bundle. The hub is packaged only with build-deploy.sh. The 0.4.0-beta.1 macOS and Windows installers are unsigned; verify downloads against the published SHA-256 checksums.

Manual Configuration​

Network​

The player app has a mainnet / testnet preference. WalletConnect uses chia:mainnet or chia:testnet (testnet11 genesis challenge) from front-end/src/constants/env.ts. The local simulator always verifies spends against the hardcoded mainnet AGG_SIG_ME additional data, so simulator sessions use mainnet genesis even if the UI preference says otherwise.

Live play requires the connected wallet to be on the same network the player app selected. A cross-network match is rejected before consent. For development without real XCH, use the simulator.

Optional CI/testing overrides: CHIA_GAMING_CHAIN_ID and CHIA_GAMING_GENESIS_CHALLENGE (or the matching window.__CHIA_GAMING_*__ values).

Transaction fees​

Live WalletConnect spends can include a fee from the player app Wallet tab (defaultFee in session preferences). The default is 100,000,000 mojos (0.0001 XCH). You can set 0 for a free transaction. The mempool treats a fee below 100,000,000 mojos as effectively zero (MIN_NONZERO_FEE_MOJOS in front-end/src/constants/fees.ts); the UI refuses to save a nonzero value in that range. A nonzero fee is built as a validate-only chia_createOfferForIds offer, converted in WASM, and aggregated into the protocol bundle before chia_pushTransactions. If the wallet cannot sign that fee offer, the app still submits the protocol spend without a fee and warns. Simulator play does not use this path.

WalletConnect Project Info Updates​

To configure WalletConnect settings, you'll need to obtain a WalletConnect Project ID. For registration and troubleshooting, refer to the WalletConnect documentation and your WalletConnect account dashboard.

The repository ships a default WalletConnect Project ID in front-end/src/constants/env.ts for development. Production or partner deployments should register their own project at WalletConnect Cloud and replace that value before building the player app.

Once you have your Project ID, update:

  1. Project ID: front-end/src/constants/env.ts: update PROJECT_ID (and RELAY_URL if needed)
  2. Chain and methods: front-end/src/constants/wallet-connect.ts: update REQUIRED_NAMESPACES / ChiaMethod if the wallet API changes (must match what the player app calls in RealBlockchainInterface.ts)

Port Configuration​

Default ports for run-local-demo.sh:

  • Port 3002: Player app (frontend web interface)
  • Port 3003: Hub (matchmaking UI + relay service)
  • Port 5800: Simulator (HTTP /health and WebSocket /ws)

Override with environment variables:

GAME_PORT=4000 HUB_PORT=4001 ./run-local-demo.sh

The hub process itself still defaults to port 5801 if PORT is not set. Always set PORT (or HUB_PORT via the demo script) so it does not collide with other local services.

For production deployments, see DEVELOPMENT.md in the repository for port and domain configuration.