fix: Blockscout and Etherscan lookups are off until the user turns them on (closes #668)

Out of the box the wallet sent the user's addresses to Blockscout for history
and token lookups. It sent each recipient to Etherscan for its label. Two
settings, "Use Blockscout" and "Check recipients on Etherscan", now gate those
requests where they are made. Both are off in a new install and offered
unticked on Welcome and in Settings. While one is off, the screens that relied
on it say so in a plain line naming the setting. After either changes in
Settings, Back draws again any screen a reopened popup can draw. ENS lookups
ask only the RPC endpoint, so a name resolved off-chain does not resolve.
README and the user guide say what is contacted by default and what each
setting adds.

Model: opus-5-5

README.md

@@ -12,20 +12,27 @@ intercepts tx status links to their own site instead of going to Etherscan, etc.
 None of the common alternatives work on Firefox.
 
 Hence, a minimally viable ERC20 browser wallet/signer that works cross-platform.
-Everything you need, nothing you don't. We import as few libraries as possible,
-don't implement any crypto, and don't send user-specific data anywhere but a
-(user-configurable) Ethereum RPC endpoint (which defaults to a public node)
-unless the user turns on one of the two lookups below. Out of the box the
-extension contacts the configured RPC node for blockchain interactions and a
-public CoinDesk API (no API key) for realtime price information, which is sent
-token symbols and nothing else. Two more services are sent none of the user's
-data until the user turns them on, on the Welcome screen or in Settings: a
-Blockscout block-explorer API for transaction history, the tokens the user has
-not tracked and transaction details ("Use Blockscout"), and best-effort
-Etherscan address label lookups during transaction confirmation ("Check
-recipients on Etherscan"). A community-maintained phishing domain blocklist is
-built into the extension at build time and checked locally; nothing is fetched
-for it at runtime.
+Everything you need, nothing you don't. We import as few libraries as possible
+and don't implement any crypto. By default the wallet sends user-specific data
+only to the Ethereum RPC endpoint. The user can change that endpoint in
+Settings; it defaults to a public node.
+
+Out of the box the extension contacts two services:
+
+- the configured RPC node, for blockchain interactions
+- a public CoinDesk API (no API key), for realtime prices. It is sent token
+  symbols and nothing else.
+
+Two more services are sent none of the user's data until the user turns them on.
+Each has a checkbox on the Welcome screen and in Settings:
+
+- "Use Blockscout": a Blockscout block-explorer API, for transaction history,
+  the tokens the user has not tracked, and transaction details
+- "Check recipients on Etherscan": a best-effort Etherscan label lookup of the
+  recipient during transaction confirmation
+
+A community-maintained phishing domain blocklist is built into the extension at
+build time and checked locally. Nothing is fetched for it at runtime.
 
 In the extension is a hardcoded list of the top ERC20 contract addresses. You
 can add any ERC20 contract by contract address if you wish, but the hardcoded
@@ -427,22 +434,28 @@ there to Sepolia must put up the `[TESTNET]` banner, and switching back to
 mainnet must take it down, both while Settings is still on screen.
 
 It also covers what a new install sends to Blockscout and Etherscan
-([#668](https://git.eeqj.de/sneak/AutistMask/issues/668)). The route handler
-records every request the extension makes, from its pages and its background
-worker, from when the harness installs it, before the first popup page opens; a
-request the background worker makes while it starts up, before then, is not
-recorded. Welcome must offer "Use Blockscout" and "Check recipients on
-Etherscan" unticked. With neither changed, Home, AddressDetail, AddressToken and
-ConfirmTx must show the lines saying what is off; the popup is then closed until
-the background has run a balance refresh of its own, and not one recorded
-request may have gone to Blockscout or Etherscan. "Use Blockscout" is then
-ticked from AddressDetail's gear: on "Back", AddressDetail must ask Blockscout
-for its history and no longer say it is off, and Blockscout must then be asked
-for the token balances. "Check recipients on Etherscan" is ticked from
-ConfirmTx's gear: on "Back", ConfirmTx must ask Etherscan about the recipient
-and show the label the stub page gives it. Both stay on for the rest of the run.
-TransactionDetail with "Use Blockscout" off is not driven here, since no history
-row leads to it then; the unit tests cover it.
+([#668](https://git.eeqj.de/sneak/AutistMask/issues/668)). The harness installs
+a route handler before the first popup page opens. From then on, the handler
+records every request the extension makes, from its pages and from its
+background worker. A request the background worker makes while it starts up
+comes earlier and is not recorded. The tests take these steps in order:
+
+- Welcome must offer "Use Blockscout" and "Check recipients on Etherscan"
+  unticked.
+- With neither ticked, Home, AddressDetail, AddressToken and ConfirmTx must each
+  show the line saying what is off.
+- The popup is then closed until the background has run a balance refresh of its
+  own. No recorded request may have gone to Blockscout or Etherscan.
+- "Use Blockscout" is ticked from AddressDetail's gear. On "Back", AddressDetail
+  must ask Blockscout for its history and no longer say the setting is off.
+  Blockscout must then be asked for the token balances.
+- "Check recipients on Etherscan" is ticked from ConfirmTx's gear. On "Back",
+  ConfirmTx must ask Etherscan about the recipient and show the label the stub
+  page gives it.
+
+Both settings stay on for the rest of the run. TransactionDetail with "Use
+Blockscout" off is not driven here, because no history row leads to it then. The
+unit tests cover it.
 
 It also covers the confirmation screen, for both a native ETH send and an ERC-20
 send: Send disabled while the fee estimate is in flight, enabled once it lands,
@@ -1411,12 +1424,18 @@ that token's previous entry, as a failed ETH balance keeps its figure, or takes
 Blockscout's entry from the same refresh when there is none. Every other token
 comes from the Blockscout `token-balances` response (`fetchTokenBalances()`), so
 tokens do appear without the user adding them, and they keep their previous
-figures while Blockscout fails. The refresh asks Blockscout only while the user
-has "Use Blockscout" on. While it is off, as it is until the user turns it on, a
-tracked token's entry has no holder count and no `decimals` of Blockscout's, so
-its balance is stated at the scale the bundled list or the tracked token
-records, and no other token is listed, those from earlier refreshes included. A
-tracked token is shown when its balance is nonzero, and any other ERC-20 when
+figures while Blockscout fails.
+
+The refresh asks Blockscout only while the user has "Use Blockscout" on. The
+setting is off until the user turns it on. While it is off:
+
+- Only tracked tokens are listed. Untracked tokens from earlier refreshes are
+  dropped.
+- A tracked token's entry has no holder count and no `decimals` from Blockscout.
+- A tracked token's balance is stated at the scale the bundled list or the
+  tracked token records.
+
+A tracked token is shown when its balance is nonzero, and any other ERC-20 when
 its balance is nonzero and it is in the bundled known-token list or has 1,000 or
 more holders. A token claiming a symbol from the bundled list from any other
 contract address is always dropped, tracked or not, and so is any token claiming
@@ -1606,8 +1625,8 @@ such as an edit typed into Settings and not yet saved. Home is the one screen
 "Back" always re-renders, so the wallet list reflects anything that changed
 while the user was away from it. Changing "Use Blockscout" or "Check recipients
 on Etherscan" in Settings makes every screen but Settings count as not yet
-rendered, so "Back" renders the screen it lands on under the new setting; the
-stack is left as it is.
+rendered. "Back" then renders again any screen a reopened popup can render. Any
+other screen, such as Send, is unhidden as it was. The stack is left as it is.
 
 A network switch leaves every screen on the page showing the previous network.
 The user makes it in Settings, or approves a site's request and the background
@@ -1650,11 +1669,11 @@ view would leave a wallet one click from deletion.
   screen in that case.
 - **Elements**:
     - "Welcome! To get started, add a wallet." text
-    - A well saying that the wallet sends the user's data only to the Ethereum
-      RPC endpoint unless one of the two settings in it is turned on, here or
-      later in Settings: the "Use Blockscout" and "Check recipients on
-      Etherscan" checkboxes, the same two as in Settings, each with its sentence
-      on what it sends and to whom. Both are unticked until the user ticks them
+    - A well with a line saying that the wallet sends the user's data only to
+      the Ethereum RPC endpoint unless one of the two checkboxes below is ticked
+    - In the well, the "Use Blockscout" and "Check recipients on Etherscan"
+      checkboxes, the same two as in Settings. Each has a sentence saying what
+      it sends and where. Both are unticked until the user ticks them
     - "Add wallet" button
 - **Transitions**:
     - Ticking or unticking either checkbox → stores the setting, as Settings
@@ -1690,7 +1709,7 @@ view would leave a wallet one click from deletion.
       says "This transaction creates a new contract. It has no recipient." The
       transaction lists on AddressDetail and AddressToken draw the same rows.
       The history comes from Blockscout. While "Use Blockscout" is off,
-      Blockscout is not asked, and this list and those two show the one line "No
+      Blockscout is not asked. This list then shows only the line "No
       transaction history is shown, because "Use Blockscout" is off in
       Settings."
     - "Add additional wallet..." link at bottom
@@ -1760,13 +1779,14 @@ view would leave a wallet one click from deletion.
     - Full address (color dot, etherscan link, tap to copy)
     - USD total for address (see [Partial USD totals](#partial-usd-totals))
     - Balance list: ETH + the ERC-20 tokens shown for this address (4 decimal
-      places, USD inline). Each balance row is clickable → **AddressToken**.
-      While "Use Blockscout" is off, the line Home has under its wallet list
-      follows it
+      places, USD inline). Each balance row is clickable → **AddressToken**
+    - While "Use Blockscout" is off, a line under the balance list: "Only
+      tracked tokens are listed, because "Use Blockscout" is off in Settings."
     - Send / Receive / + Token buttons and a "···" menu button
     - "···" dropdown containing a single "Export Private Key" entry
-    - Transaction list (with ENS resolution for counterparties), or the line
-      Home's list shows while "Use Blockscout" is off
+    - Transaction list (with ENS resolution for counterparties). While "Use
+      Blockscout" is off, it shows only the line "No transaction history is
+      shown, because "Use Blockscout" is off in Settings."
 - **Transitions**:
     - Tap balance row → **AddressToken** (for that token)
     - "Send" → **Send** (refuses with a flash message on a zero balance)
@@ -1834,11 +1854,13 @@ view would leave a wallet one click from deletion.
     - Token contract well (ERC-20 only): full contract address (tap to copy,
       etherscan link) plus name, symbol, decimals, holder count and project
       website where known. The "Holders:" row is left out, not shown as 0, when
-      the token's balance-list entry has no holder count: the explorer did not
-      report a readable one, "Use Blockscout" is off, or the token is not in the
-      balance list
-    - Token-filtered transaction list (only this token's transfers), or the line
-      Home's list shows while "Use Blockscout" is off
+      the token's balance-list entry has no holder count. That happens when:
+        - the explorer did not report a readable one
+        - "Use Blockscout" is off
+        - the token is not in the balance list
+    - Token-filtered transaction list (only this token's transfers). While "Use
+      Blockscout" is off, it shows only the line "No transaction history is
+      shown, because "Use Blockscout" is off in Settings."
 - **Transitions**:
     - "Send" → **Send** (token locked: the dropdown is replaced by a static
       symbol and contract address)
@@ -1926,10 +1948,10 @@ view would leave a wallet one click from deletion.
       that has received ETH but never sent a transaction still holds that ETH,
       so it gets no warning. The Etherscan label check is made only while "Check
       recipients on Etherscan" is on. While it is off, the Etherscan box is left
-      out and a line in its place says "This address was not checked on
-      Etherscan, because "Check recipients on Etherscan" is off in Settings."
-      Which of the two is there is known when the screen is drawn, so neither
-      moves anything later
+      out. A line in its place says "This address was not checked on Etherscan,
+      because "Check recipients on Etherscan" is off in Settings." The box or
+      the line is chosen when the screen is drawn, so neither moves anything
+      later
     - Errors (an invalid amount), plus five reserved error boxes, so the balance
       and the fee arriving later move nothing — the amount exceeds the balance
       (for a token whose scale is unknown it says the token's balance is
@@ -1975,8 +1997,8 @@ view would leave a wallet one click from deletion.
       are that network's, so a testnet transaction shows none, its From, To and
       token contract links open that network's explorer, the balance read, the
       fee estimate and the contract and never-sent recipient checks ask that
-      network's RPC endpoint, and the Etherscan label check, when it is made,
-      asks that network's explorer
+      network's RPC endpoint, and the Etherscan label check asks that network's
+      explorer
     - "Sign & Send" (correct password) when the gas limit, a fee per gas or the
       total fee the RPC endpoint fills in at signing is over its bound in
       `assertWithinCeilings()` (`src/shared/approvalVerify.js`) → nothing is
@@ -2096,9 +2118,9 @@ view would leave a wallet one click from deletion.
   on, whichever network is active: its block, network details, decoded details
   and raw data are read from that network's Blockscout, the one Settings has for
   it, and its etherscan links open that network's explorer. They are read only
-  while "Use Blockscout" is on. The screen can still be shown with it off, when
-  the user opens Settings from it, turns the setting off and presses Back; then
-  Blockscout is not asked, and a line in their place says "No block, decoded
+  while "Use Blockscout" is on. The user can open Settings from this screen,
+  turn the setting off and press Back. The screen is then drawn again without
+  asking Blockscout. A line in place of those details says "No block, decoded
   details, network details or raw data are shown, because "Use Blockscout" is
   off in Settings."
 - **Elements** (grouped into logical blocks using light well containers; field
@@ -2183,18 +2205,21 @@ view would leave a wallet one click from deletion.
       already active changes nothing and sends nothing
     - Ethereum RPC: endpoint URL input + "Save" button (validated against
       `eth_chainId` before being saved)
-    - Blockscout API: a "Use Blockscout" checkbox, unticked until the user ticks
-      it, with a sentence saying it sends the user's addresses, and the hash of
-      each transaction opened, to the Blockscout API below, for transaction
-      history, tokens not tracked, and transaction details; then the endpoint
-      URL input + "Save" button (validated against `/stats` before being saved,
-      a request the user presses for that carries no user data, made whether or
-      not the checkbox is ticked)
-    - Etherscan: a "Check recipients on Etherscan" checkbox, unticked until the
-      user ticks it, with a sentence saying it sends the address about to be
-      sent to, to Etherscan, to look for a phishing or scam label on it. Both
-      checkboxes are one setting each for every network, and Welcome offers the
-      same two
+    - Blockscout API:
+        - "Use Blockscout" checkbox, unticked until the user ticks it
+        - A sentence saying what it shows and what it sends. It sends the
+          Blockscout API the user's addresses and the hash of each transaction
+          opened
+        - Endpoint URL input + "Save" button. "Save" checks the URL by asking it
+          for `/stats` before saving it. That request carries no user data. It
+          is made whether or not "Use Blockscout" is ticked.
+    - Etherscan:
+        - "Check recipients on Etherscan" checkbox, unticked until the user
+          ticks it
+        - A sentence saying it sends each recipient's address to Etherscan to
+          check it for a phishing or scam label
+    - Each of the two settings applies to every network. Welcome offers the same
+      two checkboxes
     - Token Spam Protection:
         - "Hide fake tokens impersonating a known symbol" checkbox
         - "Hide tokens with fewer than 1,000 holders" checkbox
@@ -2738,12 +2763,17 @@ view would leave a wallet one click from deletion.
 ### External Services
 
 AutistMask is not a fully self-contained offline tool. By default it sends the
-user's data to one service only, the Ethereum RPC endpoint, and asks one more,
-the CoinDesk price API, for prices with nothing but token symbols. Two more
-services are sent none of the user's data until the user turns on the setting
-for each, on the Welcome screen or in Settings: Blockscout ("Use Blockscout")
-and Etherscan ("Check recipients on Etherscan"). Both settings are off in a new
-profile, and each is one setting for every network.
+user's data only to the Ethereum RPC endpoint. It also asks the CoinDesk price
+API for prices, sending token symbols and nothing else.
+
+Two more services are sent none of the user's data until the user turns on their
+settings:
+
+- Blockscout, with "Use Blockscout"
+- Etherscan, with "Check recipients on Etherscan"
+
+Both settings are on the Welcome screen and in Settings. Both are off in a new
+install. Each setting applies to every network.
 
 Contacted by default:
 
@@ -2752,11 +2782,10 @@ Contacted by default:
   them the balance of every tracked token at every address (`balanceOf`),
   estimate gas (`eth_estimateGas`), fetch nonces (`eth_getTransactionCount`),
   broadcast transactions (`eth_sendRawTransaction`), and check transaction
-  receipts. ENS lookups, of a name typed into Send and of the names shown for
-  the user's addresses, are made through it alone, so a name whose resolver says
-  it is resolved off-chain does not resolve. The default endpoint is a public
-  RPC (configurable by the user to any endpoint they prefer, including a local
-  node). By default the extension talks to
+  receipts. Every ENS lookup is made through it alone. A name whose resolver
+  says it is resolved off-chain therefore does not resolve. The default endpoint
+  is a public RPC (configurable by the user to any endpoint they prefer,
+  including a local node). By default the extension talks to
   `https://ethereum-rpc.publicnode.com`.
     - **Data sent**: Ethereum addresses, transaction data, contract call
       parameters. The RPC endpoint can see all on-chain queries and submitted
@@ -2771,18 +2800,21 @@ Contacted by default:
 
 Sent the user's data only while the user has turned the setting on:
 
-- **Blockscout block-explorer API** ("Use Blockscout"): Used to fetch
-  transaction history (normal transactions and ERC-20 token transfers) for Home,
-  AddressDetail and AddressToken, the balances of the ERC-20 tokens the user has
-  not tracked, token holder counts (for spam filtering), and a transaction's
-  block, network details and calldata for TransactionDetail. The default
-  endpoint is `https://eth.blockscout.com/api/v2` (configurable by the user in
-  Settings). While the setting is off, those screens say in a plain line what is
-  not shown and that this setting turns it on, and only tracked tokens are
-  listed, their balances read through the RPC endpoint. The endpoint check
-  Settings makes when the user presses "Save" beside the URL asks only for
-  `/stats` and carries no user data; it is made whether or not the setting is
-  on.
+- **Blockscout block-explorer API** ("Use Blockscout"): The default endpoint is
+  `https://eth.blockscout.com/api/v2` (configurable by the user in Settings).
+    - **Used for**:
+        - transaction history (normal transactions and ERC-20 token transfers),
+          for Home, AddressDetail and AddressToken
+        - the balances of the ERC-20 tokens the user has not tracked
+        - token holder counts, for spam filtering
+        - a transaction's block, network details and calldata, for
+          TransactionDetail
+    - **While the setting is off**: each of those screens shows a line saying
+      what it leaves out and that "Use Blockscout" is off. Only tracked tokens
+      are listed.
+    - **Saving the URL**: pressing "Save" beside the URL in Settings asks that
+      URL for `/stats`. This request carries no user data. It is made whether or
+      not the setting is on.
     - **Data sent**: Ethereum addresses, and the hash of each transaction the
       user opens. Blockscout receives the user's addresses to query their
       transaction history and token balances. No private keys, passwords, or
@@ -2793,12 +2825,11 @@ Sent the user's data only while the user has turned the setting on:
   recipient address on Etherscan to check for phishing/scam labels. This is a
   direct page fetch with no API key; the user's browser makes the request. While
   the setting is off, ConfirmTx says that no Etherscan check was made.
-    - **Data sent**: the recipient address. The user's own addresses are not
-      sent.
+    - **Data sent**: the recipient's address and nothing else.
 
 The etherscan links on the screens open a page in the browser when the user
-clicks one. They are not requests the wallet makes, and nothing is fetched from
-them until then.
+clicks one. They are not requests the wallet makes. Nothing is fetched from them
+until the user clicks.
 
 What the extension does NOT do:
 
@@ -2807,9 +2838,9 @@ What the extension does NOT do:
 - No Infura/Alchemy dependency (any JSON-RPC endpoint works)
 - No backend servers operated by the developer
 
-Users who want maximum privacy can point the RPC URL at their own node, and,
-when they turn Blockscout on, the Blockscout URL at their own instance (price
-fetching can be disabled in a future version).
+Users who want maximum privacy can point the RPC URL at their own node. With
+"Use Blockscout" on, they can point the Blockscout URL at their own instance
+too.
 
 ### Dependencies
 
@@ -2991,9 +3022,10 @@ logged.
 - Add multiple addresses within an HD wallet
 - Manage multiple wallets simultaneously
 - View ETH balance per address
-- View ERC-20 token balances (tokens the user adds by contract address, and,
-  while "Use Blockscout" is on, tokens on the bundled known-token list and
-  tokens with 1,000 or more holders)
+- View ERC-20 token balances:
+    - tokens the user adds by contract address
+    - while "Use Blockscout" is on, tokens on the bundled known-token list and
+      tokens with 1,000 or more holders
 - View transaction history and transaction details, while "Use Blockscout" is on
 - Send ETH to an address
 - Send ERC-20 tokens to an address

docs/README.md

@@ -58,7 +58,7 @@ analytics, use a portfolio tracker. The wallet is not the place for any of that.
 - **No NFT galleries or portfolio views.** This is a wallet, not a dashboard.
 
 - **No third-party token list APIs.** The balances of the tokens you track are
-  read from your RPC endpoint; while you have "Use Blockscout" on, the others
+  read from your RPC endpoint. While "Use Blockscout" is on, the other tokens
   come from the same block explorer you configure for transaction history. The
   extension ships its own hardcoded list of top ERC-20 contract addresses for
   symbol-spoofing detection. Any token you want tracked across all your
@@ -71,10 +71,12 @@ analytics, use a portfolio tracker. The wallet is not the place for any of that.
 
 AutistMask is a browser extension that runs entirely in your browser. It does
 not have a backend server. Out of the box it sends your data only to the
-Ethereum RPC endpoint, and asks the CoinDesk price API for prices with nothing
-but token symbols. Blockscout and Etherscan are sent none of your data until you
-turn on "Use Blockscout" or "Check recipients on Etherscan", on the Welcome
-screen or later in Settings. Both are off in a new install.
+Ethereum RPC endpoint. It also asks the CoinDesk price API for prices, sending
+token symbols and nothing else.
+
+Blockscout and Etherscan are sent none of your data until you turn them on.
+Their settings are "Use Blockscout" and "Check recipients on Etherscan", on the
+Welcome screen and in Settings. Both are off in a new install.
 
 ### External Services
 
@@ -100,20 +102,27 @@ addresses are necessarily visible to the RPC provider when querying balances.
 **Blockscout API** (default: `eth.blockscout.com/api/v2`;
 `eth-sepolia.blockscout.com/api/v2` on Sepolia)
 
-Off until you turn on "Use Blockscout". Used to fetch transaction history, the
-balances of the tokens you have not tracked, and the details of a transaction
-you open. Blockscout is an open-source blockchain explorer. AutistMask queries
-it for your ERC-20 token balances (including the holder counts used for spam
-filtering), your recent transactions and token transfers, and the block, fees
-and calldata of a transaction you open. You can change this in Settings to a
-self-hosted Blockscout instance. While it is off, the screens that would show
-history say so, and only the tokens you track are listed.
+Blockscout is an open-source blockchain explorer. AutistMask uses it only while
+"Use Blockscout" is on. It then asks Blockscout for:
 
-When it is contacted: while "Use Blockscout" is on, on every balance refresh,
-whenever a screen showing transaction history is opened, and when you open a
-transaction. The one exception, whether or not the setting is on, is pressing
-"Save" beside the Blockscout URL in Settings, which checks that URL by asking it
-for `/stats` and sends none of your data.
+- your recent transactions and token transfers
+- the balances of the tokens you have not tracked, with the holder counts used
+  for spam filtering
+- the block, fees and calldata of a transaction you open
+
+You can change this in Settings to a self-hosted Blockscout instance. While the
+setting is off, each screen that would show Blockscout's data says so instead.
+Only the tokens you track are listed.
+
+When it is contacted, while "Use Blockscout" is on:
+
+- on every balance refresh
+- whenever a screen showing transaction history is opened
+- when you open a transaction
+
+Pressing "Save" beside the Blockscout URL in Settings also contacts it, even
+with the setting off. That request checks the URL by asking it for `/stats`. It
+sends none of your data.
 
 What gets sent: your Ethereum addresses (to look up balances and transactions)
 and the hash of each transaction you open.
@@ -134,7 +143,7 @@ address.
 **Etherscan address labels** (`etherscan.io`; `sepolia.etherscan.io` on Sepolia)
 
 Off until you turn on "Check recipients on Etherscan". When you review a send,
-AutistMask fetches the recipient's public Etherscan address page and looks for a
+AutistMask fetches the recipient's public Etherscan address page. It looks for a
 "Fake_Phishing"/"Phish/Hack" label or a scam warning, and shows a red warning if
 it finds one. This is a plain page fetch with no API key, made by your browser.
 It is best-effort: if it fails, it is silently ignored. This endpoint is not
@@ -144,8 +153,8 @@ Etherscan check was made.
 When it is contacted: only while "Check recipients on Etherscan" is on, each
 time you reach the send confirmation screen.
 
-What gets sent: the recipient address you are about to send to, and your IP
-address. Your own addresses are not sent.
+What gets sent: the recipient's address and nothing else. As with any request,
+Etherscan sees your IP address.
 
 Etherscan links shown elsewhere in the UI (on addresses, transactions, and token
 contracts) are ordinary links. They contact nothing until you click them.
@@ -199,9 +208,9 @@ password.
 
 1. Click the AutistMask icon in your browser toolbar.
 2. Click "Add wallet" (on first use), or open Settings and click "+ Add wallet".
-   On first use the same screen offers "Use Blockscout" and "Check recipients on
-   Etherscan", both off; tick either if you want what it does (see External
-   Services). You can change both later in Settings.
+   On first use, the screen with "Add wallet" also offers "Use Blockscout" and
+   "Check recipients on Etherscan", both off. Tick either if you want what it
+   does (see External Services). You can change both later in Settings.
 3. On the "From Phrase" tab, click the die button to generate a random 12-word
    recovery phrase.
 4. **Write down the recovery phrase and store it safely.** Anyone with these
@@ -237,11 +246,14 @@ always produce the same sequence of addresses.
 
 ### Adding ERC-20 Tokens
 
-Tokens you hold show up automatically only while "Use Blockscout" is on, and
-then only if they are in the extension's bundled list of well-known tokens or
-have at least 1,000 holders; everything else is treated as spam and hidden. To
-track a token explicitly (which also shows it at zero balance, and shows it
-whether or not "Use Blockscout" is on), add it by contract address:
+Tokens you hold show up automatically only while "Use Blockscout" is on. Even
+then, a token shows up only if it is in the extension's bundled list of
+well-known tokens or has at least 1,000 holders. Everything else is treated as
+spam and hidden.
+
+A token you track is shown whether or not "Use Blockscout" is on. By default it
+is shown at zero balance too (see Display in Settings). To track a token, add it
+by contract address:
 
 1. Go to an address detail view (click `[info]` on any address).
 2. Click "+ Token".
@@ -407,9 +419,8 @@ Click the gear icon on the home screen to access settings:
   that network's defaults if you have not used it before.
 - **Ethereum RPC**: Change the Ethereum node endpoint. Default is a public RPC.
   You can use your own node for maximum privacy.
-- **Blockscout API**: "Use Blockscout", off until you tick it, and the
-  Blockscout instance used for transaction history, the tokens you have not
-  tracked and transaction details. You can use a self-hosted instance.
+- **Blockscout API**: the "Use Blockscout" checkbox, off until you tick it, and
+  the URL of the Blockscout instance. You can use a self-hosted instance.
 - **Etherscan**: "Check recipients on Etherscan", off until you tick it.
 - **Token Spam Protection**: Toggle individual scam filters and set the dust
   transaction threshold.

src/popup/index.html

@@ -46,8 +46,8 @@
                 <div class="bg-well p-3 mx-1 mb-3">
                     <p class="text-xs mb-2">
                         This wallet sends your data only to the Ethereum RPC
-                        endpoint, unless you turn on either of these, here or
-                        later in Settings.
+                        endpoint, unless you turn on one of these. You can
+                        change them later in Settings.
                     </p>
                     <label
                         class="text-xs flex items-center gap-1 cursor-pointer mb-1"
@@ -56,10 +56,10 @@
                         Use Blockscout
                     </label>
                     <p class="text-xs text-muted mb-2">
-                        Sends your addresses, and the hash of each transaction
-                        you open, to the Blockscout API, for transaction
-                        history, tokens you have not tracked, and transaction
-                        details.
+                        Shows transaction history, tokens you have not tracked
+                        and transaction details. Sends your addresses, and the
+                        hash of each transaction you open, to the Blockscout
+                        API.
                     </p>
                     <label
                         class="text-xs flex items-center gap-1 cursor-pointer mb-1"
@@ -71,8 +71,8 @@
                         Check recipients on Etherscan
                     </label>
                     <p class="text-xs text-muted">
-                        Sends the address you are about to send to, to
-                        Etherscan, to look for a phishing or scam label on it.
+                        Sends each recipient's address to Etherscan to check it
+                        for a phishing or scam label.
                     </p>
                 </div>
                 <button
@@ -1059,10 +1059,10 @@
                         Use Blockscout
                     </label>
                     <p class="text-xs text-muted mb-2">
-                        Sends your addresses, and the hash of each transaction
-                        you open, to the Blockscout API below, for transaction
-                        history, tokens you have not tracked, and transaction
-                        details.
+                        Shows transaction history, tokens you have not tracked
+                        and transaction details. Sends your addresses, and the
+                        hash of each transaction you open, to the Blockscout API
+                        below.
                     </p>
                     <p class="text-xs text-muted mb-1">
                         Change this if you run your own Blockscout instance.
@@ -1092,8 +1092,8 @@
                         Check recipients on Etherscan
                     </label>
                     <p class="text-xs text-muted">
-                        Sends the address you are about to send to, to
-                        Etherscan, to look for a phishing or scam label on it.
+                        Sends each recipient's address to Etherscan to check it
+                        for a phishing or scam label.
                     </p>
                 </div>
 

src/popup/viewRouter.js

@@ -38,13 +38,16 @@ function markViewRendered(view) {
     if (view) renderedViews.add(view);
 }
 
-// Begin a fresh page-load scope. The popup gets one by being loaded, and
-// asks for one after a network switch, because every screen then on the page
-// shows the previous network (showNewNetwork() in views/settings.js), and
-// after "Use Blockscout" or "Check recipients on Etherscan" changes in
-// Settings, because every screen then on the page was drawn under the old
-// setting; the unit tests, which simulate several page loads against one
-// module instance, ask for one too.
+// Begin a fresh page-load scope. The popup gets one by being loaded. It also
+// asks for one when every screen on the page is out of date:
+//
+//   - after a network switch, since those screens show the previous network
+//     (showNewNetwork() in views/settings.js)
+//   - after "Use Blockscout" or "Check recipients on Etherscan" changes in
+//     Settings, since those screens were drawn under the old setting
+//
+// The unit tests, which simulate several page loads against one module
+// instance, ask for one too.
 function resetRenderedViews() {
     renderedViews.clear();
 }

src/popup/views/confirmTx.js

@@ -334,8 +334,8 @@ function show(txInfo) {
     $("confirm-contract-warning").style.visibility = "hidden";
     $("confirm-burn-warning").style.visibility = "hidden";
     $("confirm-etherscan-warning").style.visibility = "hidden";
-    // While "Check recipients on Etherscan" is off there is no Etherscan
-    // warning to reserve space for, and a line in its place says so.
+    // While "Check recipients on Etherscan" is off, there is no Etherscan
+    // warning to reserve space for. A line in its place says so.
     const etherscanOn = !!state.checkRecipientsOnEtherscan;
     $("confirm-etherscan-warning").classList.toggle("hidden", !etherscanOn);
     $("confirm-etherscan-note").classList.toggle("hidden", etherscanOn);

src/popup/views/helpers.js

@@ -535,7 +535,7 @@ const CONTRACT_CREATION_TEXT =
     "This transaction creates a new contract. It has no recipient.";
 
 // What the transaction lists on Home, AddressDetail and AddressToken say while
-// the user has "Use Blockscout" off: the history comes from Blockscout alone.
+// the user has "Use Blockscout" off. Their history comes from Blockscout alone.
 const HISTORY_OFF_TEXT =
     'No transaction history is shown, because "Use Blockscout" is off in Settings.';
 

src/popup/views/settings.js

@@ -367,11 +367,11 @@ function init(_ctx) {
         showFlash("Saved.");
     });
 
-    // The screens under Settings were drawn under the old setting, so each
-    // change makes every screen but Settings count as not yet drawn, as a
-    // network switch does, and Back draws the one it lands on again. Welcome
-    // offers the same two settings and is only unhidden on Back, so its boxes
-    // are set here too.
+    // The screens under Settings were drawn under the old setting. Each change
+    // makes every screen but Settings count as not yet drawn, as a network
+    // switch does. Back then draws again any screen a reopened popup can draw.
+    // Welcome offers the same two settings, and Back only unhides it, so its
+    // boxes are set here too.
     $("settings-use-blockscout").addEventListener("change", async () => {
         state.useBlockscout = $("settings-use-blockscout").checked;
         $("welcome-use-blockscout").checked = state.useBlockscout;

src/popup/views/welcome.js

@@ -1,6 +1,6 @@
-// The first screen, shown while there is no wallet. It offers the two lookups
-// at services other than the RPC endpoint, both off until the user ticks them,
-// which Settings offers as well.
+// The first screen, shown while there is no wallet. It offers "Use Blockscout"
+// and "Check recipients on Etherscan", which Settings offers too. Both are off
+// until the user ticks them.
 
 const { $, showView } = require("./helpers");
 const { state, saveState } = require("../../shared/state");

src/shared/balances.js

@@ -1,7 +1,9 @@
-// Balance fetching: ETH balances and the balances of the tokens the user
-// tracks via RPC, the other ERC-20 token balances and the holder counts via
-// Blockscout while the user has "Use Blockscout" on, ENS reverse lookup via
-// RPC.
+// Balance fetching:
+//
+//   - ETH balances, and the balances of the tokens the user tracks, via RPC
+//   - the other ERC-20 token balances and the holder counts via Blockscout,
+//     while the user has "Use Blockscout" on
+//   - ENS reverse lookup via RPC
 
 const {
     JsonRpcProvider,
@@ -39,12 +41,12 @@ const { resolveTokenDecimals } = require("./approvalAmount");
 // is a caller bug and must not resolve to a working provider for some other
 // chain.
 //
-// `disableCcipRead` keeps every ENS lookup on the RPC endpoint. Left on, as
-// ethers has it, a resolver that says a name is resolved off-chain makes ethers
-// fetch the web address the resolver gives, straight from the browser, with the
-// name being looked up; for the reverse lookup of the user's addresses that is
-// the user's own name (https://git.eeqj.de/sneak/AutistMask/issues/668). Such a
-// name does not resolve.
+// `disableCcipRead` keeps every ENS lookup on the RPC endpoint. A resolver can
+// say a name is resolved off-chain and give a web address for it. By default
+// ethers then fetches that address straight from the browser, sending the name
+// being looked up. For the reverse lookup of the user's addresses, that is the
+// user's own name (https://git.eeqj.de/sneak/AutistMask/issues/668). With the
+// flag set, such a name does not resolve.
 function getProvider(rpcUrl, networkId) {
     const net = Network.from(requireNetworkId(networkId).id);
     const provider = new JsonRpcProvider(rpcUrl, net, { staticNetwork: net });
@@ -93,7 +95,7 @@ function rawUnits(value) {
 // Returns [{ address, name, symbol, decimals, balance, holders }].
 //
 // `useBlockscout` is the user's "Use Blockscout" setting. While it is off,
-// Blockscout is not asked and the answer is an empty list: no token the user
+// Blockscout is not asked and the answer is an empty list. So no token the user
 // has not tracked is listed.
 //
 // Filters out spam: only shows tokens that are in the known token list,
@@ -380,10 +382,10 @@ async function refreshBalances(
             // ERC-20 token balances: the tracked tokens' through the RPC
             // endpoint, and from Blockscout the tokens the user has not
             // tracked. When Blockscout fails, the untracked rows from before
-            // this refresh stay; while "Use Blockscout" is off there are none.
-            // The Blockscout request is started first and handed to
-            // fetchTrackedTokenBalances() too, which waits for it after
-            // sending its balanceOf reads, so the two run side by side.
+            // this refresh stay. While "Use Blockscout" is off, there are no
+            // untracked rows. The Blockscout request is started first and
+            // handed to fetchTrackedTokenBalances() too, which waits for it
+            // after sending its balanceOf reads, so the two run side by side.
             const previous = addr.tokenBalances || [];
             const explorerRequest = fetchTokenBalances(
                 addr.address,

src/shared/persistedState.js

@@ -48,10 +48,12 @@ const DEFAULT_STATE = {
     hideDustTransactions: true,
     dustThresholdGwei: 100000,
     utcTimestamps: false,
-    // "Use Blockscout" and "Check recipients on Etherscan" in Settings, one
-    // setting each for every network. Both off until the user turns them on:
-    // the requests they allow send the user's addresses to a service other
-    // than the RPC endpoint.
+    // "Use Blockscout" and "Check recipients on Etherscan" in Settings. Each
+    // setting applies to every network. Both are off until the user turns them
+    // on. With "Use Blockscout" on, Blockscout is sent the user's addresses and
+    // the hash of each transaction opened. With "Check recipients on
+    // Etherscan" on, Etherscan is sent the recipient's address and nothing
+    // else.
     useBlockscout: false,
     checkRecipientsOnEtherscan: false,
     fraudContracts: [],

src/shared/transactions.js

@@ -237,8 +237,7 @@ function mergeTransactions(txs, tokenTransfers) {
 // `nativeCurrency` from networks.js (`ETH`, `SepoliaETH`).
 //
 // `useBlockscout` is the user's "Use Blockscout" setting. While it is off,
-// Blockscout is not asked and there is no history: the answer is an empty
-// list.
+// Blockscout is not asked and the answer is an empty list.
 async function fetchRecentTransactions(
     address,
     blockscoutUrl,

tests/blockscoutEtherscanSettings.test.js

@@ -2,11 +2,10 @@
 // turns them on (https://git.eeqj.de/sneak/AutistMask/issues/668). A new
 // profile has "Use Blockscout" and "Check recipients on Etherscan" both off.
 // Each request to either service is skipped where it is made while its setting
-// is off, and made while it is on; the popup and the background hand the
-// stored setting to the code that makes the request. The one exception is the
-// endpoint check Settings makes when the user presses "Save" beside the
-// Blockscout URL. It asks only for `/stats` and carries no user data; it is
-// made whether or not the setting is on.
+// is off. The popup and the background hand the stored setting to the code that
+// makes the request. The one exception is the check behind "Save" beside the
+// Blockscout URL in Settings. It asks that URL only for `/stats` and carries no
+// user data. It is made whether or not the setting is on.
 //
 // The functions that make the requests are driven directly, against a fetch()
 // that records every URL it is asked for. The screens are driven through the

tests/e2e/run.js

@@ -272,18 +272,20 @@ test("the exact confirmation phrase erases the record and reloads into Welcome (
 // ------------------ Blockscout and Etherscan are sent no user data (#668)
 //
 // A fresh install sends Blockscout and Etherscan none of the user's data until
-// the user turns on "Use Blockscout" or "Check recipients on Etherscan". The
-// endpoint check Settings makes when the user presses "Save" beside the
-// Blockscout URL asks only for `/stats` and carries no user data; it is made
-// whether or not the setting is on. The route handler in tests/e2e/network.js
-// records every request the extension makes, from its pages and its background
-// worker, in env.routeOpts.requests. Recording starts when launch() in
-// tests/e2e/harness.js installs that handler, before the first popup page
-// opens; a request the background worker makes while it starts up, before
-// then, is not recorded. These tests drive Home, AddressDetail, AddressToken
-// and ConfirmTx, and the background's own balance refresh, before either
-// setting is changed, then turn each on and watch its requests start.
-// TransactionDetail, which also asks Blockscout, is left to the unit tests in
+// the user turns on "Use Blockscout" or "Check recipients on Etherscan". One
+// request is made with the setting off: pressing "Save" beside the Blockscout
+// URL asks that URL for `/stats`. It carries no user data.
+//
+// The route handler in tests/e2e/network.js records every request the
+// extension makes in env.routeOpts.requests, from its pages and its background
+// worker. Recording starts when launch() in tests/e2e/harness.js installs that
+// handler, before the first popup page opens. A request the background worker
+// makes while it starts up comes earlier and is not recorded.
+//
+// Before either setting is changed, these tests drive Home, AddressDetail,
+// AddressToken and ConfirmTx, and the background's own balance refresh. Then
+// they turn each setting on and watch its requests start. TransactionDetail,
+// which also asks Blockscout, is left to the unit tests in
 // tests/blockscoutEtherscanSettings.test.js.
 
 // What the three transaction lists say while Use Blockscout is off. Written
@@ -395,11 +397,11 @@ test("with neither setting changed, Home, AddressDetail, AddressToken and Confir
     }
 });
 
-// The background refreshes balances on its alarm, once a minute, and skips a
-// refresh when the stored record says one ran in the last 30 seconds, which
-// the open popup's own refresh does every 10. So the popup is closed, and that
-// record is written back to say no refresh has run, from the background
-// worker, as another extension page saving it would.
+// The background refreshes balances on its alarm, once a minute. It skips a
+// refresh when the stored record says one ran in the last 30 seconds, and the
+// open popup's own refresh runs every 10. So the popup is closed first. The
+// background worker then writes that record back to say no refresh has run, as
+// another extension page saving it would.
 test("with neither setting changed, nothing has reached Blockscout or Etherscan, the background's refresh included (#668)", async (env) => {
     await waitForPersisted(
         env.page,
@@ -501,8 +503,8 @@ test("turning on Use Blockscout from AddressDetail's gear asks Blockscout for th
 });
 
 // Ticked from ConfirmTx's gear, so Back lands on the screen that said no
-// Etherscan check was made. Left on for the rest of the run, as the check was
-// always made before #668.
+// Etherscan check was made. Left on for the rest of the run, so the later
+// confirmation screens are driven with the check made.
 test("turning on Check recipients on Etherscan from ConfirmTx's gear has ConfirmTx ask Etherscan on Back and show its label (#668)", async (env) => {
     env.routeOpts.ethBalanceWei = toHexWei(FUNDED_ETH_WEI);
     env.routeOpts.etherscanLabel = "Fake_Phishing668";

tests/ensOffchainLookup.test.js

@@ -1,13 +1,13 @@
 // ENS lookups ask nothing but the RPC endpoint. A resolver can answer that a
-// name is resolved off-chain, naming a web address to fetch the answer from;
-// ethers fetches it unless the provider has `disableCcipRead` set, and that
-// request would carry the name to a server other than the RPC endpoint
-// (https://git.eeqj.de/sneak/AutistMask/issues/668). With it set, such a name
-// does not resolve.
+// name is resolved off-chain, naming a web address to fetch the answer from.
+// ethers fetches it unless the provider has `disableCcipRead` set. That request
+// would carry the name to a server other than the RPC endpoint
+// (https://git.eeqj.de/sneak/AutistMask/issues/668). With the flag set, such a
+// name does not resolve.
 //
-// The provider getProvider() builds runs against a fake JSON-RPC node,
-// answered through ethers' own request hook, which also records the address of
-// every request ethers makes, the off-chain fetch included.
+// The provider getProvider() builds runs against a fake JSON-RPC node. Its
+// answers go through ethers' own request hook, which also records the address
+// of every request ethers makes, the off-chain fetch included.
 
 const { FetchRequest, Interface } = require("ethers");
 const { getProvider } = require("../src/shared/balances");
@@ -17,11 +17,13 @@ const RESOLVER = "0x5555555555555555555555555555555555555555";
 const USER = "0x1111111111111111111111111111111111111111";
 const NAME = "offchain.eth";
 
-// The ENS registry's resolver(), and the resolver's functions ethers calls: the
-// registry names RESOLVER for every name, the resolver says it resolves names
-// through resolve(), gives NAME as the reverse record of any address, and
-// answers resolve() with the OffchainLookup error that says the name is
-// resolved off-chain.
+// The ENS registry's resolver(), and the resolver's functions ethers calls:
+//
+//   - the registry names RESOLVER for every name
+//   - the resolver says it resolves names through resolve()
+//   - it gives NAME as the reverse record of any address
+//   - it answers resolve() with the OffchainLookup error, which says the name
+//     is resolved off-chain
 const ens = new Interface([
     "function resolver(bytes32) view returns (address)",
     "function supportsInterface(bytes4) view returns (bool)",