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

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

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

Мульти-тенант домени та роутінг
Wallet Agent: безпечний підпис дій
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
```text

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

```ts
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
```text

---

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

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

```text
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 не знайдено")
```text

---

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

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

URL:

```text
greenfood.daarion.city/
mydao.org/
```text

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

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

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

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

URL:

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

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

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

---

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

### Потік

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

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

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

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

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

Домен створюється зі статусом pending.
DNS checker (кожні 10 хв) змінює статус на active, коли знайдено CNAME.
Автоматичний ACME/SSL випуск.
Домен стає 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: {...}
});
```text

Wallet Agent:

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

---

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

```ts
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
```text

---

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

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

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

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

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

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

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

   ```text
   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"
```text

---

## 2.5. Wallet Agent Tools

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

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

---

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

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

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

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

---

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

### 1) Fetch external proposals

```text
fetch_dao_proposals(team_id)
```text

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

### 2) Map rituals to proposals

```text
map_ritual_to_proposal(ritual_id, proposal_id)
```text

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

### 3) Submit local result to DAO

```text
submit_ritual_result(ritual_id)
```text

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

### 4) Sync policy

```text
sync_policies_onchain()
```text

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

---

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

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

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

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

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

```ts
dao_sync_logs:
- id
- team_id
- action_type
- payload_json
- created_at
```text

---

## 3.3. DAO Agent Tools

```ts
tools: [
  "fetch_dao_proposals",
  "sync_policies_onchain",
  "submit_ritual_result",
  "resolve_dao_result"
]
```text

---

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

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

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

OperatorMode у DAO Agent:

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

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

---

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

## 5.1. Domains API

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

## 5.2. Wallet API

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

## 5.3. DAO API

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

---

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

```text
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
```text

---

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

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

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

10 KiB Raw Permalink Blame History Unescape Escape