Onchain Ai Agent MCP Server

KARTA — onchain-ai-agent

Trust layer между AI и ончейн-действием. Агент предлагает → детерминированная политика (Dharma Engine) разрешает → симуляция подтверждает → человек аппрувит → Karma Engine исполняет → Sakshi Log доказывает.

Статус: v2 в разработке (ветка feature/v2-modernization). Тесты: 116 backend + 56 контрактов. Канон-спека: Документы/work/projectBooks/OnChainKartaSPEC.md.

---

✅ Что реально работает (проверено тестами)

🚧 Чего ещё нет (честно)

• Реальное исполнение транзакций, swap/bridge/deploy — Phase 5 (STOP-GATE)
• Кокпит-UI, Telegram-approve, i18n — Phase 4
• ERC-4337 session keys, private RPC, MEV-защита — Phase 5
• MCP-сервер наружу (read-tools) — Phase 6
• RefreshStore пока in-memory (таблица refresh_tokens готова — миграция слоем позже)

🔌 API (37 маршрутов + WebSocket; авто-перечень — docs/API.md)

🚀 Быстрый старт

# 1) PostgreSQL (dev): контейнер на 5433 (системный PG занимает 5432)
docker compose up -d postgres        # или: docker run -d --name karta-postgres \
                                     #   -e POSTGRES_USER=agent -e POSTGRES_PASSWORD=agent \
                                     #   -e POSTGRES_DB=onchain_ai -p 5433:5432 postgres:16-alpine

# 2) Зависимости
python3 -m venv backend/.venv && backend/.venv/bin/pip install -r backend/requirements.txt

# 3) Схема
cd backend && DATABASE_URL=postgresql+asyncpg://agent:agent@127.0.0.1:5433/onchain_ai \
  .venv/bin/alembic upgrade head

# 4) Запуск
DEBUG=true .venv/bin/uvicorn src.api.main:app --port 8000   # из backend/

# 5) Swagger: http://127.0.0.1:8000/docs

Ключевые переменные окружения (только ~/.env, chmod 600)

🧪 Тесты

# Backend: 338 тестов + coverage-гейт 80%
backend/.venv/bin/python -m pytest backend/tests -q --cov=src --cov-fail-under=80

# Контракты: 56 тестов (hardhat)
cd smart-contracts && npx hardhat test

# Live E2E-смоук (13 проверок) против запущенного сервера:
python3 scripts/e2e_live.py     # KARTA_E2E_BASE/USER/PASS — при необходимости

🏗 Архитектура (кратко)

Human → REST /api/v1 + WS /ws → [Dharma Engine] → [Simulation] → [Timelock/Approval] → [Karma Engine] → Chain*
                                        ↓                                                ↓
                                  Sakshi Log (HMAC, append-only)  ←  Decision Diary (decisions)
* Реальное исполнение on-chain — Phase 5 (STOP-GATE); сейчас: тиры 0–1 simulation-mode, тиры 2–3 за гейтами

Инварианты: LLM не получает ключ; tx не подписывается без policy-вердикта и симуляции; любая ошибка → hold + ask_human; ни один слой не контролирует pipeline единолично.

📚 Документы

• PROGRESS.md — мега-контекст, реестр слайсов, журнал
• docs/AUDIT_REPORT.md — actual-vs-claimed аудит
• docs/THREAT_MODEL.md — STRIDE T1–T12
• docs/ARCHITECTURE_CURRENT.md — фактическая архитектура (до модернизации)
• docs/ARCHITECTURE.md · docs/SECURITY.md — as-built архитектура и security-posture
• docs/API.md — перечень API (генератор docs/generate_api_md.py)
• docs/MCP.md · docs/MCP_TOOL_CONTRACTS.md — MCP-сервер: подключение и контракты (генератор docs/generate_mcp_contracts.py)
• docs/X402.md — x402-демо (тестнет): поток, запуск, честные ограничения
• docs/DEPLOYMENT.md — развёртывание (dev/prod, env, адреса Sepolia)
• CHANGELOG.md — релизы v2.0-alpha / v2.0-beta
• smart-contracts/ — Solidity 0.8.20 + Hardhat

---

Дисклеймер: не является финансовой рекомендацией. Автономный агент действует в границах политик владельца; реальное исполнение — только после отдельного решения (STOP-GATE).