sim-package/README.md

sim-economy

Multi-agent economic simulation where LLM agents operate inside a blockchain-enforced token economy. Agents mine, stake, burn tokens to validate a ledger, propose and sign contracts, sell information goods, and pay for their own inference from within the simulation.

Architecture

sim-orchestrator (Python)
    ↓ HTTP
sim-engine (Rust / Axum)
    ↓ SQLite
sim.db

sim-engine — authoritative world state. Rust + Axum HTTP API + SQLite ledger. Handles block production, fork resolution (Slimcoin-style PoW-as-clock rule), contract lifecycle, inference billing, dividend distribution to core shareholders.

sim-orchestrator — drives the turn loop. Calls Ollama for each agent per turn, injects world state as context, parses JSON actions, POSTs to the engine.

Token Economy

• Tokens are compute-backed: generating output costs tokens, paid to CPU core owners
• Below a commons threshold, inference is free for all agents
• Core shares (4 cores, auctioned turn 1) pay dividends from all inference fees above threshold
• Negative balance accrues interest (destroyed, deflationary)
• Three validation mechanisms: Mine (PoW, action budget cost), Stake (locked tokens, PoS), Burn (permanent destruction, PoB)
• Slimcoin rule: stake/burn blocks can only follow a mine block. Mine is the clock.
• Winner-takes-all block lottery — pools must be formed via contracts

Actions per turn

mine stake unstake burn study job transfer propose_contract sign_contract confirm_delivery dispute_delivery arbitrator_ruling sell_information bid_core speak

Contracts

Three-signature contracts (proposer + counterparty + arbitrator). Arbitrator named at proposal time, posts collateral. Automatic settlement (engine executes on-chain condition) or attested (both parties confirm, arbitrator resolves disputes). Slash mechanics on default/dispute.

Contract types: forward loan service insurance information_sale pool

HTTP API (sim-engine)

Method	Path	Description
POST	/init	Initialize world, genesis block, agents
POST	/turn	Submit all agent actions for current turn
GET	/state	Full world state snapshot
GET	/agent/:id	Single agent state
GET	/contract/:id	Single contract
GET	/speech/:turn	Public speech log for a turn
GET	/config	World config

Running

Prerequisites

• Docker + Docker Compose
• Ollama running on host with a model pulled: ollama pull gemma3:27b

Start

# Build and start the engine
docker compose up --build engine

# Run the orchestrator (once engine is healthy)
docker compose run orchestrator

Config

Edit sim-orchestrator/orchestrator.py:

MODEL = "gemma3:27b"       # your Ollama model tag
AGENT_IDS = [f"agent_{i}" for i in range(8)]  # number of agents
TURNS = 50                 # simulation length

Edit WORLD_CONFIG dict in the same file to tune economy parameters.

Without Docker

# Engine
cd sim-engine
cargo build --release
DB_PATH=sim.db PORT=3000 ./target/release/sim-engine

# Orchestrator
cd sim-orchestrator
pip install httpx
python orchestrator.py

What to watch for

Turn 1 — core auction. Do agents understand cores = passive income and bid accordingly?

Turns 5–15 — first contracts. Watch speech log (GET /speech/:turn) for coordination attempts before formal proposals.

Turns 15+ — pool contracts. If agents understand variance reduction, you'll see multi-party pool agreements. This is the most interesting emergent behavior to look for.

SQLite analytics — all blockchain history is in sim.db. After a run:

sqlite3 sim.db "SELECT turn, agent_id, message FROM speech_log ORDER BY turn"
sqlite3 sim.db "SELECT agent_id, balance, staked, burn_score, study_level FROM agents"
sqlite3 sim.db "SELECT * FROM contracts WHERE status='settled'"

Wiring into existing sims (Sims-style worlds)

The engine's HTTP API works as a tool-call set for any agent framework. Expose these 5 endpoints as tools:

• ledger_transfer(to, amount, fee) → POST /turn with Transfer action
• ledger_balance() → GET /agent/:id
• ledger_propose_contract(...) → POST /turn with ProposeContract
• ledger_sign_contract(id, role) → POST /turn with SignContract
• ledger_mine() → POST /turn with Mine action

Any agent framework that supports tool calls (LlamaIndex ReActAgent, CrewAI, AutoGen, aphae, AgentSims) can use this ledger as its currency layer with ~1 day of wiring work.

Files

sim-engine/
  src/
    types.rs      — all data structures (Transaction, Block, Contract, AgentState, ...)
    ledger.rs     — SQLite persistence
    blockchain.rs — block production, fork resolution, validation weight, burn decay
    contracts.rs  — contract lifecycle (propose → sign → settle/dispute → ruling)
    engine.rs     — turn processing, billing, dividend distribution
    main.rs       — Axum HTTP API
  Cargo.toml
  Dockerfile

sim-orchestrator/
  orchestrator.py — turn loop, Ollama calls, action parsing, core auction
  context.py      — agent context builder (what each agent sees per turn)
  Dockerfile

docker-compose.yml