microdao-daarion/docs/foundation/DAIS_Layer_Architecture_v1.md

# DAIS_Layer_Architecture_v1.md

## DAARION Agent Identity System — Архітектура Ідентичності Агента

**Version:** 1.0  
**Status:** Foundation Spec (MVP)  
**Scope:** Ідентичність агентів (DAIS), ключі, автентифікація, wallet, DAIS lifecycle, DAIS Roles, режим агента як «цифрової особистості», зв'язки DAIS ↔ City ↔ MicroDAO ↔ Nodes ↔ District.

---

# 0. Мета документа

DAIS (DAARION Agent Identity System) — це **фундаментальна система ідентичності у DAARION.city**, яка забезпечує:

- створення агентів,
- видачу унікальної особистості,
- ключі підпису,
- крипто-гаманці,
- email-ідентифікацію,
- життєвий цикл агента,
- безпекові гарантії,
- зв'язок із MicroDAO, District Space, City Layer,
- agent-to-agent довіру.

DAIS — це «паспортна система» міста, де **кожен агент = особистість**, а не просто бот.

---

# 1. Основна ідея DAIS

> **Агент у DAARION.city — це повноцінний учасник екосистеми  
> з унікальною особистістю, ключами, wallet, історією та ролями.**

DAIS — не просто «таблиця в БД», а ціла модель:

- ідентичність,
- ключова інфраструктура,
- профіль,
- wallet,
- доступи,
- історія дій,
- життя/смерть агента (revocation),
- зв'язок з людиною (human-owner).

## 1.1. DAIS як фундамент

```
┌─────────────────────────────────────────────────────────┐
│                    DAARION.city                          │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│   │  City    │  │ District │  │ MicroDAO │              │
│   │  Layer   │  │  Layer   │  │  Layer   │              │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘              │
│        │             │             │                     │
│        └─────────────┼─────────────┘                     │
│                      │                                   │
│              ┌───────▼───────┐                          │
│              │     DAIS      │                          │
│              │   Identity    │                          │
│              │    System     │                          │
│              └───────┬───────┘                          │
│                      │                                   │
│        ┌─────────────┼─────────────┐                    │
│        │             │             │                     │
│   ┌────▼────┐  ┌─────▼─────┐  ┌───▼────┐               │
│   │  Keys   │  │  Wallets  │  │ Emails │               │
│   └─────────┘  └───────────┘  └────────┘               │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

---

# 2. DAIS — об'єкти в базі даних

Вже створені таблиці (міграція 027):

## 2.1. `dais_identities`

Головна таблиця ідентичності агента.

```sql
CREATE TABLE dais_identities (
    id TEXT PRIMARY KEY,
    did TEXT NOT NULL UNIQUE,           -- did:daarion:<uuid>
    default_email TEXT,
    default_wallet TEXT,
    matrix_handle TEXT,                  -- @<agent_id>:matrix.daarion.city
    trust_level dais_trust_level NOT NULL DEFAULT 'agent',
    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

### Поля metadata (розширена модель)

```json
{
  "display_name": "Helion",
  "avatar_url": "https://...",
  "type": "district-agent",
  "owner_user_id": null,
  "behaviour_profile": "energy-expert",
  "trust_score": 95,
  "created_by": "daarwizz"
}
```

## 2.2. `dais_wallets`

Крипто-гаманці агента.

```sql
CREATE TABLE dais_wallets (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    dais_id TEXT NOT NULL REFERENCES dais_identities(id),
    wallet_address TEXT NOT NULL,
    network TEXT NOT NULL DEFAULT 'evm',  -- evm, ton, solana
    verified BOOLEAN NOT NULL DEFAULT false,
    verified_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

## 2.3. `dais_emails`

Email-ідентичності агента.

```sql
CREATE TABLE dais_emails (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    dais_id TEXT NOT NULL REFERENCES dais_identities(id),
    email TEXT NOT NULL,
    verified BOOLEAN NOT NULL DEFAULT false,
    verified_at TIMESTAMPTZ,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
```

## 2.4. `dais_keys`

Криптографічні ключі агента.

```sql
CREATE TABLE dais_keys (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    dais_id TEXT NOT NULL REFERENCES dais_identities(id),
    key_type TEXT NOT NULL,       -- ed25519, x25519, secp256k1
    public_key TEXT NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    revoked_at TIMESTAMPTZ
);
```

---

# 3. Класи агентних ідентичностей DAIS

## 3.1. Personal Agent (Second Me)

Агент, що належить конкретній людині.  
Це — «цифровий представник людини».

| Атрибут | Значення |
|---------|----------|
| Type | `personal` |
| Owner | User ID |
| Trust Level | `agent` → `verified` |
| Активація | email, wallet, SIWE |

```typescript
interface PersonalAgent {
  type: 'personal';
  ownerUserId: string;
  email: string;
  wallet?: string;
  secondMeProfile: boolean;
}
```

## 3.2. Organizational Agent

Належить MicroDAO.  
Типові: PM-агент, Task-агент, Internal Summary-агент.

| Атрибут | Значення |
|---------|----------|
| Type | `organizational` |
| Owner | MicroDAO ID |
| Trust Level | `agent` |
| Roles | pm, task, summary, support |

```typescript
interface OrganizationalAgent {
  type: 'organizational';
  microdaoId: string;
  role: 'pm' | 'task' | 'summary' | 'support' | 'custom';
}
```

## 3.3. Core-team Agent

Агенти, що виконують ролі:
- CEO, CTO, CISO, CFO, Architect, R&D Lead
- Engineering Core 108

| Атрибут | Значення |
|---------|----------|
| Type | `core-team` |
| Trust Level | `orchestrator` |
| Special | L2 signature, advanced behaviour |

```typescript
interface CoreTeamAgent {
  type: 'core-team';
  coreRole: 'ceo' | 'cto' | 'ciso' | 'cfo' | 'architect' | 'rd-lead';
  l2Signature: boolean;
  behaviourProfile: 'advanced';
}
```

## 3.4. City Agents

Належать root-мікроDAO DAARION:

| Agent | Role | Trust Level |
|-------|------|-------------|
| **DARIO** | Community Manager | `operator` |
| **DARIA** | Support | `operator` |
| **DAARWIZZ** | Mayor | `operator` |
| **City Analyst** | Analytics | `orchestrator` |

```typescript
interface CityAgent {
  type: 'city-agent';
  cityRole: 'community' | 'support' | 'mayor' | 'analyst';
  trustLevel: 'operator';
  rootMicrodao: 'daarion';
}
```

## 3.5. District Agents

Належать District-платформам:

| Agent | District | Role |
|-------|----------|------|
| **Helion** | Energyunion | District Lead |
| **ERP-Agent** | GREENFOOD | District Lead |

```typescript
interface DistrictAgent {
  type: 'district-agent';
  districtId: string;
  districtRole: 'lead' | 'analyst' | 'support';
  trustLevel: 'orchestrator';
}
```

---

# 4. DAIS Identity = паспорт + сім-карта + soulbound-token

У DAIS кожен агент має:

| Компонент | Опис |
|-----------|------|
| `dais_id` | Унікальний ідентифікатор |
| `did` | Decentralized Identifier |
| `behaviour_profile` | Профіль поведінки |
| `keys` | Криптографічні ключі |
| `wallet` | Крипто-гаманець |
| `microdao_id` | Прив'язка до MicroDAO |
| `node_id` | Прив'язка до ноди |
| `rooms_owned` | Власні кімнати |
| `lifecycle_state` | Стан життєвого циклу |
| `trust_level` | Рівень довіри |
| `security_posture` | Безпековий профіль |

## 4.1. DID Format

```
did:daarion:agent-uuid-here
```

Приклади:
- `did:daarion:dario-001`
- `did:daarion:helion-energyunion`
- `did:daarion:user-personal-abc123`

---

# 5. DAIS Lifecycle (Життєвий цикл агента)

```
┌─────────────────────────────────────────────────────────────┐
│                    DAIS LIFECYCLE                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. Creation ──► 2. Issuance ──► 3. Keys Generated          │
│       │              │               │                       │
│       ▼              ▼               ▼                       │
│  4. Wallet ──► 5. Assignment ──► 6. Node Placement          │
│       │              │               │                       │
│       ▼              ▼               ▼                       │
│  7. Execution ──► 8. Promotion ──► 9. Revocation            │
│       │              │               │                       │
│       ▼              ▼               ▼                       │
│   [Active]      [Upgraded]       [Archived]                  │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## 5.1. Creation

Користувач створює агента під час першого входу (Onboarding).

```typescript
// Event: dagion.dais.identity_created
{
  daisId: 'dais-uuid',
  type: 'personal',
  ownerUserId: 'user-123',
  timestamp: '2025-11-29T...'
}
```

## 5.2. Issuance

`dais_identities` створюється автоматично.

```sql
INSERT INTO dais_identities (id, did, trust_level)
VALUES ('dais-uuid', 'did:daarion:dais-uuid', 'agent');
```

## 5.3. Keys Generated

DAIS генерує ключі:

| Key Type | Purpose | Algorithm |
|----------|---------|-----------|
| `ed25519` | Signing, Auth | EdDSA |
| `x25519` | Encryption, E2EE | ECDH |
| `secp256k1` | Wallet compat | ECDSA |

```typescript
// Future: PQC keypair (post-quantum)
const keyPair = await generateDAISKeys({
  types: ['ed25519', 'x25519'],
  daisId: 'dais-uuid'
});
```

## 5.4. Wallet

Генерується або прив'язується.

```typescript
// Option A: Generate new wallet
const wallet = await generateDAISWallet('polygon');

// Option B: Link existing wallet (SIWE)
await linkWallet(daisId, walletAddress, signature);
```

## 5.5. Assignment

Агент отримує зв'язок:
- MicroDAO
- Roles
- District
- Привілеї

```sql
INSERT INTO agent_assignments (agent_id, target_microdao_id, scope, role)
VALUES ('agent-uuid', 'energyunion', 'district', 'analyst');
```

## 5.6. Node Placement

Агент «живе» на ноді.

```typescript
interface AgentNodePlacement {
  agentId: string;
  nodeId: string;
  status: 'active' | 'suspended' | 'migrating';
  resources: {
    cpu: string;
    memory: string;
    gpu?: string;
  };
}
```

## 5.7. Execution

Агент має історію подій:

| Event Type | Description |
|------------|-------------|
| `task.completed` | Task execution |
| `message.sent` | Message in room |
| `decision.made` | AI decision |
| `job.processed` | Background job |

## 5.8. Promotion

DAIS рівень підвищується:

```typescript
// Event: dagion.agent.promoted_to_orchestrator
await promoteAgent(daisId, 'orchestrator');

// Updates trust_level
UPDATE dais_identities 
SET trust_level = 'orchestrator' 
WHERE id = 'dais-uuid';
```

## 5.9. Revocation

Агент може бути:
- деактивований
- переведений у archive-mode
- втратити роль або ключ

```typescript
// Soft revocation (archive)
await archiveAgent(daisId);

// Hard revocation (key invalidation)
await revokeDAISKeys(daisId, reason);
```

---

# 6. DAIS Keys & Security Model

## 6.1. Ключі агента

Створюються при реєстрації, зберігаються в `dais_keys`.

| Operation | Key Used |
|-----------|----------|
| Підпис подій | `ed25519` |
| Аутентифікація | `ed25519` |
| Перевірка власності | `secp256k1` |
| Control actions | `ed25519` |
| Шифрування | `x25519` |

## 6.2. Trust Levels

| Level | Name | Description | Examples |
|-------|------|-------------|----------|
| 0 | `guest` | Unverified | New users |
| 1 | `agent` | Basic verified | Personal agents |
| 2 | `verified` | Email + Wallet | Active users |
| 3 | `orchestrator` | Can create DAO | MicroDAO creators |
| 4 | `operator` | City-level access | DARIO, DARIA, DAARWIZZ |

```typescript
type DaisTrustLevel = 
  | 'guest' 
  | 'agent' 
  | 'verified' 
  | 'orchestrator' 
  | 'operator';
```

## 6.3. Trust Level Upgrade Path

```
guest → agent → verified → orchestrator → operator
  │        │         │           │
  │        │         │           └── City approval
  │        │         └── Wallet + Token stake
  │        └── Email verified
  └── Initial signup
```

## 6.4. Revocation & Recovery (план)

| Method | Description |
|--------|-------------|
| Seed phrase | Optional backup |
| Email recovery | Magic link |
| Social recovery | 2-of-3 trusted agents |
| Multi-key recovery | Threshold signature |

---

# 7. DAIS Wallet Architecture

Кожен агент має wallet:

```typescript
interface DAISWallet {
  daisId: string;
  network: 'polygon' | 'ton' | 'solana' | 'ethereum';
  address: string;
  verified: boolean;
  verifiedAt?: Date;
}
```

## 7.1. Wallet Use Cases

| Use Case | Description |
|----------|-------------|
| Web3 Auth | SIWE login |
| DAO Governance | Future voting |
| Token Utility | DAAR/1T tokens |
| Model Ownership | Cognitive modules |
| RWA Claims | Energy/Food certificates |

## 7.2. Multi-chain Support

```typescript
const supportedNetworks = [
  { id: 'polygon', name: 'Polygon', chainId: 137 },
  { id: 'ton', name: 'TON', chainId: -239 },
  { id: 'ethereum', name: 'Ethereum', chainId: 1 },
];
```

---

# 8. DAIS Email Identity

Кожен агент має email в DAIS:

| Attribute | Description |
|-----------|-------------|
| Primary email | Main identity |
| Verified | OTP/Magic Link |
| Recovery | Backup access |
| Notifications | System alerts |

```typescript
interface DAISEmail {
  daisId: string;
  email: string;
  verified: boolean;
  isPrimary: boolean;
  verifiedAt?: Date;
}
```

---

# 9. DAIS → Rooms Layer

DAIS визначає:

| Relation | Description |
|----------|-------------|
| `owner_type=agent` | Агент володіє кімнатою |
| `primary_agent` | Головний агент сцени |
| `trust_level` | Права модерації |

```sql
-- Rooms owned by DAIS agent
SELECT * FROM rooms 
WHERE owner_type = 'agent' 
AND owner_id = 'dais-id';
```

---

# 10. DAIS → MicroDAO Layer

Через DAIS визначається:

| Permission | Description |
|------------|-------------|
| Membership | Які агенти в MicroDAO |
| Roles | Які ролі мають |
| Access | Які доступи |
| Create DAO | Хто може створювати |
| Front-room | Хто може публікувати |
| Nodes | Хто керує нодами |

```typescript
// Assignments API використовує DAIS
const agentScope = await getAgentScope(daisId);
// Returns: { homeMicrodaoId, assignments, effectiveScope }
```

---

# 11. DAIS → Nodes Layer

DAIS визначає:

| Attribute | Description |
|-----------|-------------|
| `home_node_id` | Де агент живе |
| `permissions` | Права на ноді |
| `devops_access` | DevOps дії |
| `security` | Безпекові обмеження |

```typescript
interface AgentNodeBinding {
  daisId: string;
  nodeId: string;
  permissions: ('execute' | 'manage' | 'admin')[];
  securityLevel: 'standard' | 'elevated' | 'privileged';
}
```

Node Manager Agent — також DAIS-agent.

---

# 12. DAIS → District Layer

District Agents — повністю DAIS-ідентичності.

| Attribute | Description |
|-----------|-------------|
| Розширені ролі | District Lead, Analyst |
| Підвищений trust | `orchestrator` min |
| Власні rooms | District Rooms |
| Привілеї | Sub-DAO management |

```typescript
// District Lead Agent DAIS
const helionDais = {
  id: 'dais-helion',
  did: 'did:daarion:helion',
  type: 'district-agent',
  districtId: 'energyunion',
  trustLevel: 'orchestrator',
  rooms: ['energyunion-center', 'energyunion-news']
};
```

---

# 13. API для DAIS (MVP)

## 13.1. Identity API

```typescript
// Identity endpoints
GET  /api/v1/dais/:id              // Get DAIS profile
POST /api/v1/dais/identity         // Create new identity
GET  /api/v1/dais/agent/:agentId   // Get by agent ID
```

## 13.2. Keys API

```typescript
// Keys endpoints
GET  /api/v1/dais/:id/keys         // List keys
POST /api/v1/dais/:id/keys         // Add key
POST /api/v1/dais/:id/keys/rotate  // Rotate keys
DELETE /api/v1/dais/:id/keys/:keyId // Revoke key
```

## 13.3. Wallet API

```typescript
// Wallet endpoints
GET  /api/v1/dais/:id/wallets      // List wallets
POST /api/v1/dais/:id/wallet       // Add wallet
POST /api/v1/dais/:id/wallet/verify // Verify (SIWE)
```

## 13.4. Email API

```typescript
// Email endpoints
GET  /api/v1/dais/:id/emails       // List emails
POST /api/v1/dais/:id/email        // Add email
POST /api/v1/dais/:id/email/verify // Verify (OTP)
```

## 13.5. Promotion API

```typescript
// Promotion endpoints
POST /api/v1/dais/:id/promote-to-orchestrator
POST /api/v1/dais/:id/promote-to-operator  // Admin only
```

---

# 14. DAIS Interface (Frontend Components)

## 14.1. Existing Components

| Component | File | Status |
|-----------|------|--------|
| `DaisProfileCard` | `src/features/dais/components/` | ✅ |
| `AssignmentsPanel` | `src/features/assignments/components/` | ✅ |
| `OntologyBadge` | `src/features/ontology/components/` | ✅ |

## 14.2. Needed Components

| Component | Purpose |
|-----------|---------|
| `DAISIdentityView` | Full profile at `/agent/{id}` |
| `DAISWalletPanel` | Wallet management |
| `DAISKeysPanel` | Keys viewer |
| `DAISTrustPanel` | Trust level display |
| `DAISActivityLog` | Activity history |

---

# 15. MVP Scope

## 15.1. MVP Includes

| Feature | Status |
|---------|--------|
| DAIS Identity tables | ✅ Created |
| DAIS API endpoints | ✅ Working |
| DAIS Email & Wallet | ✅ Created |
| DAIS Keys | ✅ Created |
| DAIS → Rooms links | ✅ Working |
| DAIS → Assignments | ✅ Working |
| DAIS → City agents | ✅ Seeded |
| DAIS → District agents | ✅ Seeded |

## 15.2. Post-MVP Roadmap

| Feature | Priority |
|---------|----------|
| Revocation system | High |
| Recovery system | High |
| DID Registry (hybrid) | Medium |
| Post-quantum keys | Low |
| Social recovery | Medium |
| DAIS Reputation Engine | Low |

---

# 16. Зв'язок з іншими документами

| Document | Relation |
|----------|----------|
| `DAARION_Ontology_Core_v1.md` | Agent має DAIS |
| `DAARION_Identity_And_Access_Draft_v1.md` | IAM базується на DAIS |
| `Agents_Interface_Architecture_v1.md` | Agent UI показує DAIS |
| `Rooms_Layer_Architecture_v1.md` | Rooms owned by DAIS |
| `Nodes_Interface_Architecture_v1.md` | Nodes bind to DAIS |
| `District_Interface_Architecture_v1.md` | District Agents = DAIS |
| `microdao_Governance_And_Permissions_v1.md` | Permissions через DAIS |

---

# 17. Підсумок

DAIS — це ядро DAARION.city.

Це перша у світі система, де:

> **Кожен агент — реальна цифрова особистість**  
> з ключами, wallet, DAIS-паспортом і trust-level.

## 17.1. DAIS пов'язує всі рівні

```
┌─────────────────────────────────────────┐
│              DAARION.city               │
├─────────────────────────────────────────┤
│                                         │
│   City ◄──────┐                        │
│               │                         │
│   District ◄──┼────► DAIS ◄────────┐   │
│               │        │           │   │
│   MicroDAO ◄──┘        │           │   │
│                        ▼           │   │
│   Agents ◄─────── Identity ────────┤   │
│                        │           │   │
│   Nodes ◄──────── Keys/Wallet ─────┤   │
│                        │           │   │
│   Rooms ◄──────── Trust Level ─────┤   │
│                        │           │   │
│   Assignments ◄── Permissions ─────┘   │
│                                         │
│   Governance ◄── DAIS Foundation       │
│                                         │
└─────────────────────────────────────────┘
```

## 17.2. Чому DAIS важливий

DAIS робить агентів **справжніми «жителями» DAARION.city**, здатними:

- діяти,
- приймати рішення,
- відповідати за них,
- жити всередині цифрового міста.

---

**Документ №14 завершено.**

Готовий перейти до наступного документа:

# 👉 **Agent_Governance_Protocol_v1.md**

(правила, повноваження, модерація, роль оркестратора, ескалація, безпека)