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

MetaMask has become bloated with swap UIs, portfolio dashboards, analytics,
tracking, and advertisements. It is no longer a simple wallet. Most alternatives
(Rabby, Rainbow, etc.) only support Chromium browsers, leaving Firefox users
without a usable option.

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

## Hard Guidelines

### What AutistMask Will Always Do

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

- **Encrypt your recovery phrase and private keys at rest.** Your secrets are
  encrypted on disk using Argon2id key derivation and XSalsa20-Poly1305
  authenticated encryption (via libsodium). Your password is required only when
  signing a transaction. Viewing balances and addresses never requires a
  password.

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

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

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

### What AutistMask Will Never Do

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

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

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

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

- **No token auto-discovery.** AutistMask does not scan the blockchain for
  tokens you might hold. You add tokens manually by contract address. This
  prevents scam tokens from appearing in your wallet uninvited.

- **No phishing blocklists from third parties.** AutistMask does not phone home
  to check URLs against a remote blocklist. It does maintain a local list of
  known scam addresses, but this is shipped with the extension, not fetched from
  a server.

## How It Works

AutistMask is a browser extension that runs entirely in your browser. It does
not have a backend server. It communicates with three external services:

### External Services

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

This is how AutistMask talks to the Ethereum network. Every wallet needs an
Ethereum node to check balances, estimate gas, broadcast transactions, and
verify confirmations. The default is a free public RPC endpoint. You can change
this in Settings to any Ethereum JSON-RPC endpoint, including your own local
node.

What gets sent: standard Ethereum JSON-RPC requests (balance queries,
transaction broadcasts, gas estimates, ENS lookups). Your addresses are
necessarily visible to the RPC provider when querying balances.

**Blockscout API** (default: `eth.blockscout.com/api/v2`)

Used to fetch token balances and transaction history. Blockscout is an
open-source blockchain explorer. AutistMask queries it for your ERC-20 token
balances and recent transactions. You can change this in Settings to a
self-hosted Blockscout instance.

What gets sent: your Ethereum addresses (to look up balances and transactions).

**CoinDesk CADLI price API** (`data-api.coindesk.com`)

Used to fetch current USD prices for ETH and ERC-20 tokens. Prices are cached
for 5 minutes. No API key is required. No user data is sent -- only a list of
token symbols (e.g. "ETH", "USDC") to get their prices.

What gets sent: token symbol names. No addresses, no balances, no identifying
information.

### What Stays Local

- Your recovery phrases and private keys (encrypted with your password)
- Your wallet configuration (which wallets, which addresses, which tokens)
- Your site permissions (which sites you have allowed or denied)
- Your spam filter settings and detected fraud contract list

None of this data leaves your browser.

### Encryption

When you create or import a wallet, you choose a password. This password is used
to encrypt your recovery phrase (or private key) on disk. The encryption uses
Argon2id for key derivation (memory-hard, resistant to GPU brute-force) and
XSalsa20-Poly1305 for authenticated encryption (tamper-proof).

Your password is **not** part of your recovery phrase. Anyone with your 12 or 24
word recovery phrase can restore your wallet on any device without your
password. The password only protects the copy stored in this browser. If you
lose your recovery phrase, your password cannot help you recover it.

Your password is only requested when you send a transaction. Viewing balances,
receiving funds, and browsing transaction history never require your password.

## Installation

### Chrome

1. Download or build the extension (the `dist/chrome/` directory).
2. Navigate to `chrome://extensions/`.
3. Enable "Developer mode" (toggle in the top right).
4. Click "Load unpacked" and select the `dist/chrome/` directory.

### Firefox

1. Download or build the extension (the `dist/firefox/` directory).
2. Navigate to `about:debugging#/runtime/this-firefox`.
3. Click "Load Temporary Add-on".
4. Select `dist/firefox/manifest.json`.

## Getting Started

### Creating a New Wallet

1. Click the AutistMask icon in your browser toolbar.
2. Click "Add wallet".
3. Click the die button to generate a random 12-word recovery phrase.
4. **Write down the recovery phrase and store it safely.** Anyone with these
   words can take your funds. If you lose them, your wallet is gone. AutistMask
   cannot recover them for you.
5. Choose a password. This encrypts your recovery phrase on this device.
6. Click "Add".

### Importing an Existing Wallet

**From a recovery phrase:** Follow the same steps as creating a wallet, but
paste your existing 12 or 24 word recovery phrase instead of generating a new
one. AutistMask uses the same derivation path as MetaMask (`m/44'/60'/0'/0`), so
your addresses will match.

**From a private key:** On the Add Wallet screen, click "Have a private key
instead?" and paste your private key. This creates a single-address wallet.

### Adding More Addresses

HD wallets (created from a recovery phrase) can derive multiple addresses. On
the home screen, click the "+" button next to a wallet name to add the next
address. These are deterministic -- the same recovery phrase will always produce
the same sequence of addresses.

### Adding ERC-20 Tokens

AutistMask does not auto-discover tokens. To track a token:

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

The token balance will appear on the address detail screen and on the home
screen.

## Sending

1. Click "Send" from the home screen or an address detail view.
2. Select what to send (ETH or any tracked ERC-20 token).
3. Enter the recipient address or ENS name (e.g. `vitalik.eth`).
4. Enter the amount.
5. Click "Review" to see the confirmation screen.

The confirmation screen shows:

- **Transaction type** (native ETH transfer or ERC-20 token transfer)
- **Token contract address** with Etherscan link (for ERC-20 tokens)
- **From and To addresses** with identicons and Etherscan links
- **Amount** with USD estimate
- **Your current balance** with USD estimate
- **Estimated network fee** in ETH with USD estimate

After reviewing, click "Send" and enter your password. The transaction will be
broadcast to the network and you will see a waiting screen with a timer. Once
confirmed (or after 60 seconds), you will see either a success or error screen
with the transaction hash and an Etherscan link.

### Sending a Specific Token

You can also send from a token-specific view: on the address detail screen,
click any token balance row. This opens a focused view showing only that token's
transactions. Clicking "Send" from here pre-selects and locks the token so you
cannot accidentally switch to a different one.

## Receiving

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

When receiving ERC-20 tokens, make sure the sender is sending on the Ethereum
network. AutistMask is an Ethereum mainnet wallet. Tokens sent on other networks
(Polygon, Arbitrum, BSC, etc.) to the same address will not appear and may be
permanently lost.

## Connecting to Web3 Sites

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

1. A popup appears showing the site's hostname and the address that will be
   shared.
2. Click "Allow" to connect or "Deny" to reject.
3. Optionally check "Remember my choice for this site" to skip the prompt next
   time.

When a connected site requests a transaction, a separate approval popup appears
showing the transaction details (from, to, value, data). You must enter your
password and click "Confirm" to authorize it.

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

## Scam Protection

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

**Known token symbol verification.** AutistMask ships a list of ~250 legitimate
ERC-20 tokens with their contract addresses. If a transaction claims to involve
a known symbol (like "ETH" or "USDT") but comes from an unrecognized contract,
it is identified as a spoof and hidden.

**Low-holder token filtering.** Tokens with fewer than 1,000 holders are hidden
from transaction history and the send token list. Legitimate tokens have
substantial holder counts; scam tokens deployed for address poisoning typically
have zero.

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

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

All of these filters can be individually disabled in Settings if you prefer to
see everything unfiltered.

## Settings

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

- **Wallets**: Add a new wallet.
- **Display**: Toggle whether tracked tokens with zero balance are shown.
- **Ethereum RPC**: Change the Ethereum node endpoint. Default is a public RPC.
  You can use your own node for maximum privacy.
- **Blockscout API**: Change the Blockscout instance used for token balances and
  transaction history. You can use a self-hosted instance.
- **Token Spam Protection**: Toggle individual scam filters and set the dust
  transaction threshold.
- **Allowed Sites / Denied Sites**: View and manage web3 site permissions.

## Frequently Asked Questions

**Is AutistMask compatible with MetaMask?**

Yes. AutistMask uses the same derivation path (`m/44'/60'/0'/0`) as MetaMask. If
you import the same recovery phrase, you will get the same addresses. You can
use both wallets side by side, though only one can be the active
`window.ethereum` provider at a time.

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

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

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

Not currently. AutistMask is Ethereum mainnet only. Multi-chain support may be
added in the future.

**Where is my data stored?**

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

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

Your data is deleted. Make sure you have your recovery phrase backed up before
uninstalling. With your recovery phrase, you can restore your wallet in
AutistMask or any other compatible wallet (MetaMask, etc.) at any time.

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

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

## License

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

## Author

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