Skip to content

# Nodes Interface Architecture — UPDATE v1

DAARION.city Unified Node Model
Version: 1.1

# 1. Визначення НОДИ

Нода = фізичний об'єкт + локальний обчислювальний модуль + DAIS-агент + запис у таблиці `nodes`.

Нода не існує "віртуально".
Вона з'являється тільки після фактичного приєднання фізичного пристрою.

# 2. Компоненти НОДИ

## 2.1. Фізичний об'єкт ("ресурс")

- енергетична установка,
- обчислювальний сервер,
- IoT-станція,
- мікрокомп'ютер або смартфон,
- будь-яка реальна точка у світі.

## 2.2. Локальний мозок

Обов'язково існує хоча б один пристрій, здатний:

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

Це може бути:

- ноутбук,
- міні-ПК,
- сервер,
- смартфон,
- Raspberry Pi.

## 2.3. DAIS-агент

Кожна нода має свого:

- `dais_id`
- `wallet`
- `public_key`
- `role: node_agent`

Це і є "особистість" ноди, можливість підписувати операції.

## 2.4. Запис у таблиці `nodes`

У БД фіксується:

- `node_id`
- `owner_microdao_id`
- `node_agent_id`
- `kind`
- `capabilities`
- `status`
- `registered_at`

## 2.5. Node Profile — Core Invariants (PATCH v1)

Кожна нода в DAARION Ontology має чотири обов'язкові шари:

1. Metrics Layer — live-метрики CPU/GPU/RAM/Disk + heartbeat. Навіть якщо телеметрія частково відсутня, нода переходить у `metrics_status = degraded`, а не існує “порожньою”.
2. Ownership Layer — власник (MicroDAO/District) з полями `owner_microdao_id`, `owner_microdao_slug` (опційно `district_id`). Немає безхазяйних нод.
3. Models Layer — локальний Swapper + набір моделей (LLM, STT, vision, TTS, RAG). Dev-ноди так само мають DAGI-стек, просто з іншим складом моделей.
4. Orchestration Layer — локальний DAGI Router + агенти з `home_node_id`, які працюють на цій ноді.

Також кожна нода має мінімальний набір Node Core Agents:

- Node Guardian Agent — відповідає за health, безпеку, інциденти.
- Node Steward Agent — відповідає за приналежність до microDAO, профіль, онбординг.
- (опційно) Node Models/Swapper Agent — відповідає за опис і політику використання локального стека моделей.

> Принцип “немає сторінки без агентів” означає, що будь-який інтерфейс Ноди (профіль, метрики, моделі, доступи) завжди “закріплений” за хоча б одним агентом, і цей агент показується в UI.

# 3. Типи НОД

## 3.1. Energy Node

Фізична енергетична установка з датчиками.

`kind = "energy"`

## 3.2. Compute Node

Фізичний сервер/станція для AI.

`kind = "compute"`

## 3.3. Hybrid Node

Енергія + compute.

`kind = "hybrid"`

## 3.4. IoT Gateway Node

Для сенсорних мереж.

`kind = "iot_gateway"`

## 3.5. Edge Node

Смартфон, ноутбук, міні-ПК.

`kind = "edge"`

## 3.6. Datacenter Node

Потужний серверний вузол.

`kind = "datacenter"`

## 3.7. GPU Cluster Node

Спеціалізований GPU кластер.

`kind = "gpu_cluster"`

# 4. Capability-профілі ("можливості")

При реєстрації ноди описуються її можливості:

### Приклади:

    {
      "energy": {
        "max_kWt": 8.2,
        "sensors": ["temp", "co2"],
        "telemetry": "1m"
      },
      "compute": {
        "gpu_vram": "16GB",
        "cpu_cores": 12,
        "ram": "64GB",
        "storage": "2TB"
      }
    }

Цей профіль створюється самим пристроєм або оператором вручну.

# 5. Правило реєстрації

> Нода реєструється тільки тоді, коли фізичний пристрій реально з'єднується з DAARION і викликає `/nodes/register`.

Жодних автосозданих нод.
Жодних "placeholder-node".

## 5.1 Процес реєстрації

    sequenceDiagram
        participant Device as Physical Device
        participant Brain as Local Brain
        participant API as DAARION API
        participant DB as Database

        Device->>Brain: Boot & Initialize
        Brain->>API: POST /nodes/register
        API->>API: Validate DAIS identity
        API->>DB: INSERT INTO nodes
        DB-->>API: node_id
        API-->>Brain: { node_id, status: "registered" }
        Brain->>Device: Configure & Start Services

## 5.2 Required Fields

Field | Type | Required | Description
--- | --- | --- | ---
owner_microdao_id | UUID | ✅ | MicroDAO власник
node_agent_id | TEXT | ✅ | DAIS ID агента ноди
kind | ENUM | ✅ | Тип ноди
capabilities | JSONB | ✅ | Можливості
hostname | TEXT | ❌ | Ім'я хоста
ip_address | TEXT | ❌ | IP адреса

# 6. Onboarding / Offboarding

## 6.1 Onboarding

1. Фізичний пристрій підключається до мережі
2. Локальний мозок запускає DAIS-агента
3. Агент отримує DAIS identity (якщо ще немає)
4. Виклик `/nodes/register` з capability-профілем
5. Нода з'являється в системі
6. District Lead Agent підтверджує (якщо потрібно)

## 6.2 Offboarding

- власник може відключити ноду через `/nodes/{id}/deactivate`
- District Lead може заблокувати ноду при порушенні
- City Governance може ревокувати ноду при критичних інцидентах

# 7. Security

- всі операції підписані DAIS-ключами ноди
- ревокація ноди = блокування її DAIS-агента
- телеметрія може бути E2E-шифрована
- кожна нода має свій wallet для мікротранзакцій

## 7.1 Key Rotation

Ноди повинні періодично оновлювати ключі:

- автоматична ротація кожні 90 днів
- примусова ротація при підозрі компрометації
- старі ключі зберігаються в `dais_keys` з `revoked = true`

# 8. Інтеграція з District-протоколами

## 8.1 MicroDAO

Кожна нода належить певному MicroDAO:

- `owner_microdao_id` → FK до `microdaos`
- права управління нодою = права Orchestrator MicroDAO

## 8.2 District

District Lead (Helion, GREENFOOD ERP, інші) має право:

- реєстрації ноди всередині District
- перевірки capability-профілю
- блокування ноди в разі порушення протоколу
- налаштування SLA вимог

## 8.3 City

City Governance може:

- переглядати всі ноди міста з роллю `city_governance`
- блокувати ноди при критичних інцидентах
- встановлювати city-wide policies

# 9. Node Status Lifecycle

    registered → online → busy → offline → deactivated
                    ↓
                suspended (при порушенні)
                    ↓
                revoked (hard block)

Status | Description
--- | ---
`registered` | Нода зареєстрована, очікує активації
`online` | Нода активна, готова до роботи
`busy` | Нода виконує задачу
`offline` | Нода тимчасово недоступна
`suspended` | Нода призупинена адміністративно
`deactivated` | Нода деактивована власником
`revoked` | Нода заблокована назавжди

# 10. Telemetry Protocol

## 10.1 Heartbeat

Кожна нода надсилає heartbeat кожні 60 секунд:

    {
      "node_id": "...",
      "timestamp": "2025-11-30T12:00:00Z",
      "status": "online",
      "metrics": {
        "cpu_load": 0.45,
        "memory_used": 0.67,
        "disk_free": 0.82
      }
    }

## 10.2 NATS Subjects

- `nodes.heartbeat.{node_id}` — heartbeat
- `nodes.metrics.{node_id}` — детальна телеметрія
- `nodes.events.{node_id}` — події ноди
- `nodes.alerts.{node_id}` — алерти

# 11. Сумісність

Ця модель однакова для:

- Energy Union — energy/compute/hybrid ноди
- GREENFOOD — warehouse/logistics/iot ноди
- CLAN — edge/compute ноди
- SOUL — personal/edge ноди
- DAARION root DAO — datacenter/gpu_cluster ноди

# 12. Cross-References

- DAARION_Ontology_Core_v1.md — базова онтологія
- DAIS_Layer_Architecture_v1.md — система ідентичності
- Agent_Governance_Protocol_v1.md — права агентів
- ENERGYUNION_District_Protocol_v1.md — протокол Energy Union
- GREENFOOD_District_Protocol_v1.md — протокол GREENFOOD

Document Status: ✅ Ready for Implementation