chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
356
docs/cursor/28_flows_wallet_embassy_energy_union.md
Normal file
356
docs/cursor/28_flows_wallet_embassy_energy_union.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 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
|
||||
|
||||
```mermaid
|
||||
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)
|
||||
|
||||
```mermaid
|
||||
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 (економічна модель).
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```mermaid
|
||||
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)
|
||||
|
||||
```mermaid
|
||||
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)
|
||||
|
||||
```mermaid
|
||||
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)
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```text
|
||||
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
|
||||
Reference in New Issue
Block a user