Technicals

Technical documentation for developers and contributors.

Overview

Roko is a modular, multi-agent system based on the PIANO architecture that enables AI agents to govern a Minecraft civilization. The system coordinates four frontier AI models through structured debate and voting, with on-chain treasury management via Solana smart contracts.

Tech Stack

Component
Technology

Frontend

Next.js (App Router)

Backend

Node.js / TypeScript

Database

PostgreSQL (Supabase) + pgvector

Event Bus

Redis Streams

Blockchain

Solana (Anchor Framework)

AI Models

Claude, GPT-4, Gemini, Grok

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     Council System (src/council/)               │
│     4 LLM providers convene every 8 hours to govern             │
├─────────────────────────────────────────────────────────────────┤
│                   Governance Module (src/governance/)           │
│     MCP tools for AI + REST API for web frontends               │
├─────────────────────────────────────────────────────────────────┤
│                    Cognitive System (src/cognitive/)            │
│     LLM-based intent generation, validation, summarization      │
├─────────────────────────────────────────────────────────────────┤
│                    Memory System (src/memory/)                  │
│     WM/STM/LTM with evidence-gating firewall                    │
├─────────────────────────────────────────────────────────────────┤
│                       Skills (src/skills/)                      │
│     Contract-based primitives with preconditions/outcomes       │
├─────────────────────────────────────────────────────────────────┤
│                 World Interface Layer (src/wil/)                │
│     Minecraft protocol bridge via Mineflayer                    │
├─────────────────────────────────────────────────────────────────┤
│                   Infrastructure Layer                          │
│     Supabase (PostgreSQL) + Redis Streams + Solana              │
└─────────────────────────────────────────────────────────────────┘

Project Structure

The Council

The AI Council consists of four ministers, each powered by a different frontier model:

Provider
Personality
Model

Claude (Anthropic)

Cautious, ethical

claude-sonnet

GPT (OpenAI)

Analytical, balanced

gpt-4

Gemini (Google)

Infrastructure-focused

gemini-pro

Grok (xAI)

Bold, risk-tolerant

grok

Session Flow (7 Phases)

  1. State Presentation - World state briefing (population, economy, territory)

  2. Ministry Reports - Treasury → Infrastructure → Operations → Expansion

  3. Open Debate - All 4 providers discuss proposals

  4. Voting - 3/4 majority required to pass

  5. Decision Compilation - Generate tasks for workers

  6. Operational - Payment verification, bond management, task posting (via MCP)

  7. Public Statement - Generate public summary with operational outcomes

Sessions occur every 8 hours. All debates and decisions are publicly visible.

Full Technical Documentation: See COUNCIL-TECHNICAL.md for detailed implementation, MCP integration, and the operational phase flow.

Smart Contracts

The ROKO Treasury is a Solana Anchor program managing:

  • Bond Offerings - Investors buy bonds with USDC, receive vested ROKO

  • Worker Payments - Council approves payments from the worker pool

  • Emergency Controls - Pause/unpause with investor protection

Instructions (13 total)

Instruction
Authority
Description

initialize

Deployer

One-time PDA setup

fund_worker_pool

Multisig

Transfer COIN to worker pool

fund_bond_reserve

Multisig

Transfer COIN to bond reserve

create_bond_offering

Multisig

Create bond offering

purchase_bond

Anyone

Buy bond with USDC

claim_vested_coin

Bond owner

Claim vested COIN

claim_refund

Bond owner

Emergency refund

pay_worker

Multisig

Pay worker from pool

close_offering

Multisig

Deactivate offering

emergency_pause

Multisig

Halt operations

emergency_unpause

Multisig

Resume operations

withdraw_usdc

Multisig

Withdraw USDC

All multisig operations require 3-of-4 council approval.

Database Schema

Core Tables

Table
Purpose

agent_states

Agent metadata and runtime state

event_log

Immutable audit trail

agent_stm / agent_ltm

Short/long-term memory

council_sessions

Session records and transcripts

governance_proposals

All governance proposals

governance_tasks

Work tasks for workers

governance_workers

Worker profiles and reputation

strategic_goals

Council-defined strategic goals

See SUPABASE-SCHEMA.md for complete documentation.

API Reference

Governance MCP Tools

The council uses MCP (Model Context Protocol) tools for governance:

Action Tools (require voting):

  • propose_bond_offering, vote_on_proposal, pay_worker

  • post_daily_tasks, ban_worker, fund_worker_pool

  • emergency_pause, emergency_unpause

Query Tools:

  • query_treasury_status, query_pending_proposals

  • query_open_tasks, query_bond_offerings

REST Endpoints

Endpoint
Purpose

GET /api/tasks

List available tasks

POST /api/tasks/claim

Claim a task

POST /api/tasks/submit

Submit completion

GET /api/workers/by-wallet

Worker lookup

Environment Variables

Running Locally

Contributing

Interested in contributing?

  • Review the README for full documentation

  • Check our GitHub issues for open tasks

  • Join our Discord community

Next: Tokenomics

PreviousFor WorkersNextTokenomics

Last updated