Skip to content

# 23 — Domains, Wallet Agent & DAO Agent Deep Dive (MicroDAO)

Технічна специфікація мультидоменного роутингу, Wallet Agent протоколу та DAO Agent синхронізації

Цей документ деталізує три критичних технічних компоненти MicroDAO:

1. Мульти-тенант домени та роутінг

2. Wallet Agent: безпечний підпис дій

3. DAO Agent: звʼязок із зовнішнім DAO-протоколом

Документ інтегрований із попередніми модулями (12–22).

# 1. MULTI-TENANT DOMAINS & ROUTING

MicroDAO має підтримувати:

- піддомени формату `*.daarion.city`,
- власні домени адміністраторів microDAO,
- гнучке маршрутизаційне дерево,
- коректну інтеграцію front/back-end,
- автоматичні SSL-сертифікати,
- безпечне розмежування команд.

## 1.1. Модель БД

### Таблиця `teams` (microDAO)

    teams:
    - id: string
    - slug: string            // "greenfood", "musiclab"
    - primary_domain_id: string | null
    - created_at

### Таблиця `domains`

    domains:
    - id: string
    - team_id: string
    - host: string            // "greenfood.daarion.city", "mydao.org"
    - status: "pending" | "active" | "disabled"
    - is_primary: boolean
    - verified_at: Date | null
    - created_at

## 1.2. Алгоритм визначення `currentTeamId` по домену

На початку кожного HTTP-запиту:

    host := request.headers["Host"]

    1) спробувати знайти host у domains:
       SELECT team_id FROM domains
       WHERE host = $host AND status = 'active';

    2) якщо знайшли → currentTeamId = team_id.

    3) якщо ні — це, можливо, піддомен DAARION.city:
       slug = host.split('.')[0]
       SELECT id FROM teams WHERE slug = $slug;

    4) якщо знайшли → currentTeamId = id.

    5) інакше → 404 або сторінка Onboarding ("microDAO не знайдено")

## 1.3. Підтримка двох режимів UI

### Режим 1 — Піддомен / власний домен

URL:

    greenfood.daarion.city/
    mydao.org/

Усі маршрути стають:

    / → головна команда
    /projects
    /agents
    /settings

Без /t/:teamId — тому що `teamId` вже визначено з домену.

### Режим 2 — Центральний домен (наприклад, app.daarion.city)

URL:

    app.daarion.city/t/:teamId/agents

Цей режим потрібен:

- для розробки,
- для адміністрування,
- для роботи всередині DAARION.city як централізованої платформи.

## 1.4. Налаштування кастомного домену (UX)

### Потік:

1. Адмін відкриває: Settings → Domain

2. Поле: "Поточний домен: `greenfood.daarion.city`"

3. Поле: "Додати власний домен" → `mydao.org`

4. Система показує інструкцію:

`Створіть CNAME: mydao.org → domains.daarion.city`

1. Домен створюється зі статусом `pending`.

2. DNS checker (кожні 10 хв) змінює статус на `active`, коли знайдено CNAME.

3. Автоматичний ACME/SSL випуск.

4. Домен стає primary.

# 2. WALLET AGENT — ПРОТОКОЛ БЕЗПЕЧНОГО ПІДПИСУ

Wallet Agent — це інтерфейс між microDAO і зовнішніми гаманцями:

- браузерні (MetaMask, WalletConnect),
- мобільні,
- апаратні (Tangem-подібні).

Wallet Agent ніколи не отримує приватний ключ.

## 2.1. Потік підпису дії

Порядок:

### Етап 1 — Агент хоче виконати дію

Наприклад: Governance Agent хоче оновити правило.

    walletAgent.prepare_signature_payload({
      action: "update_policy",
      params: {...}
    });

Wallet Agent:

1. Валідатор: "Чи має агент право робити це?"
2. Створює запис у `sign_requests`.
3. Формує `human_description`.
4. Показує людині Approval UI.

## 2.2. Модель `sign_requests`

    sign_requests:
    - id
    - team_id
    - type                    // "governance_update", "dao_submit", ...
    - payload_json            // те, що треба підписати
    - human_description
    - created_by_agent_id
    - created_by_user_id?     // якщо ініціатор — людина
    - status: "pending" | "signed" | "rejected"
    - created_at
    - updated_at

## 2.3. UX у фронтенді

Коли є новий `sign_request`:

- у UI зʼявляється:

- "Агент пропонує підписати дію"

- опис,

- кнопки:

  - "Підписати"
  - "Скасувати"

Коли користувач натискає "Підписати":

1. фронт надсилає `payload` у wallet provider (MetaMask / WC / Tangem SDK),
2. отримує `signature`,
3. викликає:

`POST /sign_requests/:id/confirm { signature: "0x..." }`

## 2.4. Таблиця `sign_results`

    sign_results:
    - id
    - sign_request_id
    - signature
    - tx_hash?
    - confirmed_at
    - status: "broadcasted" | "failed"

## 2.5. Wallet Agent Tools

    tools: [
      "prepare_signature_payload",   // формує sign_request
      "request_signature",           // запит до користувача (UI)
      "verify_signature",            // перевірка
      "get_wallet_state"             // поточні адреси, мережі, доступи
    ]

Wallet Agent — це декларативна прослойка між дією і підписом користувача.

# 3. DAO AGENT — СИНХРОНІЗАЦІЯ З ON-CHAIN DAO

Не кожному microDAO потрібен on-chain DAO.

Але архітектура має підтримувати:

- звʼязок з DAO-контрактами,
- синхронізацію ритуалів узгодження microDAO з DAO-голосуваннями,
- оновлення локальних правил після голосування,
- відправку результатів у DAO-контракт.

## 3.1. Модель задач DAO Agent

### 1) Fetch external proposals

    fetch_dao_proposals(team_id)

Тягне список пропозицій з DAO-контракту чи API.

### 2) Map rituals to proposals

    map_ritual_to_proposal(ritual_id, proposal_id)

Звʼязує локальний ритуал і зовнішню пропозицію.

### 3) Submit local result to DAO

    submit_ritual_result(ritual_id)

Використовує Wallet Agent для підпису.

### 4) Sync policy

    sync_policies_onchain()

Порівнює локальні правила з DAO-версією.

## 3.2. Модель БД

### Таблиця `dao_proposals`

    dao_proposals:
    - id
    - team_id
    - proposal_id_onchain
    - title
    - body
    - status: "open" | "closed"
    - result: "accepted" | "rejected" | "pending"
    - mapped_ritual_id: string | null
    - created_at

### Таблиця `dao_sync_logs`

Журнал синхронізації.

    dao_sync_logs:
    - id
    - team_id
    - action_type
    - payload_json
    - created_at

## 3.3. DAO Agent Tools

    tools: [
      "fetch_dao_proposals",
      "sync_policies_onchain",
      "submit_ritual_result",
      "resolve_dao_result"
    ]

# 4. Інтеграція з Governance Agent та OperatorMode

DAO Agent працює лише тоді, коли:

- Governance Agent дозволяє це (entitlement),
- Wallet Agent підписує дії людиною.

OperatorMode у DAO Agent:

    operatorMode: {
      enabled: true,
      scopes: ["team"],
      allowedTools: [
        "fetch_dao_proposals",
        "sync_policies_onchain"
      ],
      schedule: "0 */6 * * *", // кожні 6 годин
      maxActionsPerHour: 5
    }

Оновлення правил або відправка результатів ритуалу завжди вимагає людського підпису.

# 5. API ЕНДПОЇНТИ

## 5.1. Domains API

    GET /domains?team_id
    POST /domains
    PATCH /domains/:id
    DELETE /domains/:id

## 5.2. Wallet API

    GET /sign_requests?team_id
    POST /sign_requests
    POST /sign_requests/:id/confirm
    POST /sign_requests/:id/reject

## 5.3. DAO API

    GET /dao/proposals?team_id
    POST /dao/sync
    POST /dao/ritual/:id/submit

# 6. Інструкції для Cursor

    Use 23_domains_wallet_dao_deepdive.md to implement:

    1) Multi-tenant domain routing (backend + frontend)

    2) Domains management UI (admin area)

    3) Wallet Agent protocol:

       - sign_requests
       - sign_results
       - prepare_signature_payload
       - confirm/reject endpoints

    4) DAO Agent backend model:

       - dao_proposals
       - dao_sync_logs
       - mapping rituals <-> proposals

    5) Guard all DAO Agent actions with:

       - Governance/Access entitlements
       - Wallet signature flow

    6) Add operatorMode guards where appropriate

# 7. Результат

Після впровадження:

- кожне microDAO може мати власний домен без конфігураційної плутанини,
- Wallet Agent забезпечує безпечний і прозорий протокол підпису,
- DAO Agent може синхронізуватися з зовнішніми DAO-протоколами,
- архітектура стає розширюваною для міжпросторових і міжмережевих інтеграцій,
- operatorMode забезпечує контрольований автоматизм без ризиків.