From 75cbbea03556745cba7c5621a37132c16e724de2 Mon Sep 17 00:00:00 2001 From: sneak Date: Fri, 27 Feb 2026 12:08:43 +0700 Subject: [PATCH] Add user-facing documentation in docs/README.md Covers rationale, hard guidelines (always/never), external service details (RPC, Blockscout, CoinDesk APIs with what data is sent), encryption model, installation, wallet management, sending/receiving, web3 site connections, scam protection, settings, and FAQ. Written for a technical cryptocurrency user who is not a programmer. --- docs/README.md | 331 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 331 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..3476a73 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,331 @@ +# AutistMask User Guide + +AutistMask is a minimal Ethereum wallet browser extension for Chrome and +Firefox. It manages recovery phrases and private keys, sends and receives ETH +and ERC-20 tokens, and connects to web3 sites. Nothing else. + +## Why AutistMask Exists + +MetaMask has become bloated with swap UIs, portfolio dashboards, analytics, +tracking, and advertisements. It is no longer a simple wallet. Most alternatives +(Rabby, Rainbow, etc.) only support Chromium browsers, leaving Firefox users +without a usable option. + +AutistMask exists because a wallet should be a wallet. You should be able to see +your balances, send tokens, receive tokens, and connect to sites. That is all a +wallet needs to do. If you want to swap tokens, use a DEX. If you want portfolio +analytics, use a portfolio tracker. The wallet is not the place for any of that. + +## Hard Guidelines + +### What AutistMask Will Always Do + +- **Show full addresses and transaction hashes.** Never truncated, never + abbreviated. Address poisoning attacks exploit truncated displays. If you see + an address in AutistMask, you see the whole thing. The only exception is + compact transaction list rows, where the full address is always one tap away. + +- **Encrypt your recovery phrase and private keys at rest.** Your secrets are + encrypted on disk using Argon2id key derivation and XSalsa20-Poly1305 + authenticated encryption (via libsodium). Your password is required only when + signing a transaction. Viewing balances and addresses never requires a + password. + +- **Let you choose your own RPC endpoint.** The default is a public Ethereum + RPC, but you can point it at your own node or any provider you trust. No + Infura or Alchemy lock-in. + +- **Filter scam transactions by default.** Fake token transfers, dust poisoning, + and look-alike addresses are filtered automatically. Every filter can be + turned off individually if you prefer to see everything. + +- **Work on both Chrome and Firefox.** Same codebase, same features, both + browsers. + +### What AutistMask Will Never Do + +- **No analytics, telemetry, or tracking.** Zero data about your usage is + collected or transmitted. No crash reports, no usage metrics, no user + identifiers. + +- **No advertisements or promotions.** No banners, no "try our new feature" + popups, no partner integrations. + +- **No swap UI.** Use Uniswap, 1inch, or whatever DEX you prefer in your + browser. The wallet is not a trading terminal. + +- **No NFT galleries or portfolio views.** This is a wallet, not a dashboard. + +- **No token auto-discovery.** AutistMask does not scan the blockchain for + tokens you might hold. You add tokens manually by contract address. This + prevents scam tokens from appearing in your wallet uninvited. + +- **No phishing blocklists from third parties.** AutistMask does not phone home + to check URLs against a remote blocklist. It does maintain a local list of + known scam addresses, but this is shipped with the extension, not fetched from + a server. + +## How It Works + +AutistMask is a browser extension that runs entirely in your browser. It does +not have a backend server. It communicates with three external services: + +### External Services + +**Ethereum JSON-RPC endpoint** (default: `ethereum-rpc.publicnode.com`) + +This is how AutistMask talks to the Ethereum network. Every wallet needs an +Ethereum node to check balances, estimate gas, broadcast transactions, and +verify confirmations. The default is a free public RPC endpoint. You can change +this in Settings to any Ethereum JSON-RPC endpoint, including your own local +node. + +What gets sent: standard Ethereum JSON-RPC requests (balance queries, +transaction broadcasts, gas estimates, ENS lookups). Your addresses are +necessarily visible to the RPC provider when querying balances. + +**Blockscout API** (default: `eth.blockscout.com/api/v2`) + +Used to fetch token balances and transaction history. Blockscout is an +open-source blockchain explorer. AutistMask queries it for your ERC-20 token +balances and recent transactions. You can change this in Settings to a +self-hosted Blockscout instance. + +What gets sent: your Ethereum addresses (to look up balances and transactions). + +**CoinDesk CADLI price API** (`data-api.coindesk.com`) + +Used to fetch current USD prices for ETH and ERC-20 tokens. Prices are cached +for 5 minutes. No API key is required. No user data is sent -- only a list of +token symbols (e.g. "ETH", "USDC") to get their prices. + +What gets sent: token symbol names. No addresses, no balances, no identifying +information. + +### What Stays Local + +- Your recovery phrases and private keys (encrypted with your password) +- Your wallet configuration (which wallets, which addresses, which tokens) +- Your site permissions (which sites you have allowed or denied) +- Your spam filter settings and detected fraud contract list + +None of this data leaves your browser. + +### Encryption + +When you create or import a wallet, you choose a password. This password is used +to encrypt your recovery phrase (or private key) on disk. The encryption uses +Argon2id for key derivation (memory-hard, resistant to GPU brute-force) and +XSalsa20-Poly1305 for authenticated encryption (tamper-proof). + +Your password is **not** part of your recovery phrase. Anyone with your 12 or 24 +word recovery phrase can restore your wallet on any device without your +password. The password only protects the copy stored in this browser. If you +lose your recovery phrase, your password cannot help you recover it. + +Your password is only requested when you send a transaction. Viewing balances, +receiving funds, and browsing transaction history never require your password. + +## Installation + +### Chrome + +1. Download or build the extension (the `dist/chrome/` directory). +2. Navigate to `chrome://extensions/`. +3. Enable "Developer mode" (toggle in the top right). +4. Click "Load unpacked" and select the `dist/chrome/` directory. + +### Firefox + +1. Download or build the extension (the `dist/firefox/` directory). +2. Navigate to `about:debugging#/runtime/this-firefox`. +3. Click "Load Temporary Add-on". +4. Select `dist/firefox/manifest.json`. + +## Getting Started + +### Creating a New Wallet + +1. Click the AutistMask icon in your browser toolbar. +2. Click "Add wallet". +3. Click the die button to generate a random 12-word recovery phrase. +4. **Write down the recovery phrase and store it safely.** Anyone with these + words can take your funds. If you lose them, your wallet is gone. AutistMask + cannot recover them for you. +5. Choose a password. This encrypts your recovery phrase on this device. +6. Click "Add". + +### Importing an Existing Wallet + +**From a recovery phrase:** Follow the same steps as creating a wallet, but +paste your existing 12 or 24 word recovery phrase instead of generating a new +one. AutistMask uses the same derivation path as MetaMask (`m/44'/60'/0'/0`), so +your addresses will match. + +**From a private key:** On the Add Wallet screen, click "Have a private key +instead?" and paste your private key. This creates a single-address wallet. + +### Adding More Addresses + +HD wallets (created from a recovery phrase) can derive multiple addresses. On +the home screen, click the "+" button next to a wallet name to add the next +address. These are deterministic -- the same recovery phrase will always produce +the same sequence of addresses. + +### Adding ERC-20 Tokens + +AutistMask does not auto-discover tokens. To track a token: + +1. Go to an address detail view (click `[info]` on any address). +2. Click "+ Token". +3. Enter the token's contract address (find this on Etherscan or the token's + website), or pick from the list of common tokens. +4. Click "Add". + +The token balance will appear on the address detail screen and on the home +screen. + +## Sending + +1. Click "Send" from the home screen or an address detail view. +2. Select what to send (ETH or any tracked ERC-20 token). +3. Enter the recipient address or ENS name (e.g. `vitalik.eth`). +4. Enter the amount. +5. Click "Review" to see the confirmation screen. + +The confirmation screen shows: + +- **Transaction type** (native ETH transfer or ERC-20 token transfer) +- **Token contract address** with Etherscan link (for ERC-20 tokens) +- **From and To addresses** with identicons and Etherscan links +- **Amount** with USD estimate +- **Your current balance** with USD estimate +- **Estimated network fee** in ETH with USD estimate + +After reviewing, click "Send" and enter your password. The transaction will be +broadcast to the network and you will see a waiting screen with a timer. Once +confirmed (or after 60 seconds), you will see either a success or error screen +with the transaction hash and an Etherscan link. + +### Sending a Specific Token + +You can also send from a token-specific view: on the address detail screen, +click any token balance row. This opens a focused view showing only that token's +transactions. Clicking "Send" from here pre-selects and locks the token so you +cannot accidentally switch to a different one. + +## Receiving + +1. Click "Receive" from the home screen or an address detail view. +2. Share the QR code or copy the address using the "Copy address" button. + +When receiving ERC-20 tokens, make sure the sender is sending on the Ethereum +network. AutistMask is an Ethereum mainnet wallet. Tokens sent on other networks +(Polygon, Arbitrum, BSC, etc.) to the same address will not appear and may be +permanently lost. + +## Connecting to Web3 Sites + +AutistMask injects a standard `window.ethereum` provider (EIP-1193) into web +pages. When a site requests access to your wallet: + +1. A popup appears showing the site's hostname and the address that will be + shared. +2. Click "Allow" to connect or "Deny" to reject. +3. Optionally check "Remember my choice for this site" to skip the prompt next + time. + +When a connected site requests a transaction, a separate approval popup appears +showing the transaction details (from, to, value, data). You must enter your +password and click "Confirm" to authorize it. + +You can manage site permissions in Settings. Allowed and denied sites can be +individually removed to reset their permissions. + +## Scam Protection + +AutistMask includes several defenses against common Ethereum scams, all enabled +by default: + +**Known token symbol verification.** AutistMask ships a list of ~250 legitimate +ERC-20 tokens with their contract addresses. If a transaction claims to involve +a known symbol (like "ETH" or "USDT") but comes from an unrecognized contract, +it is identified as a spoof and hidden. + +**Low-holder token filtering.** Tokens with fewer than 1,000 holders are hidden +from transaction history and the send token list. Legitimate tokens have +substantial holder counts; scam tokens deployed for address poisoning typically +have zero. + +**Fraud contract blocklist.** When AutistMask detects a fraudulent transfer, it +adds the contract address to a local blocklist. Future transactions from that +contract are hidden. This list persists across sessions. + +**Dust transaction filtering.** Tiny ETH transfers (below 100,000 gwei / 0.0001 +ETH by default) are hidden. Scammers send dust from look-alike addresses to +plant them in your transaction history. The threshold is configurable in +Settings. + +All of these filters can be individually disabled in Settings if you prefer to +see everything unfiltered. + +## Settings + +Click the gear icon on the home screen to access settings: + +- **Wallets**: Add a new wallet. +- **Display**: Toggle whether tracked tokens with zero balance are shown. +- **Ethereum RPC**: Change the Ethereum node endpoint. Default is a public RPC. + You can use your own node for maximum privacy. +- **Blockscout API**: Change the Blockscout instance used for token balances and + transaction history. You can use a self-hosted instance. +- **Token Spam Protection**: Toggle individual scam filters and set the dust + transaction threshold. +- **Allowed Sites / Denied Sites**: View and manage web3 site permissions. + +## Frequently Asked Questions + +**Is AutistMask compatible with MetaMask?** + +Yes. AutistMask uses the same derivation path (`m/44'/60'/0'/0`) as MetaMask. If +you import the same recovery phrase, you will get the same addresses. You can +use both wallets side by side, though only one can be the active +`window.ethereum` provider at a time. + +**Can I use AutistMask with a hardware wallet?** + +Not yet. Hardware wallet support may be added in the future. + +**Does AutistMask support networks other than Ethereum mainnet?** + +Not currently. AutistMask is Ethereum mainnet only. Multi-chain support may be +added in the future. + +**Where is my data stored?** + +In your browser's extension local storage. Your recovery phrases and private +keys are encrypted. Your addresses, balances, and settings are stored +unencrypted (so you can view them without entering a password). Nothing is sent +to any server operated by AutistMask. + +**What happens if I uninstall the extension?** + +Your data is deleted. Make sure you have your recovery phrase backed up before +uninstalling. With your recovery phrase, you can restore your wallet in +AutistMask or any other compatible wallet (MetaMask, etc.) at any time. + +**What happens if a transaction times out?** + +If AutistMask does not see a confirmation within 60 seconds, it shows an error +screen. This does not mean the transaction failed -- it may still confirm. The +error screen includes an Etherscan link so you can check the transaction status +directly. Network congestion or low gas prices can delay confirmation beyond 60 +seconds. + +## License + +GPL-3.0. See [LICENSE](../LICENSE). + +## Author + +[@sneak](https://sneak.berlin)