Skip to content

MICRODAO SERVICE SPEC (PORT 7004)

Version: 1.0.0

0. PURPOSE

MicroDAO Service — це базовий сервіс DAO-логіки для DAARION.city:

  • створення та управління microDAO (райони, команди, проєкти),
  • членство, ролі та entitlements (RBAC),
  • пропозиції (proposals) та голосування (voting),
  • інтеграція з ProjectBus, TeamDefinition та Agents Service,
  • точка правди про те, хто що може в межах кожного microDAO.

Фокус цієї версії (MVP):

  • Off-chain governance (Postgres + NATS),
  • без обов'язкового підключення до on-chain токенів (місце закладене, але може бути пустим).

Порт за замовчуванням: 7004.

1. CORE CONCEPTS

1.1. MicroDAO

Легка DAO-одиниця в екосистемі DAARION:

  • має microdao_id (наприклад, microdao-root, microdao-greenfood),
  • опис, місію, набір учасників,
  • пов'язане з одним або кількома project_id,
  • має власні:
  • ролі,
  • entitlements (доступи, дозволи),
  • voting-параметри.

1.2. Membership

Учасники microDAO:

  • user_id (людина),
  • agent_id (агент),
  • role_id (роль у DAO),
  • статус: active, pending, banned, left.

1.3. Roles & Entitlements

Ролі визначають, що можна робити в межах microDAO:

  • role_id: "owner", "admin", "member", "observer", "agent-core", ...
  • кожна роль має набір entitlements:
  • can_create_proposals,
  • can_vote,
  • can_manage_members,
  • can_manage_projects,
  • can_manage_teams,
  • can_manage_tokens (закладка під on-chain).

1.4. Proposals & Voting

Пропозиції:

  • створюються учасниками (люди/агенти) згідно entitlements,
  • приклади:
  • додати нового агента в команду,
  • змінити пріоритети сервісів,
  • створити новий проект,
  • змінити політику доступу,
  • мають статуси:
  • draft, open, accepted, rejected, expired.

Голосування:

  • голоси від учасників microDAO,
  • правила підрахунку/кворуму задаються у параметрах DAO.

2. HIGH-LEVEL ARCHITECTURE

[ Users / Agents / UI ]
        ↓
[ Gateway (Telegram/Web/Matrix/Front) ]
        ↓
[ DAGI Router ]
        ↓
[ MicroDAO Service (7004) ]
        ↓
[ Postgres (microdao_db) + NATS (events) + Agents Service ]

MicroDAO Service:

  • тримає модель DAO в Postgres,

  • публікує події в NATS:

  • microdao.<id>.events,

  • взаємодіє з:

  • Agents Service (щоб агенти розуміли, що їм дозволено),

  • ProjectBus (для створення/оновлення проектних каналів),
  • Mesh Directory (через параметри доступу для агентів).

3. DATA MODEL (MVP-Рівень)

3.1. microdao

CREATE TABLE microdao (
    microdao_id      TEXT PRIMARY KEY,
    name             TEXT NOT NULL,
    description      TEXT,
    status           TEXT NOT NULL DEFAULT 'active',  -- active|archived|pending
    created_at       TIMESTAMP NOT NULL DEFAULT now(),
    created_by       TEXT NOT NULL,   -- user_id/agent_id
    meta             JSONB DEFAULT '{}'::jsonb
);

3.2. microdao_project

CREATE TABLE microdao_project (
    microdao_id   TEXT NOT NULL REFERENCES microdao(microdao_id),
    project_id    TEXT NOT NULL,
    PRIMARY KEY (microdao_id, project_id)
);

3.3. microdao_role

CREATE TABLE microdao_role (
    role_id       TEXT PRIMARY KEY,
    microdao_id   TEXT NOT NULL REFERENCES microdao(microdao_id),
    name          TEXT NOT NULL,
    description   TEXT,
    entitlements  JSONB NOT NULL,  -- { "can_create_proposals": true, ... }
    meta          JSONB DEFAULT '{}'::jsonb
);

3.4. microdao_member

CREATE TABLE microdao_member (
    microdao_id   TEXT NOT NULL REFERENCES microdao(microdao_id),
    subject_id    TEXT NOT NULL,   -- user_id or agent_id
    subject_type  TEXT NOT NULL,   -- 'user' | 'agent'
    role_id       TEXT NOT NULL REFERENCES microdao_role(role_id),
    status        TEXT NOT NULL DEFAULT 'active',  -- active|pending|banned|left
    joined_at     TIMESTAMP NOT NULL DEFAULT now(),
    PRIMARY KEY (microdao_id, subject_id, subject_type)
);

3.5. microdao_proposal

CREATE TABLE microdao_proposal (
    proposal_id   TEXT PRIMARY KEY,
    microdao_id   TEXT NOT NULL REFERENCES microdao(microdao_id),
    title         TEXT NOT NULL,
    description   TEXT,
    creator_id    TEXT NOT NULL,
    creator_type  TEXT NOT NULL,  -- 'user' | 'agent'
    status        TEXT NOT NULL DEFAULT 'open', -- draft|open|accepted|rejected|expired
    created_at    TIMESTAMP NOT NULL DEFAULT now(),
    opens_at      TIMESTAMP,
    closes_at     TIMESTAMP,
    params        JSONB DEFAULT '{}'::jsonb -- voting rules overrides, payload
);

3.6. microdao_vote

CREATE TABLE microdao_vote (
    proposal_id   TEXT NOT NULL REFERENCES microdao_proposal(proposal_id),
    voter_id      TEXT NOT NULL,
    voter_type    TEXT NOT NULL,  -- 'user' | 'agent'
    choice        TEXT NOT NULL,  -- 'yes'|'no'|'abstain'|custom
    weight        NUMERIC NOT NULL DEFAULT 1,
    voted_at      TIMESTAMP NOT NULL DEFAULT now(),
    PRIMARY KEY (proposal_id, voter_id, voter_type)
);

4. CONFIGURATION

ENV:

MICRODAO_SERVICE_PORT=7004

MICRODAO_DB_DSN=postgres://...
MICRODAO_NATS_URL=nats://...

PROJECT_BUS_CONFIG_PATH=configs/project_bus_config.yaml
TEAM_DEFINITION_PATH=configs/team_definition.yaml
AGENT_REGISTRY_PATH=configs/AGENT_REGISTRY.yaml

5. PUBLIC HTTP API

5.1. POST /microdaos

Створити новий microDAO.

Request:

{
  "microdao_id": "microdao-greenfood",
  "name": "GREENFOOD DAO",
  "description": "Управління екосистемою GREENFOOD AI-ERP",
  "created_by": "user:owner1"
}

Response:

{
  "status": "ok",
  "microdao": {
    "microdao_id": "microdao-greenfood",
    "name": "GREENFOOD DAO",
    "description": "...",
    "status": "active"
  }
}

5.2. GET /microdaos

Список microDAO.

GET /microdaos?status=active

5.3. GET /microdaos/{microdao_id}

Деталі одного microDAO (включно з ролями/параметрами).

5.4. POST /microdaos/{microdao_id}/members

Додати учасника (людину/агента).

Request:

{
  "subject_id": "ag_helion",
  "subject_type": "agent",
  "role_id": "agent-core"
}

Response:

{
  "status": "ok",
  "member": {
    "microdao_id": "microdao-greenfood",
    "subject_id": "ag_helion",
    "subject_type": "agent",
    "role_id": "agent-core",
    "status": "active"
  }
}

5.5. GET /microdaos/{microdao_id}/members

Список учасників.

5.6. POST /microdaos/{microdao_id}/proposals

Створити пропозицію.

Request:

{
  "title": "Додати нового агента до команди GREENFOOD",
  "description": "Пропоную додати vision_agent до team-greenfood.",
  "creator_id": "user:owner1",
  "creator_type": "user",
  "params": {
    "required_quorum": 0.5,
    "required_yes_ratio": 0.6
  }
}

Response:

{
  "status": "ok",
  "proposal": {
    "proposal_id": "prop-123",
    "status": "open"
  }
}

5.7. POST /proposals/{proposal_id}/votes

Голосування.

Request:

{
  "voter_id": "user:member1",
  "voter_type": "user",
  "choice": "yes"
}

Response:

{
  "status": "ok",
  "vote": {
    "proposal_id": "prop-123",
    "voter_id": "user:member1",
    "choice": "yes",
    "weight": 1
  }
}

5.8. GET /microdaos/{microdao_id}/proposals

Список пропозицій DAO.

5.9. GET /proposals/{proposal_id}

Деталі пропозиції + поточний стан голосування.

6. EVENT BUS (NATS)

MicroDAO Service публікує події:

  • microdao.{microdao_id}.events

Приклади payload:

6.1. MicroDAO Created

{
  "type": "microdao_created",
  "microdao_id": "microdao-greenfood",
  "name": "GREENFOOD DAO",
  "created_by": "user:owner1",
  "ts": "2025-11-24T10:00:00Z"
}

6.2. Member Added

{
  "type": "member_added",
  "microdao_id": "microdao-greenfood",
  "subject_id": "ag_helion",
  "subject_type": "agent",
  "role_id": "agent-core",
  "ts": "2025-11-24T10:01:00Z"
}

6.3. Proposal Created

{
  "type": "proposal_created",
  "microdao_id": "microdao-greenfood",
  "proposal_id": "prop-123",
  "title": "Додати vision_agent до команди GREENFOOD",
  "ts": "2025-11-24T10:05:00Z"
}

6.4. Proposal Finalized

{
  "type": "proposal_finalized",
  "microdao_id": "microdao-greenfood",
  "proposal_id": "prop-123",
  "final_status": "accepted",
  "result": {
    "yes": 10,
    "no": 1,
    "abstain": 2,
    "quorum": 0.7
  },
  "ts": "2025-11-24T11:00:00Z"
}

7. INTEGRATION WITH OTHER SERVICES

7.1. Agents Service (7002)

Agents Service при кожному виклику:

  • запитує MicroDAO Service (або кешує його рішення), щоб:

  • перевірити, чи має агент право:

    • відповідати в конкретному project_id / microdao_id,
    • виконувати певні дії (наприклад, створювати команду, керувати іншими агентами).

Простий варіант: HTTP-запит:

GET /microdaos/{microdao_id}/members?subject_id=ag_helix&subject_type=agent

Можливий кеш у Redis.

7.2. ProjectBus / TeamDefinition

При створенні microDAO + прив'язці project_id MicroDAO Service може:

  • генерувати (або оновлювати) записи в:

  • project_bus_config.yaml,

  • team_definition.yaml (або їх runtime-аналогах в БД),

  • публікувати події:

  • project.<project_id>.events про появу нового microDAO/team.

7.3. Mesh Directory

MicroDAO Service може:

  • впливати на видимість агентів:

  • наприклад, якщо агент виключений з microDAO → його інстанси в Directory позначаються з обмеженими правами в цьому проекті.

8. SECURITY / RBAC

Важливі моменти:

  1. Усі операції (створення DAO, додавання членів, створення пропозицій, голосування) повинні проходити через перевірку entitlements:

  2. can_create_microdao

  3. can_manage_members
  4. can_create_proposals

  5. can_vote

  6. MicroDAO Service не займається аутентифікацією — він приймає вже ідентифіковані user_id / agent_id (з gateway або auth-сервісу).

  7. Системні агенти ( типу ag_guardian, ag_cryptodetective ) можуть мати особливі ролі з підвищеними entitlements (наприклад, аудит без права голосу).

9. HEALTHCHECK & METRICS

9.1. GET /healthz

{
  "status": "ok",
  "db": "ok",
  "nats": "ok",
  "uptime_seconds": 1234
}

9.2. Prometheus

  • microdao_count{status}
  • microdao_members_count{microdao_id}
  • microdao_proposals_count{microdao_id,status}
  • microdao_votes_total{microdao_id,proposal_id,choice}

10. TEST PLAN (SHORT)

Unit/Integration-тести (pytest):

  1. test_create_microdao_and_get()

  2. створення DAO, перевірка читання.

  3. test_add_member_and_query()

  4. додати члена, перевірити список.

  5. test_create_proposal_and_vote()

  6. створити пропозицію, декілька голосів, підбиття результатів.

  7. test_entitlements_block_unauthorized_actions()

  8. спроба створення пропозиції користувачем без can_create_proposals.

  9. test_events_published_on_actions()

  10. перевірити, що при створенні DAO/пропозиції/результату йдуть NATS-івенти.

11. SUMMARY

MicroDAO Service (7004):

  • є "governance ядром" для DAARION.city,

  • формально описує:

  • хто до якого microDAO належить,

  • які ролі/entitlements має,
  • як приймаються рішення (proposals/voting),

  • тісно інтегрований з:

  • Agents Service (поведінка агентів),

  • ProjectBus (потоки подій проектів),
  • Mesh Directory (видимість/скили/обмеження агентів).

Цей сервіс робить всі твої фрактальні команди та мережу агентів формально керованими через DAO-рівень.