From 6c3cc0c516452577986b0331e1fc850f54850684 Mon Sep 17 00:00:00 2001 From: sneak Date: Fri, 27 Feb 2026 12:07:11 +0700 Subject: [PATCH] Update README Screen Map with all views and state transitions Complete rewrite of the Screen Map section documenting all 17 views: Welcome, Home, AddWallet, ImportKey, AddressDetail, AddressToken, Send, ConfirmTx, WaitTx, SuccessTx, ErrorTx, Receive, TransactionDetail, AddToken, Settings, SiteApproval, TxApproval. Each view documents its elements (with display details like blockies, color dots, etherscan links, formatting) and all state transitions with their destination screens and conditions. --- README.md | 276 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 203 insertions(+), 73 deletions(-) diff --git a/README.md b/README.md index 7486824..0a173f5 100644 --- a/README.md +++ b/README.md @@ -187,140 +187,270 @@ transitions. - **When**: No wallets exist yet. - **Elements**: "AutistMask" heading, brief intro text, "Add wallet" button. - **Transitions**: - - "Add wallet" → pushes **AddWallet** + - "Add wallet" → **AddWallet** #### Home - **When**: At least one wallet exists. This is the root screen. - **Elements**: - - Header: "AutistMask", Settings button - - Total ETH balance across all addresses (large text) - - Total USD value (small text below ETH total, cached 5 min) - - List of wallets, each showing: - - Wallet name (editable — tap to rename) - - "+" button (HD wallets only) to derive next address - - List of addresses under that wallet: - - Address name (editable — tap to rename, default "Address N") - - Full address (untruncated) - - ETH balance + USD value (small text) - - "+ Add wallet" button at the bottom + - Header: "AutistMask", Settings gear button + - Active address ETH balance (large) + USD value (inline parentheses) + - Total USD value across all tokens (small text) + - Active address (color dot, full address, etherscan link, tap to copy) + - Send / Receive quick-action buttons + - ETH/USD price display + - Wallet list: each wallet shows name (tap to rename), "+" button (HD only), + and its addresses with color dots, balances, and `[info]` buttons + - Recent transactions across all addresses (merged, deduplicated, filtered) + - "Add additional wallet..." link at bottom - **Transitions**: - - Tap address → pushes **AddressDetail** - - "+" on wallet → derives address inline (no screen change) - - "+ Add wallet" → pushes **AddWallet** - - Settings → pushes **Settings** + - Tap address row → sets active address (no screen change) + - `[info]` on address → **AddressDetail** + - "Send" → **Send** (selects active address) + - "Receive" → **Receive** (shows active address QR) + - "+" on wallet → derives next address inline + - "Add additional wallet..." → **AddWallet** + - Settings gear → **Settings** (toggles; tap again to return) + - Tap home tx row → **AddressDetail** (for the address involved) #### AddWallet -- **When**: User wants to add a new wallet (from Home or Welcome). +- **When**: User wants to add a new wallet (from Home, Welcome, or Settings). - **Elements**: - - "Add Wallet" heading + - "Add Wallet" heading, "Back" button - Instruction text - - Die button `[die]` (generates random recovery phrase, can be clicked - repeatedly) - - Recovery phrase textarea (empty by default, or filled by die) + - Die button `[die]` (generates random recovery phrase) + - Recovery phrase textarea - Backup warning box (shown after die is clicked) - - "Add" button, "Back" button - - "Have a private key instead?" link → pushes **ImportKey** + - Password + confirm password inputs + - "Add" button + - "Have a private key instead?" link - **Transitions**: - - "Add" (valid phrase) → pops to **Home** - - "Back" → pops to previous (Home or Welcome) - - "Have a private key instead?" → pushes **ImportKey** + - "Add" (valid phrase + password) → **Home** + - "Back" → previous screen (Home or Welcome) + - "Have a private key instead?" → **ImportKey** #### ImportKey - **When**: User wants to import a single private key. - **Elements**: - - "Import Private Key" heading + - "Import Private Key" heading, "Back" button - Instruction text - Private key input (password-masked) - - "Import" button, "Back" button + - Password + confirm password inputs + - "Import" button - **Transitions**: - - "Import" (valid key) → pops to **Home** - - "Back" → pops to previous + - "Import" (valid key + password) → **Home** + - "Back" → **AddWallet** #### AddressDetail -- **When**: User tapped an address from Home. +- **When**: User tapped `[info]` on an address from Home. - **Elements**: - - Header: wallet name, "Back" button - - Address name (editable — tap to rename) - - ENS name (if resolved, shown above address) - - Full address (tap to copy, "Copied!" feedback) - - ETH balance (large) + USD value (small) - - "Send" button, "Receive" button - - Token list with balances - - "+ Add" token button + - "Back" button + - Blockie identicon (48px, centered) + - Title: "Wallet Name — Address N" + - ENS name (if resolved, bold with color dot) + - Full address (color dot, etherscan link, tap to copy) + - USD total for address + - Balance list: ETH + tracked ERC-20 tokens (4 decimal places, USD inline). + Each balance row is clickable → **AddressToken** + - Send / Receive / + Token buttons + - Transaction list (with ENS resolution for counterparties) - **Transitions**: - - "Send" → pushes **Send** - - "Receive" → pushes **Receive** - - "+ Add" → pushes **AddToken** - - "Back" → pops to **Home** + - Tap balance row → **AddressToken** (for that token) + - "Send" → **Send** + - "Receive" → **Receive** + - "+ Token" → **AddToken** + - Tap transaction row → **TransactionDetail** + - "Back" → **Home** + +#### AddressToken + +- **When**: User clicked a specific token balance on AddressDetail. +- **Elements**: + - "Back" button + - Blockie identicon (48px, centered) + - Title: "Wallet Name — Address N — TOKEN" + - Full address (color dot, etherscan link, tap to copy) + - USD total for this token + - Single token balance line (4 decimal places) + - Send / Receive buttons + - Token-filtered transaction list (only this token's transfers) +- **Transitions**: + - "Send" → **Send** (token pre-selected and locked in dropdown) + - "Receive" → **Receive** (ERC-20 warning shown for non-ETH tokens) + - Tap transaction row → **TransactionDetail** + - "Back" → **AddressDetail** #### Send - **When**: User wants to send ETH or a token from this address. - **Elements**: - - "Send" heading - - Token selector (ETH + any added tokens) - - "To" input (accepts address or ENS name, resolves before sending) - - Amount input - - Fee estimate (shown after entering amount) - - "Send" button, "Cancel" button - - Status area (resolving ENS, confirming, errors) + - "Send" heading, "Back" button + - From: address with color dot + etherscan link + - What to send: token dropdown (or static display with contract address when + locked from AddressToken) + - To: address or ENS name input + - Amount input with current balance display + - "Review" button - **Transitions**: - - "Send" (valid) → prompts for password (to decrypt private key), submits - transaction, shows result, stays on screen - - "Cancel" → pops to **AddressDetail** + - "Review" (valid inputs, ENS resolved) → **ConfirmTx** + - "Back" → **AddressToken** (if came from token view) or **AddressDetail** + +#### ConfirmTx + +- **When**: User reviewed send details and is ready to authorize. +- **Elements**: + - "Confirm Transaction" heading, "Back" button + - Type: "Native ETH transfer" or "ERC-20 token transfer (SYMBOL)" + - Token contract: full address + etherscan link (ERC-20 only) + - From: blockie + color dot + full address + etherscan link + wallet title + - To: blockie + color dot + full address + etherscan link + ENS name + - Amount: value + symbol (USD in parentheses) + - Your balance: value + symbol (USD in parentheses) + - Estimated network fee: ETH amount (USD in parentheses), fetched async + - Warnings (scam address, self-send) + - Errors (insufficient balance) + - "Send" button (disabled if errors) +- **Transitions**: + - "Send" → password modal → broadcast tx → **WaitTx** + - "Send" → password modal → broadcast fails → **ErrorTx** + - "Back" → **Send** + +#### WaitTx + +- **When**: Transaction has been broadcast, waiting for on-chain confirmation. +- **Elements**: + - "Transaction Broadcast" heading (no back button — tx is irreversible) + - Amount + symbol + - To: color dot + full address + etherscan link + - Transaction hash: full hash (tap to copy) + etherscan link + - Count-up timer: "Waiting for confirmation... Ns" +- **Behavior**: Polls `getTransactionReceipt` every 10 seconds. +- **Transitions**: + - Receipt found → **SuccessTx** + - 60 seconds without confirmation → **ErrorTx** (timeout message) + +#### SuccessTx + +- **When**: Transaction confirmed on-chain. +- **Elements**: + - "Transaction Confirmed" heading + - Amount + symbol + - To: color dot + full address + etherscan link + - Block number + - Transaction hash: full hash (tap to copy) + etherscan link + - "Done" button +- **Transitions**: + - "Done" → **AddressToken** (if `selectedToken` set) or **AddressDetail** + +#### ErrorTx + +- **When**: Transaction broadcast failed, or timed out waiting for confirmation. +- **Elements**: + - "Transaction Failed" heading + - Amount + symbol + - To: color dot + full address + etherscan link + - Error message (dashed border box) + - Transaction hash section (hidden if broadcast failed before getting hash): + full hash (tap to copy) + etherscan link + - "Done" button +- **Transitions**: + - "Done" → **AddressToken** (if `selectedToken` set) or **AddressDetail** #### Receive - **When**: User wants to receive funds at this address. - **Elements**: - - "Receive" heading + - "Receive" heading, "Back" button - Instruction text - QR code encoding the address - - Full address (displayed, selectable) + - Full address (color dot, selectable, etherscan link) - "Copy address" button - - "Back" button + - ERC-20 warning (shown when navigating from AddressToken for non-ETH token) - **Transitions**: - - "Back" → pops to **AddressDetail** + - "Back" → **AddressToken** (if `selectedToken` set) or **AddressDetail** + +#### TransactionDetail + +- **When**: User tapped a transaction row from AddressDetail or AddressToken. +- **Elements**: + - "Transaction" heading, "Back" button + - Status: "Success" or "Failed" + - Time: ISO datetime + relative age in parentheses + - Amount: value + symbol (bold) + - From: blockie + color dot + full address (tap to copy) + etherscan link + - ENS name if available + - To: blockie + color dot + full address (tap to copy) + etherscan link + - ENS name if available + - Transaction hash: full hash (tap to copy) + etherscan link +- **Transitions**: + - "Back" → **AddressToken** (if `selectedToken` set) or **AddressDetail** #### AddToken - **When**: User wants to track an ERC-20 token on this address. - **Elements**: - - "Add Token" heading + - "Add Token" heading, "Back" button - Instruction text (find contract address on Etherscan) - Contract address input - Token info preview (name, symbol — fetched from contract) - - "Add" button, "Cancel" button + - Common token quick-pick buttons + - "Add" button - **Transitions**: - - "Add" (valid contract) → pops to **AddressDetail** - - "Cancel" → pops to **AddressDetail** + - "Add" (valid contract) → **AddressDetail** + - "Back" → **AddressDetail** #### Settings -- **When**: User tapped Settings from Home. +- **When**: User tapped Settings gear from Home. - **Elements**: - - "Settings" heading - - Network section: RPC endpoint URL input, "Save" button, explanatory text - - "Back" button + - "Settings" heading, "Back" button + - Wallets: "+ Add wallet" button + - Display: "Show tracked tokens with zero balance" checkbox + - Ethereum RPC: endpoint URL input + "Save" button + - Blockscout API: endpoint URL input + "Save" button + - Token Spam Protection: + - "Hide tokens with fewer than 1,000 holders" checkbox + - "Hide transactions from detected fraud contracts" checkbox + - "Hide dust transactions below N gwei" checkbox + threshold input + - Allowed Sites: list with remove buttons + - Denied Sites: list with remove buttons - **Transitions**: - - "Back" → pops to **Home** + - "+ Add wallet" → **AddWallet** + - "Back" (or Settings gear again) → **Home** -#### Approval (future) +#### SiteApproval -- **When**: A connected website requests wallet access or a transaction - signature. Opened by the background script, not by user navigation. +- **When**: A website requests wallet access via `eth_requestAccounts`. Opened + in a separate popup by the background script. - **Elements**: - - "A website is requesting access" heading - - Site origin (bold) - - Request type and details (preformatted) - - "Allow" button, "Deny" button + - "Connection Request" heading + - Site hostname (bold) + - Address that will be shared (color dot + full address + etherscan link) + - "Remember my choice for this site" checkbox + - "Allow" / "Deny" buttons - **Transitions**: - "Allow" / "Deny" → closes popup (returns result to background script) +#### TxApproval + +- **When**: A connected website requests a transaction via + `eth_sendTransaction`. Opened in a separate popup by the background script. +- **Elements**: + - "Transaction Request" heading + - Site hostname (bold) + "wants to send a transaction" + - From: color dot + full address + etherscan link + - To: color dot + full address + etherscan link (or "contract creation") + - Value: amount in ETH (4 decimal places) + - Data: raw transaction data (shown if present) + - Password input + - "Confirm" / "Reject" buttons +- **Transitions**: + - "Confirm" (with password) → closes popup (returns result to background) + - "Reject" → closes popup (returns rejection to background) + ### External Services AutistMask is not a fully self-contained offline tool. It necessarily