System-apps wallet

Wallet-DApp (Tier-0) • direct in shell, geen iframe • balance, send, receive, sign, history • multi-chain 270+260 • intent-queue flow • session-keys • status: ontwerp, nog geen code

Kerndefinitie: De Wallet-DApp is een Tier-0 systeemapplicatie die direct in de shell draait, niet in een iframe. Het is de enige component die transacties mag broadcasten. Elke DApp maakt een intent, de wallet-DApp keurt goed, en de kernel broadcast pas na goedkeuring. Nooit raw keys naar DApps.

1. Architectuur

┌─────────────────────────────────────────────────────────┐
│                     Shell (Tier-0)                       │
│  ┌─────────────────────────────────────────────────┐     │
│  │              Wallet-DApp (direct)                │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │     │
│  │  │ Balance  │  │ Send/    │  │ Transaction  │  │     │
│  │  │ View     │  │ Receive  │  │ History      │  │     │
│  │  └──────────┘  └──────────┘  └──────────────┘  │     │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │     │
│  │  │ Sign     │  │ Session  │  │ Wallet-      │  │     │
│  │  │ Manager  │  │ Keys     │  │ Connect      │  │     │
│  │  └──────────┘  └──────────┘  └──────────────┘  │     │
│  └─────────────────────┬───────────────────────────┘     │
│                        │ VAPI                           │
│  ┌─────────────────────┴───────────────────────────┐     │
│  │              SharedWorker Router                 │     │
│  │  ┌──────────────┐  ┌─────────────────────────┐  │     │
│  │  │ Intent Queue │  │ Broadcast Queue         │  │     │
│  │  │ (pending)    │  │ (approved → kernel)     │  │     │
│  │  └──────────────┘  └─────────────────────────┘  │     │
│  └─────────────────────┬───────────────────────────┘     │
│                        │                                 │
│  ┌─────────────────────┴───────────────────────────┐     │
│  │              Blockchain Layer                    │     │
│  │  ┌──────────────────┐  ┌──────────────────────┐ │     │
│  │  │ Chain 270 (eigen)│  │ Chain 260 (zkSync)   │ │     │
│  │  └──────────────────┘  └──────────────────────┘ │     │
│  └─────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────┘

DApp (Tier-1/2) ──maos.request──▶ SharedWorker ──enqueue──▶ wallet-DApp queue
                                                                │
                              browser-wallet / MAOS-extension ──approve/reject
                                                                │
                                              approve ──▶ kernel broadcast ──▶ receipt

2. Kernfuncties

FunctieBeschrijvingVAPI-method
BalanceBalances tonen voor alle ketens (270, 260). Realtime via RPC-polling.wallet:balance
SendTransactie opzetten, preview tonen, approve vragen, broadcast na goedkeuring.wallet:send / chain:send
ReceiveAdres tonen + QR-code. Adres afgeleid van sessie-key of master-key.wallet:receive
Signpersonal_sign en signTypedData (EIP-712). Leesbare preview verplicht.wallet:sign / wallet:signTypedData
Transaction HistoryLijst van verzonden/ontvangen transacties per chain. Gesynchroniseerd via RPC.wallet:history

3. Intent-queue flow

Elke transactie van een DApp gaat door dezelfde pipeline. Geen uitzonderingen, geen shortcuts.

DApp stuurt: maos.request('wallet:send', { to, value, chain })
    │
    ├── 1. SharedWorker validated request
    │       ├── Rate-limit check (token bucket)
    │       ├── Permission check (manifest capabilities)
    │       └── Schema-validatie (to = address, value = uint256)
    │
    ├── 2. Intent queue (status: pending)
    │       │
    │       └── Wallet-DApp toont: DApp-id, chain, bedrag, gas, dagtotaal
    │
    ├── 3. Gebruiker keurt goed of wijst af
    │       │
    │       ├── Approved → kernel broadcast
    │       │       ├── Transaction signen (session-key of extension)
    │       │       ├── Broadcast naar RPC
    │       │       └── Receipt terug naar DApp
    │       │
    │       └── Rejected → foutmelding naar DApp
    │
    └── 4. Daglimiet-check
            ├── Onder limiet → direct broadcast
            └── Boven limiet → deny + verzoek tot verhoging

4. Multi-chain ondersteuning

Chain IDNaamRolRPC-route
270MAOS ProductionEigen productiechainAlleen via Hono-proxy allowlist
260zkSync ErazkSync mainnetIdem. Custom RPC = deny

5. Session key beheer

Regel: Maximaal 5 session keys per DApp. Auto-expiry na inactiviteit. Session keys zijn tijdelijke sleutels die een DApp mogen gebruiken voor specifieke acties.
Sessie key lifecycle:
    │
    ├── DApp vraagt key aan → wallet-DApp toont scope + expiry
    │
    ├── Gebruiker approve → key aangemaakt + gekoppeld aan DApp
    │
    ├── Key actief → DApp mag methods uitvoeren binnen scope
    │
    ├── Inactiviteit > 30 min → automatisch verlopen
    │
    └── Handmatig intrekken → key verwijderd, alle actieve sessies verbroken

6. Wallet-connect via EIP-6963

7. Beveiligingsregels

PropertyWaardeToelichting
maxKeys5Maximaal aantal actieve session keys per DApp
expiry30 minAutomatisch verlopen bij inactiviteit
scopeper methodElke key is gekoppeld aan specifieke VAPI-methoden
revocationdirectOnmiddellijk intrekken via wallet-DApp UI
RegelBeschrijvingGevolg bij schending
No raw keysDApps krijgen nooit private keys te zienDirect deny + audit log
No direct broadcastDApps mogen nooit direct broadcastenIntent-queue is de enige route
No broadcast flagGeen broadcast:true flag voor DAppsSelf-signed = deny
Full promptElk bedrag volle prompt, ook €0,10Geen drempel, geen stil auto-sign
Blind-sign denyOndecodeerbaar = denyLeesbare preview verplicht

8. Payment: Stripe top-up

BESLIST: Funds top-up (storten) kan uitsluitend via de wallet-DApp. Stripe SEPA/iDEAL als top-up-rail, daarna alles on-chain via intent-queue met approval + gas/daglimiet. MAOS draait geen eigen Stripe-integratie per DApp.
Gebruiker: onvoldoende saldo in wallet-DApp
    │
    ├── 1. Wallet-DApp toont: "Top-up nodig"
    │
    ├── 2. Redirect naar top-up scherm (wallet-DApp)
    │       ├── Bedrag invoeren
    │       ├── Betaalmethode kiezen (SEPA/iDEAL)
    │       └── Stripe Checkout (embedded)
    │
    ├── 3. Betaling geslaagd
    │       ├── Funds bijgeschreven op wallet-saldo
    │       └── On-chain betaling via intent-queue
    │
    └── 4. Receipt → originele DApp toegang geven

9. Acceptatiecriteria

10. Risico's en aanbevelingen

RisicoImpactMitigatie
Session key misbruikHoogAuto-expiry + scope-limiting + max 5 keys
EIP-6963 spoofingHoogAlleen OS-gesigneerde wallets doorlaten
RPC-failover misbruikGemiddeldGeen fallback, vaste routes per chain
Stripe-integratie complexiteitGemiddeldEnige top-up-rail in wallet-DApp, niet per DApp

11. Verwijzingen naar verwante specs

Volgende stap Na akkoord: Wallet-DApp UI implementatie + intent-queue integratie + session-key lifecycle + EIP-6963 filtering + Stripe top-up flow.