Skip to content

# 28 — Flows: Wallet, Embassy, Energy Union (MicroDAO)

Sequence-діаграми основних критичних потоків: авторизація, Wallet, Embassy, Energy Union, NATS Outbox

Це документ візуалізацій — «центральна нервова система» проєкту.

Він показує, як працює процес:

- login → capability → action,
- stake RINGK → payouts,
- embassy → nats → services,
- oracle updates → RWA → wallet,
- agent runs → PDP.

Усі діаграми подані в Mermaid, GitHub рендерить їх автоматично.

## 1. Purpose

Цей документ описує динамічні потоки (sequence diagrams) між сервісами:

- frontend (web),
- API Gateway (PEP),
- PDP (Policy Decision Point),
- Postgres (DB),
- NATS JetStream (event bus),
- Wallet Service,
- Embassy Service,
- Energy Union,
- Agent Mesh.

Ці діаграми є частиною безпекового аудиту, дебагу, тестування, QA та документації для інтеграцій.

## 2. Legend

    U      – User (browser/app)
    A      – Agent (private agent)
    API    – API Gateway (PEP)
    PDP    – Policy Service (capability checks)
    DB     – Postgres (core data)
    WAL    – Wallet Service
    NATS   – JetStream Event Bus
    EMB    – Embassy Gateway
    EU     – Energy Union backend
    RUN    – Agent Runtime

## 3. Login → Capability Token → Action

    sequenceDiagram
        participant U as User (Web)
        participant API
        participant PDP
        participant DB

        U->>API: POST /login (email+otp)
        API->>DB: validate OTP
        DB-->>API: OK
        API->>DB: fetch team_members, role, plan, entitlements
        DB-->>API: role=Member, plan=Premium, stake=100 RINGK

        API->>API: build capability-token (bundles role+plan)
        API-->>U: session cookie + cap-token

        U->>API: GET /projects
        API->>PDP: authorize(user, action=project.read)
        PDP->>DB: lookup bundles+caps
        DB-->>PDP: caps_allow
        PDP-->>API: allow
        API->>DB: SELECT * FROM projects
        DB-->>API: result
        API-->>U: JSON

## 4. Agent Run (Router → PDP → DB → RUN → NATS)

    sequenceDiagram
        participant U as User
        participant API
        participant PDP
        participant DB
        participant RUN as Agent Runtime
        participant NATS

        U->>API: POST /agent/run {prompt}
        API->>PDP: authorize(user, action=agent.run.invoke)
        PDP-->>API: allow

        API->>DB: INSERT INTO agent_runs (pending)
        DB-->>API: OK

        API->>RUN: start(agent_id, input)
        RUN-->>API: ack (accepted)

        RUN->>NATS: publish agent.run.started
        U->>API: GET /agent/run/status
        API->>DB: SELECT status=running

        RUN->>RUN: LLM inference / tools / reasoning
        RUN->>DB: UPDATE agent_runs (output, status=completed)
        RUN->>NATS: publish agent.run.completed

        API-->>U: result

## 5. Stake RINGK → Payout Flow

Це один із ключових потоків у DAARION (економічна модель).

    sequenceDiagram
        participant U as User
        participant API
        participant PDP
        participant DB
        participant WAL as Wallet Service
        participant NATS

        U->>API: POST /wallet/stake {amount}
        API->>PDP: authorize(user, action=wallet.stake.ringk)
        PDP-->>API: allow

        API->>DB: INSERT INTO staking_ringk (locked)
        DB-->>API: OK

        API->>WAL: notify stake_request(user, amount)
        WAL->>NATS: publish staking.locked

        WAL->>WAL: compute payouts for period
        WAL->>NATS: publish payout.generated {user, amount, symbol="KWT"}

        U->>API: GET /wallet/payouts
        API->>DB: SELECT * FROM payouts
        API-->>U: pending payout

## 6. Embassy Webhook → PDP → RWA Inventory → Wallet/NATS

    sequenceDiagram
        participant EXT as External Platform (EnergyUnion/GreenFood/etc)
        participant EMB
        participant API
        participant PDP
        participant DB
        participant NATS
        participant WAL as Wallet Service

        EXT->>EMB: POST /embassy/energy {kWh} + HMAC Signature
        EMB->>API: forward request

        API->>PDP: authorize(embassy_key, action=embassy.energy.update)
        PDP-->>API: allow

        API->>DB: UPDATE rwa_inventory (type=energy)
        DB-->>API: OK

        API->>NATS: publish rwa.inventory.updated

        NATS->>WAL: process inventory → compute payouts?
        WAL->>NATS: publish payout.generated (1T/KWT)

        API-->>EMB: 200 OK

## 7. Energy Union → Embassy Oracle → NATS → Wallet

    sequenceDiagram
        participant M as Meter Device
        participant EU as Energy Union
        participant EMB
        participant API
        participant PDP
        participant DB
        participant NATS
        participant WAL

        M->>EU: send meter data
        EU->>EMB: POST /embassy/oracle {site, kWh, ts}

        EMB->>API: request
        API->>PDP: authorize(emb_key, action=embassy.energy.update)
        PDP-->>API: allow

        API->>DB: INSERT INTO oracles (payload)
        DB-->>API: OK

        API->>NATS: publish oracle.reading.published

        NATS->>WAL: recalc payouts (KWT/1T)
        WAL->>DB: INSERT INTO payouts
        WAL->>NATS: publish payout.generated

## 8. Wallet Claim Flow (User Claims Payout)

    sequenceDiagram
        participant U as User
        participant API
        participant PDP
        participant DB
        participant WAL as Wallet Service
        participant CHAIN as Blockchain

        U->>API: POST /wallet/claim {payout_id}
        API->>PDP: authorize(user, action=wallet.payout.claim)
        PDP-->>API: allow

        API->>DB: SELECT payout (pending)
        DB-->>API: OK

        API->>WAL: execute claim
        WAL->>CHAIN: submit tx
        CHAIN->>WAL: tx confirmed

        WAL->>DB: UPDATE payouts (claimed)
        API-->>U: success + tx_hash

## 9. Outbox → NATS Delivery (Guarantee: At-Least-Once)

    sequenceDiagram
        participant DB
        participant WORK as Outbox Worker
        participant NATS

        DB->>WORK: SELECT events WHERE processed=false LIMIT 100
        WORK->>NATS: publish event
        NATS-->>WORK: ack
        WORK->>DB: UPDATE outbox_events SET processed=true

## 10. Governance Flow (Proposal → Vote → Policy Update)

    sequenceDiagram
        participant U as User (Guardian/Owner)
        participant API
        participant PDP
        participant DB
        participant GOV as Governance Agent
        participant NATS

        U->>API: POST /gov/proposal {change_policy}
        API->>PDP: authorize(user, action=governance.proposal.create)
        PDP-->>API: allow

        API->>DB: INSERT proposal
        DB-->>API: OK

        API->>NATS: publish governance.proposal.created

        U->>API: POST /gov/vote
        API->>PDP: authorize(user, action=governance.vote.cast)
        PDP-->>API: allow

        API->>DB: UPDATE proposal votes
        DB-->>API: OK

        GOV->>DB: finalize, update capability bundles
        GOV->>NATS: publish governance.policy.updated

## 11. Threat Model Integration Points

Flow | Threat | Mitigation
--- | --- | ---
Embassy webhook → API | Fake source, replay attack | HMAC + timestamp + PDP-check
Wallet claim | Double-spend | DB row-level lock + chain receipt
Agent run | Prompt injection | Input sanitization + safe tools
Confidential channels | E2EE bypass | No plaintext server-side, agent gets summary only
NATS events | Lost events | Outbox pattern
RWA updates | Poisoned oracle | PDP + oracle signature + anomaly detection
Payout generation | Fake energy data | embassy_key capabilities + oracle signatures

## 12. Summary

Документ покриває основні системні флоу, які визначають:

- безпеку,
- економіку,
- консистентність,
- надійність,
- інтеграцію з RWA,
- роботу агентів.

Діаграми можуть бути імпортовані у Confluence/Notion/Docs автоматично.

## 13. Завдання для Cursor

    You are a senior backend engineer. Implement the flows described in:
    - 28_flows_wallet_embassy_energy_union.md
    - 24_access_keys_capabilities_system.md
    - 12_agent_runtime_core.md

    Tasks:
    1) Implement PDP (Policy Decision Point) service.
    2) Implement PEP (Policy Enforcement Point) middleware for API Gateway.
    3) Implement Outbox Worker for NATS event delivery.
    4) Implement Wallet Service with stake/payout flows.
    5) Implement Embassy Gateway with webhook signature verification.
    6) Add sequence diagram validation tests.

    Output:
    - list of modified files
    - diff
    - summary

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

Після впровадження цих потоків:

- чітко визначені всі критичні системні інтеграції;
- готовність до тестування end-to-end сценаріїв;
- документація для QA та інтеграційних тестів;
- основа для моніторингу та дебагу production issues.

Версія: 1.0
Останнє оновлення: 2024-11-14