CipherRealms

CipherRealms is a Zama FHE-powered on-chain builder game. Players register to mint 10,000 encrypted gold, claim a 3×3 encrypted map, and spend 1,000 gold per construction to place one of four building types. All balances, choices, and map tiles remain encrypted on-chain; players decrypt locally through the relayer without exposing plaintext to the network.

Highlights

• Fully private gameplay: Gold balances, tile states, and building selections are stored as Zama encrypted types; view functions never leak sender context.
• Deterministic rules: 3×3 grid, four bounded building types, fixed build cost, and capped build count enforced by the contract.
• End-to-end FHE flow: Frontend encrypts inputs and decrypts outputs via the relayer SDK; contract uses @fhevm/solidity.
• Separation of concerns: Reads use viem; writes use ethers; ABI is sourced from Hardhat deployments (deployments/sepolia).
• Ready for mainnet-like testing: Deploy with Infura and a private key to Sepolia; no mnemonic paths are used.

Problem & Solution

• Problem: Traditional on-chain games expose player state (balances, tile choices, strategy) publicly, making gameplay predictable and privacy-poor.
• Solution: CipherRealms keeps every critical value encrypted end-to-end. Construction choices are encrypted client-side, processed homomorphically on-chain, and decrypted only by the player via the relayer. This preserves strategic secrecy while retaining on-chain verifiability.

Gameplay Loop

1. Register — Mint 10,000 encrypted gold and an empty 3×3 encrypted map (stored as euint64 and euint32[9]).
2. Build — Pick a tile (0–8) and one of four building types (clamped to 1–4). Each build burns 1,000 gold and marks the tile occupied.
3. Decrypt — Use the relayer SDK to decrypt gold and map tiles locally. On-chain data stays encrypted.
4. Repeat — Up to nine constructions per player; duplicate registrations and invalid tiles revert.

Technology Stack

• Smart contracts: Hardhat, @fhevm/solidity, TypeScript tasks/tests, hardhat-deploy, solidity-coverage.
• Frontend: React + Vite, RainbowKit/Wagmi (Sepolia only), viem for reads, ethers for writes, @zama-fhe/relayer-sdk for encryption/decryption. No frontend env vars or localStorage; ABI copied from deployments/sepolia.
• Tooling: TypeChain (ethers v6), ESLint/Prettier/Solhint, gas reporter, Hardhat tasks for encrypted actions.

Repository Layout

• contracts/CipherRealms.sol — Core game logic (registration, builds, encrypted storage, ACL).
• deploy/deploy.ts — Hardhat-deploy script for local and Sepolia targets.
• tasks/ — CLI helpers (task:address, task:register, task:build, task:decrypt-gold, task:decrypt-map).
• test/CipherRealms.ts — FHE-aware test suite using the mock FHEVM.
• deployments/sepolia/CipherRealms.json — Canonical ABI and deployed address for the frontend.
• app/ — React dapp (UI, encryption/decryption flows, Sepolia-only interaction).
• docs/ — Zama contract and relayer references used by this project.

Prerequisites

• Node.js 20+ and npm 7+.
• An Infura project key and a deployer private key (hex). Do not use a mnemonic.
• Sepolia ETH for gas when deploying or interacting live.

Environment & Configuration

• The Hardhat config loads .env via dotenv.config().
• Required env vars for networked actions:
  • INFURA_API_KEY — used in https://sepolia.infura.io/v3/${INFURA_API_KEY}.
  • PRIVATE_KEY — deployer key (0x prefix optional; mnemonics are blocked by design).
  • ETHERSCAN_API_KEY — optional, for verification.
• Frontend: no environment variables; contract address is provided via UI or app/src/config/contracts.ts. Reads/writes stay on Sepolia (no localhost chain in the UI).

Setup & Development

# Install root dependencies
npm install

# Compile contracts (also runs TypeChain)
npm run compile

# Run the FHE mock tests (skips if not on the mock)
npm run test

# Optional: coverage and linting
npm run coverage
npm run lint

Local FHEVM workflow

Use this for dev-only validation with the mock FHEVM:

# Start local node (Hardhat FHE mock)
npm run chain

# Deploy to the local network
npm run deploy:localhost

Frontend interactions are Sepolia-only; the local node is for contract development and tests.

Sepolia deployment

export INFURA_API_KEY=...
export PRIVATE_KEY=...   # hex string, no mnemonic

# Deploy
npm run deploy:sepolia

# (Optional) verify
npm run verify:sepolia -- <deployed-address>

After deployment, ensure deployments/sepolia/CipherRealms.json contains the fresh address/ABI and that the same ABI is reflected in app/src/config/contracts.ts. The dapp allows overriding the address at runtime via its input field.

Hardhat Tasks (encrypted flows)

• npx hardhat task:address --network sepolia — Print deployed address.
• npx hardhat task:register --network sepolia — Register caller, mint encrypted gold/map.
• npx hardhat task:build --position 4 --building 3 --network sepolia — Encrypt and place a structure at tile 4.
• npx hardhat task:decrypt-gold --network sepolia --player <addr?> — Decrypt a player’s gold locally (uses relayer helper).
• npx hardhat task:decrypt-map --network sepolia --player <addr?> — Decrypt all tiles for a player.

Frontend (app/)

cd app
npm install

# Run the Vite dev server
npm run dev

# Production build
npm run build

• Network: Sepolia only; connect via RainbowKit. Reads use viem, writes use ethers.
• Encryption/decryption: @zama-fhe/relayer-sdk handles ciphertext creation and user decryption; no localStorage.
• Contract config: ABI is copied from deployments/sepolia; set the live address in app/src/config/contracts.ts or paste it into the UI field.
• Gameplay UI: register, select building type, click a tile to build, decrypt balance/map via relayer-powered actions.

Contract Notes

• registerPlayer() mints encrypted gold (euint64) and initializes nine encrypted tiles (euint32), granting ACL access to player and contract.
• build(position, encryptedBuildingType, proof) clamps building types to 1–4, charges 1,000 gold, marks occupancy, and emits BuildingConstructed.
• View helpers (getGold, getMap, getTileStates, getBuildCount, isRegistered) never rely on msg.sender; callers supply the address to inspect.
• Constants: STARTING_GOLD = 10_000, BUILD_COST = 1_000, MAP_SIZE = 9.

Advantages

• Keeps player strategy confidential while remaining fully on-chain.
• Predictable, fixed rule set for easier auditing and balancing.
• Clear separation between read (viem) and write (ethers) paths to align with the project requirements.
• Deployable with standard Hardhat tooling; ABI is automatically reusable by the dapp.

Future Roadmap

• Add achievement/events history with encrypted logging and optional public decryption.
• Expand building catalog and introduce encrypted resource upgrades or trading.
• Integrate an indexer/subgraph for analytics without exposing plaintext (using relayer-based decryption on demand).
• Gas and ACL optimization passes after broader testing on Sepolia.
• Multi-user sharing: permissioned map reveals and collaborative builds via ACL extensions.

Further Reading

• Zama Solidity guide: docs/zama_llm.md
• Relayer SDK overview: docs/zama_doc_relayer.md

CipherRealms combines FHE privacy with deterministic on-chain gameplay—use this README as the single source of truth for deploying, testing, and running the project end to end.