# CLAUDE.md — Zyquo Wallet

# Project Overview

Zyquo Wallet is a native macOS self-custody stablecoin wallet built in Swift + SwiftUI. It manages real on-chain USDC on Base (Ethereum L2 by Coinbase — chosen for sub-cent gas fees and native Circle-issued USDC).

This is NOT a mock/demo app. Every feature must work against a real blockchain:

1. Real HD wallet creation (BIP-39 mnemonic → secp256k1 keys)
2. Receive USDC (real address + QR code)
3. Send USDC (real signed ERC-20 transfers broadcast via JSON-RPC)

Development rule: build and test everything on Base Sepolia testnet first. Mainnet support is enabled last, behind an explicit network switch.

# Tech Stack

If web3swift causes build issues on macOS, fallback is argentlabs/web3.swift. Never mix both.

# Network Configuration (source of truth)

enum Network {
    case baseSepolia   // DEFAULT during development
    case baseMainnet
}

• USDC has 6 decimals. Always convert with BigUInt / decimal math — never Double. 1 USDC = 1_000_000 base units.
• Public RPCs are fine for dev. For production, make the RPC URL configurable (Alchemy/QuickNode) via Settings — but never require an API key to run the app.
• Gas is paid in ETH, not USDC. The UI must clearly warn when the ETH balance is too low to send.

# Architecture

MVVM + service layer. Keep views dumb; all blockchain logic lives in services.

ZyquoWallet/
├── App/                 ZyquoWalletApp.swift, AppState (ObservableObject / @Observable)
├── Models/              Wallet, Transaction, Network, TokenAmount
├── Services/
│   ├── KeyManager.swift        // mnemonic gen/import, keystore, Keychain I/O
│   ├── WalletService.swift     // address derivation, wallet lifecycle
│   ├── RPCService.swift        // web3 provider, network switching
│   ├── BalanceService.swift    // ETH + USDC balances, polling every 15s
│   └── TransactionService.swift// build, estimate gas, sign, send, track receipt
├── ViewModels/          OnboardingVM, HomeVM, SendVM, ReceiveVM, SettingsVM
├── Views/
│   ├── Onboarding/      Welcome, CreateWallet (show + verify mnemonic), ImportWallet
│   ├── Home/            Balance card, tx list, Send/Receive buttons
│   ├── Send/            recipient + amount + gas preview + confirm sheet
│   ├── Receive/         address display, QR, copy button
│   └── Settings/        network switch, RPC override, export seed (auth-gated), reset
└── Utils/               formatting, address validation (EIP-55), errors

• Use async/await everywhere; wrap web3swift callbacks if needed.
• One AppState injected via .environment; services are protocol-backed for testability.
• Every service method that touches the network returns typed errors (WalletError enum), never fatalError.

# Security Requirements (non-negotiable)

1. Mnemonic & private key never leave the device. No analytics, no telemetry, no network calls except JSON-RPC and explorer API.
2. Store the mnemonic (or derived keystore) in Keychain with kSecAttrAccessibleWhenUnlockedThisDeviceOnly. Never in UserDefaults, files, or iCloud.
3. Gate seed export and every send behind LocalAuthentication (Touch ID / password).
4. Never log mnemonics, private keys, or signatures. Never put them in error messages.
5. Never hardcode keys, mnemonics, or API keys anywhere in the repo — including tests. Test wallets are generated at runtime.
6. Onboarding must force a mnemonic backup verification step (user re-enters 3 random words) before showing the wallet.
7. Validate recipient addresses: hex format + EIP-55 checksum. Warn (don't block) on all-lowercase addresses.
8. Enable App Sandbox (with network client entitlement) and Hardened Runtime.
9. Confirm screen before send must show: recipient, amount, network, estimated gas, and total — no one-tap sends.
10. If the clipboard is used for addresses, never auto-paste into the recipient field without user action (clipboard-hijack protection).

# Feature Phases (implement in order, each must compile + pass tests)

# Phase 1 — Wallet core

• Generate 12-word BIP-39 mnemonic, derive account at m/44'/60'/0'/0/0
• Import from mnemonic
• Persist via KeyManager/Keychain; app relaunch restores wallet
• Onboarding flow with backup verification

# Phase 2 — Receive

• Show checksummed address, copy button, QR code (address only, no ethereum: URI needed for v1)

# Phase 3 — Balances

• ETH balance (eth_getBalance) + USDC balance (balanceOf(address))
• Poll every 15s while app is active; manual refresh; loading/error states

# Phase 4 — Send USDC

• ERC-20 transfer(to, amount) with EIP-1559 fees
• Gas estimation shown in ETH + rough USD
• Sign locally, broadcast, then poll eth_getTransactionReceipt until confirmed
• Pending/confirmed/failed states surfaced in UI, link to BaseScan

# Phase 5 — History & polish

• Transaction list from BaseScan API (USDC transfers in/out) with graceful fallback if API unavailable
• Network switcher (Sepolia ⇄ Mainnet) with a prominent "TESTNET" badge on Sepolia
• Settings: custom RPC, export seed (auth-gated), delete wallet (typed confirmation)

# Build & Test Commands

# Build
xcodebuild -scheme ZyquoWallet -destination 'platform=macOS' build

# Tests
xcodebuild -scheme ZyquoWallet -destination 'platform=macOS' test

• Unit-test: mnemonic → address derivation (against known BIP-39 test vectors), USDC decimal conversion, address validation, amount formatting.
• Never write tests that send real mainnet funds. Network-dependent tests run against Base Sepolia and must be skippable offline.

# Manual test checklist (Base Sepolia)

1. Create wallet → relaunch app → same address restored
2. Fund via Circle faucet (USDC) + Base faucet (ETH for gas)
3. Balance appears within one polling cycle
4. Send 1 USDC to a second test wallet → confirm on sepolia.basescan.org
5. Import that second wallet from mnemonic → balance matches

# Conventions & Pitfalls

• All amounts are BigUInt in base units internally; convert to display strings only at the UI edge.
• USDC = 6 decimals, ETH = 18 decimals. Mixing these up is the #1 bug source.
• Chain ID must match the selected network in every signed transaction (replay protection).
• Handle RPC failures with retry + user-visible error; the app must never crash on network errors.
• Comments and UI strings in English; French localization can come later via String Catalog.
• Small, focused commits per phase. Do not start a later phase before the earlier one builds and passes tests.