docs: reframe Token Contracts as Fee Currencies, split stablecoin address list

[GigaHierz]

The "Token Contracts" page is autogenerated from celocli network:whitelist, so it actually lists the tokens allowlisted to pay gas rather than a token directory — it is retitled to Fee Currencies and now says so, and the generator emits the Whitelisted Address column it was previously dropping (the value passed as feeCurrency, and the adapter address for non-18-decimal tokens like USDC and USD₮).

The stablecoin page is split along the same lines: build-with-local-stablecoin keeps the ecosystem overview in Build, while the address matrix moves to a new generated tooling/contracts/stablecoin-contracts page — Mento stablecoins plus USDC, USD₮ and USA₮ are read from the fee-currency allowlist (the only source covering Celo Sepolia), and third-party issuers with no registry are curated in scripts/data/stablecoins.json.

The MetaMask and Coinbase Wallet links are repointed at the address page since they wanted token addresses rather than fee currencies, and the fee-currency references in the specs, ContractKit and fee-abstraction pages are relabelled.

Verified with npx mintlify broken-links (clean) and by running the generator with celocli mocked, which reproduces the new stablecoin page byte-for-byte; no addresses were lost in the move, and USDC's previously blank Celo Sepolia cell is now filled in. The new feeCurrency Address column populates on the next real generator run, which needs celocli and TENDERLY_API_KEY.

🤖 Generated with Claude Code

[palango]

The reframing is right. "Token Contracts" was always mislabelled, since it has only ever been the celocli network:whitelist output, and pulling the address matrix out of the Build page is a clean split. The new feeCurrency column fixes a real footgun too: copy USDC's token address into feeCurrency and your transaction fails. I checked all 34 addresses survive the move, and the counts in the new intro (7 USD-pegged, 26 regional, plus G$) match the rows.

Two things block merge for me.

1. scripts/data/stablecoins.json isn't in the PR

scripts/.gitignore line 1 is *.json, which matches at any depth, so the file never got staged:

$ git check-ignore -v scripts/data/stablecoins.json
scripts/.gitignore:1:*.json	scripts/data/stablecoins.json

git ls-tree -r <branch> scripts/ lists only .gitignore, README.md and update_contracts.py, and calling load_stablecoin_data() on a checkout of the branch gives:

FileNotFoundError: [Errno 2] No such file or directory: 'scripts/data/stablecoins.json'

The annoying part is what it does on the way down. At scripts/update_contracts.py:411-414 the output file is opened "w", so it's already truncated and the header already written by the time load_stablecoin_data() raises. Next generator run, stablecoin-contracts.mdx becomes a bare header and the address table is gone.

So: narrow the ignore (add !data/) and commit the file. And while you're in there, move load_stablecoin_data() above the open(...) so a missing input can't truncate the page it failed to build.

Side effect worth naming: scripts/README.md:11 documents a file that isn't there, and neither the third-party addresses nor the Sepolia overrides can be reviewed here.

2. The Fee Currencies page describes a column it doesn't have

tooling/contracts/token-contracts.mdx:16 tells readers to "Pass the feeCurrency address ... and use the token address when transferring the token itself." The committed tables are still | Token | Symbol | Token Address |.

I know the description says this fills in on the next real generator run. But nothing triggers one. .github/workflows/docs-validation.yml only runs mintlify broken-links, and nothing under .github/ mentions update_contracts, so unless someone remembers to run it by hand the page ships pointing at a column readers can't find. Regenerate with real celocli before merge, or hold that paragraph back.

Worth addressing

Sepolia carries BRLm, EURm and USDm twice at different addresses. EURm is both 0x6B172e33... and 0xA99dC247.... allowlisted_stablecoins keeps whichever lands last in the CSV and prints a warning (update_contracts.py:223-236), which is reasonable, but the reader gets nothing: two EURm rows on Fee Currencies, one on Stablecoin Contracts, no hint which deployment is live. The warning tells you to pin it in scripts/data/stablecoins.json, except the override map only covers Sepolia. If mainnet ever picks up a duplicate there's no lever at all.

build-on-celo/build-with-local-stablecoin.mdx:54 says "every Mento stablecoin plus USDC, USD₮ and USA₮ is on the allowlist ... See [Fee Currencies]", and the mainnet table it links to has no USA₮ row. using-fee-abstraction.mdx:46 does list a USA₮ adapter, so I assume the allowlist page is just stale rather than the claim being wrong. Either way, that sentence walks the reader into the contradiction.

Last one, and this is more a nit than a finding: name.startswith("Mento ") at update_contracts.py:230 fails silently. If those token names change upstream, every Mento stablecoin drops off the page and the only symptom is a shorter table. An explicit set of expected symbols that warns on a miss would at least be loud about it.

Minor

• Title is now "Fee Currencies" while the URL and id stay token-contracts. Fine for link stability, but the next person here will wonder. A comment in the generator would cover it, or rename with a redirect at some point.
• The /token-addresses redirect fix and repointing MetaMask/Coinbase at the address page are both correct. Those wanted token addresses, not fee currencies.
• FIAT_BACKED_SYMBOLS (update_contracts.py:24) is an odd name given Mento stablecoins are fiat-referenced too. NON_MENTO_STABLECOIN_SYMBOLS is what the comment beside it already says.

CI's green, but broken-links only checks links, so none of this would have surfaced there.

[GigaHierz]

Thanks — both blockers were real. Rebased onto latest main and pushed.

1. scripts/data/stablecoins.json wasn't committed. Confirmed exactly as you described: scripts/.gitignore line 1 is *.json, which matched at any depth. scripts/.gitignore now re-includes data/*.json, the file is in the tree (git ls-tree -r HEAD scripts/ lists it), and README.md documents the trap so the next curated input doesn't hit it. Also moved load_stablecoin_data() above every open(..., "w") — good catch that the failure mode was a truncated page, not just an exception.

2. The page described a column it didn't have. You were right that nothing would trigger a regeneration. Rather than hold the paragraph back, I switched the fee-currency source from celocli network:whitelist to FeeCurrencyDirectory.getCurrencies() read through cast, which is already a documented prerequisite and already used by get_l1_contracts. Both pages are now generated from live chain state and committed with real data.

That surfaced more than the missing column:

• USA₮ and XAUt0 were missing from the allowlist page entirely. Both are now there, which also resolves the contradiction you flagged — the "USA₮ is on the allowlist" sentence now links to a table that shows it.
• The Sepolia "duplicates" aren't duplicates. 0x6B172e33… reports symbol() == cEUR, name Celo Euro — it's the legacy cUSD/cEUR/cREAL deployments, not second copies of USDm/EURm/BRLm. The old page mislabelled them. The override map is gone, and the duplicate warning now names both addresses and the network rather than pointing at a Sepolia-only lever.
• Adapters come in two generations. adaptedToken() works for the USDC adapter but reverts on the USD₮ and USA₮ ones, which expose getAdaptedToken(). The generator tries both, and using-fee-abstraction.mdx said only adaptedToken() — corrected.

Silent startswith("Mento ") failure: added EXPECTED_MENTO_SYMBOLS; the generator warns if an expected stablecoin is absent from the allowlist, so a rename upstream can't quietly empty the table.

Minor: FIAT_BACKED_SYMBOLS → NON_MENTO_STABLECOIN_SYMBOLS. And on the title/URL mismatch — the page is now at /tooling/contracts/fee-currencies, with redirects from /tooling/contracts/token-contracts and /contracts/token-contracts.

Also picked up #2233 and #2234 in the rebase: cNGN added, vEUR removed.

Verification: mintlify broken-links clean; full main() run against mainnet and Celo Sepolia regenerates both pages byte-identically with no warnings. celocli is still needed for the core-contracts page, but no longer for these two.