microdao-daarion/docs/cursor/23_domains_wallet_dao_deepdive.md

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
   

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

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

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

8. Домен стає 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 забезпечує контрольований автоматизм без ризиків.