[chrisli30]

Closes #38.

What changes for consumers

• More tokens. BNB Chain goes from 2 rows to 17 (WBNB first). Ethereum gains 25 (RLUSD, USDG, GHO, cbETH, sDAI, crvUSD, …) and Base gains 13 (RLUSD, WBTC, GHO, LBTC, tBTC, weETH, …). Every Aave V3 Core reserve on the three mainnets is now in Tokens by address.
• Fixes
  • Base Sepolia USDT said 6 decimals; the contract returns 18.
  • lookupToken(56, WBNB) returned symbol "WETH" through Uniswap's wrapped-native slot.
• Breaking: Ethereum Tokens["SolvBTC.BBN"] is renamed Tokens.xSolvBTC, following Solv's rebrand (the contract's name() and symbol() both return xSolvBTC). This is a major changeset, so the next release is 2.0.0.
• New optional field TokenChainEntry.transferConstraints (TOKEN_TRANSFER_CONSTRAINT):
  • permissionedRecipient on OUSG, BUIDL and USYC: a transfer to a fresh address reverts.
  • rebasing on stETH and eETH: a full-balance transfer can leave 1–2 wei.

Audit deliverables (#38)

Deliverable	Where
Per-chain coverage matrix (present / missing / bridged / legacy / unverified / transfer handling, with sources and verification dates)	docs/TOKEN_COVERAGE.md, generated by yarn report:tokens; a test fails if it is stale
Prioritized gaps, filled with changesets and integrity tests	WBNB and RLUSD first; KNOWN_GAPS is now empty
Inclusion and maintenance policy, plus remaining gaps	docs/TOKEN_CATALOG.md (an explicit per-chain target, not "all common tokens")
Consumer guidance: recognizing an asset vs. transferring it	docs/TOKEN_CATALOG.md, "Guidance for consumers"

Provenance. Each audited row records its canonical source, issuance (native, bridged or test), bridge, legacy status and verifiedAt in src/tokens/provenance/*.json. These files are not shipped.

• Tests pin each provenance address to the catalog.
• The 80 rows listed before the audit are on an explicit pending list, and that list can only shrink.

Tooling

• yarn verify:tokens: an on-chain check of code, decimals() and symbol(). It needs network access, so it is not part of yarn test.
• An EIP-55 checksum test, which caught one address I had mistyped.

How it was verified

No transaction was sent and nothing was signed.

• On-chain: yarn verify:tokens checks all 196 rows with 0 errors and 0 warnings.
• Addresses: every added address was checked against the issuer's or protocol's own address page.
• Transfer behaviour: every mainnet row was simulated with a read-only full-balance transfer (eth_call with a state override), except seven bridged rows that had no simulatable holder. They are named in the audit record.
• Repo checks: yarn typecheck is clean, 127 tests pass, and yarn build works. The sidecar has 196 entries, and the tarball excludes the provenance files and docs.

Follow-ups outside this repo

• EigenLayer-AVS core/taskengine/tokenwhitelist/ carries the same wrong Base Sepolia USDT decimals (6) and still names Ethereum SolvBTC.BBN. Its drift check against the sidecar should flag both.
• Studio:
  • drop the EURC compatibility rows in app/lib/erc20/catalog.ts;
  • show transferConstraints on the Sweep selection step;
  • bump to @avaprotocol/protocols@^2.

🤖 Generated with Claude Code