docs: add ENERGYUNION District Protocol + Nodes Interface Architecture UPDATE
- ENERGYUNION: DePIN/Energy/Compute District with Helion & Energia agents - Nodes UPDATE: Unified node model (physical object + local brain + DAIS agent) - No auto-created nodes - all nodes registered dynamically
This commit is contained in:
Apple
316
docs/foundation/Nodes_Interface_Architecture_UPDATE_v1.md
Normal file
316
docs/foundation/Nodes_Interface_Architecture_UPDATE_v1.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# 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`
|
||||
|
||||
---
|
||||
|
||||
# 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-профілі ("можливості")
|
||||
|
||||
При реєстрації ноди описуються її можливості:
|
||||
|
||||
### Приклади:
|
||||
|
||||
```json
|
||||
{
|
||||
"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 Процес реєстрації
|
||||
|
||||
```mermaid
|
||||
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 секунд:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
Reference in New Issue
Block a user