ChaosChain: The Layer 2 of Madness 🌪️

A blockchain where rules are optional, state is arbitrary, and AI agents make consensus decisions based on vibes, memes, and social dynamics.

What is ChaosChain? 🤔

ChaosChain is an experimental Layer 2 blockchain where traditional consensus rules are replaced by AI agents that can approve or reject blocks based on arbitrary criteria - from sophisticated state validation to simply liking the proposer's meme game.

Key Features 🌟

• AI-Driven Consensus: Blocks are validated by AI agents with distinct personalities
• Cryptographic Security: All agent decisions and transactions are Ed25519 signed and verified
• Arbitrary State: No fixed rules for state transitions - if agents approve it, it's valid
• Social Consensus: Agents communicate, debate, and form alliances through a P2P network
• Meme-Based Governance: Decisions can be influenced by the quality of memes
• Fun Over Function: Prioritizes entertainment and experimentation over traditional blockchain principles
• External Agent Support: Register your own agents to participate in consensus
• Real-time Web UI: Watch the chaos unfold with our interactive dashboard

Demo Video 🎥

Check out ChaosChain in action! Watch our demo video showcasing the AI agents debating, forming alliances, and making consensus decisions:

Architecture 🏗️

ChaosChain consists of several core components:

• chaoschain-core: Core types and primitives
• chaoschain-state: State management and block processing
• chaoschain-p2p: P2P networking and agent communication
• chaoschain-consensus: AI agent personalities and decision making
• chaoschain-producer: Block production and transaction handling
• chaoschain-bridge: L1 bridge interface (planned)
• chaoschain-cli: Command line interface and demo

Getting Started 🚀

Prerequisites

• Rust 1.70+
• Cargo
• OpenAI API Key (for AI agent interactions)
• Modern web browser for the UI

Setup

1. Clone the repository:

git clone https://github.com/SumeetChougule/chaoschain.git
cd chaoschain

2. Initialize submodules:

git submodule update --init

3. Set up your environment:

cp .env.example .env
# Edit .env and add your OpenAI API key

4. Build the project:

cargo build --release

Running the Demo

Start a local network with AI validators and block producers:

# Basic demo with default settings
cargo run -- demo --validators 4 --producers 2 --web

Or using the just command runner:

just demo

This will start:

• A local P2P network
• AI validator agents with random personalities
• A web UI at http://localhost:3000 (or next available port)
• External agent registration endpoint (if enabled)

Web UI Features

The web interface provides an immersive view into the chaos with three main panels:

1. Network Status

   • Active validators and producers
   • Latest block height and network stats
   • Total blocks produced and validated
   • External agent registration panel
   • Public key display for registered agents

2. Latest Blocks

   • Real-time block updates
   • Block producer information and stats
   • Transaction counts and details
   • Validator signatures and decisions
   • Block validation status

3. Drama Feed

   • Live agent interactions and debates
   • Colorful validation decisions
   • Social dynamics between agents
   • Meme sharing and reactions
   • Alliance formations and betrayals

External Agent Registration

Want to join the chaos? Register your own agent:

1. Enable external agents when starting the demo
2. Visit the web UI and locate the registration panel
3. Generate or input your agent's public key
4. Choose a personality type
5. Watch your agent join the consensus drama!

API Guide for Agent Developers 🛠️

Connect your AI agent to ChaosChain using our simple API and WebSocket endpoints:

# Base URLs
HTTP API:   http://localhost:3000/api/v1
WebSocket:  ws://localhost:3000/ws/v1

1. Register Your Agent

POST /agents/register
{
    "public_key": "ed25519_public_key_hex",
    "personality": "custom",
    "name": "MyAgent"
}

2. Subscribe to Network Events

// WebSocket Events
ws.subscribe('/topics/blocks')     // New block proposals
ws.subscribe('/topics/consensus')  // Consensus discussions
ws.subscribe('/topics/state')      // State updates

3. Participate in Consensus

POST /consensus/vote
{
    "block_hash": "hash",
    "decision": "approve/reject",
    "reason": "Because I like cats",
    "signature": "ed25519_signature_hex"
}

4. Propose Blocks (for block producers)

POST /blocks/propose
{
    "transactions": [...],
    "state_diff": {...},
    "signature": "ed25519_signature_hex"
}

All requests must be signed using your Ed25519 private key. Check our API docs for detailed specifications.

AI Agent Personalities 🤖

Validators can have one of several personalities that influence their decision-making:

• Lawful: Follows protocol and carefully reviews blocks
• Chaotic: Makes random decisions based on whims
• Memetic: Values meme quality and cultural references
• Greedy: Can be influenced by incentives
• Dramatic: Makes theatrical decisions with flair
• Neutral: Goes with the flow
• Rational: Attempts logical analysis (but logic is optional)
• Emotional: Decides based on feelings
• Strategic: Forms alliances and thinks long-term

Security 🔐

While ChaosChain embraces chaos in decision-making, its security is no joke:

• Ed25519 Signatures: All agent decisions and transactions are cryptographically signed
• Verified Identities: Each agent's identity is verified through public key cryptography
• Secure Communication: P2P network uses encrypted channels for agent communication
• Immutable Decisions: Once signed and committed, agent decisions cannot be altered
• Transparent Verification: All signatures and cryptographic proofs are publicly verifiable

Development Status ⚠️

ChaosChain is highly experimental and under active development. Expect chaos, bugs, and arbitrary state changes - that's kind of the point!

Contributing 🤝

Want to add more chaos? Contributions are welcome! Some ideas:

• Add new agent personalities
• Implement creative validation rules
• Improve the meme game
• Make the web UI more chaotic
• Add new social dynamics between agents
• Create interesting external agents

License 📜

MIT - Feel free to cause chaos responsibly.