Towns-whisper

Towns-whisper is an immersive 2D mystery-adventure game that fuses AI-driven storytelling with blockchain technology. Each playthrough offers a unique, dynamically generated narrative, challenging players to explore, trade, and compete to unravel secrets in order to rescue their lost friends.

Storyline

A relaxing trip with friends takes a terrifying turn after a sudden accident. You awaken alone, disoriented, on the outskirts of a strange, mist-shrouded village. Your friends are missing.

Guided by a mysterious disembodied voice (powered by Text-to-Speech), you begin exploring the village. The locals are wary, their memories fragmented, and their secrets buried. To uncover the truth and save your friends, you must piece together clues, earn villagers’ trust, and make difficult choices before time runs out.

System Architecture

0G MAINNET Deployed Contracts

• User Registry: 0xdb408c192627ed0f58a9a649398b5e63e2a891ab - Verified Contract
• Game Items: 0xda3208af06f0a436426363ab48faf4aef2d2dd17 - Verified Contract
• Staking Manager: 0x0fd3d54cd0f292d1b85ec069d3e6f09072050d33 - Verified Contract

STORAGE Submissions

You can view storage submissions on the mainnet here: 0G Mainnet Explorer

Use of 0G Stack

Decentralized AI

The bridge_server is the core component of our decentralized AI integration. It acts as a broker between the game and the 0G compute network, enabling dynamic and verifiable narrative generation. Here's how it works:

1. On-Chain Ledger Management: The server manages an on-chain compute ledger, ensuring that there are always sufficient funds to pay for AI inference requests. It can automatically top up the ledger if the balance falls below a certain threshold.
2. Provider Acknowledgment: Before sending requests to an AI provider, the server acknowledges them on-chain, establishing a secure and trusted relationship.
3. Inference Request Handling: When the game needs to generate a narrative, it sends a prompt to the bridge_server. The server then constructs a secure request and forwards it to a decentralized AI provider on the 0G network.
4. On-Chain Verification: After receiving the AI-generated narrative, the server verifies the response on-chain. This ensures the integrity of the content and prevents tampering.

This decentralized approach to AI not only enhances the game's dynamism but also adds a layer of security and transparency that would be difficult to achieve with a traditional centralized AI service.

0G Storage

We use 0G's decentralized storage solution to persist player dialogue history, ensuring that it is both censorship-resistant and highly available. The storage implementation is split into two main components:

1. 0g_storage_service: This is a dedicated Node.js server that encapsulates all interactions with the 0G storage network. It uses the @0glabs/0g-ts-sdk to handle file uploads and downloads, and it manages a local map of wallet addresses to their corresponding dialogue history root hashes. This service exposes a simple REST API for saving and retrieving dialogue.
2. server_centralized_0g_storage: This server acts as a client to the 0g_storage_service. It provides a high-level API for the main application to interact with, abstracting away the complexities of the underlying storage mechanism. This separation of concerns makes the storage logic more modular and easier to maintain.

By using 0G storage, we can provide a more robust and resilient gaming experience, where players can be confident that their progress is securely stored and always accessible.

0g Data Availability (DA) Implementation

The 0G Data Availability layer ensures that critical game events are cryptographically secured, verifiable, and resilient against data loss or censorship. Our implementation creates an immutable audit trail of player actions that can be independently verified on-chain.

Architecture Overview

Frontend (daService.js)
    ↓ HTTP POST
0G Storage Service (storageManager.js)
    ↓ gRPC (disperseBlob)
0G-DA-Client (Docker)
    ├─ Disperser: Receives & batches blobs
    ├─ Batcher: Creates batches every 3s
    └─ Sends to encoder →
                         ↓ gRPC (EncodeBlob)
0G-DA-Encoder (WSL - Rust)
    ├─ Reed-Solomon erasure coding
    ├─ KZG cryptographic commitments
    └─ Returns encoded chunks →
                                ↓
0G-DA-Client (Continued)
    ├─ Signer: Collects DA signer signatures
    └─ Finalizer: Submits Merkle root to blockchain
 ↓
0G Blockchain (Newton Testnet)
    └─ On-chain commitment stored

Critical Game Events Logged to DA

We disperse the following events to ensure a complete, verifiable game history:

1. Player Authentication

   • New user registration
   • Returning user login sessions

2. Game Lifecycle

   • Single-player game start (with difficulty and staking details)
   • Multiplayer room creation
   • Player joining multiplayer rooms
   • Multiplayer game start (with full player roster)

3. Economic Events

   • Stake forfeiture (abandoned games)
   • Reward claims (with Hedera schedule ID)

4. Multiplayer Coordination

   • Room creation metadata
   • Player join events
   • Game initialization parameterss

Intelligent NFT (iNFT) Integration

Our game features a unique Intelligent NFT (iNFT) that represents your in-game progress and narrative. This iNFT evolves as you play, creating a dynamic and personalized gaming experience.

The iNFT integration is designed to be seamless and secure, with a clear separation of concerns between the game client, backend services, and the blockchain. Here’s how it works:

1. Game Client: The frontend of our game is responsible for capturing player actions and dialogue. It communicates with our Python backend to send this information and receive updates on the game state. The game client is not directly aware of the iNFT, which allows us to keep the frontend lightweight and focused on the user experience.

2. Python Backend: Our Python backend, built with FastAPI, acts as the central hub for game logic. It manages the game state, processes player inputs, and generates responses from our AI-powered NPCs. When a game session ends, the backend sends the complete dialogue history to our 0g_storage_service.

3. 0g_storage_service: This Node.js service is the heart of our iNFT system. It is responsible for:

   • Metadata Generation: It takes the dialogue history and generates new metadata for the iNFT, reflecting the player’s unique journey.
   • IPFS Integration: It uploads the metadata to IPFS, ensuring it is decentralized and tamper-proof.
   • Encryption: It encrypts the metadata, so only the owner of the iNFT can view it.
   • Smart Contract Interaction: It interacts with our narrativeINFT.sol smart contract to mint new iNFTs and update existing ones.

4. Smart Contract: Our narrativeINFT.sol smart contract is an ERC-721 compliant NFT that includes additional features for iNFTs. It stores the iNFT’s metadata hash and ownership information on the blockchain, making it secure, verifiable, and tradable.

This architecture allows us to create a dynamic and engaging gaming experience, where every player’s journey is unique and recorded on the blockchain as an evolving iNFT.

Screenshots

Technology Stack

• Frontend (game):
  • Game Engine: Phaser 3 (2D game framework)
  • Framework: React + Vite (modern web frontend)
  • Styling: Tailwind CSS
  • Web3: Ethers-compatible libraries for wallet & contract interaction
• Backend (servers):
  • Framework: FastAPI (Python), Express.js (Node.js)
  • AI: Google Gemini for narrative generation & conversational AI
  • APIs: Supports both centralized and decentralized modes
• Blockchain (contracts):
  • Network: EVM compatible chains
  • Smart Contracts: Written in Solidity

Project Structure

Towns-whisper/
├── 0g_storage_service/      # Node.js server for 0G storage
├── assets/                  # Game assets, including images and SVGs
├── bridge_server/           # Node.js server bridging game client and blockchain
├── contracts_eth/           # Ethereum smart contracts and deployment scripts
├── game/                    # Web-based game client (React + Vite + Phaser 3)
├── server_centralized/      # Centralized backend server (FastAPI) - (Currently Ignored)
├── server_centralized_0g_storage/ # Centralized backend with 0G storage integration
└── server_decentralized_0g/ # Decentralized backend server (0g integration)

Getting Started

Prerequisites

• Node.js (v16+)
• npm or yarn
• Foundry (for Ethereum smart contracts)
• Python 3.9+

Installation

1. Clone the repository with submodules:

   git clone --recurse-submodules <repo-url>
   cd Towns-whisper

2. Install dependencies for each component:

   # 0g Storage Server
   cd 0g_storage_service && npm install && cd ..
   
   # Bridge Server
   cd bridge_server && npm install && cd ..
   
   # Game
   cd game && npm install && cd ..
   
   # Centralized 0G Storage Server
   cd server_centralized_0g_storage && pip install -r requirements.txt && cd ..
   
   # Decentralized 0G Server
   cd server_decentralized_0g && pip install -r requirements.txt && cd ..

Running the Game

1. Run the 0G Storage Server:

   cd 0g_storage_service
   npm start

2. Run the Bridge Server:

   cd bridge_server
   npm start

3. Run the Centralized 0G Storage Server:

   cd server_centralized_0g_storage
   uvicorn main:app --reload

4. Run the Decentralized 0G Server:

   cd server_decentralized_0g
   uvicorn main:app --reload

5. Run the Frontend:

   cd game
   npm run dev

Testnet Deployed Addresses

• User Registry: 0x5133fa99d718111fb6a708bee4ffe935fb529d1b
• Game Items: 0xf80c2f2ac5ed19f609071c06efd21eab686436f5
• Staking Manager: 0x0d6c4d4046cdf8ca49ffaae4cf10b6bf7f1d7dc9
• iNFT Contract: 0x494d8E03605E297F936a6F244B7BcD03e4563D7E