AutistMask/docs/README.md

# AutistMask User Guide

AutistMask is a minimal Ethereum wallet browser extension for Chrome and
Firefox. It manages recovery phrases and private keys, sends and receives ETH
and ERC-20 tokens, and connects to web3 sites. Nothing else.

## Why AutistMask Exists

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.

AutistMask exists because a wallet should be a wallet. You should be able to see
your balances, send tokens, receive tokens, and connect to sites. That is all a
wallet needs to do. If you want to swap tokens, use a DEX. If you want portfolio
analytics, use a portfolio tracker. The wallet is not the place for any of that.

## Hard Guidelines

### What AutistMask Will Always Do

- **Show full addresses and transaction hashes.** Never truncated, never
  abbreviated. Address poisoning attacks exploit truncated displays. If you see
  an address in AutistMask, you see the whole thing. The only exception is
  compact transaction list rows, where the full address is always one tap away.

- **Encrypt your recovery phrase and private keys at rest.** Your secrets are
  encrypted on disk using Argon2id key derivation and XSalsa20-Poly1305
  authenticated encryption (via libsodium). Your password is required 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.

- **Let you choose your own RPC endpoint.** The default is a public Ethereum
  RPC, but you can point it at your own node or any provider you trust. No
  Infura or Alchemy lock-in.

- **Filter scam transactions by default.** Fake token transfers, dust poisoning,
  and look-alike addresses are filtered automatically. Every filter can be
  turned off individually if you prefer to see everything.

- **Work on both Chrome and Firefox.** Same codebase, same features, both
  browsers.

### What AutistMask Will Never Do

- **No analytics, telemetry, or tracking.** Zero data about your usage is
  collected or transmitted. No crash reports, no usage metrics, no user
  identifiers.

- **No advertisements or promotions.** No banners, no "try our new feature"
  popups, no partner integrations.

- **No swap UI.** Use Uniswap, 1inch, or whatever DEX you prefer in your
  browser. The wallet is not a trading terminal.

- **No NFT galleries or portfolio views.** This is a wallet, not a dashboard.

- **No 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.

- **No backend servers operated by the developer.** Nothing is sent to any
  server run by AutistMask. Every network destination is listed below.

## How It Works

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.

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.

### External Services

**Ethereum JSON-RPC endpoint** (default: `ethereum-rpc.publicnode.com`;
`ethereum-sepolia-rpc.publicnode.com` on Sepolia)

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.

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.

When it is contacted:

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

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.

**Blockscout API** (default: `eth.blockscout.com/api/v2`;
`eth-sepolia.blockscout.com/api/v2` on Sepolia)

Blockscout is an open-source blockchain explorer. AutistMask sends it your data
only while "Use Blockscout" is on. AutistMask then asks Blockscout for:

- 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

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.

When it is contacted, while "Use Blockscout" is on:

- on every balance refresh
- whenever a screen showing transaction history is opened
- when you open a transaction

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.

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

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 Key:** Paste a single private key. This creates a single-address wallet.

**From xprv:** Paste an extended private key. This imports the HD wallet and
scans for used addresses.

All three tabs ask for the same password fields, and the "Import" button
finishes the job.

### Adding More Addresses

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 ERC-20 Tokens

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

1. Go to an address detail view (click `[info]` on any address).
2. Click "+ Token".
3. Enter the token's contract address (find this on Etherscan or the token's
   website), or pick from the list of common tokens.
4. Click "Add".

The token balance will appear on the address detail screen and on the home
screen. Tokens can also be added from Settings, under "Tracked Tokens".

## 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.

The confirmation screen shows:

- **Transaction type** (native ETH transfer or ERC-20 token transfer)
- **Token contract address** with Etherscan link (for ERC-20 tokens)
- **From and To addresses** with identicons and Etherscan links
- **Amount** with USD estimate
- **Your current balance** with USD estimate
- **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

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.

### Sending a Specific Token

You can also send from a token-specific view: on the address detail screen,
click any token balance row. This opens a focused view showing only that token's
transactions. 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.

## Receiving

1. Click "Receive" from the home screen or an address detail view.
2. Share the QR code or copy the address using the "Copy address" button.

When receiving ERC-20 tokens, make sure the sender is sending on the 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.

## Connecting to Web3 Sites

AutistMask injects a standard `window.ethereum` provider (EIP-1193) into web
pages. When a site requests access to your wallet:

1. A popup appears showing the site's 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.

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.

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.

A connected site can also ask to switch the wallet's network. A popup 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.

If the requesting site's domain is on the phishing blocklist, all four approval
screens show a red phishing warning before you decide.

You can manage site permissions in Settings. Allowed and denied sites can be
individually removed to reset their permissions.

## Scam Protection

AutistMask includes several defenses against common Ethereum scams, all enabled
by default:

**Known token symbol verification.** AutistMask ships a 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.

**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.

**Fraud contract blocklist.** When AutistMask detects a fraudulent transfer, it
adds the contract address to a local blocklist. Future transactions from that
contract are hidden. This list persists across sessions.

**Dust transaction filtering.** Tiny ETH transfers (below 100,000 gwei / 0.0001
ETH by default) are hidden. Scammers send dust from look-alike addresses to
plant them in your transaction history. The threshold is configurable in
Settings.

**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.

**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.

The first four filters can be individually disabled in Settings if you prefer to
see everything unfiltered.

## Settings

Click the gear icon on the home screen to access settings:

- **Wallets**: 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.

## 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.

**Can I use AutistMask with a hardware wallet?**

Not yet. Hardware wallet support may be added in the future.

**Does AutistMask support networks other than Ethereum mainnet?**

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.

**Where is my data stored?**

In your browser's extension local storage. Your recovery phrases and private
keys are encrypted. Your addresses, balances, and settings are stored
unencrypted (so you can view them without entering a password). Nothing is sent
to any server operated by AutistMask.

**What happens if I uninstall the extension?**

Your data is deleted. Make sure you have your recovery phrase backed up before
uninstalling. With your recovery phrase, you can restore your wallet in
AutistMask or any other wallet that uses the standard derivation path.

**What happens if a transaction times out?**

If AutistMask does not see a confirmation within 60 seconds, it shows an error
screen. This does not mean the transaction failed -- it may still confirm. The
error screen includes an Etherscan link so you can check the transaction status
directly. Network congestion or low gas prices can delay confirmation beyond 60
seconds.

## License

GPL-3.0. See [LICENSE](../LICENSE).

## Author

[@sneak](https://sneak.berlin)