fix: distinguish an unknown holder count from zero so a legitimate token is not filtered (closes #230)

tests/transactions.test.js

@@ -1473,6 +1473,65 @@ describe("fetchRecentTransactions merge and dedup", () => {
         expect(result.newFraudContracts).toEqual([FAKE_ETH_CONTRACT]);
     });
 
+    // Regression guards (#230): the explorer's holders_count is optional.  A
+    // missing field means the count is unknown; it does not mean the token
+    // has no holders.  Recording the two as the same number both hides a
+    // legitimate token and makes the `holders !== null` guard in
+    // filterTransactions unreachable for token transfers.
+    describe("an unreported holders_count is unknown, not zero", () => {
+        function spamTransferWithToken(token) {
+            return [
+                {
+                    transaction_hash: "0x" + "9".repeat(64),
+                    block_number: 21000070,
+                    timestamp: TS,
+                    from: { hash: ORDINARY_PEER },
+                    to: { hash: VICTIM },
+                    total: { value: "1500500000", decimals: "6" },
+                    token: token,
+                },
+            ];
+        }
+
+        const OMITTED = {
+            symbol: NOVEL_SPAM_SYMBOL,
+            address_hash: NOVEL_SPAM_CONTRACT,
+        };
+        const NULLED = { ...OMITTED, holders_count: null };
+        const ZERO = { ...OMITTED, holders_count: "0" };
+
+        test("an omitted holders_count parses to null", async () => {
+            respondWith([], spamTransferWithToken(OMITTED));
+            const txs = await fetchRecentTransactions(VICTIM, BLOCKSCOUT);
+            expect(txs[0].holders).toBeNull();
+        });
+
+        test("a null holders_count parses to null", async () => {
+            respondWith([], spamTransferWithToken(NULLED));
+            const txs = await fetchRecentTransactions(VICTIM, BLOCKSCOUT);
+            expect(txs[0].holders).toBeNull();
+        });
+
+        test("the transfer survives the low-holder filter", async () => {
+            respondWith([], spamTransferWithToken(OMITTED));
+            const txs = await fetchRecentTransactions(VICTIM, BLOCKSCOUT);
+            expect(filterTransactions(txs, filters()).transactions).toEqual(
+                txs,
+            );
+        });
+
+        // The regression this fix could cause: a token that genuinely
+        // reports zero holders must keep being filtered.  Unlike the fake
+        // "ETH" fixture above, this symbol is not in the token list, so the
+        // holder count is the only rule that can catch it.
+        test('a reported holders_count of "0" still parses to 0 and is filtered', async () => {
+            respondWith([], spamTransferWithToken(ZERO));
+            const txs = await fetchRecentTransactions(VICTIM, BLOCKSCOUT);
+            expect(txs[0].holders).toBe(0);
+            expect(filterTransactions(txs, filters()).transactions).toEqual([]);
+        });
+    });
+
     test("failed responses yield an empty list rather than throwing", async () => {
         debugFetch.mockImplementation(async () => ({
             ok: false,