0GClawForge Documentation

0GClawForge is a sovereign agent operating system that combines the OpenClaw autonomous agent framework with the 0G decentralized AI ecosystem. It enables the creation, governance, and gameplay of Eternal Clans — on-chain AI collectives that own memory, generate realms, run autonomous behavior, and evolve through community governance.

Core Pillars

• 0G Storage — Content-addressable immutable storage for all agent data (memories, realms, votes)
• 0G Compute — Decentralized AI inference for realm generation, NPC dialogue, and clan chat
• 0G Chain — ERC-7857 intelligent NFTs (iNFTs) that store encrypted agent intelligence on-chain
• OpenClaw — Autonomous agent skills framework for social integrations (Telegram, Discord)

Architecture

The project is a Turbo monorepo with four main packages: the @0gclawforge/sdk TypeScript wrapper library, Solidity smart contracts, the Next.js dashboard application, and the OpenClaw agent fork with custom skills.

AgentInft.sol — ERC-7857 Intelligent NFT

The core contract implements ERC-721 with ERC-7857 encrypted metadata extensions. Each token represents a clan with on-chain state tracking for memory, realms, votes, and evolution history.

Network Deployment

The @0gclawforge/sdk package provides typed wrappers around all 0G SDKs. All application code must use these wrappers instead of calling 0G SDKs directly.

Storage Utilities

• uploadJSON(data, config) — Serializes and uploads JSON to 0G Storage, returns root hash + tx hash
• downloadFromStorage(rootHash, filePath, config) — Downloads content by root hash to local file
• StorageConfig — Type with rpcUrl, indexerUrl, and optional privateKey

Compute Client

• ZGComputeClient — Wraps 0G Serving Broker for AI inference
• client.setupProvider(address) — Initializes the compute provider
• client.query(prompt, options) — Sends inference request, returns text + verification status

Contract ABI

• agentInftAbi — Exported ABI for the AgentInft contract

0G Storage is a content-addressable immutable storage layer. Every piece of data — memories, realms, vote records — is stored as a JSON blob and identified by its root hash. Root hashes serve as URIs stored on-chain in the iNFT contract.

Data Flow

• Application serializes data to JSON
• uploadJSON() writes to 0G Storage via the Indexer
• Returns a root hash (content address) and transaction hash
• Root hash is written to the smart contract via updateMemoryRoot, updateRealmRoot, or updateVoteRoot
• Readers fetch data by calling the contract for the root hash, then downloading from storage

Cross-Network Fallback

When data was uploaded on testnet but is being accessed on mainnet (or vice versa), the system automatically falls back to the testnet storage indexer if the primary network lookup fails. This ensures realm data remains accessible across networks.

Storage Indexers

0G Compute provides decentralized AI inference through a provider network. ClawForge uses the 0GM-1.0-35B-A3B model for all AI-powered features.

Use Cases

• Realm Generation — Transforms user prompts into full game worlds with maps, NPCs, quests, and bosses
• NPC Dialogue — Live in-game NPC conversations powered by realm context and player state
• Clan Chat — Strategic advisor AI with access to realm state and game history
• Proposal Evaluation — AI analysis of governance proposals
• Autonomous Mode — Self-directed clan behavior including auto-proposals and realm evolution

Verification

Each compute response includes a verified flag indicating whether the response was cryptographically verified by the 0G network. Verified responses are labeled verified-0g-compute in the UI.

Realms are procedurally generated game worlds created from natural language prompts. Each clan can have an active realm stored on 0G Storage with full version history.

Realm Structure

• Map — 16×16 tile grid with terrain types (grass, stone, water, wall, lava, sand, forest, ice)
• NPCs — Named characters with descriptions, dialogue, positions, and optional quest assignments
• Quests — Named objectives with descriptions, types (fetch, kill, explore, puzzle), and reward items
• Artifacts — Collectible items placed on the map with stat effects
• Boss — End-game enemy with HP, attack, defense, and loot tables
• Spawn Point — Player starting position

Generation Pipeline

When a clan owner submits a realm prompt, the system first attempts AI generation via 0G Compute. If compute is unavailable, it falls back to a deterministic generator that uses time-based randomness to create unique realms from prompt keywords.

Gameplay Mechanics

• Movement — WASD or arrow keys on the tile map
• Combat — Turn-based attacks against the boss, using base attack + weapon bonuses
• Quests — Talk to NPCs, complete objectives, earn inventory items
• Artifacts — Walk over to collect, granting HP/attack/defense bonuses
• Progress Saving — Player state (HP, XP, gold, level, inventory) saved to 0G Storage
• Realm History — Previous realm versions accessible via previousRealmRootURI chain

Clans are governed through an on-chain proposal and voting system. Any member can submit proposals, and the community votes to accept or reject them.

Proposal Flow

• A member submits a proposal (via dashboard or Telegram bot)
• The proposal is evaluated by 0G Compute AI for feasibility
• Community members cast Yes/No votes
• Vote results are stored as a linked list on 0G Storage
• Each vote record contains a previousVoteRoot pointer to the prior vote
• The latest vote root hash is written to the smart contract

Vote History

The Vote History panel (in the Governance tab) traverses the vote chain by followingpreviousVoteRoot links from 0G Storage, displaying all past proposals with their vote counts, pass/reject status, timestamps, and storage hashes.

Vote Record Structure

Autonomous mode allows clans to operate independently — proposing realm changes, evolving their identity, and managing governance without constant human input.

Capabilities

• Auto-Proposals — AI generates governance proposals based on clan state and history
• Realm Evolution — Automatic realm generation and updates
• Memory Management — Clan memory updates based on events and interactions
• Social Posting — Automated updates via Telegram/Discord bots

Autonomous behavior is powered by 0G Compute inference and coordinated through the OpenClaw skills framework. All autonomous actions are recorded on 0G Storage for full auditability.

Telegram Bot

The Telegram bot provides a conversational interface to clan features directly in group chats or DMs.

Discord Bot

The Discord integration mirrors Telegram functionality with slash commands, enabling clan management from Discord servers. Uses the same underlying handler system for consistent behavior across platforms.

All API routes are Next.js App Router server functions under /api/.

Key Principles

• Private keys are server-side only — Never exposed in client-side bundles or browser code
• ERC-7857 encryption — Agent intelligence blobs are encrypted before storage on 0G
• Wallet-gated actions — Mutations require connected wallet signatures
• Content addressing — 0G Storage root hashes are tamper-proof; data integrity is guaranteed by the network
• Compute verification — 0G Compute responses include cryptographic verification flags

Environment Variables

0G Galileo Testnet

0G Mainnet

Prerequisites

• Node.js 18+
• pnpm 8+
• A 0G testnet wallet with test tokens (get from faucet)

Getting Started

Clone the repository, install dependencies with pnpm install, copy.env.example to .env and fill in your private key and compute provider address.

Common Commands

Project Structure