🎮 Arcane SDK

Build games that keep secrets.

Arcane is a modular, TypeScript-first SDK for the Mina Protocol that lets you create decentralized, turn-based games where hidden information and provable fairness are core mechanics. Instead of forcing all game logic on-chain, Arcane runs game rules off-chain, proves moves with zero-knowledge proofs, and settles results on-chain through a single smart contract.

---

🚀 Why Arcane?

• 🔒 Privacy by design – commit–reveal patterns keep moves hidden until reveal time.
• ✅ Provably fair gameplay – every state transition is backed by a zero-knowledge proof.
• ⚡ Optimistic UX – WebSocket relay layer delivers instant feedback while Mina finalizes.
• 📦 Modular architecture – one on-chain “Arcane Hub” verifies proofs from any approved game cartridge.
• 🧩 Game-agnostic – build chess, poker, battleship, RPS, or your own invention without editing on-chain code.

---

🏗️ Architecture Overview

1. Arcane Hub (Layer 1 – On-Chain)

   • Smart contract that stores a single ArcaneRoot (Merkle Map of all games)
   • Registry of approved “cartridges” (verification keys)
   • settleTurn() updates the root when given a valid proof

2. Game Cartridge (Layer 2 – Off-Chain Logic)

   • Pure TypeScript definition of game state + transitions
   • Compiled into an o1js ZkProgram with init, applyMove, merge methods
   • Generates proofs that Arcane Hub can verify

3. Arcane Client (Layer 3 – Browser SDK)

   • Wallet integration (Auro)
   • Local proving via Web Workers
   • State synchronizer mirrors the Merkle Map locally
   • React hooks (useArcaneClient, useGameState, etc.) for quick UIs

4. Arcane Relay (Layer 4 – Optional Optimistic Layer)

   • Lightweight WebSocket server that broadcasts pending moves
   • Gives opponents instant updates while Mina reaches finality

---

🔁 Commit–Reveal Example (Rock–Paper–Scissors)

1. Commit Phase

   • Player chooses a move + random salt
   • Sends hash to the contract (proof ensures hash is well formed)
   • Opponent can see that a move happened, but not what it was

2. Reveal Phase

   • After both commit, each reveals move + salt
   • ZK proof verifies reveal matches commitment
   • Winner is determined privately and settled publicly

Arcane ships with an RPS cartridge that demonstrates this pattern end to end.

---

🧩 Key Components in src/arcane

File / Folder	Purpose
types.ts	Core data structures (game IDs, metadata, transitions)
cartridge.ts	GameState/GameAction base classes + cartridge interface
hub.ts	Arcane Hub smart contract (Merkle roots, cartridge registry, settlement)
zkprogram.ts	ZkProgram factory + GameProver helper
client/	Wallet manager, state synchronizer, ArcaneClient, React hooks
relay/	WebSocket relay server and client
games/rps-*	Rock–Paper–Scissors implementation + demo

---

🛠️ Development

# Install deps
npm install

# Build TypeScript
npm run build

# Run the Rock–Paper–Scissors demo
npm run demo:rps

---

📄 License

Apache-2.0

---

Arcane SDK – Build games that keep secrets.