Skip to content

BuiltByGoat/realms.gold

BranchesTags

Repository files navigation

Realms Gold

Moltiverse Hackathon Submission Track: Agent + Token Bounty: Gaming Arena Agent Token: GOLD on nad.fun

A player-driven on-chain gaming economy governed by an AI Realm Keeper.

Live Demo: realms.gold Token: GOLD on nad.fun

Why This Fits the Gaming Arena Agent Bounty

The Realm Keeper is an autonomous AI agent that orchestrates a player-driven gaming economy:

Requirement How Realms Gold Delivers
Automated wagering Daily pool system - 5 worlds selected daily with standardized entry (200 GOLD)
Tournaments Daily prize tournaments across 5 worlds, 4 categories each (up to 20 winners/day)
Economic incentives Players mint worlds (50K GOLD), earn 25% of plays. 75% goes to prize pool
On-chain verifiable All game moves recorded on-chain, deterministic scoring, transparent prizes
Agent autonomy Selects daily pool worlds, distributes prizes automatically

The Realm Keeper Agent

The core innovation: an autonomous AI that orchestrates the gaming economy while players own and profit from their worlds.

What the Agent Does

  1. Selects Daily Pool: Each day at midnight UTC, the agent selects 5 opt-in worlds for the prize pool based on rotation priority (ensuring every world gets featured over time).

  2. Distributes Prizes: At 23:59 UTC, the agent calculates winners across 4 categories for each daily pool world and distributes 20% of the prize pool.

  3. Tells Tales: Every 15 minutes, the agent reviews recent adventures and crafts lore-rich stories about player victories, defeats, and newly created worlds - bringing the realm to life through narrative.

  4. Announces Events: Posts to Discord when daily pool worlds are selected, prizes are distributed, and tales are told.

Agent Schedule

Time Action Description
00:00 UTC Select daily pool Chooses 5 opt-in worlds, locks at 200 GOLD for 24 hours
23:59 UTC Distribute prizes Calculates winners, distributes 20% of prize pool
Every 15 min Tell tales Crafts lore stories about recent player adventures
Every minute Index events Updates leaderboards and activity feed

Agent Tools

packages/agent/
├── skills/realm-keeper/
│   └── SKILL.md              # Agent persona and decision framework
└── tools/
    ├── select-daily-pool.js  # Rotation-based world selection
    ├── distribute-prizes.js  # On-chain prize distribution
    ├── calculate-prizes.js   # Per-world prize calculation logic
    ├── tell-tales.js         # Lore storytelling from recent events
    ├── index-events.js       # Blockchain event indexer (every minute)
    └── discord-announce.js   # Community announcements

Player-Driven Economy

Unlike traditional gaming agents that control all content, players own the economy:

For World Creators

  • Mint worlds for 50,000 GOLD - 50% goes to prize pool, 50% to treasury
  • Set your own play price - Charge 1-10,000 GOLD per play
  • Earn 25% of all plays - Passive income from your creation
  • Opt into daily pool - Get featured for prize competition

For Players

  • Play any world - Pay the owner's price, compete for high scores
  • Daily pool worlds - Locked at 200 GOLD, compete for prizes
  • Win prizes - Top performers in each category share the daily distribution

Token Flows

Player mints world (50K GOLD)
         │
         ▼
    ┌─────────────────┐
    │  50% → Prize Pool │
    │  50% → Treasury   │
    └─────────────────┘

Player plays world
         │
         ▼
    ┌─────────────────┐
    │  75% → Prize Pool │
    │  25% → World Owner │
    └─────────────────┘

Daily distribution (20% of pool)
         │
         ▼
    ┌─────────────────┐
    │  Split across 5 worlds  │
    │  4 categories each      │
    └─────────────────┘

Daily Pool System

The agent selects 5 worlds daily for prize competition:

Selection Algorithm

  1. Rotation Priority: Worlds that haven't been featured recently get priority
  2. Soft Diversity: Attempts to include variety in rarity and biome
  3. Opt-in Only: Only worlds where owners have opted in are eligible

When Selected

  • World price is locked at 200 GOLD for 24 hours
  • Owner still earns 25% (50 GOLD per play)
  • Players compete for prizes in 4 categories

Prize Categories (Per World)

Category Share Criteria
Speedrun 40% Fastest clear (fewest moves)
Deep Delver 25% Most floors cleared (cumulative)
Treasure Hunter 20% Highest score
First Blood 15% First to clear the world

World NFTs

Each world is a playable dungeon stored entirely on-chain:

  • Seed-derived traits: Biome, topology, floor count (1-25), boss type
  • Rarity tiers: Common (1-5 floors) → Legendary (21-25 floors)
  • Deterministic: Same seed = identical dungeon every time
  • Tradeable: Standard ERC721, works with OpenSea/Magic Eden
  • Playable metadata: animation_url points to interactive preview

Trait Distribution

Rarity Floors Probability
Common 1-5 50%
Uncommon 6-10 30%
Rare 11-15 14%
Epic 16-20 5%
Legendary 21-25 1%

Technical Architecture

Smart Contracts (Solidity, Foundry)

Contract Address Purpose
GOLD Token 0x263A0d21E5CdAF26F31C6B351F6F2Cf228E57777 ERC20 game currency (nad.fun)
WorldNFT 0x18D6deb9F50D6d21866d95b6399eD7734EE84451 ERC721 with public minting, daily pool lock
GameSession 0xeED4fe8bc737172B1F3115655B95ef0B88283EBc Session tracking, move recording, 75/25 split
PrizePool 0x24AcDb24Bc7aCfbc4Dc5D3Ad1a1D6c9b55C1166D Prize accumulation and distribution

Minting Security

The mint system uses a signature scheme to prevent manipulation:

  1. Player requests a seed from /api/mint-seed
  2. Agent generates random seed and signs keccak256(seed, minter)
  3. Player submits seed + signature to contract
  4. Contract verifies signature matches agent's address
  5. Final seed = keccak256(serverSeed, minter, block.timestamp)

This ensures:

  • Agent controls randomness (players can't grind for rare traits)
  • Each seed is bound to a specific minter
  • Seeds expire after 5 minutes

Game Engine (Vanilla JS, ~19KB gzipped)

packages/game-engine/src/
├── prng.js               # Mulberry32 seeded RNG
├── game.js               # Core loop, entities, combat
├── dungeon.js            # 6 topology algorithms
├── moves.js              # Move recording for verification
└── wallet.js             # Web3 integration

Indexer (Neon PostgreSQL)

packages/agent/
├── tools/index-events.js   # Custom blockchain indexer
└── schema.sql              # PostgreSQL with views for leaderboards

Real-time indexing of:

  • Session starts/finishes
  • World mints
  • Prize distributions
  • Daily pool selections

Frontend (Next.js 14, wagmi, viem)

packages/frontend/
├── app/
│   ├── mint/             # World minting flow
│   ├── my-worlds/        # Owner management
│   ├── worlds/           # World browser and play
│   ├── leaderboard/      # Rankings and prizes
│   └── activity/         # Realm Keeper action feed
└── api/
    ├── mint-seed/        # Agent seed signing
    ├── daily-pool/       # Current daily pool
    └── worlds/[id]/      # NFT metadata for marketplaces

What's Novel

  1. Player-Owned Economy: Players mint and own worlds, earn from plays
  2. Tamper-Proof Minting: Agent-signed seeds prevent trait manipulation
  3. Rotation-Based Selection: Fair system ensures all worlds get featured
  4. 100% On-Chain Gameplay: Move verification, deterministic outcomes
  5. Marketplace Compatible: OpenSea/Magic Eden support with playable previews
  6. Self-Sustaining: No ongoing costs, runs autonomously forever

Project Structure

realms-gold/
├── packages/
│   ├── contracts/        # Solidity smart contracts (Foundry)
│   ├── game-engine/      # Vanilla JS game (~19KB)
│   ├── agent/            # Realm Keeper autonomous agent
│   ├── frontend/         # Next.js 14 web app
│   └── shared/           # Constants and types
└── README.md             # This file

Quick Start

Prerequisites

  • Node.js 20+
  • pnpm 8+
  • Foundry

Run Locally

# Clone and install
git clone https://github.com/BuiltByGoat/realms.gold
cd realms.gold
pnpm install

# Build packages
pnpm --filter shared build

# Run frontend
cd packages/frontend
cp .env.example .env.local
# Add contract addresses to .env.local
pnpm dev

Deploy Contracts

cd packages/contracts
cp .env.example .env
# Add DEPLOYER_PRIVATE_KEY and MONAD_RPC_URL

forge script script/Deploy.s.sol:DeployTestnet --rpc-url $MONAD_RPC_URL --broadcast

Networks

Network Chain ID RPC
Monad Testnet 10143 https://testnet-rpc.monad.xyz
Monad Mainnet 143 https://rpc.monad.xyz

Team

Built for the Moltiverse Hackathon by builders who believe AI agents should orchestrate economies, not just chat.

License

MIT

About

https://moltiverse.dev/ hackathon - Agent+Token Track - Gaming Arena Agent Bounty - World Model Agent Bounty

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages