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
| Functie | Beschrijving | VAPI-method |
| Balance | Balances tonen voor alle ketens (270, 260). Realtime via RPC-polling. | wallet:balance |
| Send | Transactie opzetten, preview tonen, approve vragen, broadcast na goedkeuring. | wallet:send / chain:send |
| Receive | Adres tonen + QR-code. Adres afgeleid van sessie-key of master-key. | wallet:receive |
| Sign | personal_sign en signTypedData (EIP-712). Leesbare preview verplicht. | wallet:sign / wallet:signTypedData |
| Transaction History | Lijst 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 ID | Naam | Rol | RPC-route |
270 | MAOS Production | Eigen productiechain | Alleen via Hono-proxy allowlist |
260 | zkSync Era | zkSync mainnet | Idem. Custom RPC = deny |
- Chain-keuze bepaalt welke RPC wordt gebruikt. DApp mag geen eigen RPC-URL zetten.
- Uitbreiding alleen per manifest-allowlist, nooit vrij veld.
- Fallback-routing uitgeschakeld.
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.
| Property | Waarde | Toelichting |
maxKeys | 5 | Maximaal aantal actieve session keys per DApp |
expiry | 30 min | Automatisch verlopen bij inactiviteit |
scope | per method | Elke key is gekoppeld aan specifieke VAPI-methoden |
revocation | direct | Onmiddellijk intrekken via wallet-DApp UI |
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
- EIP-6963 announces worden gefilterd in de Worker: alleen OS-gesigneerde wallets worden doorgelaten.
- DApp-injectie wordt genegeerd. Geen
window.ethereum chaos.
- DApp ziet alleen
maos.provider (gefilterde EIP-1193).
- Wallet wisselen = sessie-reset + nieuwe attest.
- Voorkomt announce-spoofing + address-confusion bij 10k+ DApps.
7. Beveiligingsregels
| Regel | Beschrijving | Gevolg bij schending |
| No raw keys | DApps krijgen nooit private keys te zien | Direct deny + audit log |
| No direct broadcast | DApps mogen nooit direct broadcasten | Intent-queue is de enige route |
| No broadcast flag | Geen broadcast:true flag voor DApps | Self-signed = deny |
| Full prompt | Elk bedrag volle prompt, ook €0,10 | Geen drempel, geen stil auto-sign |
| Blind-sign deny | Ondecodeerbaar = deny | Leesbare 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
- Wallet-DApp draait direct in shell, niet in iframe.
- Elke transactie passeert intent-queue met volledige approval-prompt.
- Session keys automatisch verlopen na 30 min inactiviteit.
- Max 5 session keys per DApp, overschrijding = deny.
- EIP-6963 announces gefilterd, alleen OS-gesigneerde wallets.
- Multi-chain 270+260 bereikbaar via Hono-proxy allowlist.
- Stripe top-up werkt via SEPA/iDEAL in wallet-DApp.
- Geen DApp krijgt ooit raw keys of broadcast-rechten.
10. Risico's en aanbevelingen
| Risico | Impact | Mitigatie |
| Session key misbruik | Hoog | Auto-expiry + scope-limiting + max 5 keys |
| EIP-6963 spoofing | Hoog | Alleen OS-gesigneerde wallets doorlaten |
| RPC-failover misbruik | Gemiddeld | Geen fallback, vaste routes per chain |
| Stripe-integratie complexiteit | Gemiddeld | Enige 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.