Citizen Wallet Platform Specification (Draft)

Status: Draft – v0.1 (2025‑06‑04)

Audience: Product, Engineering, DevRel, Security, Community Contributors

Purpose: Define the architecture, modules, APIs, and non‑functional requirements for Citizen Wallet – a modular, open‑source developer platform that aims to be the “Supabase of Web3”.

---

1  Introduction

Citizen Wallet is an Ethereum‑based wallet and developer platform that abstracts away Web3 complexity. Much like Supabase/Firebase in Web2, Citizen Wallet bundles essential backend services – identity, data, real‑time events, and security – into a coherent, self‑hostable package that accelerates dApp development.

2  Vision & Goals

Goal	Description	Success Metric
Simplicity	One‑line SDK install & deploy.	<10 min to first transaction.
Modularity	Each service deployable standalone or as a suite.	80% features consumable à la carte.
Security	Smart‑account native with audited contracts.	0 critical vulnerabilities post‑audit.
Scalability	Horizontally scalable micro‑services, multi‑chain ready.	1k tx/sec sustained.
Community‑Driven	MIT/Apache 2.0 licensing, governance via DAO.	100+ outside PRs per release cycle.

3  System Architecture Overview

+-------------+    WebSocket  +-------------+
|   dApps &   | <-----------> | Event Relay |
|   SDKs      |               +-------------+
|  (JS/TS,    | REST / RPC    | Metadata   |
|   Rust, ...) +----+        +-------------+
+-------------+     |        |  Off‑Chain  |
       ^            |        | Storage (PG |
       |            v        | + IPFS)     |
+-------------+  +-----------+-------------+
| Smart        |  |  RPC Proxy & Rate‑Lim. |
| Contracts    |  +-----------+-------------+
| (ERC‑4337,   |              |
|  ERC‑721)    |     Metrics  |
+-------------+              v
                       +-------------+
                       |  DevOps &   |
                       | Monitoring  |
                       +-------------+

3.1  Major Components

1. Smart‑Account Layer – Factory, Paymaster, ERC‑4337 Bundler, Safe Account Sessions.
2. Profile Layer – Soul‑Bound ERC‑721 for user profiles.
3. Event Layer – On‑chain event indexer & real‑time push (WebSocket).
4. Storage Layer – Off‑chain metadata DB (Postgres) + optional IPFS pinning.
5. Integration Layer – REST API, Websockets, Webhooks, and RPC Proxy with caching & rate limits.
6. DevEx Layer – CLI, SDKs, admin dashboard, templates.

3.2  Data Flow Summary

1. User signs action in dApp → SDK compiles ERC‑4337 UserOperation.
2. Bundler packages tx → submits to mempool → Paymaster sponsors gas.
3. Account execution emits events → Event Relay captures, enriches, stores.
4. dApp receives real‑time webhook/WebSocket update; off‑chain metadata available via REST.

3.3  Deployment Model

• Self‑Hosted (Docker) – default; infra‑agnostic.
• Managed Cloud – hosted SaaS tier with SLAs.

4  Core Modules

4.1  Account Abstraction (AA)

Component	Contract	Key Features
Account Factory	AccountFactory.sol	CREATE2 deterministic address; upgradable logic pointers.
Smart Account	Safe.sol	Session keys; modular validation; multi‑sig support.
Bundler	Off‑chain Golang service	Mempool watcher, gas opt., MEV protection hooks.
EntryPoint	EntryPoint.sol	Simplified entry point that removes reliance on a full node.
Paymaster	Paymaster.sol	Rule‑based gas sponsorship, ERC‑20 or credit balance.
Sessions	SessionManagerModule.sol	Manage session requests and transaction hooks.
Session Service	Rest micro‑service	Generates & rotates session keys.

4.2  Identity & Profiles (ERC‑721 SBT)

• Non‑transferrable profile NFTs store ENS, PGP, social links (JSON metadata).
• Role‑based access (e.g., community‑verified, KYC‑verified).
• Hooks for soul‑bound revocation under community governance.

4.3  Event Stream & Indexer

• Indexer: Event log indexing into Postgres (event parsing into json).
• Real‑Time Relay: WebSocket event listener.
• Webhook Engine: Retry with exponential backoff, signature headers.

4.4  Off‑Chain Storage

• Postgres for relational metadata.
• Optional IPFS pin‑set per workspace.

4.5  RPC Proxy

• Alchemy/Infura pooling, rate‑limit, caching (Redis).
• Metrics: p95 latency, request volume.

5  API Specification (High‑Level)

Method	Endpoint	Description
POST	/v1/aa/userops	Submit ERC‑4337 UserOperation.
GET	/v1/accounts/{address}	Get smart‑account & profile.
GET	/v1/events	Query historical on‑chain events.
WS	/v1/stream	Real‑time event subscription.
POST	/v1/webhooks	Manage webhooks (+secret).
POST	/v1/storage/metadata	Pin metadata JSON to IPFS.

Authentication via JWT scoped per workspace → bound to API key (HMAC).

SDKs auto‑generate typed clients (OpenAPI 3.1).

6  Smart Contract Details

1. Languages & Tooling: Solidity 0.8.x, Foundry tests, OpenZeppelin libraries.
2. Upgrade Path: UUPS proxies or Diamond pattern (TBD) with timelock.
3. Gas Benchmarks: <100k gas for simple execute() via session key.
4. Audits: 3rd‑party audit (Phase 0 in July 2025, Phase 1 before v1.0 GA).

7  Security & Compliance

Area	Approach
Key Mgmt	Non‑custodial; session keys encrypted at rest.
Supply‑Chain	Dependabot + SLSA‑compliant CI.
Privacy	GDPR‑ready opt‑in analytics; data minimization.
Regulatory	Assess FinCEN/OFAC implications for Paymaster.
Audit Trail	Immutable event logs, SIEM forwarding.

8  Performance & Scalability Targets

• Indexer: 2k events/sec ingest.
• Bundler: 500 UserOps/sec per node.
• Latency: p95 <1 s end‑to‑end (dApp click → chain tx hash).
• Availability: 99.9% (self‑hosted reference); 99.99% (managed).

Horizontal scaling via Kubernetes + Kafka for queueing.

9  Developer Experience

• CLI – citizen init, citizen deploy, citizen tail.
• Templates – Next.js, React Native boilerplates.
• Dashboard – Usage analytics, webhook logs, key mgmt.
• Docs – MDX docs site auto‑built from OpenAPI & Solidity NatSpec.

10  Open‑Source Governance

• License: MIT.
• Stewardship DAO: Token‑gated voting on roadmap & treasury.
• Contributor Guide: Conventional Commits, CLA‑signed PRs.

11  Roadmap (H2 2025 – H1 2026)

Quarter	Milestone
Q3 2025	Public alpha, smart‑account SDK, basic event relay.
Q4 2025	Managed Cloud GA, paymaster credit system, audit 0.
Q1 2026	Multi‑chain (L2s, Alt‑EVM), social recovery UX.

12  Glossary

• AA – Account Abstraction (ERC‑4337).
• SBT – Soul‑Bound Token (non‑transferable ERC‑721).
• UserOperation – Bundled tx call data defined by ERC‑4337.
• Workspace – Isolated tenant context within Citizen Wallet.

---

Next Steps: • Review module interface details (Section 5) and provide feedback. • Prioritize audit scope. • Align Q3 2025 resource allocation.