Sealed Guess Game

Private (sealed) number guessing with on-chain settlement and off-chain coordination. Players encrypt their guesses to a public key published on-chain for the current round. The backend decrypts guesses off-chain, computes public hints, adapts fees using a density-aware policy (DBAE), and immediately finalizes on exact hits. A simple deal mechanism lets viewers negotiate access to a player’s private guess via sealed reveals.

For deeper system design and diagrams, see docs/MASTER_ARCHITECTURE.md.

High-level Overview

• Contracts

  • Single game contract manages: games (rounds), per-guess fees, encrypted target, encrypted guesses, deals, and finalization/withdrawals.
  • Each game stores a base64 public key and a sealed encryptedTarget for the server-only value (the winning number).
  • Players submit their encryptedNumber (sealed to the game’s public key). Fees follow a linear model that the operator can adjust as play heats up.

• Backend (Operator)

  • Derives a deterministic sealed-box X25519 keypair from MNEMONIC and publishes the public key when creating a round.
  • Subscribes to GuessSubmitted events, decrypts payloads off-chain, computes hints (cold/warm/hot/blazing), and updates the on-chain fee slope according to DBAE.
  • Finalizes instantly when a decrypted guess exactly matches the target; otherwise the pot is distributed on operator finalization.
  • Exposes simple HTTP endpoints for reading status, hints, and deal-based sealed reveals.

• Frontend

  • Users generate a client sealed-box keypair in the browser and encrypt guesses to the current game public key.
  • Shows hints, past activity, lets viewers propose/accept/reject on-chain deals, and decrypts sealed reveals returned by the backend.

Encryption uses libsodium sealed boxes (X25519). Encrypted payloads are base64-wrapped JSON tagged as { ver: "sodium-seal/v1", ct: "..." }.

Flow (Simplified)

1. Round bootstrap

   • Backend ensures a live round exists and writes the round’s public key and a sealed encryptedTarget on-chain.

2. Play

   • Player encrypts { guess } to the round’s public key and calls submitGuess, paying the current fee.
   • Backend decrypts off-chain on event, caches payload, computes a public hint, and adjusts the fee slope using DBAE.
   • If a guess exactly matches the target, backend finalizes to the winner immediately.

3. Deals (optional)

   • Viewer proposes an on-chain deal for a specific guess (pot-share bps + viewerPublicKey). Owner accepts/rejects on-chain.
   • Viewer calls backend /deals/view/...; if accepted, backend returns a sealed JSON reveal encrypted to the viewer’s key.

4. Payouts & Withdrawals

   • Finalization distributes pot to recipients on-chain. Users withdraw from their internal balances with a delay safety valve.

DBAE: Density-Based Adaptive Escalation

The entry fee increases linearly with guess count and adapts to public momentum:

• Linear component: L(k) = F_base + δ × (k − 1)
• Primary multiplier by hottest known hint H_best: Cold 1.0, Warm 1.5, Hot 4.0, Blazing 10.0
• Additive density: A(C) = (C − 1) × W_density for C > 0 (e.g., W_density = 0.5)
• Effective multiplier: M(H_best) + A(C)

Example (F_base = $1.00, δ = $0.05, W_density = 0.5):

k	Event	H_best	L(k)	C	M	A(C)	Total	Fee(k)
1	Game starts	Cold	1.00	0	1.0	0.0	1.0	1.00
20	Exploration	Cold	1.95	0	1.0	0.0	1.0	1.95
21	First “Hot” appears	Hot	2.00	1	4.0	0.0	4.0	8.00
23	Second “Hot”	Hot	2.10	2	4.0	0.5	4.5	9.45
25	First “Blazing”	Blazing	2.20	4	10.0	1.5	11.5	25.30

This makes searching costlier as momentum concentrates, pushing latecomers toward negotiating information instead of blind guessing.

Repository Layout

• contracts/ — Game contract, interfaces, Foundry tests, deploy/upgrade scripts
• backend/ — Operator service (Express + viem) that decrypts, computes hints, updates fees, and serves read endpoints
• frontend/ — Next.js app (Privy + wagmi) for guessing, viewing hints, and managing deals
• docs/ — Architecture notes and Mermaid diagrams (SVGs compiled)

Folder-specific readmes provide setup and deployment details.

Getting Started

Prerequisites

• Node.js 20+
• pnpm (recommended) or npm
• Foundry (foundryup) for contracts

1. Deploy contracts

• See contracts/README.md for environment variables and scripts. Save the deployed proxy address as your CONTRACT_ADDRESS.

2. Run the backend

• See backend/README.md for environment variables (MNEMONIC, RPC_URL, CHAIN_ID, CONTRACT_ADDRESS, …) and endpoints. Start it locally with pnpm dev.

3. Run the frontend

• See frontend/README.md for environment variables (NEXT_PUBLIC_*) and usage. Start it with pnpm dev and open the app.

Production tips: secure your mnemonic and RPCs, restrict CORS, and consider persistent storage for decrypted caches if needed.