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