diff --git a/docs/README.md b/docs/README.md index 9d8465f..5c6eae3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,496 +1,747 @@ # 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 (12 or 24 words), + from a private key, or from an extended private key. An extended private key + is a single key that many addresses are computed from. +- It shows the ETH and ERC-20 token balances of your addresses. ETH is the + currency of Ethereum. A contract is a program that runs on Ethereum. An ERC-20 + token is a token issued by a contract under the ERC-20 standard. +- 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 (a swap exchanges one token for another); +- no portfolio view; +- no NFT gallery (an NFT is a non-fungible token, such as a collectible); +- 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. Each service +named below sees your IP address, as any website you visit does. -- **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. The blockchain is the shared record of all Ethereum +transactions. It grows in blocks; a block is a batch of transactions that the +network adds together. Usually the endpoint is a node, a computer running the +Ethereum software. 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. While the wallet is open, it asks for your +balances every 10 seconds. While it is closed, it asks every 60 seconds. 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 main Ethereum network, the wallet reads USD prices +through the RPC endpoint, from Chainlink price feeds. A Chainlink price feed is +a contract that publishes an exchange rate on Ethereum. No price service is +contacted. A token with no Chainlink price feed shows no USD value. -- **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 settings +are off in a new install. The first screen and Settings both offer the two +settings. -### What AutistMask Will Never Do +- "Use Blockscout". Blockscout is an open-source block explorer, a service that + reads the whole blockchain and answers questions about it. With the setting + on, the wallet sends Blockscout your addresses each time it refreshes your + balances, and the hash of each transaction you open. A hash is the id of a + transaction. In return the wallet shows your transaction history, transaction + details and the tokens you have not added yourself. 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. The wallet 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. +Each time a site's request opens a window, the wallet checks the site 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; +- your wallet names and your settings; +- which sites you have allowed or denied; +- the list of contracts that the wallet has caught issuing fake tokens. -- **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. -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. +While a phrase wallet is in this browser, `[recovery phrase]` in Settings shows +its phrase after your password. If you lose the written phrase and this +browser's copy is gone, the wallet is lost. -**Blockscout API** (default: `eth.blockscout.com/api/v2`; -`eth-sepolia.blockscout.com/api/v2` on Sepolia) +The wallet asks for the password when you: -Blockscout is an open-source blockchain explorer. AutistMask sends it your data -only while "Use Blockscout" is on. AutistMask then asks Blockscout for: +- send a transaction; +- sign a transaction, message or typed data for a site (typed data is structured + data laid out as named fields); +- show a recovery phrase; +- export a private key; +- delete a wallet with "Confirm Delete". -- 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 +It never asks for the password to: -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. +- show balances; +- receive funds; +- read the transaction history; +- remove an address. -When it is contacted, while "Use Blockscout" is on: +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. -- on every balance refresh -- whenever a screen showing transaction history is opened -- when you open a transaction +## Getting started -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. +### Creating a wallet -What gets sent: your Ethereum addresses (to look up balances and transactions) -and the hash of each transaction you open. +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. Without them, this browser's copy is the only copy of your wallet. +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". -**Etherscan address labels** (`etherscan.io`; `sepolia.etherscan.io` on Sepolia) +Later wallets are added from Settings with "+ Add wallet", or with the "Add +additional wallet..." link at the bottom of the home screen. -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 computes + addresses from the phrase by the rule `m/44'/60'/0'/0`, called the derivation + path. Most wallets use the same rule, 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; `xprv` is the usual short name for + one. It must be the master key, the one that every other key of the wallet is + computed from, not a key computed from it. 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. The scan counts an address as used when it holds ETH or has sent a +transaction. An address that only received tokens is not found. The scan 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 wallet's address 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 wallet +computes the next address 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 +the active address. 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 stops listing the address and forgets the sites allowed or +denied for it. + +Getting the address back is not easy. "+" computes only addresses that this +wallet has never listed. The removed address was listed once, so "+" skips it. +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 holds ETH or has sent a +transaction. + +### 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 yourself, by its contract address. A tracked +token is listed on every address while "Show tracked tokens with zero balance" +is on, which it is in a new install. With that setting off, a tracked token is +listed only on the addresses that hold it. Tracked tokens are shown whether or +not "Use Blockscout" is on. + +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 built-in 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. + +The balance list and the send screen hide a token that carries a well-known +symbol, `ETH` included, but comes from another contract. A token you track +yourself is still listed at zero while "Show tracked tokens with zero balance" +is on. 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 (the number of decimal places its amounts have); +- how many addresses hold it, 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. The network fee is the price the network charges to process a +transaction. It depends on the recipient, 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. +An ENS name is refused when it has no address recorded on Ethereum. A name whose +owner serves its address from a web server instead is refused too. 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: "Native ETH transfer", or "ERC-20 token transfer" with the token's + symbol. Native means that ETH is built into the network and needs no contract; +- 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. The screen shows what the transfer is expected to cost, and + under it the larger amount reserved until the network has processed the + transaction. 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 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. A failed lookup shows no warning. A missing warning + therefore does not prove that Etherscan was asked. While the 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 sends it to the network. Before signing, it refuses when: + +- the network was switched since you reviewed the send; +- the selected wallet 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. Gas is the unit Ethereum measures + work in, and the gas limit is the most gas the transaction may use; +- 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 every 10 seconds for the receipt, the network's record that the +transaction was included in a block. The wait resumes if you close and reopen +the wallet. 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. A + timeout does not mean the transaction failed. It may still be included 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 warns that this token sent on another +network is lost. -## 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 up to 25 of the most recent transactions across all your + addresses. +- An address's screen lists up to 25 of its most recent transactions. +- A token's screen lists the token's transfers among those 25. -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, "Sent" or "Received". A transaction can also ask a + contract to do something; that is a contract call. A row for a contract call + shows the call's name instead, such as "Approve" or "Swap"; +- the amount. A contract call row shows an amount only when the call moved a + token. A swap row shows the amount received, or the amount paid in when no + token came back. A row with no amount shows a symbol alone; +- the other party's address, in full. A swap row shows your own address here. -A connected site can also ask to switch the wallet's network. A popup shows the +The scam filters below hide fake transfers and dust from these lists. Dust is a +tiny amount of ETH. + +Tap a row to open the transaction. The transaction screen shows: + +- the hash; +- the type, one of: + - "Native ETH Transfer"; + - "ERC-20 Token Transfer"; + - "Swap"; + - "Token Approval", a call that lets a contract move your tokens; + - "Contract Call", any other call to a contract; + - "Contract Creation", a transaction that puts a new contract on the + network; +- the status, "Success" or "Failed"; +- 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; +- these details from Blockscout: + - the block number; + - the nonce, the sender's sequence number for this transaction; + - the gas price, the gas used and the fee; + - what the transaction did, when the wallet can read it; + - the raw data, the bytes the transaction carried. + +Tapping the hash, an address, the amount or a detail copies it. Each address, +hash and block has an Etherscan link. + +## Connecting to web3 sites + +AutistMask offers every page a standard wallet connection. It takes +`window.ethereum`, the name sites look for, when no other wallet has taken it. +Sites that list wallets can pick AutistMask by name. A site that wants your +wallet opens a connection request. + +### Connection requests + +The request shows the site's origin, for example `https://app.example`. The +origin is the start of the site's web address, before any path. It holds the +scheme (`https` or `http`), the host name (`app.example`) and a port number, +which most addresses leave out. The request also shows the address that will be +shared, which is the active address. Click "Allow" or "Deny". + +"Remember my choice for this site" starts ticked. The box stays as you last left +it. While it is ticked, the wallet keeps your answer, and the site is not asked +again. The answer applies to that exact origin and to the active address. A +choice remembered for `https://app.example` does not cover `http://app.example` +or another port of the same host name. A choice remembered for one address does +not cover another. + +Without "Remember", an allowed site stays connected until: + +- the browser closes; +- you make another address active; +- you remove the site in Settings; +- you remove the address, or delete its wallet. + +### 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. Uniswap is a + token exchange made of contracts on Ethereum, and the Universal Router is + its contract that carries out a swap in steps; +- 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 the + price per unit of 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 in the +window before it sends 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, across all sites. While one is open, +the wallet refuses any other, and the site is asked to send it again later. + +### Signature requests + +A connected site can ask you to sign a message or typed data. The request opens +in a window of its own. The window shows: + +- the site's origin; +- whether a message or typed data is to be signed; +- the From address; +- what will be signed. + +A plain message is shown as text, left to right in the order it was written, so +right-to-left characters cannot reorder it. An invisible character, such as a +zero-width space, is shown as its code in a small box, for example `U+200B`. The +message is also shown as hex, that is as the hexadecimal digits of its bytes. + +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". + +Some typed data is a token permission: a signature that lets a spender take your +tokens later without asking you again. The spender is the contract or address +that the permission names. The wallet recognises two kinds: + +- `Permit`, a signed permission that a token's own contract accepts; +- a Permit2 permission. Permit2 is Uniswap's contract for token allowances, that + is for permissions to move tokens. + +For a token permission, a red warning names the spender and each token and +amount that the spender may take. + +"Sign" is disabled, and the window 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 hex. + +A request made with `eth_sign`, an older way of asking for a signature, shows a +warning that names it. 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 the site. 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. A site whose remembered +choice covers only the old address is not told the new one. -**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. +Address poisoning is a scam. The scammer makes an address that looks like one +you have dealt with. The scammer then puts that address in your history, hoping +you copy it later by mistake. Five defenses guard against this and related +scams. The list of known scam addresses is always on. Settings has a switch for +each of the other four, and all four are on in a new install. + +Fake tokens. Scammers issue tokens from their own contracts under a well-known +symbol, such as `USDT` or `ETH`. The wallet knows which contracts may carry each +symbol on its built-in list. The balance list and the send screen hide a token +that carries one of those symbols but comes from another contract. `ETH` and the +test network's `SepoliaETH` belong to no contract at all, so every token that +claims them is hidden. In the history, the rule applies while "Hide fake tokens +impersonating a known symbol" is on. A token you track yourself is still listed +at zero while "Show tracked tokens with zero balance" is on. + +Tokens with few holders. Real tokens have many holders; 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 built-in list or has at least 1,000 reported holders. When +Blockscout reports no holder count for a token, the history and the send screen +still show it. While "Use Blockscout" is off, no holder count is known. + +Fraud contracts. When the wallet detects a fake token transfer, it adds the +token's contract to a list that it keeps. While "Hide transactions from detected +fraud contracts" is on, the history hides transfers from the contracts on that +list. The send screen never offers those tokens. Turning "Hide fake tokens +impersonating a known symbol" off also stops new contracts being added to the +list. + +Dust transactions. Scammers send tiny amounts of ETH from an address that +resembles one you have dealt with, so that the similar address 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 known for fraud, +including phishing addresses and wallet drainers. A wallet drainer is a contract +that empties a wallet once given permission. Sending to a listed address raises +a warning on the confirmation screen, and a listed address cannot be tracked as +a token. The list holds only addresses involved in fraud; it is not a sanctions +list. + +Addresses and hashes are shown in full, because address poisoning relies on +shortened ones. The only shortened address is the label of a token with no known +symbol: the first 10 characters of its contract address and "…". That label +appears on the send screen, on the token screen, and on the confirmation and +result screens of a send. + +The wallet also warns about phishing sites. The list of phishing sites 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 the wallet, 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": times are shown in UTC, the world reference time, + instead of your local time; + - 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. The API + is the address at which a program, here the wallet, asks Blockscout its + questions. "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 switches described under Scam protection: + - "Hide fake tokens impersonating a known symbol"; + - "Hide tokens with fewer than 1,000 holders"; + - "Hide transactions from detected fraud contracts"; + - "Hide dust transactions below N gwei", with the threshold N as a field. +- Allowed Sites, Connected Sites, Denied Sites: see Managing sites. +- About: + - the project link; + - the license and the author; + - the version and the release date; + - the source code revision (the commit) the build came from. +- Debug: hidden until you click the version ten times. It holds the checkbox + "Enable debug mode". That checkbox turns on a red banner and more detailed + logging in the browser console, the browser's own log for developers. -## 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 when it allows one. 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 computes addresses by the rule `m/44'/60'/0'/0`, so the same +recovery phrase gives the same addresses as any other wallet using that rule. +Two wallet extensions can be installed side by side. Only one of them can hold +`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. +The browser deletes the extension's storage. 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 rule `m/44'/60'/0'/0`. -**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 +After 60 seconds without a receipt the wallet shows the error screen. A timeout +does not mean the transaction failed. It may still be included later; check the +hash on Etherscan. A busy network or a low fee can delay a transaction past 60 seconds. ## License -GPL-3.0. See [LICENSE](../LICENSE). +GPL-3.0. See [`LICENSE`](../LICENSE). ## Author