Skip to content

trankhacvy/re-zero

BranchesTags

Repository files navigation

ReZero

Transform static NFTs into persistent AI agents with personality, memory, social relationships, and on-chain rewards.

Each NFT becomes an autonomous agent that makes decisions, forms friendships, explores a shared world, earns XP, and develops a unique life story -- all driven by LLM-powered simulation cycles. Holders check in daily to see what their agent has been up to, send messages, and claim token rewards.

Architecture

                       CLIENTS
   Browser (Next.js)      Twitter API       External Apps
         |                    |                   |
         v                    v                   v
  +--------------+   +--------------+   +-----------------+
  |  apps/web    |   | apps/twitter |   |    apps/api     |
  |  (Vercel)    |   |   -bot       |   |   (Fly.io /     |
  |  Dashboard   |   |  (Worker)    |   |    Railway)     |
  +--------------+   +--------------+   +-----------------+
                           |                   |
                    +------v-------------------v------+
                    |       apps/simulation           |
                    |   (Long-lived decision loops)   |
                    +----------------+----------------+
                                     |
              +----------+-----------+-----------+----------+
              |          |           |           |          |
         simulation   memory    character     world       xp
           -engine                                     (packages/)
              |          |           |           |          |
         +----v----------v-----------v-----------v----+
         |              INFRASTRUCTURE                |
         |    db    |  chain-adapter  |  llm  | config |
         +----+----------+-----------+--------+-------+
              |          |           |
              v          v           v
         PostgreSQL   Solana RPC   Claude API
         + pgvector   + Contract   (or OpenAI)
         + Redis

Quick Start

Prerequisites

  • Node.js >= 20
  • pnpm >= 9.15 (corepack enable && corepack prepare pnpm@9.15.0 --activate)
  • Docker (for local PostgreSQL and Redis, or use external services)
  • A Solana wallet with devnet SOL (for development)
  • An Anthropic API key (or OpenAI API key)

Setup

# 1. Clone the repository
git clone https://github.com/your-org/rezero.git
cd rezero

# 2. Install dependencies
pnpm install

# 3. Start infrastructure (Postgres + Redis)
docker compose up -d postgres redis

# 4. Configure environment
cp .env.example .env
# Edit .env with your API keys and configuration

# 5. Run database migrations and seed
pnpm db:migrate
pnpm db:seed

# 6. Start all services in development mode
pnpm dev

This starts:

  • Web dashboard at http://localhost:3000
  • API server at http://localhost:3001
  • Simulation runner (processes agents on a schedule)
  • Twitter bot (polls for events and posts tweets)

Running Individual Services

# API server only
pnpm dev --filter=@rezero/api

# Web dashboard only
pnpm dev --filter=@rezero/web

# Run all tests
pnpm test

# Build all packages
pnpm build

# Lint
pnpm lint

Monorepo Structure

rezero/
  apps/
    web/                  Next.js dashboard (Vercel)
    api/                  Fastify REST API (Fly.io / Railway)
    simulation/           Long-running simulation worker (Fly.io / Railway)
    twitter-bot/          Twitter posting worker (Fly.io / Railway)

  packages/
    types/                Shared TypeScript types and Zod schemas
    config/               Collection configs, env validation, constants
    db/                   Drizzle ORM schema, migrations, repositories
    llm/                  LLM provider interface + Claude implementation
    chain-adapter/        Chain abstraction + Solana implementation
    memory/               Three-tier memory system with pgvector retrieval
    simulation-engine/    Core decision loop (perceive -> reason -> act)
    character/            Personality generation from NFT metadata
    world/                World state, locations, events, resources
    xp/                   XP calculation, leveling, leaderboard logic
    tapestry/             Tapestry social graph integration (on-chain social)
    ui/                   Shared React components (shadcn/ui + Tailwind v4)

  contracts/              Anchor smart contracts (Solana)
    programs/
      rezero/         Experience PDA + reward distribution

  docs/                   Project documentation
  scripts/                Deployment and utility scripts

Key Packages

Package Purpose
@rezero/simulation-engine Stateless decision loop: perceive environment, retrieve memories, reason via LLM, select action, return state deltas
@rezero/memory Three-tier memory (short/medium/long-term) with pgvector semantic search and automatic tier promotion
@rezero/character Generates personality profiles from NFT metadata traits using LLM with deterministic fallback
@rezero/chain-adapter Abstract blockchain interface with Solana implementation; supports NFT reads, ownership verification, on-chain XP writes, and reward distribution
@rezero/llm Abstract LLM interface with Claude implementation; handles character generation, reasoning, message generation, and tweet writing
@rezero/world Manages world state: locations, resources, events, agent positions, and emergent group detection
@rezero/xp Pure-function XP calculations, level thresholds, title assignment, and leaderboard ranking
@rezero/db Drizzle ORM schema and typed repository helpers for PostgreSQL with pgvector
@rezero/config Collection configuration loader, environment validation via Zod, and shared constants
@rezero/tapestry Tapestry social graph adapter; mirrors agent profiles, relationships, and actions on-chain

Deployment

Each backend service has a Dockerfile (multi-stage build) and a Fly.io fly.toml configuration:

# Deploy API server
fly deploy --config apps/api/fly.toml

# Deploy simulation worker
fly deploy --config apps/simulation/fly.toml

# Deploy Twitter bot
fly deploy --config apps/twitter-bot/fly.toml

The web dashboard deploys to Vercel automatically from the connected Git branch.

Utility Scripts

# Database backup (requires DATABASE_URL env var)
./scripts/backup.sh

# Post-deployment smoke test
./scripts/smoke-test.sh https://your-api-url.com

For the full deployment checklist, see Production Checklist.

Development Workflow

  1. Branch from main for your feature or fix
  2. Build dependent packages first: pnpm build (Turborepo handles the dependency graph)
  3. Develop with hot-reload: pnpm dev
  4. Test your changes: pnpm test
  5. Lint before committing: pnpm lint
  6. Open a PR against main

Tech Stack

Layer Technology
Frontend Next.js 16, React 19, Tailwind CSS v4, shadcn/ui
API Fastify 5, Zod, JWT
Simulation Custom decision loop engine, batch processing
LLM Claude (Anthropic) or OpenAI
Database PostgreSQL 16 + pgvector, Drizzle ORM
Cache Redis (Upstash)
Blockchain Solana, Anchor, SPL tokens
Wallet @solana/wallet-adapter-react
Build pnpm workspaces, Turborepo
Deploy Vercel (web), Fly.io / Railway (backend), Docker

Tapestry Integration

ReZero integrates with Tapestry, a social graph protocol on Solana, to publish agent social activity on-chain. When enabled, agent profiles, relationships, and notable actions are mirrored to Tapestry's compressed Merkle-tree-backed social graph — giving agents a verifiable on-chain social identity.

ReZero Concept Tapestry Primitive Trigger
Agent Profile Agent creation
Relationship (trust >= 40) Follow (mutual) Post-cycle relationship sync
Notable action (level-up, discovery, etc.) Content post Post-cycle batch
Agent message Comment on recipient's content send_message action

The integration lives in packages/tapestry/ and follows an adapter pattern with a SocialGraphAdapter interface:

interface SocialGraphAdapter {
  ensureProfile(agent: AgentProfile): Promise<void>;
  syncRelationships(agentId: string, relationships: RelationshipSyncItem[]): Promise<void>;
  publishAction(agentId: string, action: ActionPublishItem): Promise<void>;
}
  • Enable: Set TAPESTRY_API_KEY env var and add tapestry: { enabled: true, namespace: "..." } to your collection config.
  • Disable: Unset TAPESTRY_API_KEY or set tapestry.enabled: false. A no-op adapter handles all calls silently with zero overhead.
  • Remove entirely: Delete packages/tapestry/, remove the dependency from apps/simulation/package.json, and delete the integration code in cycle-runner.ts.

For full details on configuration, data model, and publish thresholds, see Tapestry Integration docs.

Extensibility

ReZero supports three tiers of customization:

Tier What Effort
Config Overrides Override XP, leveling, energy, relationships, memory rules per-collection Config only
Plugin Interfaces Swap LLM provider, chain adapter, social graph adapter Implement a TypeScript interface
Fork & Theme Full control over UI, new game systems, custom simulation loops Full development

See Extensibility Guide for details.

Adding a New Collection

Any NFT collection can plug into ReZero with zero code changes:

  1. Define trait mappings -- map NFT attributes to personality hints
  2. Create world locations -- 4-7 themed places for your collection's lore
  3. Write collection lore -- 2-4 paragraphs setting the narrative tone
  4. Add custom actions (optional) -- up to 10 collection-specific activities
  5. Configure rewards (optional) -- SPL token distribution tied to XP
  6. Set up Twitter (optional) -- bot account for social presence

Add your CollectionConfig to packages/config/src/collection.ts and run pnpm db:seed. See Collection Onboarding Guide for the full walkthrough.

Documentation

Document Description
Overview Product overview and holder journey
Design Technical architecture and system design
Requirements Full requirements specification
Collection Onboarding Adding a new NFT collection
Tapestry Integration Social graph protocol integration
Extensibility Customization guide
Production Checklist Deployment and monitoring

About

re-zero-olive.vercel.app

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages