From ba3528209256fc06fda8438b84b98288fb6c8b3d Mon Sep 17 00:00:00 2001 From: clawbot Date: Wed, 12 Aug 2026 10:20:40 +0200 Subject: [PATCH] docs: describe the bundled token list by its criterion, not a drifting count (closes #239) --- 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