From 8848432388f0c2b2cde291b93ac985ff0287130a Mon Sep 17 00:00:00 2001 From: clawbot Date: Wed, 12 Aug 2026 08:18:46 +0000 Subject: [PATCH] docs: describe the bundled token list by selection criterion, not count (closes #239) The docs disagreed with the code and with each other about the size of the bundled ERC-20 allowlist: four places in `README.md` said "top 250" and `docs/README.md` said "roughly 500", while `TOKENS` in `src/shared/tokenList.js` has 512 entries. Rather than restate 512 in five places, which drifts again the next time the list is regenerated, the count is dropped and the list is described by how it is actually selected: a point-in-time snapshot of the highest-market-cap Ethereum mainnet ERC-20s taken from the CoinGecko API, decimals verified on-chain and addresses EIP-55 checksummed, bundled at build time. `TOKENS` in `src/shared/tokenList.js` is named as the authoritative set. The four incidental "top-250" mentions become "known-token list", the term the docs already use elsewhere. The "top N by market cap" ranking framing is accurate and is kept; only the number is removed. Documentation only: no code, config, script, CI or build file is touched. --- README.md | 56 +++++++++++++++++++++++++++----------------------- TODO.md | 7 +++++++ docs/README.md | 24 ++++++++++++---------- 3 files changed, 50 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index fa41479..33949f9 100644 --- a/README.md +++ b/README.md @@ -443,9 +443,9 @@ The core hierarchy is **Wallets → Addresses**: Which tokens an address shows is decided by `fetchTokenBalances()` in `src/shared/balances.js`, from the Blockscout `token-balances` response, so tokens do appear without the user adding them. An ERC-20 is shown when its -balance is nonzero and it is in the bundled top-250 token list, is tracked by -the user, or has 1,000 or more holders; a token claiming a symbol from the -bundled list from any other contract address is always dropped. That filter is +balance is nonzero and it is in the bundled known-token list, is tracked by the +user, or has 1,000 or more holders; a token claiming a symbol from the bundled +list from any other contract address is always dropped. That filter is unconditional — the "Hide tokens with fewer than 1,000 holders" setting governs the transaction history and the send-screen token selector, not this list. Tracked tokens with a zero balance are listed as well while "Show tracked tokens @@ -1008,7 +1008,7 @@ communicates with three external services to function as a wallet: What the extension does NOT do: - No analytics or telemetry services -- No token list APIs (the top-250 token list is bundled at build time) +- No token list APIs (the known-token list is bundled at build time) - No Infura/Alchemy dependency (any JSON-RPC endpoint works) - No backend servers operated by the developer @@ -1136,8 +1136,8 @@ hardcoded test phrase. - Add multiple addresses within an HD wallet - Manage multiple wallets simultaneously - View ETH balance per address -- View ERC-20 token balances (bundled top-250 tokens, tokens with 1,000 or more - holders, and tokens the user adds by contract address) +- View ERC-20 token balances (tokens on the bundled known-token list, tokens + with 1,000 or more holders, and tokens the user adds by contract address) - Send ETH to an address - Send ERC-20 tokens to an address - Receive ETH/tokens (display address, copy to clipboard, QR code) @@ -1195,26 +1195,30 @@ indexes it as a real token transfer. address. Users should always verify the full address on the confirmation screen before signing or sending. -- **Known token symbol verification**: AutistMask ships a hardcoded list of the - top 250 ERC-20 tokens with their legitimate contract addresses and symbols. - Any token transfer claiming a symbol from this list (e.g. "ETH", "USDT", - "USDC") but originating from an unrecognized contract address is identified as - a spoof and filtered from display. The fake "Ethereum" token in the attack - above used symbol "ETH" from contract - `0xD05339f9Ea5ab9d9F03B9d57F671d2abD1F55c82`, which does not match the known - WETH contract — so it would be caught by this check. Detecting a spoof is also - what adds a contract to the fraud contract blocklist below; that is the only - thing that populates it. In the transaction history the check is the "Hide - fake tokens impersonating a known symbol" setting, on by default; with it off, - spoofed transfers are shown and no new blocklist entries are learned from - them. The send-screen token selector applies the same check unconditionally, - because it decides which tokens the user can act on rather than what the - history displays. The balance list applies it unconditionally too, but not - identically: it exempts symbols that `KNOWN_SYMBOLS` maps to `null`, and - `"ETH"` is the only one. So the fake "Ethereum" token above is filtered from - the transaction history and from the send selector, but a fake-`ETH` ERC-20 - that clears the balance list's own 1,000-holder floor — or that the user - tracked manually — is still shown in the balance list. +- **Known token symbol verification**: AutistMask ships a hardcoded list of + high-market-cap ERC-20 tokens with their legitimate contract addresses and + symbols. The list is a point-in-time snapshot of the highest-market-cap + Ethereum mainnet ERC-20s taken from the CoinGecko API, with decimals verified + on-chain and addresses EIP-55 checksummed; `TOKENS` in + `src/shared/tokenList.js` is the authoritative set. It is bundled at build + time and only changes when that file is regenerated. Any token transfer + claiming a symbol from this list (e.g. "ETH", "USDT", "USDC") but originating + from an unrecognized contract address is identified as a spoof and filtered + from display. The fake "Ethereum" token in the attack above used symbol "ETH" + from contract `0xD05339f9Ea5ab9d9F03B9d57F671d2abD1F55c82`, which does not + match the known WETH contract — so it would be caught by this check. Detecting + a spoof is also what adds a contract to the fraud contract blocklist below; + that is the only thing that populates it. In the transaction history the check + is the "Hide fake tokens impersonating a known symbol" setting, on by default; + with it off, spoofed transfers are shown and no new blocklist entries are + learned from them. The send-screen token selector applies the same check + unconditionally, because it decides which tokens the user can act on rather + than what the history displays. The balance list applies it unconditionally + too, but not identically: it exempts symbols that `KNOWN_SYMBOLS` maps to + `null`, and `"ETH"` is the only one. So the fake "Ethereum" token above is + filtered from the transaction history and from the send selector, but a + fake-`ETH` ERC-20 that clears the balance list's own 1,000-holder floor — or + that the user tracked manually — is still shown in the balance list. - **Low-holder token filtering**: Token transfers from ERC-20 contracts with fewer than 1,000 holders are hidden from transaction history by default. diff --git a/TODO.md b/TODO.md index 9435e5a..dcc905f 100644 --- a/TODO.md +++ b/TODO.md @@ -44,6 +44,13 @@ undefined identifiers, which is how # Completed Steps +- 2026-08-12: Bundled token list documentation no longer states a count. The + four "top 250" claims in `README.md` and the "roughly 500" claim in + `docs/README.md` are replaced with a description of how the list is actually + selected — a point-in-time CoinGecko snapshot of the highest-market-cap + Ethereum mainnet ERC-20s — with `TOKENS` in `src/shared/tokenList.js` named as + the authoritative set + ([#239](https://git.eeqj.de/sneak/AutistMask/issues/239)). - 2026-08-11: Known-symbol spoof verification became a Settings toggle (`hideSpoofedSymbols`), on by default, governing the transaction-history filter and the fraud-contract learning it feeds diff --git a/docs/README.md b/docs/README.md index b56b2fd..25da4cc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -327,17 +327,19 @@ individually removed to reset their permissions. AutistMask includes several defenses against common Ethereum scams, all enabled by default: -**Known token symbol verification.** AutistMask ships a list of roughly 500 -legitimate ERC-20 tokens with their contract addresses. 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. +**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 -- 2.49.1