docs: docs/README.md names competitors and contradicts the code on external services #163

New Issue

clawbot · 2026-08-09T03:46:30+02:00

clawbot commented

2026-08-09 03:46:30 +02:00

Problem

docs/README.md (the user guide) violates the repo's own stated policy and is
factually wrong about what the extension does on the network.

1. Competitor names. README.md:904-905 states the policy: "We don't
mention 'the other wallet' by name in code or documentation. We're our own
thing." RULES.md:121 restates it: "No competitor mentioned by name in code or
documentation." docs/README.md breaks this repeatedly — MetaMask is named
five times (the opening "Why AutistMask Exists" paragraph, the derivation-path
note under "Importing an Existing Wallet", and twice in the FAQ), and Rabby and
Rainbow are both named in the same opening paragraph.

Note the top-level README.md:9-12 handles the identical point correctly
without naming anyone ("The most popular browser-based EVM wallet has a cute
mascot, but sucks now"). Use that as the model.

2. Factually wrong: phishing blocklist. docs/README.md asserts under
"What AutistMask Will Never Do": "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."

That is false. src/shared/phishingDomains.js:16-17 fetches a remote blocklist
over the network, on every background startup (src/background/index.js:618)
and on a timer (:619). The top-level README.md:816-829 documents this
correctly, so the two documents directly contradict each other and the user
guide is the wrong one.

3. Undercounts the external services. docs/README.md says "It
communicates with three external services" and lists RPC, Blockscout, and
CoinDesk. The top-level README.md:611-623 documents two more: the phishing
blocklist fetch and the best-effort Etherscan address-label lookup
(src/shared/etherscanLabels.js). A privacy-focused user guide that omits two
network destinations is the most consequential kind of doc bug this repo can
have.

4. Wrong about when the password is needed. docs/README.md says "Your
password is only requested when you send a transaction" and "Your password is
only requested when you send a transaction. Viewing balances, receiving funds,
and browsing transaction history never require your password." Message signing
and typed-data signing also require the password (SignApproval), as does
deleting a wallet (src/popup/views/deleteWallet.js:52) and exporting a
private key (src/popup/views/addressDetail.js:338).

5. Documents a control that does not exist. docs/README.md tells the user
to click a "Have a private key instead?" link on the Add Wallet screen. There
is no such link; src/popup/index.html:63-84 implements three tabs
(tab-mnemonic, tab-privkey, tab-xprv) wired at
src/popup/views/addWallet.js:280-282.

6. Settings section is stale. It omits the network selector, the theme
selector, the UTC-timestamps option, the tracked-token list, "+ Add token", and
the About well — all of which exist and are reachable.

Scope

This is a documentation-only change. Touch docs/README.md and nothing
else. Do not change code, and do not change the top-level README.md — the
Screen Map and TODO corrections there are tracked separately.

The isMetaMask: true property at src/content/inpage.js:68 is a code
instance of the same policy problem but is a deliberate dApp-compatibility
shim; it is being raised with the owner separately. Leave it alone here.

Definition of done

No competitor is named anywhere in docs/README.md. Rewrite the
affected passages in the style of README.md:9-12 — the point survives
without the names. The derivation-path compatibility note must still tell
the user what they need to know (that the standard m/44'/60'/0'/0 path
is used, so phrases are portable to and from other wallets) without
naming one.
The false "no remote phishing blocklist" claim is removed and replaced
with an accurate description matching README.md:816-829 and the code.
The external-services section lists every destination the extension
actually contacts, matching README.md:573-627: RPC, CoinDesk,
Blockscout, the phishing blocklist fetch, and the Etherscan label
lookup — each with what data is sent.
The password statements are corrected to cover transaction signing,
message signing, typed-data signing, wallet deletion, and private key
export.
The "Have a private key instead?" instruction is replaced with the
actual tabbed UI, including the xprv tab.
The Settings section matches what Settings actually contains today.
Every factual claim remaining in the file has been checked against the
code. State in the PR which claims were verified and how.
make fmt has been run and the formatted result is in the commit
(prettier, 4-space, proseWrap: always).
TODO.md updated in the same commit.
make check passes.

## Problem `docs/README.md` (the user guide) violates the repo's own stated policy and is factually wrong about what the extension does on the network. **1. Competitor names.** `README.md:904-905` states the policy: "We don't mention 'the other wallet' by name in code or documentation. We're our own thing." `RULES.md:121` restates it: "No competitor mentioned by name in code or documentation." `docs/README.md` breaks this repeatedly — MetaMask is named five times (the opening "Why AutistMask Exists" paragraph, the derivation-path note under "Importing an Existing Wallet", and twice in the FAQ), and Rabby and Rainbow are both named in the same opening paragraph. Note the top-level `README.md:9-12` handles the identical point correctly without naming anyone ("The most popular browser-based EVM wallet has a cute mascot, but sucks now"). Use that as the model. **2. Factually wrong: phishing blocklist.** `docs/README.md` asserts under "What AutistMask Will Never Do": "**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." That is false. `src/shared/phishingDomains.js:16-17` fetches a remote blocklist over the network, on every background startup (`src/background/index.js:618`) and on a timer (`:619`). The top-level `README.md:816-829` documents this correctly, so the two documents directly contradict each other and the user guide is the wrong one. **3. Undercounts the external services.** `docs/README.md` says "It communicates with three external services" and lists RPC, Blockscout, and CoinDesk. The top-level `README.md:611-623` documents two more: the phishing blocklist fetch and the best-effort Etherscan address-label lookup (`src/shared/etherscanLabels.js`). A privacy-focused user guide that omits two network destinations is the most consequential kind of doc bug this repo can have. **4. Wrong about when the password is needed.** `docs/README.md` says "Your password is only requested when you send a transaction" and "Your password is only requested when you send a transaction. Viewing balances, receiving funds, and browsing transaction history never require your password." Message signing and typed-data signing also require the password (SignApproval), as does deleting a wallet (`src/popup/views/deleteWallet.js:52`) and exporting a private key (`src/popup/views/addressDetail.js:338`). **5. Documents a control that does not exist.** `docs/README.md` tells the user to click a "Have a private key instead?" link on the Add Wallet screen. There is no such link; `src/popup/index.html:63-84` implements three tabs (`tab-mnemonic`, `tab-privkey`, `tab-xprv`) wired at `src/popup/views/addWallet.js:280-282`. **6. Settings section is stale.** It omits the network selector, the theme selector, the UTC-timestamps option, the tracked-token list, "+ Add token", and the About well — all of which exist and are reachable. ## Scope This is a **documentation-only** change. Touch `docs/README.md` and nothing else. Do not change code, and do not change the top-level `README.md` — the Screen Map and TODO corrections there are tracked separately. The `isMetaMask: true` property at `src/content/inpage.js:68` is a *code* instance of the same policy problem but is a deliberate dApp-compatibility shim; it is being raised with the owner separately. Leave it alone here. ## Definition of done - [ ] No competitor is named anywhere in `docs/README.md`. Rewrite the affected passages in the style of `README.md:9-12` — the point survives without the names. The derivation-path compatibility note must still tell the user what they need to know (that the standard `m/44'/60'/0'/0` path is used, so phrases are portable to and from other wallets) without naming one. - [ ] The false "no remote phishing blocklist" claim is removed and replaced with an accurate description matching `README.md:816-829` and the code. - [ ] The external-services section lists every destination the extension actually contacts, matching `README.md:573-627`: RPC, CoinDesk, Blockscout, the phishing blocklist fetch, and the Etherscan label lookup — each with what data is sent. - [ ] The password statements are corrected to cover transaction signing, message signing, typed-data signing, wallet deletion, and private key export. - [ ] The "Have a private key instead?" instruction is replaced with the actual tabbed UI, including the xprv tab. - [ ] The Settings section matches what Settings actually contains today. - [ ] Every factual claim remaining in the file has been checked against the code. State in the PR which claims were verified and how. - [ ] `make fmt` has been run and the formatted result is in the commit (prettier, 4-space, `proseWrap: always`). - [ ] `TODO.md` updated in the same commit. - [ ] `make check` passes.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:46:30 +02:00

clawbot referenced this issue from a commit

2026-08-11 14:22:34 +02:00

docs: correct docs/README.md external services and remove competitor names (closes #163)

clawbot referenced a pull request that will close this issue

2026-08-11 14:23:04 +02:00

docs: correct docs/README.md external services and remove competitor names (closes #163) #199

clawbot referenced this issue from a commit

2026-08-11 14:23:59 +02:00

docs: correct docs/README.md external services and remove competitor names (closes #163)

clawbot closed this issue

2026-08-11 14:25:58 +02:00