walletpress/ARCHITECTURE.md

# WalletPress — Architecture & Moving-Forward Plan

> **Status:** Canonical. Owner: WalletPress Engineering.
> **Last updated:** 2026-06-30.
> **Audience:** All engineers and agents. Read alongside AUDIT.md and SECURITY.md.
> **Purpose:** What the system is, why it is shaped that way, and where it's going.

---

## The product

**WalletPress** is an open-source (MIT) multi-chain wallet generation & management platform. The repository ships four surfaces:

| Surface | Path | Tech | Purpose |
|---------|------|------|---------|
| **Backend** | `backend/` | Python 3.12, FastAPI, SQLite | Wallet gen, vault, agent, marketplace |
| **WP plugin** | `wp-plugin/` | PHP 8, WordPress | Token gating, payments, login for WP sites |
| **Standalone MCP** | `walletpress-mcp/` | Python, FastMCP | Talk to any WalletPress backend from Claude Code / opencode / Cursor |
| **CLI** | `backend/walletpress_cli.py` | Python | Operator workflow (serve, init, generate, backup, doctor) |

Plus a marketing site (`index.html`, `buy.html`, `docs.html`, etc.) — out of scope for this doc.

---

## Architecture

### High-level

```
┌────────────────────────────────────────────────────────────────────────┐
│                          WALLETPRESS BACKEND                            │
│                                                                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌────────────┐ │
│  │  HTTP API    │  │   MCP        │  │   CLI        │  │  WS Events │ │
│  │  /docs       │  │   /mcp/sse   │  │  walletpress │  │  /ws/events│ │
│  │  50+ endpoints│  │   30+ tools  │  │   9 cmds     │  │            │ │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘ │
│         │                 │                 │                │        │
│         ▼                 ▼                 ▼                ▼        │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                      Routers + Services                          │ │
│  │   chain_vault  wallet_analysis  hosting  x402  agent_safety     │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│         │                                                              │
│         ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                          Core                                    │ │
│  │  Vault | Auth | Audit | Proof | AgentSafety | Hosting | TOTP     │ │
│  │  Email | Webhooks | License | HostingDB | EventBus | RateLimit  │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│         │                                                              │
│         ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                       Wallet Engine                              │ │
│  │   generator (BIP39/32/44) | chains (55 metadata) | CHAINS.yaml  │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│         │                                                              │
│         ▼                                                              │
│  ┌─────────────────────────────────────────────────────────────────┐ │
│  │                       Adapters                                   │ │
│  │   langchain | crewai | eliza | openai_agents | vercel_ai         │ │
│  └─────────────────────────────────────────────────────────────────┘ │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
        │
        ▼  (Tailscale or Tailscale+TLS via Caddy)
┌────────────────────────────────────────────────────────────────────────┐
│   OPERATOR (Talisman)                │   END USERS                      │
│   - Dashboard                       │   - WP plugin users              │
│   - x402 marketplace                │   - MCP clients                  │
│   - Backup/restore                  │   - Bot/automation devs          │
└────────────────────────────────────────────────────────────────────────┘
```

### Module map

```
backend/
├── main.py                 # FastAPI app, lifespan, middleware stack
├── x402_service.py         # Pay-per-wallet marketplace (mounted sub-app)
├── walletpress_cli.py      # CLI entrypoint
├── client_sdk.py           # Python SDK for talking to the API
│
├── core/
│   ├── config.py           # All env-driven config
│   ├── vault.py            # AES-GCM encrypted SQLite wallet store
│   ├── auth.py             # API key store + scopes
│   ├── audit.py            # Append-only JSONL audit log
│   ├── proof.py            # Merkle tree attestations + Ed25519 receipts
│   ├── agent_safety.py     # HITL, kill switch, spending limits, address book, audit chain
│   ├── hosting.py          # Hosted-mode users + Stripe stub
│   ├── rate_limit.py       # Token bucket middleware
│   ├── ip_allowlist.py     # CIDR allowlist middleware
│   ├── license.py          # JWT-signed license keys
│   ├── license_check.py    # Middleware that enforces license tier
│   ├── totp.py             # 2FA (TOTP)
│   ├── webhooks.py         # Outbound webhook delivery + retries
│   ├── email_notify.py     # SMTP notifications
│   ├── event_bus.py        # In-process pub/sub
│   ├── db_pool.py          # SQLite connection pool helper
│   ├── smart_wallet.py     # ERC-4337 smart wallet logic (754 lines — review needed)
│   ├── arweave.py          # Arweave client wrapper
│   ├── x402_verify.py      # On-chain payment verification
│   ├── x402_marketplace.py # Marketplace business logic
│   ├── pdf.py              # PDF generation (paper wallet, birth cert)
│   ├── response.py         # Response helpers
│   ├── onboarding.py       # CLI onboarding / setup wizard
│   └── proof_digest.py     # Digest / hashing helpers
│
├── wallet_engine/
│   ├── chains.py           # 55-chain registry + ChainFamily enum
│   ├── chains.yaml         # User-overridable chain config
│   └── generator.py        # BIP39/BIP32 wallet generator (594 lines)
│
├── routers/
│   ├── chain_vault.py      # Wallet CRUD + paper wallet + export (2249 lines — split)
│   ├── wallet_analysis.py  # Address scoring, risk
│   ├── wallet_memory.py    # Wallet notes / metadata
│   ├── balance_fetcher.py  # Multi-chain balance lookups
│   ├── tx_broadcaster.py   # Send tx via RPC
│   ├── test_vectors.py     # BIP39 test vector endpoint
│   ├── metrics.py          # Prometheus metrics
│   ├── airdrop.py          # CSV-driven wallet generation for airdrops
│   ├── retention.py        # Data retention policies
│   ├── health_monitor.py   # Health probes
│   ├── hosting.py          # Hosted user CRUD
│   └── license_router.py   # License key admin
│
├── agent/
│   ├── orchestrator.py     # Natural-language → plan
│   ├── mcp_server.py       # FastMCP server with 30+ tools
│   ├── scheduler.py        # Background DCA / monitor / rotate tasks
│   ├── detector.py         # Anomaly detection
│   └── providers.py        # 20 AI provider configs
│
├── adapters/               # Thin wrappers for agent frameworks (stubs)
│   ├── langchain.py
│   ├── crewai.py
│   ├── eliza.py
│   ├── openai_agents.py
│   └── vercel_ai.py
│
├── plugins/
│   ├── defi.py             # DeFi integrations + referral revenue
│   └── sdk.py              # Plugin SDK
│
├── alembic/                # Migration framework (currently unused)
└── tests/                  # 63 tests collected
```

---

## Critical user journeys

### Journey 1: User generates a wallet via WP plugin

```
WP admin → POST /wp-json/walletpress/v1/generate
   → WP plugin → backend POST /api/v1/chain-vault/wallets
      → require_auth_on_mutations (X-API-Key check)
      → chain_vault router
         → Vault.put(WalletEntry)
         → ProofOfGeneration.attest()
         → AuditTrail.log()
         → EventBus.publish("wallet.generated")
            → WebSocket broadcast → subscribers
            → Webhook delivery → subscribers
      → return {wallet_id, address, derivation_path}
   → WP plugin displays address + QR
```

**Trust assumptions:** WP plugin has a valid `walletpress_api_key`. Backend has the WP plugin's IP in `WP_ALLOWED_IPS`.

### Journey 2: AI agent executes a plan

```
User prompt: "Generate 5 SOL wallets for the airdrop"
   → MCP tool `agent_plan`
      → Orchestrator.plan_operation()
         → LLM (e.g. GPT-4o via OpenAI-compatible API)
         → Returns JSON plan: [{"tool": "wallet_generate", "args": {"chain": "sol", "count": 5}}]
   → MCP tool `agent_execute(plan, confirm=False)`
      → Orchestrator.execute_plan()
         → For each step:
            → _call_tool("wallet_generate", {...})
               → mcp_server.wallet_generate
                  → _write_with_hitl → returns confirmation_id
                  → user calls agent_confirm → executes
                     → Vault.put()
                     → ProofOfGeneration.attest()
                     → AgentSafety.audit_log() (with hash chain)
   → returns execution results
```

**Trust assumptions:** LLM doesn't go off-script. Confirmation flow is respected. Audit chain is intact.

### Journey 3: Bot pays via x402 marketplace

```
Bot → POST /api/v1/marketplace/generate
  → x402_service
     → Idempotency check (return existing order if same key)
     → Payment check:
        → credits: balance check + deduct (BROKEN: P0-1)
        → onchain: verify_payment() via Solana RPC
        → free: < MIN_ORDER_USD
     → Generate wallets (in memory)
     → Sign receipt + key-deletion attestation
     → Insert order in marketplace.db
     → Return {wallets, receipt, deletion_attestation}
```

**Trust assumptions:** Receipt signing key is private. Generated keys are not logged anywhere downstream.

### Journey 4: Operator deploys to production

```
$ walletpress deploy --domain example.com
  → check license (Pro required)
  → detect OS
  → install system deps (apt-get)
  → create /opt/walletpress + venv
  → pip install -r requirements.txt
  → generate secrets (openssl rand)
  → write /etc/walletpress/env (mode 0600)
  → install systemd unit
  → enable + start walletpress.service
  → print admin key + vault password (USER MUST SAVE)
```

**Trust assumptions:** The operator reads and saves the credentials. No one else has root on the host. Tailscale mesh is configured.

---

## Why these choices

### Why FastAPI?

- Async-native. We do a lot of I/O (RPC calls, DB queries, LLM calls).
- Auto-generated OpenAPI schema → WordPress plugin gets typed SDK.
- Pydantic validation everywhere.
- Fast iteration with `uvicorn --reload`.

### Why SQLite?

- Single-file deployment. No separate DB process to manage.
- WAL mode handles concurrent reads.
- `sqlite-vec` / FTS5 for search.
- Trade-off: no horizontal scaling. For hosted mode with >100k users, migrate to Postgres (the project already has Postgres on Talos).

### Why a separate x402 sub-app?

- The marketplace has different operational requirements (no admin key needed, no internal vault, scales independently).
- `app.mount("/", x402_app)` in main.py shares the process but the routes are isolated.
- Trade-off: shared memory = shared fate. If x402 hangs, the whole process hangs.

### Why one repo, three deliverables?

- WordPress plugin is the funnel (free).
- Backend is the engine (Pro / hosted).
- CLI is the ops surface (for Pro self-hosters).
- Same repo = atomic changes, no version drift.

### Why MCP?

- AI agents (Claude Code, opencode, Cursor) are the new ops surface.
- MCP = standard protocol. Any agent that speaks MCP can use WalletPress.
- The hosted MCP is the easiest way to give non-developers access to the wallet engine.

### Why BIP39 + BIP32?

- Industry standard. Every wallet supports it.
- Same mnemonic → same address across every tool. Users can verify against MetaMask, Phantom, Trezor.
- Determinism = trust.

---

## Moving-forward plan

The product has shipped v1.0.0-beta. Before v1.0 stable, we need to:

### Phase 0: Stabilize (this week, blocking)

Goal: No P0 or P1 bugs remain. See AUDIT.md.

| Order | Item | Owner | Estimate |
|-------|------|-------|----------|
| 1 | Disable 17 BROKEN chains (P0-4) | @engineer-1 | 1 day |
| 2 | Fix x402 credits verification (P0-1) | @engineer-2 | 0.5 day |
| 3 | Move hosted passwords to Argon2id (P0-2) | @engineer-1 | 1 day |
| 4 | Persist team keys + role enforcement (P0-3) | @engineer-2 | 1 day |
| 5 | KEK file backend (P0-5) | @engineer-1 | 2 days |
| 6 | Implement or rename wallet_sweep + DCA (P0-6 + P1-13) | @engineer-3 | 1 day |
| 7 | Audit chain mutex (P1-12) | @engineer-3 | 0.5 day |
| 8 | Receipt redaction in audit log (P1-5) | @engineer-3 | 0.5 day |
| 9 | Fix x402 verify_order DB path (P1-6) | @engineer-2 | 0.25 day |
| 10 | LLM timeout + rate limit (P1-9, P1-10, P1-11) | @engineer-3 | 1 day |
| 11 | Fix _verify saves on read (P1-1) | @engineer-2 | 0.5 day |
| 12 | Audit trail integrity (P1-4) | @engineer-2 | 1 day |

**Total: ~10 engineer-days.** Cut `v1.0.0-audit` after this phase.

### Phase 1: Fix the 17 broken chains (this sprint)

Per-chain work. Each chain needs:
- Reference SDK installed in dev requirements
- `tests/test_address_vectors.py` golden-vector test
- Implementation in `wallet_engine/generator.py` (or a new per-chain module)
- Update `chains.py` to remove `generation_disabled`
- Update `ADDRESS_GENERATION.md`

Priority order (highest user demand first):
1. **Stellar** (`xlm`) — 30 min, use `stellar-sdk`
2. **Tezos** (`xtz`) — 1 hour, use `pytezos`
3. **Injective** (`inj`) — 1 hour, bech32 + ETH path
4. **Cosmos Hub** (`atom`) — 1 hour, bech32
5. **Osmosis / Sei / Juno / Evmos** — 2 hours each, same pattern
6. **Algorand** (`algo`) — 1 hour, base32 + checksum
7. **TON** (`ton`) — 2 hours, custom format
8. **Filecoin** (`fil`) — 1 hour, blake2b
9. **Nano** (`xno`) — 1 hour, base32 + blake2b
10. **Polkadot / Kusama** — 4 hours, sr25519 (use `substrate-interface`)
11. **Monero** (`xmr`) — 6 hours, custom Monero crypto
12. **Cardano** (`ada`) — 8 hours, Bech32 stake/enterprise
13. **Bitcoin Cash** (`bch`) — 1 hour, cashaddr
14. **XRP** (`xrp`) — 2 hours, custom base58 alphabet
15. **Zcash** (`zec`) — 1 hour, prefix fix

**Total: ~25 engineer-days.** Cut `v1.1.0` after this phase.

### Phase 2: Architectural cleanup (next sprint)

| Item | Why | Estimate |
|------|-----|----------|
| Split `chain_vault.py` (2249 lines) into 4 modules | Maintainability | 2 days |
| Migrate raw SQL → Alembic | Schema migrations | 3 days |
| Consolidate DB paths to one `walletpress.db` | Operations | 1 day |
| Pluggable KeyBackend (env / file / KMS) | P0-5 follow-on | 3 days |
| Per-wallet derived keys (HKDF) | Revocation granularity | 2 days |
| Pydantic models for all MCP tool args | Type safety | 2 days |
| Repository pattern for SQLite stores | Testability | 3 days |
| Replace JSON `KeyStore` + `TeamKeyStore` with SQLite | Persistence | 1 day |

**Total: ~17 engineer-days.** Cut `v1.2.0` after this phase.

### Phase 3: Ship the roadmap (next month)

From ROADMAP.md (now validated against actual code gaps):

| Item | From | Status | Notes |
|------|------|--------|-------|
| #1 Paper wallet PDF | ROADMAP | already exists (`core/pdf.py`) | Verify output |
| #2 SSE progress for batch | ROADMAP | not built | High impact |
| #3 Mnemonic auto-detect chain | ROADMAP | not built | After phase 1 |
| #4 QR codes on addresses | ROADMAP | already built (`?include_qr=true`) | Verify |
| #5 Webhook delivery log + retry | ROADMAP | partial | `webhooks.py` has retries but no UI |
| #6 Per-API-key rate limit | ROADMAP | partial | Falls back to IP — fix |
| #7 Backup + restore CLI | ROADMAP | partial — doesn't encrypt | Add encryption |
| #8 Clean error messages | ROADMAP | partial | Audit each router |
| #9 Temporal wallet cleanup | ROADMAP | built (`temporal_cleanup_loop`) | Verify |
| #10 Full-text search | ROADMAP | built (FTS5) | Verify |
| #11 Email verification | ROADMAP | **not built** | High priority for hosted |
| #12 Login rate limit | ROADMAP | **not built** | High priority |
| #13 Birth certificate PDF | ROADMAP | already built (`core/pdf.py`) | Verify |
| #14 Chain auto-detect on import | ROADMAP | not built | After phase 1 |
| #15 Signed webhook payloads | ROADMAP | already built (HMAC-SHA-256) | Verify |

**Real outstanding: SSE batch, email verification, login rate limit, encrypted backup, chain auto-detect.**

### Phase 4: Operational maturity (month 2)

- Off-site backup replication (Hydra mirror, daily)
- Monitoring + alerting (Loki + GlitchTip + Grafana)
- Load testing (Locust)
- Penetration test (external)
- SBOM + Sigstore for Docker images
- GDPR data export + delete endpoints for hosted

### Phase 5: Desktop + Mobile (month 3+)

From STRATEGY.md:
- **Tauri desktop app** (offline-capable, bundled backend)
- **PWA / React Native** (mobile wallet generator)

These are separate product surfaces. Defer until v1.2.0 ships.

---

## What we are NOT building

To keep the team focused, we're explicitly saying no to:

1. **Browser-extension wallet.** Too much surface area for security bugs. MetaMask owns this. WP plugin + MCP is enough.
2. **On-chain transaction broadcasting as a feature for self-hosted.** Tx broadcasting requires custody decisions and MEV protection. Pro users get signing only. Hosted gets delegated through Stripe KYC'd accounts.
3. **In-app DEX / swap.** Too many chains, too many MEV risks, too much regulatory exposure. The referral kickback via `plugins/defi.py` is enough.
4. **Multi-sig / threshold sig.** Complex. High error rate. Trezor/Ledger own this.
5. **Hardware wallet integration.** Ledger/Trezor already cover this. We're the software layer on top.

---

## Non-goals (for v1.x)

- ICO / token launch tooling
- NFT minting
- DAO tooling
- Web3 identity (DID / verifiable credentials)
- Decentralized storage integration
- Browser extension

---

## Open architectural questions

Need product-side decisions before we build:

1. **Hosted vs self-hosted split.** Today both share a codebase. Should hosted be a fork?
   - Pro: cleaner boundary, fewer env vars
   - Con: double maintenance burden
   - Recommendation: shared codebase, but `if cfg.hosted:` branches in the right places.

2. **MCP as the only AI surface, or also LangChain/CrewAI/Eliza adapters?**
   - The adapters are stubs today. Either implement or remove.
   - Recommendation: implement only MCP. It's the standard. The others can wrap MCP if needed.

3. **WordPress plugin strategy.**
   - The plugin is GPL by WordPress convention. Backend is MIT.
   - Recommendation: keep plugin separate, MIT-licensed too. Some users fork.

4. **Postgres migration for hosted mode.**
   - SQLite + WAL handles ~100 concurrent users.
   - Beyond that, need Postgres.
   - Recommendation: phase this when we hit 1000 paid users.

5. **Lightweight Postgres-only deployment.**
   - Skip SQLite, always Postgres.
   - Recommendation: out of scope for v1. SQLite is part of the value prop.

---

## Cross-product consistency

WalletPress is one of three Rug Munch Media products. To avoid duplicate implementations:

| Concern | WalletPress | RMI | Pry |
|---------|-------------|-----|-----|
| Multi-tenant user mgmt | `core/hosting.py` | (RMI uses Talos Postgres auth) | (Pry is single-tenant) |
| API key store | `core/auth.py` | (RMI uses HTTP-only sessions) | (Pry uses env) |
| Audit trail | `core/audit.py` (JSONL) | RMI `app/audit/` (Postgres) | (Pry logs to stderr) |
| RPC pool | hardcoded list in `chains.py` | `app/databus/` (52 files) | per-job RPC |
| Provider pattern | `agent/providers.py` (20 AI providers) | `app/scanners/shared.py` | per-job |

**Decision:** Each product owns its own. Sharing via a `rugmunch-common` package is rejected — over-engineering for three products. Copy-paste OK if it keeps the products independent.

---

## See also

- `AUDIT.md` — bugs and fixes (priority-ordered)
- `SECURITY.md` — threat model, auth, crypto rules
- `ADDRESS_GENERATION.md` — per-chain truth table
- `BUILDER.md` — daily workflow for agents
- `WALLETPRESS.md` — single-paragraph product summary