Developers Guide

Alpha Release

This is an alpha release of the Chia Gaming system. The codebase is subject to change, and breaking changes may occur in future versions. Use this system for development and testing purposes.

Funds Left On-Chain

When using a live WalletConnect instance, funds will be left on-chain after shutdown. Upon shutdown, a new game is created, leading to one game's worth of funds being left on-chain and not returned to users. For example, if the game stake is 10 mojo, then 10 mojos will remain on-chain after shutting down the session (once per lobby not per game). Use the simulator for development to avoid this issue. This is a high priority issue which we are working to fix ASAP.

Easy Developer Config Coming Soon

The easy developer configuration is still in development. Currently, parameters need to be manually coded. See the Manual Configuration section below for details.

Intro

This guide covers the development, testing, and deployment process for the Chia Gaming system. The system consists of two Docker images: the lobby server and the game code server.

To follow this guide, you will need:

Linux operating system
Docker (latest version recommended)
Chia 2.5.7 (for WalletConnect testing)
Access to the chia-gaming repository

For game rules and mechanics, see:

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

Dependencies and Setup

Developer Dependencies

Operating System: Linux
Containerization: Docker (latest version recommended)
Chia Wallet: Chia 2.5.7 (only needed for live WalletConnect testing/playthroughs, not required for simulator testing)
Codebase: Access to the chia-gaming repository or the Docker images
Testing (Optional): Firefox or Chrome, and their respective Selenium drivers for running automated tests

User Dependencies

Chia Wallet: Chia 2.5.7 (light wallet, full node not required)
Blockchain Data: The backend connects to coinset.org for blockchain data. Users' wallets perform transaction spends via WalletConnect. Both services are required for gameplay.

Common Issues

For common setup issues and solutions (Docker version, permissions, etc.), see the Known Issues document.

Development Workflow

Setup and Build

Get the Codebase: Choose one of the following options:

Option A: Clone the Repository:
```
git clone https://github.com/Chia-Network/chia-gaming.git
cd chia-gaming
```
Option B: Use Docker Images from Releases: Download the Docker images from the chia-gaming releases page.
Install Dependencies: Ensure all developer dependencies (Linux, Docker, Chia 2.5.7) are installed and configured.
Manual Configuration (Optional): If you need to customize network settings, WalletConnect project info, ports, or domain, see the Manual Configuration section below.
Build Docker Images:
```
./build-docker-images.sh
```
This command automatically configures both Docker images, compiles any new code within those images, and then launches both the lobby server and game code server.
Port Configuration
Ports are manually coded in the build-docker-images.sh and run-docker-demo.sh scripts. The default ports are:
- Port 3000: Frontend web interface (game UI)
- Port 3001: Lobby server API
- Port 5800: Simulator service
To change ports, edit these scripts directly.
Run Docker Images (if not automatically started):
```
./run-docker-demo.sh
```
Note: The build command automatically runs this once complete.

Making Code Changes

Repository Required

To make code changes, you must have cloned the repository (Option A from the Setup and Build section). Code changes cannot be made when using Docker images from releases (Option B).

Edit Source Code: Make your changes to the codebase.
Rebuild Docker Images: After making changes, rebuild the Docker images:
```
./build-docker-images.sh
```
This will recompile your changes and restart the services.
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 WalletConnect instance.

Using Simulator (Recommended for Development):

Navigate to the game server URL (typically http://localhost:3000)
Enable the simulator option in the UI
Create a room and copy the generated room link
Open a different web browser, user profile, or incognito/private window
Paste the room link to join as the second player using the simulator

Using Live WalletConnect (Advanced Testing):

Funds Left On-Chain

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 (computers) with separate wallet installations.

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)
Use two different computers or systems, each with its own Chia wallet installation
Each player connects their separate wallet via WalletConnect
Follow the standard game flow with both players using their respective wallets

Viewing Logs

View Docker container logs for debugging:

# View all container logs
docker ps  # Get container IDs
docker logs <container-id>

# Follow logs in real-time
docker logs -f <container-id>

Running Individual Services

For development, you may want to run services separately. See the repository documentation:

Lobby Server: See the Lobby Server documentation for running the lobby service individually
Game Server: See the Game Server documentation for running the game service individually

Verification

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

Check Docker Containers: Ensure both containers are running:
```
docker ps
```
You should see containers for both the lobby server and game server.
Test with Simulator:
- Navigate to http://localhost:3000 (or your configured port)
- Enable simulator mode
- Create a room and test the connection
Test with Live WalletConnect:
- Connect a Chia wallet via WalletConnect
- Verify the connection is established
- Test creating a room

Check Network Connectivity: Ensure the backend can reach coinset.org:

# For mainnet
curl https://coinset.org
# For testnet
curl https://testnet11.api.coinset.org

Deploy to Production

Config Directory Not Yet Available

The config directory feature is not yet implemented. This is a known issue. Currently, you must manually update configuration values in the codebase as described in the Manual Configuration section.

Manual Configuration: Update all necessary production-specific configurations manually in the codebase (e.g., live network settings, correct ports, production domain).
Build Images: Build the production Docker images:
```
./build-docker-images.sh
```
Launch Images: Launch the built Docker images on your production server(s).

Distribution

Each image (lobby server and game code server) can be launched on separate physical or virtual servers. Once the config directory feature is available, you'll be able to update the relevant server address parameters through configuration files.

Manual Configuration

Manual Configuration Required

The easy developer configuration is still in development. Currently, developers must manually update various parameters in the codebase before building and deploying.

Network Updates

To configure the network settings (e.g., switching to testnet), update the following files:

agg_sig_additional change to testnet constant:

File: src/common/constants.rs
Location: Line 32

Update the AGG_SIG_ME_ADDITIONAL_DATA constant to the testnet value. Replace the mainnet array with:

pub const AGG_SIG_ME_ADDITIONAL_DATA: [u8; 32] = [
    0xe3, 0xb0, 0xc4, 0x42, 0x98, 0xfc, 0x1c, 0x14, 0x9a, 0xfb, 0xf4, 0xc8, 0x99, 0x6f, 0xb9, 0x24,
    0x27, 0xae, 0x41, 0xe4, 0x64, 0x9b, 0x93, 0x4c, 0xa4, 0x95, 0x99, 0x1b, 0x78, 0x52, 0xb8, 0x55,
];

View in repository

chain_id to testnet:
- File: resources/gaming-fe/src/constants/env.ts
- Location: Line 3
- Update the chain_id to testnet: chia:testnet
- View in repository
coinset URL for testnet:
- Update all instances of coinset.org to the testnet endpoint: https://testnet11.api.coinset.org
- This includes (but is not limited to):
  - File: resources/nginx/game.conf (Content Security Policy header, line 17)
  - File: resources/lobby-service/src/index.ts (Content Security Policy header, line 48)
  - Any other files that reference coinset.org
- View examples in repository

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.

Once you have your Project ID, update the following:

Project ID:
- File: resources/gaming-fe/src/constants/env.ts
- Location: Line 1
- Update the WalletConnect project ID with your registered Project ID
- View in repository
Project Info:
- File: resources/gaming-fe/src/constants/wallet-connect.ts
- Location: Line 52
- Update the WalletConnect project information with your project details
- View in repository

Ports and Domain Updates

Default Ports:

The default Docker configuration exposes the following ports:

Port 3000: Frontend web interface (game UI)
Port 3001: Lobby server API
Port 5800: Simulator service

Port Configuration

Ports are manually coded in the Docker build and run commands within build-docker-images.sh and run-docker-demo.sh. To change ports, edit these scripts directly.

For production deployments, ports and domain should be configured via the methods documented in the repository:

Game Server: See the Game Server documentation for configuring ports and domain
Lobby Server: See the Lobby Server documentation for configuring ports and domain

Intro​

Dependencies and Setup​

Developer Dependencies​

User Dependencies​

Development Workflow​

Setup and Build​

Making Code Changes​

Testing​

Viewing Logs​

Running Individual Services​

Verification​

Deploy to Production​

Manual Configuration​

Network Updates​

WalletConnect Project Info Updates​

Ports and Domain Updates​