Update README Screen Map with all views and state transitions
All checks were successful
check / check (push) Successful in 17s

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.
This commit is contained in:
Jeffrey Paul 2026-02-27 12:07:11 +07:00
parent d229000258
commit 6c3cc0c516

276
README.md
View File

@ -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