diff --git a/README.md b/README.md index ec81126..fac0082 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ Free control-plane application for EDUT onboarding and entitlement-aware install 4. Signed package download and verification orchestrator. 5. Member app-channel inbox. +Primary v1 wallet behavior and acceptance criteria are specified in: + +- `docs/wallet-v1-product-spec.md` + ## Out of Scope 1. Governance runtime internals. diff --git a/docs/conformance-vectors.md b/docs/conformance-vectors.md index 67fbde1..02791d8 100644 --- a/docs/conformance-vectors.md +++ b/docs/conformance-vectors.md @@ -7,3 +7,6 @@ 5. `L-005` Expired install token blocks install. 6. `L-006` Distinct payer wallet without ownership proof blocks quote request. 7. `L-007` Event inbox polling works when push unavailable. +8. `L-008` Wallet onboarding creates local wallet without forcing seed phrase display. +9. `L-009` Outgoing sends require biometric/PIN confirmation. +10. `L-010` Primary wallet screens render USD-first balances and plain-language history. diff --git a/docs/release-gate.md b/docs/release-gate.md index 99edd2e..cb83b74 100644 --- a/docs/release-gate.md +++ b/docs/release-gate.md @@ -6,9 +6,11 @@ 2. Package verification pass/fail tests pass. 3. Governance install path fails closed on invalid evidence. 4. Marketplace and status APIs are called with app-session auth. +5. Wallet v1 acceptance criteria pass (`docs/wallet-v1-product-spec.md`). ## Blockers 1. Any path that installs unsigned package. 2. Any path that leaks private key material. 3. Any path that bypasses entitlement checks for governance activation. +4. Any launch flow that exposes seed phrase by default. diff --git a/docs/wallet-bootstrap-flow.md b/docs/wallet-bootstrap-flow.md index acf016e..667334b 100644 --- a/docs/wallet-bootstrap-flow.md +++ b/docs/wallet-bootstrap-flow.md @@ -1,5 +1,9 @@ # Wallet Bootstrap Flow (Launcher) +This document is a narrow bootstrap subset. Full wallet behavior is defined in: + +- `docs/wallet-v1-product-spec.md` + ## Objective Create or import an ownership wallet locally before paid actions. diff --git a/docs/wallet-v1-product-spec.md b/docs/wallet-v1-product-spec.md new file mode 100644 index 0000000..39f46d3 --- /dev/null +++ b/docs/wallet-v1-product-spec.md @@ -0,0 +1,164 @@ +# EDUT Wallet v1 Product Spec + +## Product Contract + +The launcher wallet is a real, user-owned wallet from day one. It is not a hidden license container. + +At launch, the wallet is the primary interface for: + +1. Identity and ownership +2. Funding +3. EDUT purchases +4. Person-to-person sends +5. Plain-language transaction visibility + +## Launch Scope + +### In scope + +1. Automatic wallet creation during onboarding +2. USD-first balance display +3. Add money via embedded on-ramp (card / Apple Pay / Google Pay when provider supports it) +4. Receive from another wallet (QR + copy address) +5. Buy EDUT products from wallet balance +6. Auto-open on-ramp for checkout shortfall +7. Send funds to any address (QR scan or paste) +8. Biometric/PIN confirmation for all spend/send actions +9. Plain-language transaction history +10. Recovery path available but not forced + +### Out of scope (post-launch) + +1. Off-ramp to fiat +2. Multi-token portfolio management beyond USDC + ETH +3. DeFi integrations + +## UX Language Contract + +Never show crypto jargon by default. + +1. Show: `Add money`, `Receive`, `Pay someone`, `Balance` +2. Hide by default: gas, wei, long hex fields, tx hashes, block explorers +3. Reveal technical details only behind explicit `View details` + +## Core Flows + +## 1) First Launch Onboarding + +1. User installs and opens launcher. +2. Wallet is created automatically on device. +3. User sees: `Your wallet is ready`. +4. User is not shown seed phrase unless they explicitly open recovery settings. +5. Balance card is visible immediately in USD (`$0.00` initial state). + +### Rules + +1. Private key material never leaves device. +2. Key storage uses secure OS keystore where available. +3. If secure keystore is unavailable, launcher requires local passcode and stores encrypted key locally. + +## 2) Add Money + +1. User taps `Add money`. +2. Embedded on-ramp opens. +3. User selects amount and payment method. +4. On-ramp delivers funds to EDUT wallet address. +5. Balance updates in USD when chain confirms. + +### Rules + +1. On-ramp session is initiated from launcher context. +2. On-ramp failures return user to wallet with actionable error state. +3. No fiat custody by EDUT backend. + +## 3) Receive From Another Wallet + +1. User taps `Receive`. +2. Launcher shows QR code and copy-address action. +3. Label shown to user: `Receive from another wallet`. +4. Incoming transfer appears in history and updates USD balance. + +## 4) Buy EDUT Product + +1. User selects product in store. +2. Checkout shows USD amount and available wallet balance. +3. If balance is sufficient, complete purchase from wallet. +4. If insufficient, launcher opens on-ramp for difference. +5. After funding, checkout resumes and completes. + +### Rules + +1. No hidden split charges. +2. User always sees final USD amount before confirmation. +3. Membership and entitlement purchases write deterministic receipts. + +## 5) Pay Someone + +1. User taps `Pay someone`. +2. User scans QR or pastes address. +3. User enters USD amount. +4. Confirmation screen shows: + 1. USD amount + 2. Destination summary (`0x...abcd` short form) + 3. Clear `Confirm payment` action +5. Biometric/PIN confirmation required before send. + +## 6) Transaction History + +History is plain-language first. + +Examples: + +1. `Added $100` +2. `Bought Human Membership` +3. `Sent $50 to 0x12ab...90ef` +4. `Received $200 from 0x98cd...11aa` + +Technical details are available only in expanded view: + +1. Full wallet addresses +2. Tx hash +3. Raw asset amounts + +## Security Requirements + +1. Biometric or PIN required for every outgoing transaction. +2. Device-local key ownership is mandatory. +3. Recovery path must exist but remain opt-in in onboarding. +4. Sensitive operations fail closed on secure storage errors. +5. Wallet export (seed/private key) requires explicit authenticated flow. + +## Asset/Display Model + +Launch-supported assets: + +1. USDC (primary purchasing balance) +2. ETH (network fee balance) + +Display rules: + +1. Primary balance shown in USD. +2. Token-level balances available in details view. +3. Checkout amounts shown in USD first, then token equivalent if expanded. + +## Integration Requirements (Execution) + +Launcher implementation must support: + +1. Embedded on-ramp provider integration +2. Wallet funding address retrieval for receive flow +3. Store checkout integration with backend quote/confirm APIs +4. Deterministic local transaction journal rendering +5. Price conversion for USD display (USDC fixed, ETH converted via trusted feed) + +## Acceptance Criteria + +1. Fresh install reaches usable wallet state without manual key setup. +2. User can add funds and see updated USD balance. +3. User can copy/QR receive address and receive funds. +4. User can buy EDUT product from wallet balance. +5. Insufficient-balance checkout opens on-ramp and resumes. +6. User can send funds with biometric/PIN confirmation. +7. History entries are human-readable and accurate. +8. No crypto jargon appears in primary flow screens. +9. Off-ramp and non-USDC/ETH asset management are absent from v1 UI.