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
+balance is nonzero and it is in the bundled known-token list, is tracked by the
-the user, or has 1,000 or more holders; a token claiming a symbol from the
+user, or has 1,000 or more holders; a token claiming a symbol from the bundled
-bundled list from any other contract address is always dropped. That filter is
+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
+- View ERC-20 token balances (tokens on the bundled known-token list, tokens
-  holders, and tokens the user adds by contract address)
+  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
+- **Known token symbol verification**: AutistMask ships a hardcoded list of
-  top 250 ERC-20 tokens with their legitimate contract addresses and symbols.
+  high-market-cap ERC-20 tokens with their legitimate contract addresses and
-  Any token transfer claiming a symbol from this list (e.g. "ETH", "USDT",
+  symbols. The list is a point-in-time snapshot of the highest-market-cap
-  "USDC") but originating from an unrecognized contract address is identified as
+  Ethereum mainnet ERC-20s taken from the CoinGecko API, with decimals verified
-  a spoof and filtered from display. The fake "Ethereum" token in the attack
+  on-chain and addresses EIP-55 checksummed; `TOKENS` in
-  above used symbol "ETH" from contract
+  `src/shared/tokenList.js` is the authoritative set. It is bundled at build
-  `0xD05339f9Ea5ab9d9F03B9d57F671d2abD1F55c82`, which does not match the known
+  time and only changes when that file is regenerated. Any token transfer
-  WETH contract — so it would be caught by this check. Detecting a spoof is also
+  claiming a symbol from this list (e.g. "ETH", "USDT", "USDC") but originating
-  what adds a contract to the fraud contract blocklist below; that is the only
+  from an unrecognized contract address is identified as a spoof and filtered
-  thing that populates it. In the transaction history the check is the "Hide
+  from display. The fake "Ethereum" token in the attack above used symbol "ETH"
-  fake tokens impersonating a known symbol" setting, on by default; with it off,
+  from contract `0xD05339f9Ea5ab9d9F03B9d57F671d2abD1F55c82`, which does not
-  spoofed transfers are shown and no new blocklist entries are learned from
+  match the known WETH contract — so it would be caught by this check. Detecting
-  them. The send-screen token selector applies the same check unconditionally,
+  a spoof is also what adds a contract to the fraud contract blocklist below;
-  because it decides which tokens the user can act on rather than what the
+  that is the only thing that populates it. In the transaction history the check
-  history displays. The balance list applies it unconditionally too, but not
+  is the "Hide fake tokens impersonating a known symbol" setting, on by default;
-  identically: it exempts symbols that `KNOWN_SYMBOLS` maps to `null`, and
+  with it off, spoofed transfers are shown and no new blocklist entries are
-  `"ETH"` is the only one. So the fake "Ethereum" token above is filtered from
+  learned from them. The send-screen token selector applies the same check
-  the transaction history and from the send selector, but a fake-`ETH` ERC-20
+  unconditionally, because it decides which tokens the user can act on rather
-  that clears the balance list's own 1,000-holder floor — or that the user
+  than what the history displays. The balance list applies it unconditionally
-  tracked manually — is still shown in the balance list.
+  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.

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

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
+**Known token symbol verification.** AutistMask ships a bundled list of
-legitimate ERC-20 tokens with their contract addresses. If a transaction or
+high-market-cap ERC-20 tokens with their legitimate contract addresses — a
-balance claims to involve a known symbol (like "ETH" or "USDT") but comes from
+point-in-time snapshot of the highest-market-cap Ethereum mainnet ERC-20s, fixed
-an unrecognized contract, it is identified as a spoof and hidden. In your
+at build time and updated only when a new release ships a newer snapshot. If a
-transaction history this is the "Hide fake tokens impersonating a known symbol"
+transaction or balance claims to involve a known symbol (like "ETH" or "USDT")
-setting, which you can switch off; doing so also stops new entries being added
+but comes from an unrecognized contract, it is identified as a spoof and hidden.
-to the fraud contract blocklist below, since detecting a spoof is what fills it.
+In your transaction history this is the "Hide fake tokens impersonating a known
-The send token list always applies the check. Your balances apply it too, with
+symbol" setting, which you can switch off; doing so also stops new entries being
-one exception: a token claiming the symbol "ETH" is not filtered there, so a
+added to the fraud contract blocklist below, since detecting a spoof is what
-fake "ETH" token can still show up in your balance list even though it is hidden
+fills it. The send token list always applies the check. Your balances apply it
-from your transaction history and from the send token list.
+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