Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,6 @@ build/
.DS_Store
Thumbs.db

# Deno
deno.lock

# Database
*.db
*.sqlite
Expand Down
48 changes: 24 additions & 24 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,74 +7,78 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
Go Fish card game built on **Paima Engine (Effectstream)** with a hybrid blockchain architecture:
- **EVM (Solidity/Hardhat)**: Lobbies, matchmaking, player stats
- **Midnight (Compact language)**: Private game logic, card shuffling/dealing with ZK proofs
- **Paima Node (Deno)**: State machine processing blockchain events, REST API
- **Paima Node (Bun)**: State machine processing blockchain events, REST API
- **Frontend**: Three.js 3D game scene with HTML overlay screens (Vite + TypeScript)

## Build & Run Commands

```bash
# First time setup
deno install --allow-scripts
bun install

# Build EVM contracts (required before first run)
deno task build:evm
bun run build:evm

# Full stack dev (launches frontend:3000, API:9996, EVM:8545, explorer:10590)
deno task dev
bun run dev

# Dev with batcher mode (no Lace wallet needed)
deno task dev:batcher
bun run dev:batcher

# Dev with TypeScript contract (no Midnight infrastructure needed)
deno task dev:typescript
bun run dev:typescript

# Frontend only
deno task frontend:dev
bun run frontend:dev

# Build Midnight contracts
deno task build:midnight
bun run build:midnight
```

### Testing

```bash
# Run node tests (Deno test runner, api.test.ts)
deno task test
# Run node tests (bun:test, api.test.ts)
bun run test

# Watch mode
deno task --filter @go-fish/node test:watch
bun run --filter @go-fish/node test:watch

# Run a single test file directly
deno test -A --no-check --unstable-raw-imports packages/client/node/src/api.test.ts
bun test packages/client/node/src/api.test.ts

# Midnight contract tests
cd packages/shared/contracts/midnight && deno task test
cd packages/shared/contracts/midnight && bun run test

# EVM contract tests
cd packages/shared/contracts/evm && npx hardhat test

# E2E smoke tests
bun run --filter @go-fish/e2e smoke:imports
bun run test:e2e
```

### EVM Contract Build Details

```bash
# Full compile (forge + hardhat + deploy + artifact generation)
deno task --filter @go-fish/evm-contracts contract:compile
bun run --filter @go-fish/evm-contracts contract:compile

# Individual steps
cd packages/shared/contracts/evm
deno task build:forge # Forge only
deno task build:hardhat # Hardhat only
deno task deploy:standalone # Start chain, deploy, stop
bun run build:forge # Forge only
bun run build:hardhat # Hardhat only
bun run deploy:standalone # Start chain, deploy, stop
```

### Midnight Infrastructure (for full Midnight dev)

```bash
# Terminal 1: Start all Midnight services
EFFECTSTREAM_STDOUT=true deno task -f @go-fish/node midnight:setup
EFFECTSTREAM_STDOUT=true bun run --filter @go-fish/node midnight:setup

# Terminal 2: Dev server connecting to running infra
USE_TYPESCRIPT_CONTRACT=false EFFECTSTREAM_STDOUT=true USE_BATCHER_MODE=true SKIP_MIDNIGHT_INFRA=true deno task dev
USE_TYPESCRIPT_CONTRACT=false EFFECTSTREAM_STDOUT=true USE_BATCHER_MODE=true SKIP_MIDNIGHT_INFRA=true bun run dev
```

## Architecture
Expand Down Expand Up @@ -129,11 +133,7 @@ Paima concise grammar commands (defined in `data-types/src/grammar.ts`):

**Fix pattern:** Fetch all secrets unconditionally, use ternary (`? :`) to select the right value (compiles to safe `cond_select`), then call `ec_mul` once unconditionally.

**Verify after compiling:** Run the detection script in `ZKIR-EC-MUL-GUARD-BUG.md` after every `deno task compact` to ensure no circuit has both `ec_mul` and guarded `public_input` ops.

## Lint Config

Deno lint with these rules excluded: `no-this-alias`, `require-yield`, `no-explicit-any`, `ban-types`, `no-unused-vars`, `no-slow-types`.
**Verify after compiling:** Run the detection script in `ZKIR-EC-MUL-GUARD-BUG.md` after every `bun run --filter @go-fish/midnight-contract compact` to ensure no circuit has both `ec_mul` and guarded `public_input` ops.

## Compact Point Comparison

Expand Down
44 changes: 22 additions & 22 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ Run the complete development environment with orchestrator:

```bash
# First time setup
deno install --allow-scripts
bun install

# Build EVM contracts
deno task build:evm
bun run build:evm

# Start all services (backend + frontend + blockchain)
deno task dev
bun run dev
```

This will launch:
Expand All @@ -31,10 +31,10 @@ For development with Midnight blockchain integration, you can run the infrastruc

```bash
# Terminal 1: Start Midnight infrastructure (node, indexer, proof server, contract deployment)
EFFECTSTREAM_STDOUT=true deno task -f @go-fish/node midnight:setup
EFFECTSTREAM_STDOUT=true bun run --filter @go-fish/node midnight:setup

# Terminal 2: Start the dev server with batcher mode (after infra is ready)
USE_TYPESCRIPT_CONTRACT=false EFFECTSTREAM_STDOUT=true USE_BATCHER_MODE=true SKIP_MIDNIGHT_INFRA=true deno task dev
USE_TYPESCRIPT_CONTRACT=false EFFECTSTREAM_STDOUT=true USE_BATCHER_MODE=true SKIP_MIDNIGHT_INFRA=true bun run dev
```

The `SKIP_MIDNIGHT_INFRA=true` flag tells the dev server to skip launching Midnight infrastructure since it's already running from the first command.
Expand All @@ -44,9 +44,7 @@ The `SKIP_MIDNIGHT_INFRA=true` flag tells the dev server to skip launching Midni
For quick frontend-only development:

```bash
cd packages/frontend
npm install
npm run dev
bun run frontend:dev
```

Visit **http://localhost:3000**
Expand Down Expand Up @@ -103,25 +101,27 @@ Go Fish is a classic card matching game:

```bash
# Frontend Development
cd packages/frontend
npm install
npm run dev # Start dev server
npm run build # Production build
npm run preview # Preview build
bun run frontend:dev # Start dev server
bun run frontend:build # Production build

# Backend
deno task dev # Start Paima node
deno task testnet # Start in testnet mode
bun run dev # Start full stack via orchestrator
bun run mainnet # Start in mainnet mode

# Testing
bun run test # Node API unit tests
bun run test:e2e # E2E game-round test

# Smart Contracts (EVM)
cd packages/shared/contracts/evm
npx hardhat compile # Compile Solidity contracts
npx hardhat test # Run contract tests
npx hardhat deploy # Deploy to local network
bun run build # Compile contracts
npx hardhat test # Run contract tests

# Root Level
deno task frontend:dev # Start frontend from root
deno task frontend:build # Build frontend from root
bun run build:evm # Compile EVM contracts
bun run build:midnight # Compile Midnight contracts
bun run frontend:dev # Start frontend from root
bun run frontend:build # Build frontend from root
```

## Environment Variables
Expand Down Expand Up @@ -155,7 +155,7 @@ These are set in a `.env` file in `packages/frontend/` or passed inline when run

```bash
# Start with existing Hardhat instance
SKIP_EVM_LAUNCH=true USE_TYPESCRIPT_CONTRACT=true EFFECTSTREAM_STDOUT=true deno task dev
SKIP_EVM_LAUNCH=true USE_TYPESCRIPT_CONTRACT=true EFFECTSTREAM_STDOUT=true bun run dev
```

## Database Schema
Expand Down Expand Up @@ -195,7 +195,7 @@ See [packages/shared/data-types/src/grammar.ts](packages/shared/data-types/src/g

## Technology Stack

- **Backend**: Deno, TypeScript, Paima Engine
- **Backend**: Bun, TypeScript, Paima Engine
- **Frontend**: Vite, TypeScript, Three.js, postprocessing, gsap
- **Blockchain (EVM)**: Hardhat, Solidity (lobbies & stats)
- **Blockchain (Midnight)**: Midnight contracts (game logic - stub)
Expand Down
4 changes: 2 additions & 2 deletions ZKIR-EC-MUL-GUARD-BUG.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ dealCards

## Detection Method

After compiling with `deno task compact`, check each generated ZKIR file for the combination
After compiling with `bun run --filter @go-fish/midnight-contract compact`, check each generated ZKIR file for the combination
of `ec_mul` and non-null guarded `public_input` ops:

```bash
Expand Down Expand Up @@ -161,7 +161,7 @@ call `ec_mul` once outside any branch.
> **Every `ec_mul` in every compiled ZKIR must have `public_input { guard: null }` feeding
> its `a_x` and `a_y` inputs — never a guarded `public_input { guard: N }` for any `N`.**

Run the detection script above after every `deno task compact` to verify this invariant holds.
Run the detection script above after every `bun run --filter @go-fish/midnight-contract compact` to verify this invariant holds.
If any circuit shows both `ec_mul` and non-null guarded `public_input`, find the `if/else`
containing the `ec_mul` call chain and apply the ternary-select fix.

Expand Down
Loading