Battleship

A trustless, on-chain Battleship game implementation using Zero-Knowledge Succinct Non-Interactive Arguments of Knowledge (ZK-SNARKs) for complete anti-cheat guarantees.

Overview

This project implements a fully trustless Battleship game where players cannot cheat due to cryptographic guarantees. Ship positions remain private until game end, and all game actions are verified through zero-knowledge proofs before being accepted on-chain.

Table of Contents

• Prerequisites
• Quick Start
• Installation
• Usage
• Project Structure
• Architecture
• Development
• Troubleshooting
• Resources

Prerequisites

Required Software

• Node.js (v22+) with Pnpm (v10+)
• Docker or Podman for running services
• Foundry for smart contract development
• Just as task runner (recommended, cargo install just)

⚠️ Version Requirements ⚠️

Please verify you're running Node.js v22+ and Pnpm v10+ before proceeding. Older versions may cause compatibility issues. Check your versions with node --version and pnpm --version.

Optional Tools

• Nix for complete development environment setup
• Circom (2.1.0+) for compiling our circuits (installation guide)

GitHub Container Registry

The amp Docker image is currently hosted in our private GitHub container registry. In order to access it, you'll have to login to ghcr.io with Docker. Create a new personal access token (classic) with the read:packages permission at https://github.com/settings/tokens. Now run the following command and insert the newly generated token as your password when prompted.

docker login ghcr.io --username <YOUR GITHUB USERNAME>

Quick Start

1. Clone and install dependencies:

   # NOTE: Make sure to use `--recursive` to also clone the `forge-std` git submodule 
   git clone --recursive <repository-url>
   cd battleship
   just install

2. Start services:

   just up

3. Deploy contracts:

   just deploy

4. Start development servers:

   just dev

5. Open your browser:

   • Game interface: http://localhost:5173
   • Database explorer: http://localhost:7402
   • Monitoring: http://localhost:3030

Installation

1. Environment Setup

Clone the repository (with --recursive) and install dependencies:

# NOTE: Make sure to use `--recursive` to also clone the `forge-std` git submodule 
git clone --recursive <repository-url>
cd battleship
just install

2. Start Infrastructure Services

Launch PostgreSQL, Anvil (local Ethereum), and other services:

just up

This starts:

• PostgreSQL (port 5432) - Database backend
• Anvil (port 8545) - Local Ethereum node
• Amp (ports 1602, 1603, 1610) - Data engineering layer
• Adminer (port 7402) - Database explorer
• Grafana (port 3030) - Monitoring dashboard

3. Build ZK-SNARK Circuits (optional)

This is an optional step. The repository contains pre-built circuits. You'll only need to run this if you are modifying the circuits.

Compile circuits and generate verification keys:

just circuits

This process:

• Downloads Powers of Tau ceremony file (if needed)
• Compiles Circom circuits to R1CS
• Runs trusted setup ceremony with random entropy
• Exports Solidity verifier contracts
• Copies circuit files to frontend

4. Deploy Smart Contracts

Deploy the Battleship contract to local network:

just deploy

5. Start Application

Start the application frontend and the Amp development & proxy servers.

just dev

Usage

Development Commands

Basic Operations

• just install - Install all dependencies
• just up [services] - Start infrastructure services
• just dev - Run all development services in parallel
• just down - Stop all services and clean up

Circuit Development

• just circuits - Build all circuits with full ceremony
• just circuits board - Build only board validation circuit
• just circuits impact - Build only impact verification circuit

Testing and Quality

• just test - Run all tests (Solidity + TypeScript)
• just check - Run linting and type checking
• just fmt - Format all code

Monitoring

• just logs - View logs from all services
• just logs postgres - View PostgreSQL logs only
• just stop - Stop services without cleanup

Game Development Workflow

1. Make circuit changes in circuits/
2. Rebuild circuits: just circuits
3. Run tests: just test
4. Redeploy contracts (if needed): just deploy
5. Test in browser: Game runs at http://localhost:5173

Testing

Run comprehensive test suite covering anti-cheat mechanisms:

# All tests
just test

# Specific test patterns
just test-sol --match-path "**/Battleship.t.sol"
just test-ts circuit

Project Structure

battleship/
├── circuits/                 # ZK-SNARK circuits
│   ├── board.circom         # Board validation circuit
│   ├── impact.circom        # Impact verification circuit
│   └── build/               # Compiled circuit artifacts
├── contracts/               # Smart contracts
│   ├── src/Battleship.sol   # Main game contract
│   ├── src/*Verifier.sol    # Generated proof verifiers
│   └── test/                # Comprehensive test suite
├── app/                     # Frontend application
│   ├── src/components/      # React components
│   ├── src/lib/            # Blockchain utilities
│   └── public/circuits/    # Circuit files for browser
├── infra/                  # Infrastructure configuration
│   ├── postgres/           # Database setup
│   ├── amp/            # Data indexing config
│   └── grafana/           # Monitoring dashboards
├── justfile               # Development commands
└── docker-compose.yaml    # Service orchestration

Architecture

ZK-SNARK Workflow

1. Board Setup: Players generate cryptographic commitments to their ship positions using the board circuit
2. Game Turns: Each attack requires a zero-knowledge proof from the defender using the impact circuit
3. State Chain: Game states are linked through commitments to prevent tampering
4. Verification: Smart contract validates all proofs before accepting state transitions

Circuit Details

Board Circuit (board.circom)

• Purpose: Validates ship placement follows game rules
• Inputs: Ship positions + random salt (private)
• Outputs: Board commitment + initial state commitment
• Validates: Bounds checking, no overlaps, correct ship lengths

Impact Circuit (impact.circom)

• Purpose: Proves hit/miss results and maintains game state integrity
• Inputs: Previous state, attack coordinates, ship positions (private)
• Outputs: New state commitment, remaining ships count
• Validates: State consistency, hit detection, claim accuracy

Anti-Cheat Mechanisms

• Ship Movement Prevention: Board commitments lock ship positions
• False Claims Prevention: Impact proofs cryptographically verify hit/miss results
• State Manipulation Prevention: Commitment chains prevent tampering
• Double-Shot Prevention: On-chain tracking with bit-packed grids

Development

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the full test suite: just test
5. Format code: just fmt
6. Commit and push changes
7. Open a pull request

Service URLs

• Frontend: http://localhost:5173
• Database Explorer: http://localhost:7402 (user: postgres, pass: postgres)
• Ethereum RPC: http://localhost:8545
• Grafana Monitoring: http://localhost:3030
• Amp Admin: http://localhost:1610

Development Tips

• Use just logs to monitor service health
• Check just --list for all available commands
• Circuit artifacts are automatically copied to app/public/circuits/

Resources

Documentation

• ZK-SNARK Technical Details - Comprehensive technical documentation
• Circom Documentation - Circuit development
• snarkjs Guide - Proof generation and verification
• Foundry Documentation - Smart contract development

---

For technical implementation details, see BATTLESHIP.md.