From 74c137dadff9c501abb9d37405757ab39e20145f Mon Sep 17 00:00:00 2001
From: clawbot <clawbot@noreply.example.org>
Date: Tue, 11 Aug 2026 15:38:05 +0200
Subject: [PATCH] fix: add a Settings toggle for known-symbol spoof
 verification (closes #176)

---
 README.md                        |  33 +++++++--
 TODO.md                          |   4 +
 docs/README.md                   |   9 ++-
 src/popup/index.html             |   9 +++
 src/popup/views/addressDetail.js |   1 +
 src/popup/views/addressToken.js  |   1 +
 src/popup/views/home.js          |   1 +
 src/popup/views/settings.js      |   6 ++
 src/shared/state.js              |   8 ++
 src/shared/transactions.js       |  11 ++-
 tests/state.test.js              |  57 +++++++++++++++
 tests/transactions.test.js       | 122 ++++++++++++++++++++++++++-----
 12 files changed, 234 insertions(+), 28 deletions(-)

diff --git a/README.md b/README.md
index 392c7ef..40ae2c3 100644
--- a/README.md
+++ b/README.md
@@ -728,6 +728,7 @@ of it.
     - Blockscout API: endpoint URL input + "Save" button (validated against
       `/stats` before being saved)
     - Token Spam Protection:
+        - "Hide fake tokens impersonating a known symbol" checkbox
         - "Hide tokens with fewer than 1,000 holders" checkbox
         - "Hide transactions from detected fraud contracts" checkbox
         - "Hide dust transactions below N gwei" checkbox + threshold input
@@ -1116,7 +1117,19 @@ indexes it as a real token transfer.
   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.
+  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.
@@ -1146,11 +1159,19 @@ indexes it as a real token transfer.
   about. The threshold is user-configurable in Settings; a threshold of `0`
   hides nothing, exactly as clearing the checkbox does.
 
-- **User-configurable**: All of the above filters (known symbol verification,
-  low-holder threshold, fraud contract blocklist, dust threshold) are settings
-  that default to on but can be individually disabled by the user. AutistMask is
-  designed as a sharp tool — users who understand the risks can configure the
-  wallet to show everything unfiltered, unix-style.
+- **User-configurable**: All four filters (known symbol verification, low-holder
+  threshold, fraud contract blocklist, dust threshold) are settings that default
+  to on but can be individually disabled by the user. AutistMask is designed as
+  a sharp tool — users who understand the risks can configure the wallet to show
+  everything unfiltered, unix-style. All four settings govern the transaction
+  history; what else each one reaches varies. The known-symbol check also runs
+  unconditionally on the send-screen token selector, and on the balance list
+  except for symbols mapped to `null` (`"ETH"` alone), which the balance list
+  does not filter. The fraud contract blocklist is applied unconditionally on
+  that selector and is not consulted by the balance list at all. The low-holder
+  setting also gates the send selector, while the balance list's own
+  1,000-holder floor is unconditional (see Data Model). The dust threshold
+  applies to the transaction history alone.
 
 #### Phishing Domain Protection
 
diff --git a/TODO.md b/TODO.md
index 65a9a57..fabbb81 100644
--- a/TODO.md
+++ b/TODO.md
@@ -44,6 +44,10 @@ undefined identifiers, which is how
 
 # Completed Steps
 
+- 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
+  ([#176](https://git.eeqj.de/sneak/AutistMask/issues/176)).
 - 2026-08-11: `script/verify-build` now walks `dist/` NUL-delimited and asserts
   `dist/` is a real directory, so a path with a trailing space or a newline can
   no longer carry a debug marker past the unlisted-bundle check
diff --git a/docs/README.md b/docs/README.md
index 08f244a..25e985a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -323,7 +323,14 @@ 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.
+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
diff --git a/src/popup/index.html b/src/popup/index.html
index 75c1dac..2c02f0d 100644
--- a/src/popup/index.html
+++ b/src/popup/index.html
@@ -956,6 +956,15 @@
                         transfers and prevent interaction with suspicious
                         tokens.
                     </p>
+                    <label
+                        class="text-xs flex items-center gap-1 cursor-pointer mb-2"
+                    >
+                        <input
+                            type="checkbox"
+                            id="settings-hide-spoofed-symbols"
+                        />
+                        Hide fake tokens impersonating a known symbol
+                    </label>
                     <label
                         class="text-xs flex items-center gap-1 cursor-pointer mb-2"
                     >
diff --git a/src/popup/views/addressDetail.js b/src/popup/views/addressDetail.js
index 006e3ae..aaf5864 100644
--- a/src/popup/views/addressDetail.js
+++ b/src/popup/views/addressDetail.js
@@ -148,6 +148,7 @@ async function loadTransactions(address) {
             state.blockscoutUrl,
         );
         const result = filterTransactions(rawTxs, {
+            hideSpoofedSymbols: state.hideSpoofedSymbols,
             hideLowHolderTokens: state.hideLowHolderTokens,
             hideFraudContracts: state.hideFraudContracts,
             hideDustTransactions: state.hideDustTransactions,
diff --git a/src/popup/views/addressToken.js b/src/popup/views/addressToken.js
index 145e562..2193632 100644
--- a/src/popup/views/addressToken.js
+++ b/src/popup/views/addressToken.js
@@ -222,6 +222,7 @@ async function loadTransactions(address, tokenId) {
             state.blockscoutUrl,
         );
         const result = filterTransactions(rawTxs, {
+            hideSpoofedSymbols: state.hideSpoofedSymbols,
             hideLowHolderTokens: state.hideLowHolderTokens,
             hideFraudContracts: state.hideFraudContracts,
             hideDustTransactions: state.hideDustTransactions,
diff --git a/src/popup/views/home.js b/src/popup/views/home.js
index 32d1d64..52b631f 100644
--- a/src/popup/views/home.js
+++ b/src/popup/views/home.js
@@ -163,6 +163,7 @@ async function loadHomeTxs(ctx) {
     if (allAddresses.length === 0) return;
 
     const filters = {
+        hideSpoofedSymbols: state.hideSpoofedSymbols,
         hideLowHolderTokens: state.hideLowHolderTokens,
         hideFraudContracts: state.hideFraudContracts,
         hideDustTransactions: state.hideDustTransactions,
diff --git a/src/popup/views/settings.js b/src/popup/views/settings.js
index 3727dcb..f3ca461 100644
--- a/src/popup/views/settings.js
+++ b/src/popup/views/settings.js
@@ -303,6 +303,12 @@ function init(ctx) {
         applyTheme(state.theme);
     });
 
+    $("settings-hide-spoofed-symbols").checked = state.hideSpoofedSymbols;
+    $("settings-hide-spoofed-symbols").addEventListener("change", async () => {
+        state.hideSpoofedSymbols = $("settings-hide-spoofed-symbols").checked;
+        await saveState();
+    });
+
     $("settings-hide-low-holders").checked = state.hideLowHolderTokens;
     $("settings-hide-low-holders").addEventListener("change", async () => {
         state.hideLowHolderTokens = $("settings-hide-low-holders").checked;
diff --git a/src/shared/state.js b/src/shared/state.js
index 14e76eb..b7e627f 100644
--- a/src/shared/state.js
+++ b/src/shared/state.js
@@ -21,6 +21,7 @@ const DEFAULT_STATE = {
     deniedSites: {},
     rememberSiteChoice: true,
     showZeroBalanceTokens: true,
+    hideSpoofedSymbols: true,
     hideLowHolderTokens: true,
     hideFraudContracts: true,
     hideDustTransactions: true,
@@ -61,6 +62,7 @@ async function saveState() {
         deniedSites: state.deniedSites,
         rememberSiteChoice: state.rememberSiteChoice,
         showZeroBalanceTokens: state.showZeroBalanceTokens,
+        hideSpoofedSymbols: state.hideSpoofedSymbols,
         hideLowHolderTokens: state.hideLowHolderTokens,
         hideFraudContracts: state.hideFraudContracts,
         hideDustTransactions: state.hideDustTransactions,
@@ -112,6 +114,12 @@ async function loadState() {
             saved.showZeroBalanceTokens !== undefined
                 ? saved.showZeroBalanceTokens
                 : true;
+        // A profile written before this setting existed has no key for it.
+        // It is a safety filter, so absent must load as on, not as undefined.
+        state.hideSpoofedSymbols =
+            saved.hideSpoofedSymbols !== undefined
+                ? saved.hideSpoofedSymbols
+                : true;
         state.hideLowHolderTokens =
             saved.hideLowHolderTokens !== undefined
                 ? saved.hideLowHolderTokens
diff --git a/src/shared/transactions.js b/src/shared/transactions.js
index 9941dbc..ee7a9fe 100644
--- a/src/shared/transactions.js
+++ b/src/shared/transactions.js
@@ -267,12 +267,19 @@ function filterTransactions(txs, filters = {}) {
     const dustThresholdGwei = filters.dustThresholdGwei ?? 100000;
     const newFraud = [];
     const filtered = [];
+    // Fail-safe, unlike the three flags below: this one is off only when the
+    // caller says so explicitly, so a caller that omits the key keeps the
+    // check rather than silently losing it.  The setting also governs the
+    // blocklist learning below, which exists only to serve this check —
+    // leaving learning on while the check is off would re-hide the very rows
+    // the user asked to see, through the fraud-contract rule.
+    const hideSpoofed = filters.hideSpoofedSymbols !== false;
 
     for (const tx of txs) {
         const contract = normalizeAddress(tx.contractAddress);
 
-        // Always filter spoofed known symbols and record the fraud contract
-        if (isSpoofedSymbol(tx)) {
+        // Filter spoofed known symbols and record the fraud contract
+        if (hideSpoofed && isSpoofedSymbol(tx)) {
             if (contract && !fraudSet.has(contract)) {
                 fraudSet.add(contract);
                 newFraud.push(contract);
diff --git a/tests/state.test.js b/tests/state.test.js
index 353d7e6..70a1ef0 100644
--- a/tests/state.test.js
+++ b/tests/state.test.js
@@ -102,3 +102,60 @@ describe("loadState hasWallet reconciliation", () => {
         expect(mod.state.activeAddress).toBe(ADDRESS);
     });
 });
+
+// The known-symbol spoof filter is a safety filter, so an existing profile
+// stored before the setting existed must load with it on rather than with
+// undefined, which would read as off.
+describe("hideSpoofedSymbols persistence", () => {
+    test("defaults to on with empty storage", async () => {
+        const { mod } = loadModuleWith(null);
+        await mod.loadState();
+        expect(mod.state.hideSpoofedSymbols).toBe(true);
+    });
+
+    test("a profile stored without the key loads with it on", async () => {
+        const { mod } = loadModuleWith({ wallets: oneWallet() });
+        await mod.loadState();
+        expect(mod.state.hideSpoofedSymbols).toBe(true);
+    });
+
+    test("an explicit false survives the load", async () => {
+        const { mod } = loadModuleWith({
+            wallets: oneWallet(),
+            hideSpoofedSymbols: false,
+        });
+        await mod.loadState();
+        expect(mod.state.hideSpoofedSymbols).toBe(false);
+    });
+
+    test("saveState persists the flag", async () => {
+        const { mod, set } = loadModuleWith(null);
+        mod.state.hideSpoofedSymbols = false;
+        await mod.saveState();
+        expect(set).toHaveBeenCalledWith({
+            autistmask: expect.objectContaining({ hideSpoofedSymbols: false }),
+        });
+    });
+
+    test("the flag round-trips off through save and load", async () => {
+        const first = loadModuleWith(null);
+        first.mod.state.hideSpoofedSymbols = false;
+        await first.mod.saveState();
+        const persisted = first.set.mock.calls[0][0].autistmask;
+
+        const second = loadModuleWith(persisted);
+        await second.mod.loadState();
+        expect(second.mod.state.hideSpoofedSymbols).toBe(false);
+    });
+
+    test("the flag round-trips back on through save and load", async () => {
+        const first = loadModuleWith(null);
+        first.mod.state.hideSpoofedSymbols = true;
+        await first.mod.saveState();
+        const persisted = first.set.mock.calls[0][0].autistmask;
+
+        const second = loadModuleWith(persisted);
+        await second.mod.loadState();
+        expect(second.mod.state.hideSpoofedSymbols).toBe(true);
+    });
+});
diff --git a/tests/transactions.test.js b/tests/transactions.test.js
index a9d51d5..d7c6043 100644
--- a/tests/transactions.test.js
+++ b/tests/transactions.test.js
@@ -78,6 +78,7 @@ const ORDINARY_PEER = "0x5aa0f9f1e0a1d0e0e5c1e7ce3b7dbbe9c19f0a11";
 
 // The documented default settings (README.md:810-814, state.js:24-27).
 const DEFAULT_FILTERS = {
+    hideSpoofedSymbols: true,
     hideLowHolderTokens: true,
     hideFraudContracts: true,
     hideDustTransactions: true,
@@ -367,30 +368,112 @@ describe("known-symbol spoof verification", () => {
         expect(result.newFraudContracts).toEqual([FAKE_ETH_CONTRACT]);
     });
 
-    // Documents current behaviour: README.md:810-814 says all four filters
-    // "default to on but can be individually disabled".  There is no setting
-    // for known-symbol verification, and filterTransactions applies it
-    // unconditionally, so it cannot be turned off.
-    test("current behaviour: spoof filtering cannot be disabled by any setting", () => {
-        const allFiltersOff = {
-            hideLowHolderTokens: false,
-            hideFraudContracts: false,
-            hideDustTransactions: false,
-            dustThresholdGwei: 1,
-            fraudContracts: [],
-        };
+    // Turning the other three filters off must not turn this one off: each
+    // filter is independent, and this is the one the README calls out as the
+    // defense against the fake "ETH" attack.
+    test("the check still runs when the other three filters are off", () => {
         const result = filterTransactions(
             [fakeEthTokenTransfer()],
-            allFiltersOff,
+            filters({
+                hideLowHolderTokens: false,
+                hideFraudContracts: false,
+                hideDustTransactions: false,
+                dustThresholdGwei: 1,
+            }),
         );
         expect(result.transactions).toEqual([]);
         expect(result.newFraudContracts).toEqual([FAKE_ETH_CONTRACT]);
     });
 
-    test("current behaviour: spoof filtering also applies with no filters argument", () => {
+    test("spoof filtering also applies with no filters argument", () => {
         const result = filterTransactions([fakeEthTokenTransfer()]);
         expect(result.transactions).toEqual([]);
     });
+
+    // Fail-safe: unlike the other three flags, an absent hideSpoofedSymbols
+    // leaves the check ON.  A caller that forgets the key keeps the wallet's
+    // headline protection; only a user who deliberately switched the setting
+    // off sends an explicit false.
+    test("an absent hideSpoofedSymbols leaves the check on", () => {
+        const result = filterTransactions([fakeEthTokenTransfer()], {
+            fraudContracts: [],
+        });
+        expect(result.transactions).toEqual([]);
+    });
+
+    test("a truthy-but-not-true hideSpoofedSymbols leaves the check on", () => {
+        const result = filterTransactions(
+            [fakeEthTokenTransfer()],
+            filters({ hideSpoofedSymbols: undefined }),
+        );
+        expect(result.transactions).toEqual([]);
+    });
+});
+
+describe("disabling known-symbol spoof verification", () => {
+    test("the spoofed transfer is shown when hideSpoofedSymbols is false", () => {
+        const attack = fakeEthTokenTransfer();
+        const result = filterTransactions(
+            [attack],
+            filters({
+                hideSpoofedSymbols: false,
+                // The blocklist rule would otherwise hide the same row via a
+                // contract this pass had already learned.
+                hideFraudContracts: false,
+                hideLowHolderTokens: false,
+            }),
+        );
+        expect(result.transactions).toEqual([attack]);
+    });
+
+    // The blocklist is populated only by this check, so switching the check
+    // off stops the learning too.  Leaving learning on would make the setting
+    // a no-op: the contract it recorded would immediately hide the same row
+    // through the fraud-contract rule, which is on by default.
+    test("no fraud contract is learned when hideSpoofedSymbols is false", () => {
+        const result = filterTransactions(
+            [fakeEthTokenTransfer()],
+            filters({ hideSpoofedSymbols: false }),
+        );
+        expect(result.newFraudContracts).toEqual([]);
+    });
+
+    test("the setting off does not stop the other three rules", () => {
+        const dust = nativeDustTransfer();
+        const lowHolder = tokenTx({
+            symbol: NOVEL_SPAM_SYMBOL,
+            contractAddress: NOVEL_SPAM_CONTRACT,
+            holders: 0,
+        });
+        const result = filterTransactions(
+            [dust, lowHolder],
+            filters({ hideSpoofedSymbols: false }),
+        );
+        expect(result.transactions).toEqual([]);
+    });
+
+    // An already-persisted fraud contract keeps being filtered: the blocklist
+    // rule is a separate setting and is unaffected by this one.
+    test("an already-blocklisted contract is still hidden with the check off", () => {
+        const result = filterTransactions(
+            [fakeEthTokenTransfer()],
+            filters({
+                hideSpoofedSymbols: false,
+                fraudContracts: [FAKE_ETH_CONTRACT],
+            }),
+        );
+        expect(result.transactions).toEqual([]);
+        expect(result.newFraudContracts).toEqual([]);
+    });
+
+    test("a genuine transfer is unaffected by the setting either way", () => {
+        const tx = tokenTx();
+        expect(
+            filterTransactions([tx], filters({ hideSpoofedSymbols: false }))
+                .transactions,
+        ).toEqual([tx]);
+        expect(filterTransactions([tx], filters()).transactions).toEqual([tx]);
+    });
 });
 
 describe("low-holder token filtering (the 1,000-holder rule)", () => {
@@ -662,7 +745,8 @@ describe("dust threshold filtering", () => {
 });
 
 describe("filter defaults promised by the README and Settings", () => {
-    test("all three toggles default to on and the threshold to 100,000 gwei", () => {
+    test("all four toggles default to on and the threshold to 100,000 gwei", () => {
+        expect(state.hideSpoofedSymbols).toBe(true);
         expect(state.hideLowHolderTokens).toBe(true);
         expect(state.hideFraudContracts).toBe(true);
         expect(state.hideDustTransactions).toBe(true);
@@ -673,10 +757,10 @@ describe("filter defaults promised by the README and Settings", () => {
         expect(state.fraudContracts).toEqual([]);
     });
 
-    // Documents current behaviour: filterTransactions itself defaults every
-    // optional filter to off.  The "default to on" promise is satisfied by
-    // the state defaults above, which every caller passes in; the pure
-    // function makes no assumption of its own.
+    // Documents current behaviour: filterTransactions defaults the other three
+    // optional filters to off.  Their "default to on" promise is satisfied by
+    // the state defaults above, which every caller passes in.  Spoof
+    // verification is the exception and stays on unless explicitly disabled.
     test("current behaviour: with no filters argument only spoof filtering runs", () => {
         const dust = nativeDustTransfer();
         const lowHolder = tokenTx({