chore: bring the token-list enrichment tooling into script/lib (closes #495)

The two node programs and the data file from f7a2437 regenerate the name and
url of each token in src/shared/tokenList.js. They are now CommonJS under
script/lib/ and read ethereum-lists at a pinned commit. The apply step also
rewrites an entry that already has a name and url, so it runs on the current
list, and stops on an address that matches no list entry. Exported as
applyEnrichment, it is run by tests/applyEnrichment.test.js, which fails when
the committed list differs from what it writes. Its table of websites now gives
FLOKI and TURBO a URL. make enrich-tokens and make apply-enrichment run the
programs. script/check-censored allows the MUSD token's on-chain name in the
data file.

Model: opus-5-5

Makefile

@@ -1,4 +1,4 @@
-.PHONY: bootstrap setup install test test-e2e test-e2e-firefox lint fmt fmt-check check check-censored docker hooks build build-debug package vendor-blocklist icons clean dev
+.PHONY: bootstrap setup install test test-e2e test-e2e-firefox lint fmt fmt-check check check-censored docker hooks build build-debug package vendor-blocklist icons enrich-tokens apply-enrichment clean dev
 
 # Standard targets are thin shims; the implementations live in script/
 # per the scripts-to-rule-them-all pattern (see the Entrypoints section
@@ -111,6 +111,20 @@ vendor-blocklist:
 icons:
 	@node script/lib/icons.js
 
+# Fetch a name and a website for every token in src/shared/tokenList.js into
+# script/lib/token-enrichment.json. Run deliberately, land the diff: the names
+# come from live data, so a later run can return different ones.
+enrich-tokens:
+	@node script/lib/enrich-tokens.js
+
+# Write the names and websites in script/lib/token-enrichment.json into
+# src/shared/tokenList.js. Commit the result with the data file:
+# tests/applyEnrichment.test.js fails while the list differs from what this
+# writes, or while an address in the data or in the script's table of websites
+# matches no entry in the list.
+apply-enrichment:
+	@node script/lib/apply-enrichment.js
+
 clean:
 	@rm -rf dist/ release/
 

README.md

@@ -250,11 +250,13 @@ provide:
   nowhere in the working tree or under `dist/` outside its documented
   exceptions: the pinned source reference in `script/vendor-blocklist`, the two
   provider-shim identifiers in `src/content/inpage.js`, and one ERC-20's
-  on-chain name in `src/shared/tokenList.js`. Each is scoped to that path and
+  on-chain name in `src/shared/tokenList.js` and in
-  fails anywhere else. Run by the `lint` phase, so part of `make check`; it
+  `script/lib/token-enrichment.json`, the fetched data that file's names are
-  inspects `dist/` when there is one and says loudly when there is not, and the
+  written from. Each is scoped to the paths named and fails anywhere else. Run
-  build context of that phase never has one. `make build` re-runs it with
+  by the `lint` phase, so part of `make check`; it inspects `dist/` when there
-  `--require-dist`, so a build artifact is always covered
+  is one and says loudly when there is not, and the build context of that phase
+  never has one. `make build` re-runs it with `--require-dist`, so a build
+  artifact is always covered
 - `script/package` — produce the release artifacts: `make build` first, so the
   archives can only ever be made from a `dist/` that has been verified against
   that build's own receipt as a RELEASE build, then one self-contained,
@@ -326,6 +328,19 @@ The Makefile shims to those. It also carries a few targets that have no
   that already holds the drawn image, the same IHDR and every pixel, is left
   untouched. Commit the files with the drawing: `make check` fails while their
   image differs from what it draws
+- `make enrich-tokens` — fetch the name of each token in
+  `src/shared/tokenList.js` from CoinGecko's coin list and its website from the
+  `ethereum-lists/tokens` repository, at a pinned commit, into
+  `script/lib/token-enrichment.json`, by running `script/lib/enrich-tokens.js`.
+  CoinGecko's list is live and has no fixed version, so a later run can return
+  different names
+- `make apply-enrichment` — write the names and URLs in
+  `script/lib/token-enrichment.json` into `src/shared/tokenList.js`, by running
+  `script/lib/apply-enrichment.js`, taking a URL from the table of project
+  websites in that script only where the fetched data has none. Commit the list
+  with the data file: `make check` fails while the list differs from what this
+  writes. Neither target changes which tokens are on the list, and no build runs
+  either
 - `make clean` — remove `dist/` and `release/`
 - `make dev` — run the build `make build` runs, without the checks that follow
   it, then run it again after every change to a file under `src/`, `manifest/`
@@ -2816,7 +2831,7 @@ exact URL, the commit it is pinned to and the sha256 of the bytes that commit
 serves, because a source reference nobody can verify is not a source reference.
 `script/check-censored` reads the name back out of that one file and fails the
 build wherever else it appears, save for three shipped-code literals it cannot
-avoid — each permitted only at the one path that carries it, and listed in that
+avoid — each permitted only at the paths that carry it, and listed in that
 script's header.
 
 ## Author

script/check-censored

@@ -18,6 +18,8 @@
 #     (src/shared/balances.js), and this contract's on-chain name is that
 #     string, so censoring the repo cannot stop the wallet displaying it.
 #     Dropping the entry instead would cost the user MUSD spoof detection.
+#     script/lib/token-enrichment.json, the fetched data tokenList.js's names
+#     are written from, carries the same name for the same reason.
 #
 # Everything else fails, in the working tree and under dist/. The last two are
 # literals rather than whole files, so they are enforced by counting, and each
@@ -102,8 +104,8 @@ allowed_literals_for() {
     src/content/inpage.js | dist/*/src/content/inpage.js)
         printf 'is%s\n_%s\n' "$NAME" "$NAME" >"$ALLOWED_LITERALS_FILE"
         ;;
-    src/shared/tokenList.js | dist/*/src/background/index.js | \
+    src/shared/tokenList.js | script/lib/token-enrichment.json | \
-        dist/*/src/popup/index.js)
+        dist/*/src/background/index.js | dist/*/src/popup/index.js)
         printf '%s USD\n' "$NAME" >"$ALLOWED_LITERALS_FILE"
         ;;
     esac

script/lib/apply-enrichment.js

@@ -0,0 +1,159 @@
+// Writes the names and URLs in script/lib/token-enrichment.json, which
+// script/lib/enrich-tokens.js fetches, into the matching entries of
+// src/shared/tokenList.js: the name and url an entry already has are replaced,
+// and an entry without them gets them after its decimals. Where the fetched
+// data has no URL for a token, EXTRA_URLS below supplies one. An entry the data
+// does not mention is left as it is. An address in the data or in EXTRA_URLS
+// that matches no entry in tokenList.js, capitals included, is an error naming
+// that address. Run by
+// `make apply-enrichment`; no build runs it. tests/applyEnrichment.test.js
+// checks that the committed tokenList.js is exactly what this writes from the
+// committed data.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const TOKEN_LIST = path.join(__dirname, "..", "..", "src/shared/tokenList.js");
+
+// Project websites by token address, each spelled as tokenList.js spells it. A
+// token gets its URL here only where the fetched data has none, so an address
+// the data has a URL for is never used.
+const EXTRA_URLS = {
+    "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2": "https://weth.io",
+    "0xdAC17F958D2ee523a2206206994597C13D831ec7": "https://tether.to",
+    "0xB8c77482e45F1F44dE1745F52C74426C631bDD52": "https://www.bnbchain.org",
+    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": "https://www.circle.com/usdc",
+    "0xdC035D45d973E3EC169d2276DDab16f1e407384F": "https://sky.money",
+    "0x2AF5D2aD76741191D15Dfe7bF6aC92d4Bd912Ca3": "https://www.bitfinex.com",
+    "0x514910771AF9Ca656af840dff83E8264EcF986CA": "https://chain.link",
+    "0x4c9EDD5852cd905f086C759E8383e09bff1E68B3": "https://ethena.fi",
+    "0x8d0D000Ee44948FC98c9B98A4FA4921476f08B0d":
+        "https://www.worldlibertyfinancial.com",
+    "0x6B175474E89094C44Da98b954EedeAC495271d0F": "https://makerdao.com",
+    "0x6c3ea9036406852006290770BEdFcAbA0e23A0e8":
+        "https://www.paypal.com/us/digital-wallet/manage-money/crypto/pyusd",
+    "0x95aD61b0a150d79219dCF64E1E6Cc01f0B64C4cE": "https://shibatoken.com",
+    "0xdA5e1988097297dCdc1f90D4dFE7909e847CBeF6":
+        "https://www.worldlibertyfinancial.com",
+    "0xA0b73E1Ff0B80914AB6fe0444E65848C4C34450b": "https://crypto.com",
+    "0x582d872A1B094FC48F5DE31D3B73F2D9bE47def1": "https://ton.org",
+    "0x68749665FF8D2d112Fa859AA293F07A622782F38": "https://gold.tether.to",
+    "0x196C20DA81Fbc324EcdF55501e95Ce9f0bD84d14": "https://polkadot.network",
+    "0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984": "https://uniswap.org",
+    "0x45804880De22913dAFE09f4980848ECE6EcbAf78":
+        "https://www.paxos.com/paxgold",
+    "0x3c3a81e81dc49A522A592e7622A7E711c06bf354": "https://www.mantle.xyz",
+    "0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9": "https://aave.com",
+    "0x75231F58b43240C9718Dd58B4967c5114342a86c": "https://www.okx.com",
+    "0x6982508145454Ce325dDbE47a25d4ec3d2311933": "https://www.pepe.vip",
+    "0x5A98FcBEA516Cf06857215779Fd812CA3beF1B32": "https://lido.fi",
+    "0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72": "https://ens.domains",
+    "0xD533a949740bb3306d119CC777fa900bA034cd52": "https://curve.fi",
+    "0x111111111117dC0aa78b770fA6A738034120C302": "https://1inch.io",
+    "0x163f8C2467924be0ae7B5347228CABF260318753": "https://worldcoin.org",
+    "0xC011a73ee8576Fb46F5E1c5751cA3B9Fe0af2a6F": "https://synthetix.io",
+    "0xBBbbCA6A901c926F240b89EacB641d8Aec7AEafD": "https://loopring.org",
+    "0xC669928185DbCE49d2230CC9B0979BE6DC797957": "https://bitstable.finance",
+    "0xfAbA6f8e4a5E8Ab82F62fe7C39859FA577269BE3": "https://ondo.finance",
+    "0x6De037ef9aD2725EB40118Bb1702EBb27e4Aeb24": "https://www.render.com",
+    "0x4a220E6096B25EADb88358cb44068A3248254675": "https://www.quant.network",
+    "0xba5BDe662c17e2aDFF1075610382B9B691296350": "https://superrare.com",
+    "0xc00e94Cb662C3520282E6f5717214004A7f26888": "https://compound.finance",
+    "0xE41d2489571d322189246DaFA5ebDe1F4699F498": "https://0x.org",
+    "0x0bc529c00C6401aEF6D220BE8C6Ea1667F6Ad93e": "https://yearn.fi",
+    "0x6fB3e0A217407EFFf7Ca062D46c26E5d60a14d69": "https://iotex.io",
+    "0xF57e7e7C23978C3cAEC3C3548E3D615c346e79fF": "https://immutable.com",
+    "0x0F5D2fB29fb7d3CFeE444a200298f468908cC942": "https://decentraland.org",
+    "0x3845badAde8e6dFF049820680d1F14bD3903a5d0": "https://www.sandbox.game",
+    "0x6810e776880C02933D47DB1b9fc05908e5386b96": "https://gnosis.io",
+    "0x5f98805A4E8be255a32880FDeC7F6728C6568bA0": "https://www.liquity.org",
+    "0x0D8775F648430679A709E98d2b0Cb6250d2887EF":
+        "https://basicattentiontoken.org",
+    "0xc944E90C64B2c07662A292be6244BDf05Cda44a7": "https://thegraph.com",
+    "0x853d955aCEf822Db058eb8505911ED77F175b99e": "https://frax.finance",
+    "0x0000000000085d4780B73119b644AE5ecd22b376": "https://www.trueusd.com",
+    "0x3432B6A60D23Ca0dFCa7761B7ab56459D9C964D0": "https://frax.finance",
+    "0xf939E0A03FB07F59A73314E73794Be0E57ac1b4E": "https://curve.fi",
+    "0x808507121B80c02388fAd14726482e061B8da827": "https://pendle.finance",
+    "0xCa14007Eff0dB1f8135f4C25B34De49AB0d42766": "https://starknet.io",
+    "0x8457CA5040ad67fdebbCC8EdCE889A335Bc0fbFB": "https://alt.layer",
+    "0xB50721BCf8d664c30412Cfbc6cf7a15145234ad1": "https://arbitrum.io",
+    "0x6985884C4392D348587B19cb9eAAf157F13271cd": "https://layerzero.network",
+    "0xFe0c30065B384F05761f15d0CC899D4F9F9Cc0eB": "https://ethfi.org",
+    "0x5283D291DBCF85356A21bA090E6db59121208b44": "https://blur.io",
+    "0x43Dfc4159D86F3A37A5A4B3D4580b888ad7d4DDd": "https://dydx.exchange",
+    "0xcf0C122c6b73ff809C693DB761e7BaeBe62b6a2E": "https://floki.com",
+    "0xe53EC727dbDEB9E2d5456c3be40cFF031AB40A55": "https://superfarm.com",
+    "0x32353A6C91143bfd6C7d363B546e62a9A2489A20": "https://www.agora.finance",
+    "0x1aBaEA1f7C830bD89Acc67eC4af516284b1bC33c": "https://www.euro-coin.com",
+    "0xA35923162C49cF95e6BF26623385eb431ad920D3": "https://www.turbo-eth.com",
+    "0x1151CB3d861920e07a38e03eEAd12C32178567F6": "https://bonk.com",
+    "0x090185f2135308BaD17527004364eBcC2D37e5F6": "https://spell.club",
+    "0xAf5191B0De278C7286d6C7CC6ab6BB8A73bA2Cd6": "https://stargate.finance",
+};
+
+// Returns tokenList, the text of tokenList.js, with the name and url of each
+// token in enrichment, the parsed data file, written into its entry.
+function applyEnrichment(tokenList, enrichment) {
+    for (const addr of Object.keys(EXTRA_URLS)) {
+        if (!tokenList.includes(`address: "${addr}"`)) {
+            throw new Error(
+                `No entry in src/shared/tokenList.js has the address ${addr} from EXTRA_URLS.`,
+            );
+        }
+    }
+
+    let result = tokenList;
+
+    for (const [addr, data] of Object.entries(enrichment)) {
+        // Escape special regex characters in the address
+        const escaped = addr.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+        // Match the token block: { address: "...", symbol: "...", decimals: N, }
+        // and the name: "...", url: "..." after decimals when it has them.
+        // The closing }, may have trailing whitespace
+        const blockRe = new RegExp(
+            `(\\{\\s*address:\\s*"${escaped}",\\s*symbol:\\s*"[^"]+",\\s*decimals:\\s*\\d+)` +
+                `(?:,\\s*name:\\s*"(?:[^"\\\\]|\\\\.)*",\\s*url:\\s*"(?:[^"\\\\]|\\\\.)*")?` +
+                `,?(\\s*\\})`,
+        );
+
+        const match = result.match(blockRe);
+        if (!match) {
+            throw new Error(
+                `No entry in src/shared/tokenList.js matches the address ${addr} from script/lib/token-enrichment.json.`,
+            );
+        }
+
+        // A URL from EXTRA_URLS only where the fetched data has none.
+        const url = data.url || EXTRA_URLS[addr] || "";
+
+        // Build replacement: original fields + name + url
+        const nameEscaped = data.name
+            .replace(/\\/g, "\\\\")
+            .replace(/"/g, '\\"');
+        const urlEscaped = url.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        const replacement =
+            match[1] +
+            `,\n        name: "${nameEscaped}",` +
+            `\n        url: "${urlEscaped}",` +
+            match[2];
+
+        // A function, so a "$" in a name is not read as a replacement pattern.
+        result = result.replace(blockRe, () => replacement);
+    }
+
+    return result;
+}
+
+if (require.main === module) {
+    const enrichment = JSON.parse(
+        fs.readFileSync(path.join(__dirname, "token-enrichment.json"), "utf8"),
+    );
+    const original = fs.readFileSync(TOKEN_LIST, "utf8");
+    fs.writeFileSync(TOKEN_LIST, applyEnrichment(original, enrichment));
+}
+
+module.exports = { applyEnrichment };

script/lib/enrich-tokens.js

@@ -0,0 +1,115 @@
+// Fetches a name and a website for every token in src/shared/tokenList.js and
+// writes them, keyed by address, to script/lib/token-enrichment.json, which
+// script/lib/apply-enrichment.js then writes into tokenList.js. Run by
+// `make enrich-tokens`; no build runs it and nothing here is shipped.
+//
+// Names come from CoinGecko's coin list, fetched whole in one request, matched
+// on the token's Ethereum contract address. A token CoinGecko does not list
+// gets its symbol as its name. The list is live data with no fixed version, so
+// a later run can return different names.
+//
+// Websites come from the ethereum-lists/tokens repository, one file per token,
+// read at a pinned commit. Most tokens have no file there and get an empty URL.
+// A file that is missing is not an error; any other failed request stops the
+// run, so a network fault cannot quietly empty a URL.
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const TOKEN_LIST = path.join(__dirname, "..", "..", "src/shared/tokenList.js");
+const OUTPUT = path.join(__dirname, "token-enrichment.json");
+
+const COINGECKO_LIST =
+    "https://api.coingecko.com/api/v3/coins/list?include_platform=true";
+// ethereum-lists/tokens at its master of 2026-02-27, when the committed
+// token-enrichment.json was made.
+const ETHEREUM_LISTS =
+    "https://raw.githubusercontent.com/ethereum-lists/tokens/c3560d499a380a38e94caa7c4968d59aeffde59a/tokens/eth";
+
+const CONCURRENT = 10;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function main() {
+    const src = fs.readFileSync(TOKEN_LIST, "utf8");
+
+    const tokens = [];
+    const re =
+        /\{\s*address:\s*"(0x[a-fA-F0-9]{40})",\s*symbol:\s*"([^"]+)",\s*decimals:\s*(\d+)/g;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        tokens.push({ address: m[1], symbol: m[2], decimals: parseInt(m[3]) });
+    }
+    console.error(`Parsed ${tokens.length} tokens`);
+
+    // --- Names from CoinGecko ---
+    console.error("Fetching CoinGecko coins list...");
+    const listResp = await fetch(COINGECKO_LIST);
+    if (!listResp.ok) throw new Error(`CoinGecko list HTTP ${listResp.status}`);
+    const coins = await listResp.json();
+
+    const addrMap = new Map();
+    for (const coin of coins) {
+        const eth = (coin.platforms?.ethereum || "").toLowerCase().trim();
+        if (eth && eth.startsWith("0x")) {
+            addrMap.set(eth, { name: coin.name, id: coin.id });
+        }
+    }
+    console.error(`CoinGecko map: ${addrMap.size} Ethereum tokens`);
+
+    const enriched = new Map();
+    let namesMatched = 0;
+    for (const t of tokens) {
+        const info = addrMap.get(t.address.toLowerCase());
+        if (info) namesMatched++;
+        enriched.set(t.address, { name: info?.name || t.symbol, url: "" });
+    }
+    console.error(`Matched ${namesMatched}/${tokens.length} names`);
+
+    // --- Websites from ethereum-lists ---
+    console.error("Fetching URLs from ethereum-lists GitHub...");
+    let urlsFound = 0;
+
+    for (let i = 0; i < tokens.length; i += CONCURRENT) {
+        const batch = tokens.slice(i, i + CONCURRENT);
+        await Promise.all(
+            batch.map(async (t) => {
+                const r = await fetch(`${ETHEREUM_LISTS}/${t.address}.json`);
+                if (r.status === 404) return;
+                if (!r.ok) {
+                    throw new Error(
+                        `ethereum-lists HTTP ${r.status} for ${t.address}`,
+                    );
+                }
+                const data = await r.json();
+                const website = (data.website || "").trim();
+                if (website && website !== "https://") {
+                    enriched.get(t.address).url = website;
+                    urlsFound++;
+                }
+            }),
+        );
+        if (i % 100 === 0) {
+            console.error(
+                `  GitHub: ${Math.min(i + CONCURRENT, tokens.length)}/${tokens.length}, ${urlsFound} URLs`,
+            );
+        }
+        await sleep(200);
+    }
+    console.error(`Found ${urlsFound} URLs in ethereum-lists`);
+
+    // --- Output, in the layout prettier gives it ---
+    const output = {};
+    for (const [addr, e] of enriched) {
+        output[addr] = { name: e.name, url: e.url };
+    }
+    fs.writeFileSync(OUTPUT, JSON.stringify(output, null, 4) + "\n");
+    console.error(`Done! ${tokens.length} names, ${urlsFound} URLs.`);
+}
+
+main().catch((err) => {
+    console.error(`enrich-tokens: ${err.message}`);
+    process.exit(1);
+});

src/shared/tokenList.js

@@ -576,7 +576,7 @@ const TOKENS = [
         symbol: "FLOKI",
         decimals: 9,
         name: "FLOKI",
-        url: "",
+        url: "https://floki.com",
     },
     {
         address: "0x7420B4b9a0110cdC71fB720908340C03F9Bc03EC",
@@ -1290,7 +1290,7 @@ const TOKENS = [
         symbol: "TURBO",
         decimals: 18,
         name: "Turbo",
-        url: "",
+        url: "https://www.turbo-eth.com",
     },
     {
         address: "0xA27EC0006e59f245217Ff08CD52A7E8b169E62D2",

tests/applyEnrichment.test.js

@@ -0,0 +1,19 @@
+// The token names and URLs in src/shared/tokenList.js are written from
+// script/lib/token-enrichment.json by script/lib/apply-enrichment.js
+// (`make apply-enrichment`). This fails when the committed list differs from
+// what the script writes from the committed data, and when the data or the
+// script's table of websites has an address that no entry in the list matches.
+
+const fs = require("fs");
+const path = require("path");
+
+const enrichment = require("../script/lib/token-enrichment.json");
+const { applyEnrichment } = require("../script/lib/apply-enrichment");
+
+test("src/shared/tokenList.js is what make apply-enrichment writes from the committed data", () => {
+    const committed = fs.readFileSync(
+        path.join(__dirname, "..", "src/shared/tokenList.js"),
+        "utf8",
+    );
+    expect(applyEnrichment(committed, enrichment)).toBe(committed);
+});