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-рівень.