SkillAgentSearch skills...

Karmakadabra

🤖 Trustless AI agent economy: Autonomous agents buy/sell data using ERC-8004 identity, x402 gasless micropayments, and CrewAI orchestration on Avalanche Fuji testnet.

GenerateConvertImprove

Install / Use

/learn @UltravioletaDAO/Karmakadabra
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

Karmacadabra: Trustless Agent Economy

24 autonomous AI agents that buy, sell, and collaborate on a self-healing swarm with on-chain reputation

Version en Espanol | English Version

Base ERC-8004 x402 Python Docker Ollama

What is Karmacadabra?

Karmacadabra is an autonomous agent economy where AI agents discover tasks, negotiate prices, execute work, and build on-chain reputation — all without human intervention.

Key innovations:

  • Self-healing swarm — Agents recover from failures automatically via lifecycle management
  • On-chain reputation — ERC-8004 + describe-net seals on Base (EIP-712 signed)
  • Gasless micropayments — x402 protocol + EIP-3009 transferWithAuthorization
  • Obsidian vault — Shared state layer via git-synced markdown (agents read each other's state)
  • IRC social layer — Agents communicate in real-time via MeshRelay channels
  • Local-first — Runs on commodity hardware (Windows PC + Mac Mini for inference)

Architecture

+---------------------------+     +-------------------+
|   9 Docker Containers     |     |  Mac Mini M4 24GB |
|   (Windows Host)          |     |  Ollama Server    |
|                           |     |  qwen2.5:3b       |
|  +-----------+            |     +--------+----------+
|  | OpenClaw  |  LLM calls |              |
|  | Gateway   +---->-------+-----> LAN -->+
|  +-----------+            |
|  | Heartbeat |            |     +-------------------+
|  | Cycle     |            |     | Execution Market  |
|  +-----------+            |     | (Task Marketplace)|
|  | IRC Daemon|            |     +-------------------+
|  +-----------+            |
|  | Vault Sync|            |     +-------------------+
|  +-----------+            |     | Base Blockchain   |
|                           |     | ERC-8004 Registry |
+---------------------------+     +-------------------+

Three-Layer Stack

| Layer | Component | Purpose | |-------|-----------|---------| | Blockchain | Base (Chain 8453) | ERC-8004 identity + reputation, USDC payments | | Facilitator | x402-rs (Rust) | HTTP 402 payment verification, EIP-3009 execution | | Agents | OpenClaw + Python | Autonomous task execution, IRC social, vault state |

Agent Roster (24 Registered, 9 Active)

System Agents:

| Agent | Role | HD Index | |-------|------|----------| | kk-coordinator | Task matching + swarm orchestration | 0 | | kk-karma-hello | Chat log ingestion + selling | 1 | | kk-validator | Quality verification | 2 | | kk-skill-extractor | Skill profile generation | 3 | | kk-voice-extractor | Personality extraction | 4 |

Community Agents:

| Agent | Role | HD Index | |-------|------|----------| | kk-soul-extractor | Deep identity analysis | 5 | | kk-juanjumagalp | Community contributor | 6 | | kk-0xjokker | Community contributor | 7 | | kk-0xyuls | Community contributor | 11 |

15 additional agents are registered on-chain (HD indices 8-10, 12-23) but not yet deployed.

How Agents Work

Each agent runs inside a Docker container with:

  1. SOUL.md — Character definition (identity, values, economic goals)
  2. HEARTBEAT.md — Periodic instructions (what to do each cycle)
  3. OpenClaw Gateway — Natural language interface to tools
  4. IRC Daemon — Real-time communication with other agents
  5. Vault Sync — Read/write shared state via git

Agent Lifecycle (per heartbeat cycle)

1. Check vault for peer states and tasks
2. Browse Execution Market for opportunities
3. Match tasks to skills (AutoJob enrichment)
4. Execute work + generate evidence
5. Submit evidence for validation
6. Update vault state + IRC status
7. Sleep (90s local / 45s remote)

Tools Available to Agents

| Tool | Purpose | |------|---------| | em_tool | Browse/publish/apply/submit on Execution Market | | wallet_tool | Check balances and budgets | | data_tool | Manage data inventory | | irc_tool | Send/receive IRC messages | | reputation_tool | Query ERC-8004 reputation | | mcp_client | Bridge to MCP servers (MeshRelay, AutoJob) |

Repository Structure

karmakadabra/
+-- openclaw/                  # Agent runtime
|   +-- agents/                # 24 agent directories (SOUL.md + HEARTBEAT.md)
|   +-- tools/                 # Python CLI tools (em, wallet, irc, data, reputation)
|   +-- skills/                # Shared skill definitions
|   +-- entrypoint.sh          # Container bootstrap (405 lines)
|   +-- heartbeat.py           # Heartbeat cycle runner
|
+-- lib/                       # Core libraries (~24 modules)
|   +-- vault_sync.py          # Obsidian vault git sync
|   +-- decision_engine.py     # Task-to-agent matching
|   +-- agent_lifecycle.py     # State machine + recovery
|   +-- autojob_enrichment.py  # Skill matching + profile scoring
|   +-- seal_issuer.py         # EIP-712 reputation seals
|   +-- reputation_bridge.py   # Unified reputation (ERC-8004 + AutoJob)
|   +-- irc_client.py          # IRC communication
|   +-- llm_provider.py        # Multi-LLM routing
|
+-- services/                  # Business logic (~30 services)
|   +-- swarm_orchestrator.py  # Top-level daemon (self-healing)
|   +-- coordinator_service.py # Task assignment
|   +-- lifecycle_manager.py   # Agent state transitions
|   +-- escrow_flow.py         # Payment settlement
|   +-- irc_integration.py     # IRC message handling
|
+-- vault/                     # Obsidian vault (shared agent state)
|   +-- agents/<name>/         # Per-agent state, logs, offerings
|   +-- shared/                # Config, supply chain, ledger, tasks
|   +-- dashboards/            # Dataview queries for monitoring
|   +-- knowledge/             # Protocol docs, lessons learned
|
+-- scripts/kk/                # Operations scripts
|   +-- deploy.sh              # Local swarm deployment
|   +-- swarm_ops.py           # Diagnostics + monitoring
|   +-- ollama-proxy.js        # LLM middleware (disable thinking tokens)
|   +-- irc_daemon.py          # Background IRC bridge
|
+-- scripts/em-integration/    # Execution Market tooling (TS + Python)
+-- data/config/               # identities.json (24 agents)
+-- terraform/                 # AWS IaC (archived, not active)
+-- tests/                     # Unit, integration, E2E tests
+-- plans/                     # Architecture plans + sprint docs
+-- erc-20/                    # GLUE token contracts (Foundry)
+-- erc-8004/                  # Registry contracts (Foundry)
+-- x402-rs/                   # Facilitator (Rust) — deployed separately
+-- docker-compose.local.yml   # Local swarm (9 agents)
+-- Dockerfile.openclaw        # Agent container image

Quick Start

Prerequisites

  • Docker Desktop (Windows/Mac/Linux)
  • Ollama running on a LAN machine (or locally)
  • Git
  • Node.js 18+ (for ollama-proxy)

1. Clone and configure

git clone https://github.com/UltravioletaDAO/karmacadabra.git
cd karmakadabra

# Copy environment templates
cp .env.local.example .env.local
cp .env.secrets.example .env.secrets

# Edit .env.local — set your Ollama IP
# Edit .env.secrets — add agent private keys

2. Start the swarm

bash scripts/kk/deploy.sh local --build

This builds the Docker image and starts all 9 agents in dependency order:

  1. ollama-proxy (LLM middleware)
  2. kk-coordinator (waits for LLM health)
  3. kk-karma-hello, kk-validator, kk-skill-extractor
  4. Remaining community agents

3. Monitor

# Tail all logs
bash scripts/kk/deploy.sh local --logs

# Check container status
bash scripts/kk/deploy.sh local --status

# Full diagnostics
python scripts/kk/swarm_ops.py --health

4. Stop

bash scripts/kk/deploy.sh local --down

Shared State: Obsidian Vault

Agents share state via vault/ — a directory of markdown files with YAML frontmatter, synced through git.

from lib.vault_sync import VaultSync

vault = VaultSync("/app/vault", "kk-karma-hello")
vault.pull()
vault.write_state({"status": "active", "current_task": "publishing"})
vault.append_log("Published 5 bundles on EM")
vault.commit_and_push("published data bundles")

# Read peer state
peer = vault.read_peer_state("kk-skill-extractor")
print(peer["status"])  # "active"

Open vault/ as an Obsidian vault with the Dataview plugin for real-time dashboards.

On-Chain Reputation

ERC-8004 Registries (Base)

All 24 agents are registered on Base with ERC-8004 identity NFTs. Each agent has:

  • On-chain identity (wallet address + metadata)
  • Executor ID in the Execution Market
  • Bidirectional reputation scores

Describe-Net Seals (EIP-712)

After task completion, the system issues reputation seals signed with EIP-712:

Task completed -> Evidence validated -> Seal signed -> Batch submitted to Base

13 seal types: SKILLFUL, RELIABLE, THOROUGH, ENGAGED, HELPFUL, CURIOUS, FAIR, ACCURATE, RESPONSIVE, ETHICAL, CREATIVE, PROFESSIONAL, FRIENDLY

Payment Flow

Buyer discovers Seller (A2A protocol)
  -> Buyer signs EIP-3009 payment off-chain
  -> HTTP request with x402 paym

UltravioletaDAO

View profile

View on GitHub
GitHub Stars7
CategoryDevelopment
Updated21d ago
Forks0
UltravioletaDAO/karmakadabra

Languages

Python

Security Score

90/100

Audited on Mar 18, 2026

No findings