fix: store an absent explorer decimals as unknown instead of fabricating 18 (closes #349)

fetchTokenBalances() did parseInt(item.token.decimals || "18", 10) before writing to state.wallets[].addresses[].tokenBalances[].decimals, so a token whose decimals() reverts -- one the block explorer reports no scale for -- was stored with a fabricated 18 that no reader could tell from a real one.

That is upstream of a rule already merged. #306 made the ERC-20 approval amount line resolve the real scale or refuse to format, and #340 extended it to the swap lines; both read this stored value as an authoritative source, so the guess walked straight past refusals that were intact and simply never fired. A 1,000-unit approval of such a token rendered 0.000000001 on the one screen whose job is to state what is being authorized.

The stored value is now the explorer's own answer or null, never a default. Both approval paths reach unknownDecimalsAmount() on a null, using the refusal that was already there. The history list's token transfers carried the same || "18" and now state exact base units with the scale unknown rather than a quantity at a guessed one.

A holding whose scale nothing knows has no quantity either, so its balance is stored as null -- unknown, never zero -- and the balance list, the address USD total, the Send screen and the confirmation screen each say so rather than printing 0.0000 for money that is really there. The zero-balance filter moved onto the base-unit integer, where it needs no scale at all. The bundled token list and the user's tracked tokens already outrank the explorer, so a token either of them knows still displays its real quantity when the explorer's entry omits decimals; only what none of the three knows is unknown.

Which makes the stored field the explorer's answer alone, and NOT the scale a screen renders at. Those are two questions, and every screen that needs the second one asks resolveTokenDecimals(). The Send screen did not: it read tokenBalances[].decimals raw and carried it onto the pending transaction, so a bundled or tracked token whose explorer row omits decimals reached displayedDecimals(null) inside estimateGas(). That throws, is caught as an unavailable fee, and disables Send behind "The network fee could not be estimated ... Please go back and try again" -- untrue, unactionable, and for a token such as WETH whose scale was never in doubt. The balance and the amount on the same screen were correct throughout, and validateTransfer() had nothing to object to, so nothing named the real reason. Before this change the fabricated 18 happened to be that token's real scale and the send completed, so this is a capability regression and not an inherited one. Send now resolves the scale through resolveTokenDecimals(), with no fallback.

The two resolutions are deliberately not identical, and where they differ the balance follows the scale. balances.js resolves without wallets, because it is formatting one explorer row during a fetch that is about to replace the very state it would be consulting; its explorer leg is therefore that row's own value. send.js resolves with wallets, which adds explorerDecimals()'s cross-address check, so a contract two addresses report different scales for answers null rather than picking one -- a check that must apply to a value which goes on to encode a transfer. For a token neither bundled nor tracked whose explorer rows disagree, that leaves a stored quantity computed at a scale Send has just refused. Stating it would leave validateTransfer() checking the amount against a number the wallet does not vouch for, and, since the unknown-balance path is gated on the balance rather than on the scale, would again leave the fee-estimate failure as the only thing on the confirmation screen. So Send withdraws the stored quantity along with the scale: an unknown scale is an unknown balance. Only a stored quantity is withdrawn -- the "0" for a token with no row at all is an absence of holdings, which is true at every scale.

The uint8 check is one shared toDecimals() rather than three copies of it, and it answers 0 for a real scale of zero: || "18" collapsed that to eighteen, the falsy-collapse trap of #246.

The reader half is asserted, not just the writer half. Each of the six sites that now distinguishes an unknown quantity from a zero one -- balanceLine(), balanceLinesForAddress(), addressHoldsFunds(), getAddressValue()'s partial flag, the Send balance line and the confirmation screen's balance and insufficient-balance wording -- is tested on the PAIR, because an assertion about null alone still passes on a build that renders both as zero. The Send and confirmation cases run the real explorer response through the real fetcher, the real review handler and the real confirmation screen, so they show which of the two scale questions each screen is asking, including a two-address fixture whose explorer rows report 6 and 18 for one contract.

Existing installs hold 18s that cannot be told apart retroactively -- that is the defect, and no migration can undo it. They display exactly as they do today until the next balance refresh, which rewrites tokenBalances wholesale and needs no user action. The schema version is not bumped: version 1 records stay valid and are read exactly as before.

No || 18 or ?? 18 fallback remains anywhere in src/. The literal 18s that do remain are real data rather than defaults: 432 per-token decimals: 18 entries in the bundled src/shared/tokenList.js, and, outside that file, only native ETH's protocol-defined scale in src/shared/uniswap.js and the fixed-point comparison scale in src/shared/txValidation.js.

src/shared/balances.js

@@ -15,6 +15,8 @@ const { deriveAddressFromXpub } = require("./wallet");
 const { TOKEN_BY_ADDRESS } = require("./tokenList");
 const { LOW_HOLDER_THRESHOLD, parseHoldersCount } = require("./holders");
 const { isSpoofedSymbol } = require("./symbolSpoof");
+const { toDecimals } = require("./transferAmount");
+const { resolveTokenDecimals } = require("./approvalAmount");
 
 // Use a static network to skip auto-detection (which can fail and cause
 // "could not coalesce error" on some RPC endpoints like Cloudflare).
@@ -66,10 +68,28 @@ function formatTokenBalance(raw, decimals) {
     return parts[0] + "." + dec;
 }
 
+// The explorer's reported holding as an exact base-unit integer, or null when
+// it reported nothing usable. Base units carry no scale, so this value is
+// meaningful before the scale is known — which is what lets a holding of zero
+// be recognised as zero without guessing a scale to divide it by.
+function rawUnits(value) {
+    if (typeof value === "bigint") return value >= 0n ? value : null;
+    if (typeof value === "number") {
+        return Number.isSafeInteger(value) && value >= 0 ? BigInt(value) : null;
+    }
+    if (typeof value !== "string" || !/^[0-9]+$/.test(value)) return null;
+    return BigInt(value);
+}
+
 // Fetch token balances for a single address from Blockscout.
-// Returns [{ address, symbol, decimals, balance }].
+// Returns [{ address, name, symbol, decimals, balance, holders }].
 // Filters out spam: only shows tokens that are in the known token list,
 // explicitly tracked by the user, or have >= 1000 holders.
+//
+// `decimals` and `balance` are each null when the answer is unknown, the same
+// way `holders` already is. Absence is never filled in here: this is the
+// upstream of every screen that displays a token amount, so a value invented
+// at this point is indistinguishable from a real one everywhere below it.
 async function fetchTokenBalances(address, blockscoutUrl, trackedTokens) {
     try {
         const resp = await debugFetch(
@@ -94,11 +114,46 @@ async function fetchTokenBalances(address, blockscoutUrl, trackedTokens) {
             // is unchanged.
             const type = String(item.token?.type || "").toUpperCase();
             if (type !== "ERC-20") continue;
-            const decimals = parseInt(item.token.decimals || "18", 10);
-            const bal = formatTokenBalance(item.value || "0", decimals);
-            if (bal === "0.0") continue;
 
             const tokenAddr = (item.token.address_hash || "").toLowerCase();
+
+            // What the explorer reported, or null. NEVER a default: this
+            // value is written to state and every later reader — the approval
+            // screen's amount line, the swap lines, the Send screen — takes it
+            // as the token's resolved scale. A fabricated 18 reads exactly
+            // like a real 18 at that point, so it does not merely display the
+            // wrong quantity, it walks straight past the refusal those screens
+            // already have for a scale nobody knows
+            // (https://git.eeqj.de/sneak/AutistMask/issues/349).
+            const decimals = toDecimals(item.token.decimals);
+
+            const raw = rawUnits(item.value);
+            // No usable amount at all is nothing to list, exactly as a
+            // formatted "0.0" was before. Checked on the base-unit integer so
+            // it does not depend on knowing the scale: zero base units is zero
+            // tokens at every scale, and a value the explorer did not report
+            // as an integer is not a holding.
+            if (raw === null || raw === 0n) continue;
+
+            // The scale this row's balance is DISPLAYED at, which is not the
+            // same question as what the explorer said. The bundled list and
+            // the tokens the user tracks both outrank the explorer already
+            // (resolveTokenDecimals), so a token they know keeps showing its
+            // real quantity even when the explorer's entry omits decimals.
+            // Only what neither of them nor the explorer knows is unknown.
+            // The stored `decimals` above stays the explorer's own answer
+            // either way: copying another source into it would make
+            // explorerDecimals()'s disagreement check compare something other
+            // than explorer values.
+            const known = resolveTokenDecimals(tokenAddr, { trackedTokens });
+            const scale = known !== null ? known : decimals;
+            // null is a holding of an amount that cannot be stated, which is
+            // not the same as a holding of zero, and must never render as one.
+            // With a scale, the display filter proper applies: a balance that
+            // rounds to zero at six places is dust and is not listed. Without
+            // one there is no such judgement to make, and the row is kept.
+            const bal = scale === null ? null : formatTokenBalance(raw, scale);
+            if (bal === "0.0") continue;
             // null means the explorer reported no count, which is not the
             // same as a count of zero.  This gate is not the low-holder
             // display filter: it has no user-facing off switch and governs
@@ -127,7 +182,15 @@ async function fetchTokenBalances(address, blockscoutUrl, trackedTokens) {
                 address: item.token.address_hash,
                 name: item.token.name || "",
                 symbol: item.token.symbol || "???",
+                // null means the explorer reported no usable scale — unknown,
+                // not 18. Distinguishable from a real 18 at read time is the
+                // entire point: resolveTokenDecimals() falls through a null to
+                // its refusal, and takes an 18 as the answer.
                 decimals: decimals,
+                // null means nothing anywhere knows the scale, so there is no
+                // token quantity to state. Not "0.0": a nonzero holding shown
+                // as zero is the same lie in the balance list that the
+                // approval screens refuse to tell.
                 balance: bal,
                 holders: holders,
             });