microdao-daarion/docs/core-services-mvp.md

title, version, status, last_updated

title	version	status	last_updated
Core Services (MVP) — Wallet, DAOFactory, Registry, PDP	1.0.0	canonical	2024-11-14

Core Services (MVP) — Wallet, DAOFactory, Registry, PDP

Мета цього документа — формалізувати мінімальний набір core-сервісів для MVP MicroDAO / DAARION.city.

Ці сервіси є "хребтом" системи:

• Wallet Service — токени DAAR / DAARION, базові перевірки доступу.
• DAOFactory Service — створення MicroDAO та платформ.
• Registry Service — каталог DAO і платформ.
• PDP Service — єдина точка прийняття рішень по доступу.

Документ повʼязує високорівневі документи (overview.md, microdao-architecture.md, pdp_access.md, api.md) з конкретними сервісами, які треба реалізувати в коді.

---

1. Загальна картина

MVP передбачає роботу чотирьох базових сервісів:

1. Wallet Service

   • читає баланси DAAR / DAARION
   • надає util-методи для перевірки доступу (balance/stake)

2. DAOFactory Service

   • створює MicroDAO (A3/A4)
   • створює платформи (A2)
   • ініціалізує базові метадані DAO

3. Registry Service

   • зберігає всі DAO
   • зберігає всі платформи (позначені як A2)
   • надає публічний каталог DAO/платформ

4. PDP Service

   • приймає рішення, чи дозволена дія (allow/deny/require-elevation)
   • використовується Wallet, DAOFactory, Registry та іншими модулями

---

2. Wallet Service (MVP)

2.1 Відповідальність

• зчитування балансів DAAR / DAARION користувача

• зчитування стейкінгу DAARION (для доступу до платформ/ролей)

• надання простих helper-функцій типу:

  • hasEnoughForDaoCreate(user)
  • hasEnoughForVendorRegister(user)
  • hasEnoughForPlatformCreate(user)

Фінансові транзакції, стейкінг, payout-и не входять у MVP (можуть бути заглушені або відкладені).

2.2 Інтерфейс (логічний)

type TokenSymbol = 'DAAR' | 'DAARION';

interface WalletService {
  getBalances(userId: string): Promise<Array<{ symbol: TokenSymbol; amount: string }>>;

  hasEnoughForDaoCreate(userId: string): Promise<boolean>;
  hasEnoughForVendorRegister(userId: string): Promise<boolean>;
  hasEnoughForPlatformCreate(userId: string): Promise<boolean>;
}

2.3 Інтеграція з API

Мапінг на api.md:

• GET /api/v1/wallet/me → getBalances
• POST /api/v1/wallet/check-access → використовує hasEnough*-методи

2.4 Залежності

• зовнішній або внутрішній модуль для читання ончейн-даних (або stub)
• PDP (на наступних фазах, якщо будуть складніші правила)

---

3. DAOFactory Service (MVP)

3.1 Відповідальність

• створення нових DAO (A3/A4)
• створення платформ (A2) — з маркуванням рівня та типу
• валідація вхідних параметрів
• виклик PDP для перевірки прав
• запис DAO у Registry

3.2 Інтерфейс (логічний)

interface CreateDaoInput {
  name: string;
  description?: string;
  type: 'public' | 'private';
  level: 'A3' | 'A4';
  settings?: Record<string, unknown>;
}

interface CreatePlatformInput {
  name: string;
  slug: string;
  description?: string;
  domain?: string; // 'energy' | 'food' | 'water' | ...
}

interface DaoFactoryService {
  createDao(userId: string, input: CreateDaoInput): Promise<{ daoId: string }>;
  createPlatform(userId: string, input: CreatePlatformInput): Promise<{ daoId: string }>;
}

3.3 Інтеграція з API

Мапінг на api.md:

• POST /api/v1/dao → createDao
• POST /api/v1/platforms → createPlatform

3.4 Залежності

• Wallet Service — перевірка наявності DAAR/DAARION
• PDP Service — policy.dao.create, policy.platform.create
• Registry Service — запис нового DAO / платформи

---

4. Registry Service (MVP)

4.1 Відповідальність

• зберігання інформації про всі DAO
• маркування DAO як платформи (A2) або MicroDAO (A3/A4)
• надання публічного каталогу DAO/платформ

4.2 Мінімальна модель DAO

interface DaoRecord {
  daoId: string;
  name: string;
  description?: string;
  level: 'A1' | 'A2' | 'A3' | 'A4';
  type: 'platform' | 'public' | 'private';
  parentDaoId?: string | null;
  federationMode: 'none' | 'member' | 'superdao';
  createdAt: string;
}

4.3 Інтерфейс (логічний)

interface RegistryService {
  saveDao(record: DaoRecord): Promise<void>;

  getDaoById(daoId: string): Promise<DaoRecord | null>;

  listDaos(filter?: { level?: string; type?: string }): Promise<DaoRecord[]>;

  listPlatforms(): Promise<DaoRecord[]>; // level A2, type = 'platform'
}

4.4 Інтеграція з API

Мапінг на api.md:

• GET /api/v1/dao/{dao_id} → getDaoById
• GET /api/v1/dao → listDaos
• GET /api/v1/platforms → listPlatforms

4.5 Залежності

• немає критичних зовнішніх залежностей (простий сервіс над БД)
• може використовувати PDP для фільтрації приватних DAO

---

5. PDP Service (MVP)

5.1 Відповідальність

• централізоване прийняття рішень про доступ
• інтерпретація політик із pdp_access.md
• надання простого API для інших сервісів

5.2 Основний інтерфейс

export type Decision = 'allow' | 'deny' | 'require-elevation';

interface PdpContext {
  userId?: string;
  daoId?: string;
  daoLevel?: 'A1' | 'A2' | 'A3' | 'A4';
  // додатковий контекст: ролі, баланси, стейкінг тощо
}

interface PdpService {
  check(policyId: string, resource: Record<string, unknown>, context: PdpContext): Promise<{
    decision: Decision;
    reason?: string;
  }>;
}

5.3 Приклади використання

5.3.1 DAOFactory → створення DAO

const res = await pdp.check('policy.dao.create', { type: 'dao' }, { userId, daoLevel: 'A3' });
if (res.decision !== 'allow') throw new Error('ACCESS_DENIED');

5.3.2 Vendor → реєстрація на платформі

const res = await pdp.check('policy.vendor.register', { platformId }, { userId, daoId: platformDaoId, daoLevel: 'A2' });

5.4 Інтеграція з API

Мапінг на api.md:

• POST /api/v1/pdp/check → обгортка над PdpService.check (діагностика/адмінки)

5.5 Залежності

• Wallet Service — для перевірки балансів
• Registry Service — для визначення рівня DAO
• джерело політик (конфіги/БД)

---

6. Потоки взаємодії (MVP)

6.1 Створення DAO (користувач → MicroDAO)

1. Frontend → POST /api/v1/dao
2. API → DAOFactory Service
3. DAOFactory → WalletService (hasEnoughForDaoCreate)
4. DAOFactory → PDP Service (policy.dao.create)
5. DAOFactory → Registry (saveDao)
6. Повернення dao_id користувачу

6.2 Створення платформи

1. Frontend → POST /api/v1/platforms
2. DAOFactory → WalletService (hasEnoughForPlatformCreate)
3. DAOFactory → PDP (policy.platform.create)
4. DAOFactory → Registry (saveDao із level=A2, type=platform)

6.3 Реєстрація вендора

1. Frontend → POST /api/v1/platforms/{id}/vendors
2. Service → PDP (policy.vendor.register)
3. Якщо allow → запис у БД

---

7. MVP Scope vs. Future Scope

7.1 Входить у MVP

• Wallet Service: лише читання балансів + прості перевірки
• DAOFactory: створення DAO/платформ
• Registry: читання/запис DAO, список платформ
• PDP: базові політики (див. pdp_access.md)

7.2 Поза рамками MVP (може бути додано пізніше)

• повні транзакції DAAR/DAARION
• стейкінг (on-chain інтеграція)
• payout-и й автоматичний розподіл винагород
• розширені політики PDP (rate-limits, time-based rules)
• audit trails на рівні подій (окремий сервіс)

---

8. Використання цього документа

Цей документ служить

• для бекенд-розробників — як точний опис того, які сервіси реалізувати й які інтерфейси їм дати;
• для архітекторів — як карта залежностей між Wallet, DAOFactory, Registry, PDP;
• для фронтенду — як звʼязок між API (api.md) і внутрішньою логікою.

Наступний крок після цього документа — створення каркасів сервісів у коді (наприклад, у /services/wallet, /services/dao-factory, /services/registry, /services/pdp).

---

9. Integration with Other Docs

Цей документ інтегрується з:

• overview.md — загальний огляд системи
• microdao-architecture.md — архітектура A1-A4
• pdp_access.md — PDP та система доступів
• api.md / api-mvp.md — API специфікації
• superdao-federation.md — SuperDAO та федерації
• tokenomics/city-tokenomics.md — токеноміка

---

10. Changelog

v1.0.0 — 2024-11-14

• Початкова версія специфікації Core Services (MVP)
• Додано Wallet Service (читання балансів, перевірки доступу)
• Додано DAOFactory Service (створення DAO та платформ)
• Додано Registry Service (каталог DAO та платформ)
• Додано PDP Service (централізоване прийняття рішень)
• Додано потоки взаємодії між сервісами
• Додано розмежування MVP vs Future Scope

---

Версія: 1.0.0
Останнє оновлення: 2024-11-14
Документ готовий до інтеграції у Cursor, GitHub або будь-який інший проект.