diff --git a/docs/README.md b/docs/README.md index 9d8465f..d119481 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,496 +1,652 @@ # 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. +AutistMask is an Ethereum wallet. It runs as a browser extension in Chrome and +Firefox. This guide explains how to install it and how to use it. -## Why AutistMask Exists +## What it does -The most popular browser-based EVM wallet has become bloated with swap UIs, -portfolio dashboards, analytics, tracking, and advertisements. It is no longer a -simple wallet. The common alternatives only support Chromium browsers, leaving -Firefox users without a usable option. +- It keeps your wallets. A wallet comes from a recovery phrase, a private key or + an extended private key. +- It shows the ETH and ERC-20 token balances of your addresses. ETH is the + currency of Ethereum. An ERC-20 token is a token issued by a contract on + Ethereum. +- It sends and receives ETH and ERC-20 tokens. +- It connects to web3 sites and signs what you approve. A web3 site is a website + that asks a wallet to sign for it. -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. +It does nothing else. It has: -## Hard Guidelines +- no swap screen; +- no portfolio view; +- no NFT gallery; +- no advertising; +- no tracking. -### What AutistMask Will Always Do +## What it sends, and to whom -- **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. +The wallet runs in your browser. The developer runs no server. -- **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 whenever a - secret has to be decrypted: signing a transaction, signing a message or typed - data, exporting a private key, and deleting a wallet. Viewing balances and - addresses never requires a password. +By default the wallet talks to one service: the Ethereum RPC endpoint. The RPC +endpoint is the server that the wallet asks about the blockchain and sends your +transactions through. A new install uses a public one, +`https://ethereum-rpc.publicnode.com`. You can change it in Settings. -- **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. +The RPC endpoint sees every address that the wallet asks about and every +transaction that the wallet sends. If you want privacy, point the Ethereum RPC +setting at a node of your own. -- **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. +On Ethereum Mainnet the wallet reads USD prices through the RPC endpoint, from +Chainlink price feed contracts. No price service is contacted. -- **Work on both Chrome and Firefox.** Same codebase, same features, both - browsers. +Two more services get your data only after you turn on a setting. Both are off +in a new install. The first screen and Settings both offer them. -### What AutistMask Will Never Do +- "Use Blockscout". Blockscout is an open-source block explorer, a service that + indexes the blockchain. With the setting on, the wallet sends your addresses, + and the hash of each transaction you open, to the Blockscout server set in + Settings. In return the wallet shows your transaction history, transaction + details and the tokens you have not tracked. You can point the setting at a + Blockscout server of your own. +- "Check recipients on Etherscan". Etherscan is a block explorer website. With + the setting on, the wallet fetches the recipient's Etherscan page each time + you review a send. It warns when Etherscan labels the address as phishing, + scam or exploiter. Only the recipient's address is sent. The Etherscan server + cannot be changed. -- **No analytics, telemetry, or tracking.** Zero data about your usage is - collected or transmitted. No crash reports, no usage metrics, no user - identifiers. +The wallet checks each site that asks to connect, to send or to sign against a +phishing list built into the extension. That check sends nothing anywhere. -- **No advertisements or promotions.** No banners, no "try our new feature" - popups, no partner integrations. +These stay in your browser and never leave it: -- **No swap UI.** Use Uniswap, 1inch, or whatever DEX you prefer in your - browser. The wallet is not a trading terminal. +- your recovery phrases, private keys and extended private keys, encrypted with + your password; +- which wallets, addresses and tokens you have; +- which sites you have allowed or denied; +- the spam filter settings and the list of fraud contracts that the wallet has + seen. -- **No NFT galleries or portfolio views.** This is a wallet, not a dashboard. +The Etherscan links on the screens are ordinary links. They contact nothing +until you click them. -- **No third-party token list APIs.** The balances of the tokens you track are - read from your RPC endpoint. While "Use Blockscout" is on, the other tokens - come from the same block explorer you configure for transaction history. The - extension ships its own hardcoded list of top ERC-20 contract addresses for - symbol-spoofing detection. Any token you want tracked across all your - addresses, you add yourself by contract address. +## Installing -- **No backend servers operated by the developer.** Nothing is sent to any - server run by AutistMask. Every network destination is listed below. +AutistMask is built from source. [`../README.md`](../README.md) says how: +`make setup` and then `make build` write the extension into `dist/chrome/` and +`dist/firefox/`. -## How It Works +Chrome: -AutistMask is a browser extension that runs entirely in your browser. It does -not have a backend server. Out of the box it contacts only the Ethereum RPC -endpoint. USD prices are read from Chainlink price feed contracts through that -endpoint. +1. Open `chrome://extensions/`. +2. Turn on "Developer mode". +3. Click "Load unpacked" and pick `dist/chrome/`. -Blockscout and Etherscan are sent none of your data until you turn on a setting -for each. The settings are "Use Blockscout" and "Check recipients on Etherscan". -Both are off in a new install. Welcome and Settings both offer them. +Firefox, version 115 or newer: -### External Services +1. Open `about:debugging#/runtime/this-firefox`. +2. Click "Load Temporary Add-on" and pick `dist/firefox/manifest.json`. -**Ethereum JSON-RPC endpoint** (default: `ethereum-rpc.publicnode.com`; -`ethereum-sepolia-rpc.publicnode.com` on Sepolia) +A temporary add-on is unloaded when Firefox exits. Add it again the same way on +every start. Your wallets survive the restart, because Firefox keeps the +extension's storage between loads. Removing the add-on in `about:addons` +destroys that storage. On Firefox, Remove is final. Your recovery phrase, +private key or extended private key is then the only way back. -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. +AutistMask does not run in Firefox private windows. If Firefox is set to never +remember history, every window is private, and the extension does not run at +all. -On mainnet, AutistMask also reads USD prices through this endpoint. The prices -come from Chainlink's price feed contracts. A token with no Chainlink feed shows -no USD value. +## Your password and your backup -When it is contacted: +Each wallet has its own password. The password encrypts that wallet's secret, +its recovery phrase or key, on this device. The encryption uses Argon2id to turn +the password into a key and XSalsa20-Poly1305 to encrypt with it, through the +libsodium library. -- on every balance refresh (every 10 seconds while the popup is open, every 60 - seconds in the background) -- on mainnet, to read USD prices, at most every 5 minutes while the popup is - open -- when you review a send to an ENS name -- when a send is prepared and broadcast -- while a pending transaction is polled for its receipt -- for the reverse ENS lookups used to label addresses (cached for 12 hours) +The password is not part of your recovery phrase. Anyone with the phrase can +restore the wallet on any device without the password. The password protects +only the copy stored in this browser. If you lose the phrase, the password +cannot bring it back. -What gets sent: standard Ethereum JSON-RPC requests (balance queries, -transaction broadcasts, gas estimates, ENS lookups, contract-code checks). Your -addresses are necessarily visible to the RPC provider when querying balances. +The wallet asks for the password when you: -**Blockscout API** (default: `eth.blockscout.com/api/v2`; -`eth-sepolia.blockscout.com/api/v2` on Sepolia) +- send a transaction; +- sign a transaction, message or typed data for a site; +- show a recovery phrase; +- export a private key; +- delete a wallet with "Confirm Delete". -Blockscout is an open-source blockchain explorer. AutistMask sends it your data -only while "Use Blockscout" is on. AutistMask then asks Blockscout for: +It never asks for the password to show balances, to receive funds, to read the +transaction history or to remove an address. -- your recent transactions and token transfers -- the balances of the tokens you have not tracked, with the holder counts used - for spam filtering -- the block, fees and calldata of a transaction you open +The password cannot be recovered or reset. If you forget it, you can still +delete the wallet with "I have lost my password". Then add the wallet again from +your backup, with a new password. See Deleting a wallet below. -You can change the endpoint in Settings to a self-hosted Blockscout instance. -While the setting is off, each screen that would show Blockscout's data says -instead that the setting is off. Only the tokens you track are listed. When you -turn the setting off, every other token leaves the lists at once. +## Getting started -When it is contacted, while "Use Blockscout" is on: +### Creating a wallet -- on every balance refresh -- whenever a screen showing transaction history is opened -- when you open a transaction +1. Click the AutistMask icon in the browser toolbar. +2. The first screen offers "Use Blockscout" and "Check recipients on Etherscan". + Both start off. Tick what you want; you can change both later in Settings. +3. Click "Add wallet". +4. On the "From Phrase" tab, click the die button. It writes a new 12-word + recovery phrase into the box. +5. Write the words down and keep them safe. Anyone with them can take your + funds. If you lose them, the wallet is gone, and AutistMask cannot recover + them. +6. Choose a password and type it twice. It needs at least 12 characters, unless + "Allow weak passwords" is on in Settings. +7. Click "Import". -Pressing "Save" beside the Blockscout URL in Settings checks the URL by asking -it for `/stats`. That happens whether or not the setting is on. The request -sends none of your data. +Later wallets are added from Settings with "+ Add wallet", or with the "Add +additional wallet..." link at the bottom of the home screen. -What gets sent: your Ethereum addresses (to look up balances and transactions) -and the hash of each transaction you open. - -**Etherscan address labels** (`etherscan.io`; `sepolia.etherscan.io` on Sepolia) - -While "Check recipients on Etherscan" is on, AutistMask fetches the recipient's -public Etherscan address page when you review a send. AutistMask looks for a -"Fake_Phishing"/"Phish/Hack" label or a scam warning, and shows a red warning if -it finds one. This is a plain page fetch with no API key, made by your browser. -It is best-effort: if it fails, it is silently ignored. This endpoint is not -user-configurable. - -The setting is off in a new install. While it is off, the confirmation screen -says that no Etherscan check was made. - -When it is contacted: only while "Check recipients on Etherscan" is on, each -time you reach the send confirmation screen. - -What gets sent: the recipient's address and nothing else. As with any request, -Etherscan sees your IP address. - -Etherscan links shown elsewhere in the UI (on addresses, transactions, and token -contracts) are ordinary links. They contact nothing until you click them. - -### 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 requested whenever an encrypted secret must be decrypted: when -you send a transaction, when a site asks you to sign a message or typed data, -when you export an address's private key, and when you delete a wallet. 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`. - -AutistMask does not work in Firefox private windows. If Firefox is set to "Never -remember history", every window is private, so AutistMask does not work at all. - -## Getting Started - -### Creating a New Wallet - -1. Click the AutistMask icon in your browser toolbar. -2. Click "Add wallet" (on first use), or open Settings and click "+ Add wallet". - On first use, the screen with "Add wallet" also offers "Use Blockscout" and - "Check recipients on Etherscan", both off. External Services above says what - each one does. You can change both later in Settings. -3. On the "From Phrase" tab, 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 and confirm it. This encrypts your recovery phrase on this - device. -6. Click "Import". - -### Importing an Existing Wallet +### Importing a wallet The Add Wallet screen has three tabs: -**From Phrase:** Paste your existing 12 or 24 word recovery phrase instead of -generating a new one. AutistMask uses the standard BIP-44 Ethereum derivation -path (`m/44'/60'/0'/0`), which is what other wallets use by default, so your -addresses will match and your phrase stays portable in both directions. +- "From Phrase": paste a 12 or 24 word recovery phrase. AutistMask derives + addresses on the path `m/44'/60'/0'/0`, the one most wallets use, so the same + phrase gives the same addresses here and elsewhere. +- "From Key": paste one private key. The wallet gets one address. +- "From xprv": paste an extended private key, a key from which a whole series of + addresses is derived. It must be the master key, the root of that series. The + wallet behaves like a phrase wallet but has no phrase to show. -**From Key:** Paste a single private key. This creates a single-address wallet. +All three tabs ask for the same password fields. "Import" finishes the job. -**From xprv:** Paste an extended private key. This imports the HD wallet and -scans for used addresses. +After a phrase or xprv import the wallet looks for addresses that have been +used. It checks addresses through the RPC endpoint, five at a time, and stops +after five unused ones in a row. When it finds more than one used address, those +addresses replace the list, and a message says how many were found. -All three tabs ask for the same password fields, and the "Import" button -finishes the job. +The wallet refuses: -### Adding More Addresses +- a phrase or key that is already added; +- an invalid phrase or key; +- an extended private key that is not a master key. -HD wallets (created from a recovery phrase or an xprv) 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 addresses -### Adding ERC-20 Tokens +A wallet made from a phrase or an extended private key can hold many addresses. +On the home screen, click the "+" button next to the wallet's name. The next +address is derived at once. The same phrase always gives the same sequence of +addresses. Each address is labelled "Address N". -The wallet looks for tokens you hold only while "Use Blockscout" is on. Even -then, a token shows up only if it is in the extension's bundled list of -well-known tokens or has at least 1,000 holders. Everything else is treated as -spam and hidden. +### The active address -The wallet shows every token you track, whether or not "Use Blockscout" is on. -By default a tracked token is shown at zero balance too (see Display in -Settings). To track a token, add it by contract address: +One address is the active address. The home screen shows it at the top, with its +ETH balance and its USD value. "Send" and "Receive" on the home screen act on +it. Connected sites see the active address and no other. Tap any address row on +the home screen to make that address active. -1. Go to an address detail view (click `[info]` on any address). +### Removing an address + +Each address of a phrase or xprv wallet with more than one address has an `[x]` +button on the home screen. The confirmation screen explains what removing does. +Nothing is destroyed: the address stays yours, and any funds at it stay where +they are. The wallet only stops listing it. + +Getting the address back is not easy. "+" derives the next unused address, not +the removed one. The way back is to delete the whole wallet and import its +backup again. The scan after the import finds the address only if it has been +used. + +### Deleting a wallet + +Open Settings and click `[x]` next to the wallet. Type the wallet's password and +click "Confirm Delete". Deleting erases the copy of the key stored in this +browser and the wallet's site permissions. Nothing on the blockchain changes. + +If you have forgotten the password, click "I have lost my password". The next +screen asks you to type the wallet's name instead. "Delete This Wallet Forever" +then deletes the wallet without a password. With a kept copy of the wallet's +backup you can add the wallet again with a new password. Without one, deleting +the wallet loses everything it holds, forever. + +## Tokens + +### Which tokens are shown + +A tracked token is one you added by contract address. Tracked tokens are shown +on every address, whether or not "Use Blockscout" is on. By default a tracked +token is shown even at zero balance; the Display setting changes that. + +Other tokens appear only while "Use Blockscout" is on. Blockscout reports every +token that an address holds. The wallet lists such a token only when it is on +the bundled list of well-known tokens or has at least 1,000 holders. Everything +else is treated as spam and hidden. Turning "Use Blockscout" off removes every +untracked token from the lists at once. + +A fake token that claims a well-known symbol from the wrong contract is hidden +everywhere, `ETH` included. See Scam protection. + +### Tracking a token + +From an address: + +1. Click `[info]` on the 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. +3. Enter the token's contract address, or pick one of the common tokens offered. + The common tokens are offered on Ethereum Mainnet only. 4. Click "Add". -The token balance will appear on the address detail screen and on the home -screen. Tokens can also be added from Settings, under "Tracked Tokens". +From Settings, under Tracked Tokens, click "+ Add token". That screen offers the +top 10 tokens as buttons, the top 100 in a dropdown, and a contract address +field. The two lists are offered on Ethereum Mainnet only. + +A token is tracked on the network that it was added on. Settings lists the +tracked tokens of the active network, each with an `[x]` button that stops +tracking it. + +The wallet refuses to track: + +- a token that is already tracked; +- an address on its scam list; +- a contract that does not answer as an ERC-20 token. + +### The token screen + +On an address's screen, click any balance row. The token screen shows: + +- the token's balance; +- its contract address; +- its name, symbol and decimals; +- its holder count, when known; +- its website, when known; +- the token's own transaction history. ## Sending -1. Click "Send" from the home screen or an address detail view. -2. Select what to send: ETH, or a token you track that this address holds. While - "Use Blockscout" is on, Send also offers other tokens with a balance on this - address that survive the spam filters. -3. Enter the recipient address or ENS name (e.g. `vitalik.eth`). AutistMask does - not look up a name resolved off-chain. For such a name, enter the address - instead. -4. Enter the amount, or click "Max" to fill it in: a token's balance, cut to 18 - decimal places, or your ETH balance minus the amount reserved for the network - fee. -5. Click "Review" to see the confirmation screen. +1. Click "Send" on the home screen, on an address's screen or on a token's + screen. +2. Choose what to send: ETH, or one of the tokens that the address holds. +3. Enter the recipient. This is an address, or an ENS name such as + `vitalik.eth`. An ENS name stands for an address, and the wallet looks it up + through the RPC endpoint. +4. Enter the amount, or click "Max". +5. Click "Review". -The confirmation screen shows: +"Max" fills in a token's whole balance. For ETH it fills in the balance minus +the network fee that the confirmation screen will reserve, so enter the +recipient first. A message says why when there is nothing to fill in. -- **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 -- **Network fee** — what the transfer is expected to cost, in ETH with a USD - estimate, and below it the larger amount reserved until it confirms. The - reserve is what the network requires up front and what the balance check gates - on; the refund of the difference is why the two differ -- **Warnings** if the recipient is: - - a contract - - a burn address - - one of your own addresses - - on the bundled scam-address list - - while "Check recipients on Etherscan" is on, labelled as a phisher on - Etherscan +An amount must be a number above zero, written as digits with at most one +decimal point. ETH has 18 decimal places. A token has as many as it declares, up +to 18. Digits beyond them must be zeros. -After reviewing, enter your password and click "Sign & Send". 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. +A name that has no on-chain address is refused. So is a name whose owner keeps +its address off-chain. Enter the address instead. -### Sending a Specific Token +### The confirmation screen -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. While "Use Blockscout" is off, the view says instead that no -transaction history is shown. Clicking "Send" from here pre-selects and locks -the token so you cannot accidentally switch to a different one. +The screen shows: + +- the type: a native ETH transfer or an ERC-20 token transfer; +- the token's contract address, for a token; +- the From and To addresses, each in full, with an identicon (a small pixel + picture made from the address) and an Etherscan link; +- the amount, with its USD value; +- your balance on this network; +- the network fee: what the transfer is expected to cost, and under it the + larger amount reserved until the transaction confirms. The network refunds the + difference. + +It warns when the recipient is: + +- on the wallet's list of known scam addresses; +- a burn address, one nobody controls, where funds are destroyed; +- the address you are sending from; +- a contract, a program on Ethereum rather than a person's address; +- an address that has never sent a transaction and holds no ETH; +- labelled as phishing, scam or exploiter on Etherscan, while "Check recipients + on Etherscan" is on. While that setting is off, a line says the address was + not checked. + +It refuses to send, and says why, when: + +- the amount is not a valid number; +- the amount is more than you hold; +- the amount plus the fee is more than your ETH; +- your ETH does not cover the fee of a token transfer; +- the fee could not be estimated; +- your balance could not be read. + +Enter your password and click "Sign & Send". The wallet signs the transaction +and broadcasts it to the network. Before signing, it refuses when: + +- the network was switched since you reviewed the send; +- the wallet shown no longer holds the From address; +- the fee or gas limit that the network quotes is above the wallet's limits, + which allow a total fee of at most 1 ETH; +- the token contract now reports a different number of decimals than the amount + was shown with. + +### After sending + +A waiting screen shows the transaction hash and a counter. The wallet asks the +network for the receipt every 10 seconds, and the wait resumes if you close and +reopen the popup. Then: + +- a receipt opens the success screen, with the block number, the hash and + Etherscan links; +- no receipt after 60 seconds opens the error screen with a timeout message. The + transaction may still confirm later; check the hash on Etherscan; +- six failed lookups in a row open the error screen with a message saying the + network could not be reached. Check the Ethereum RPC setting. + +### Sending a specific token + +On a token's screen, "Send" opens the send screen with that token locked in. +What to send cannot be changed there. ## 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. +1. Click "Receive" on the home screen, on an address's screen or on a token's + screen. +2. Show the QR code, or click "Copy address". -When receiving ERC-20 tokens, make sure the sender is sending on the network you -are using. AutistMask supports Ethereum mainnet and the Sepolia testnet. Tokens -sent on other networks (Polygon, Arbitrum, BSC, etc.) to the same address will -not appear and may be permanently lost. +Give the address only to senders on the network you are using. AutistMask works +on Ethereum Mainnet and the Sepolia test network. Tokens sent to your address on +another network do not appear in AutistMask, and it cannot move them. Opened +from a token's screen, the Receive screen says this for that token. -## Connecting to Web3 Sites +## Transaction history -AutistMask injects a standard `window.ethereum` provider (EIP-1193) into web -pages. When a site requests access to your wallet: +Transaction history comes from Blockscout, so it needs "Use Blockscout". While +the setting is off, each history list shows one line saying so. -1. A popup appears showing the site's origin (its scheme, host and port, for - example `https://app.example`) 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. The choice applies to that exact origin only: a choice remembered for - `https://app.example` does not cover `http://app.example` or another port of - the same host, which ask again. +- The home screen lists the 25 most recent transactions across all your + addresses. +- An address's screen lists that address's transactions. +- A token's screen lists that token's transfers for the address. -When a connected site requests a transaction, a separate approval popup appears -showing the transaction details (from, to, value, data, network fee, network and -nonce). Every one of those values is checked against the transaction that is -actually signed before anything is broadcast, so what you read on that screen is -what goes out or nothing does. The popup appears once the wallet has worked out -the fee and gas from the network, which takes a moment; if that fails, no popup -appears and the site is told the transaction could not be prepared. You must -enter your password and click "Confirm" to authorize it. Message and typed-data -signature requests work the same way, with a "Sign" button, and also require -your password. +Each row shows: -If a transaction or signature popup closes before you answer, for example when -you click away to copy your password, the request stays open. Closing the popup -does not turn the request down. Click the AutistMask icon in your browser -toolbar to bring the request back. Until you answer, the icon opens the request -instead of your wallet. If several requests are waiting this way, the oldest -comes first. +- the age and the direction; +- the amount; +- the other party's address, in full. -A connected site can also ask to switch the wallet's network. A popup shows the +The scam filters below hide fake and dust transactions from these lists. + +Tap a row to open the transaction. The transaction screen shows: + +- the hash; +- the type: native ETH transfer, ERC-20 token transfer, swap, token approval, + contract call or contract creation; +- the status; +- the From and To addresses, in full; +- the time, as a date and time and as an age; +- the exact amount, and under it the amount in the token's smallest unit; +- the token's contract address, for a token transfer; +- the block number; +- the nonce, the transaction's sequence number for your address; +- the gas price, the gas used and the fee; +- what the transaction did, when the wallet can read it; +- the raw data. + +Tapping a value copies it. Each address, hash and block has an Etherscan link. +The block, nonce, gas, fee and raw data come from Blockscout. + +## Connecting to web3 sites + +AutistMask gives every page a standard wallet connection (`window.ethereum`). A +site that wants your wallet opens a connection request. + +### Connection requests + +The request shows the site's origin, that is its scheme, host and port, for +example `https://app.example`. It shows the address that will be shared, which +is the active address. Click "Allow" or "Deny". + +Tick "Remember my choice for this site" to skip the request next time. The +choice applies to that exact origin. A choice remembered for +`https://app.example` does not cover `http://app.example` or another port of the +same host. + +Without "Remember", an allowed site stays connected until the browser closes, +until you make another address active, or until you remove the site in Settings. + +### Transaction requests + +A connected site can ask you to send a transaction. The request opens in a +window of its own. The wallet first fills in the nonce from the network, and the +fee and gas limit too when the site gave none. If that fails, no window opens +and the site is told. + +The window shows: + +- the site's origin; +- what the transaction does, when the wallet can read it: + - a token transfer; + - a token approval; + - a swap through the Uniswap Universal Router, step by step; +- the From address and the contract or recipient, in full; +- the value in ETH and its USD value; +- the largest network fee the transaction can cost, with the gas limit and fee + per gas; +- the network and the nonce; +- the raw data. + +Enter your password and click "Confirm". The wallet signs exactly the +transaction shown, and checks the signed transaction against every value on the +screen before it broadcasts anything. What you read is what goes out, or nothing +does. "Reject" tells the site you refused. + +One transaction request is open at a time. A site that sends another while one +is unanswered is told to wait. + +### Signature requests + +A connected site can ask you to sign a message or typed data. Typed data is +structured data laid out as named fields. The request opens in a window of its +own and shows the site's origin, the type, the From address and what will be +signed. + +A plain message is shown as text, in the order of its bytes. A character that +paints nothing, such as a zero-width character, is shown as a marked code +instead. The hex form of the message is shown under the text. + +Typed data is shown as its fields. Fields that the site added but that are not +signed are listed apart, under "Not part of the signature". When the data is a +token permission (a `Permit`, or a Permit2 permission; Permit2 is Uniswap's +token allowance contract), a red warning names the spender, and each token and +amount that the signature lets the spender take. + +"Sign" is disabled, and the screen says why, when: + +- the typed data cannot be signed as shown; +- the typed data names a different network than the active one; +- a message is not in hex form. + +A request made with the older `eth_sign` method shows a warning that says so. +Enter your password and click "Sign" to sign. "Reject" tells the site you +refused. + +### Network switch requests + +A connected site can ask to switch the wallet's network. The window shows the site's origin, the current network and the requested network. Nothing changes -unless you click "Switch"; clicking "Reject" or closing the popup leaves -everything as it was. Switching works exactly as it does in Settings, and -changes the network for the whole wallet and for every site, not only for the -one that asked. +until you click "Switch". Switching changes the network for the whole wallet and +for every site. "Reject", or closing the window, leaves everything as it was. -If the requesting site's domain is on the phishing blocklist, all four approval -screens show a red phishing warning before you decide. +### Closed windows -You can manage site permissions in Settings. Allowed and denied sites can be -individually removed to reset their permissions. +If you close a transaction or signature window without answering, the request +stays open; the site is not told you refused. Click the AutistMask icon in the +toolbar to bring the request back. Until you answer, the icon opens the request +instead of the wallet. When several requests wait this way, the oldest comes +first. A closed connection or network switch window counts as a refusal. -## Scam Protection +### Phishing warnings -AutistMask includes several defenses against common Ethereum scams, all enabled -by default: +When the requesting site is on the built-in phishing list, every one of these +windows shows a red warning at the top before you decide. -**Known token symbol verification.** AutistMask ships a bundled list of -high-market-cap ERC-20 tokens with their legitimate contract addresses — a -point-in-time snapshot of the highest-market-cap Ethereum mainnet ERC-20s, fixed -at build time and updated only when a new release ships a newer snapshot. If a -transaction or balance claims to involve a known symbol (like "ETH" or "USDT") -but comes from an unrecognized contract, it is identified as a spoof and hidden. -In your transaction history this is the "Hide fake tokens impersonating a known -symbol" setting, which you can switch off; doing so also stops new entries being -added to the fraud contract blocklist below, since detecting a spoof is what -fills it. The send token list always applies the check. Your balances apply it -too, with one exception: a token claiming the symbol "ETH" is not filtered -there, so a fake "ETH" token can still show up in your balance list even though -it is hidden from your transaction history and from the send token list. +### Managing sites -**Low-holder token filtering.** Tokens with fewer than 1,000 holders are hidden -from transaction history and the send token list, and are left out of your -balances unless they are on the bundled known-token list or you added them -yourself. Legitimate tokens have substantial holder counts; scam tokens deployed -for address poisoning typically have zero. When the explorer reports no holder -count for a token, or reports something other than a whole number in plain -digits (such as "1,000"), the count is unknown. While "Use Blockscout" is off, -no holder count is known. An unknown count does not hide a token from your -transaction history or the send token list, and it does not get a token into -your balances either: such a token is listed only if it is on the bundled -known-token list or you added it yourself. The screen you reach by clicking a -token balance shows a "Holders:" line only when the count is known. +Settings lists the sites under three headings: -**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. +- Allowed Sites: allowed with "Remember my choice for this site"; +- Connected Sites: allowed without it; +- Denied Sites: denied with it. -**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. +`[x]` beside an allowed or connected site disconnects it. The site is told it +has no address. `[x]` beside a denied site forgets the refusal. -**Scam address list.** A list of known fraud, drainer, and phishing addresses is -shipped with the extension. Sending to one of them raises a warning on the -confirmation screen. It contains only addresses involved in fraud -- it is not a -sanctions list. +Making another address active disconnects every site allowed without "Remember" +and rejects every request still waiting for an answer. -**Phishing domain warnings.** Sites asking to connect or to have something -approved are checked against a community-maintained list of known phishing -domains, and flagged with a red banner if they match. The list is built into the -extension: the check is entirely local, so nobody is told which sites you visit, -and it works offline. It is also only as current as the release you are running -— a domain added to the list upstream reaches you in the next version of the -extension, not the same day. +## Scam protection -The first four filters can be individually disabled in Settings if you prefer to -see everything unfiltered. +Five defenses are on in a new install. + +Fake tokens. Scammers create tokens that borrow a well-known symbol, such as +`USDT` or `ETH`, from a contract that has nothing to do with it. The wallet +knows which contracts may carry each symbol on its bundled list. A token that +carries one of those symbols from any other contract is hidden from your +balances, from the send screen and from the transaction history. `ETH` and the +test network's `SepoliaETH` belong to no contract at all, so every token that +claims them is hidden. A token you tracked yourself is still listed, at zero. In +the history, this is the setting "Hide fake tokens impersonating a known +symbol". + +Tokens with few holders. Real tokens have many holders; scam tokens made for +address poisoning have almost none. While "Hide tokens with fewer than 1,000 +holders" is on, the history and the send screen hide a token with fewer than +1,000 reported holders. The balance list has its own rule: an untracked token +appears only when it is on the bundled list or has at least 1,000 reported +holders. A token whose holder count Blockscout does not report is not hidden +from the history or the send screen. While "Use Blockscout" is off, no holder +count is known. + +Fraud contracts. When the wallet detects a fake token transfer, it adds the +contract to a list that it keeps. Transfers from those contracts are hidden from +the history while "Hide transactions from detected fraud contracts" is on. The +send screen always leaves them out. Turning the fake-token setting off also +stops new contracts being added to the list. + +Dust transactions. Scammers send tiny amounts of ETH from addresses that +resemble your real contacts, so that the look-alike lands in your history. While +"Hide dust transactions below N gwei" is on, ETH transfers below the threshold +are hidden from the history. A gwei is a billionth of an ETH. The threshold +starts at 100,000 gwei, which is 0.0001 ETH. A threshold of 0 hides nothing. + +Known scam addresses. The wallet ships a list of addresses used for fraud, +phishing and wallet draining. Sending to one of them raises a warning on the +confirmation screen, and such an address cannot be tracked as a token. The list +holds only addresses involved in fraud; it is not a sanctions list. + +The wallet also warns about phishing sites. The list of phishing domains is +built into the extension and checked in your browser, so nobody learns which +sites you visit. The list is as current as the AutistMask build you run. + +## Networks + +AutistMask works on Ethereum Mainnet, the real network, and on the Sepolia +Testnet, a network for testing whose ETH has no value. Switch between them under +Network in Settings. A connected site can also ask for a switch, which you +approve or reject. + +Switching: + +- restores the Ethereum RPC and Blockscout URLs you last used on that network, + or that network's defaults; +- shows the tokens tracked on that network; +- reloads every balance and history for the new network; +- tells every open site about the new network. + +On Sepolia, a red `[TESTNET]` banner sits at the top of every screen, and no USD +values are shown. ## Settings -Click the gear icon on the home screen to access settings: +Click the gear in the title bar. -- **Wallets**: Your wallets, and "+ Add wallet". -- **Passwords**: Tick "Allow weak passwords" to choose a password shorter than - 12 characters when you add a wallet. -- **Tracked Tokens**: The ERC-20 tokens tracked across all addresses, and "+ Add - token". -- **Display**: Toggle whether tracked tokens with zero balance are shown, switch - timestamps to UTC, and choose the theme (System, Light, or Dark). -- **Network**: Switch between Ethereum Mainnet and Sepolia Testnet. Switching - restores the RPC and Blockscout endpoints you last used on that network, or - that network's defaults if you have not used it before. -- **Ethereum RPC**: Change the Ethereum node endpoint. Default is a public RPC. - You can use your own node for maximum privacy. -- **Blockscout API**: the "Use Blockscout" checkbox, off until you tick it, and - the URL of the Blockscout instance. You can use a self-hosted instance. -- **Etherscan**: "Check recipients on Etherscan", off until you tick it. -- **Token Spam Protection**: Toggle individual scam filters and set the dust - transaction threshold. -- **Allowed Sites / Denied Sites**: View and manage web3 site permissions. -- **About**: License, author, version, release date, and a link to the commit - this build came from. +- Wallets: your wallets. Tap a name to rename it. `[recovery phrase]` shows a + phrase wallet's recovery phrase, after your password. `[x]` deletes a wallet. + "+ Add wallet" adds one. +- Passwords: "Allow weak passwords" lets you choose a password shorter than 12 + characters when you add a wallet. +- Tracked Tokens: the tokens tracked on the active network, each with `[x]`, and + "+ Add token". +- Display: "Show tracked tokens with zero balance", "UTC Timestamps" (otherwise + times are shown in your local time) and the theme, System, Light or Dark. +- Network: Ethereum Mainnet or Sepolia Testnet. +- Ethereum RPC: the RPC endpoint URL. "Save" checks that the URL answers for the + shown network before storing it. +- Blockscout API: the "Use Blockscout" checkbox and the Blockscout URL. "Save" + checks that the URL answers before storing it. That check sends no data of + yours and runs whether or not the checkbox is ticked. +- Etherscan: the "Check recipients on Etherscan" checkbox. +- Token Spam Protection: the four filters described under Scam protection, and + the dust threshold in gwei. +- Allowed Sites, Connected Sites, Denied Sites: see Managing sites. +- About: the project link, the license, the author, the version, the release + date and the commit the build came from. +- Debug: hidden until you click the version ten times. It holds a checkbox that + turns on a red banner and more detailed logging in the browser console. -## Frequently Asked Questions +The URLs you save are remembered per network. + +## If the wallet cannot read its saved data + +When AutistMask cannot read what it stored, it shows a screen headed "Saved Data +Cannot Be Read" instead of the wallet. Nothing has been changed or erased, and +nothing can be signed or sent. Sites that ask the wallet for anything are told +that the saved data cannot be read. + +Click "Export Saved Data" first. The stored data appears in a box on the screen, +and the browser offers it as a download where it can. Keep that copy. It may +hold the encrypted keys of your wallets, and it is the only copy. + +"Erase Saved Data" deletes every wallet stored in this browser and starts the +wallet fresh. You must type `ERASE MY WALLET` first. With a kept recovery +phrase, private key or extended private key, you can add a wallet again +afterwards. Without that, or the exported copy, everything the wallet holds is +gone. + +## Frequently asked questions **Can I use AutistMask alongside another wallet?** -Yes. AutistMask uses the standard `m/44'/60'/0'/0` derivation path, so importing -the same recovery phrase gives you the same addresses as any other wallet using -that path. Two wallet extensions can be installed side by side, though only one -can be the active `window.ethereum` provider at a time. +Yes. AutistMask derives addresses on the path `m/44'/60'/0'/0`, so the same +recovery phrase gives the same addresses as any other wallet using that path. +Two wallet extensions can be installed side by side. Only one of them can answer +a site as `window.ethereum`; sites that list wallets can pick AutistMask by +name. -**Can I use AutistMask with a hardware wallet?** +**Can I use a hardware wallet?** -Not yet. Hardware wallet support may be added in the future. +No. AutistMask does not support hardware wallets. -**Does AutistMask support networks other than Ethereum mainnet?** +**Which networks are supported?** -Ethereum mainnet and the Sepolia testnet, selectable in Settings. No other -networks are supported today. On Sepolia, USD values are not shown, because -testnet tokens have no market value. +Ethereum Mainnet and the Sepolia Testnet. No others. **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. +In your browser's extension storage. Recovery phrases and keys are encrypted +with your password. Addresses, balances and settings are stored unencrypted, so +the wallet can show them without a password. Nothing is sent to any server run +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 wallet that uses the standard derivation path. +Your data is deleted. Make sure you have your recovery phrase, private key or +extended private key before uninstalling. With that backup you can restore the +wallet in AutistMask or in any other wallet that uses the standard path. -**What happens if a transaction times out?** +**What happens when 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. +After 60 seconds without a receipt the wallet shows the error screen. The +transaction has not failed; it may still confirm. Check the hash on Etherscan. +Congestion or a low fee can delay confirmation past 60 seconds. ## License -GPL-3.0. See [LICENSE](../LICENSE). +GPL-3.0. See [`LICENSE`](../LICENSE). ## Author