Implement token-to-icon mappings (mapTokensBatch)

[igor53627]

Summary

The IconRegistry contract has a tokenToIcon mapping that maps token addresses (with chain IDs) to icon slugs. This mapping is currently empty and needs to be populated.

Context

• Contract: 0x342e808c40D8E00656fEd124CA11aEcBB96c61Fc (mainnet)
• The contract already has 9,869 icons uploaded
• Chain ID mappings are set up (184 chains via chainToIcon)
• Token mappings need a similar approach

Requirements

1. Add mapTokensBatch function to contract

The current contract only has mapToken for single mappings. For efficiency, we need:

function mapTokensBatch(
    address[] calldata tokens,
    uint256[] calldata chainIds,
    string[] calldata slugs
) external onlyOwner

2. Create token mapping data source

Need to build a canonical list of token → icon mappings. Possible sources:

• DefiLlama token lists
• CoinGecko API
• Trust Wallet assets
• Custom curation

3. Create deployment script

Similar to setup-chain-mappings.ts:

• Read token list from JSON
• Check which mappings already exist
• Batch deploy new mappings
• Use Turnkey for signing

Estimated Scope

• ~10,000+ token mappings across multiple chains
• Contract upgrade to add batch function
• New token-mappings.json data file
• setup-token-mappings.ts script

Open Questions

1. Should we use the same icon for a token across all chains (e.g., USDC on Ethereum = USDC on Arbitrum)?
2. Do we need versioning for token icons?
3. Should we integrate with an existing token list standard (Uniswap, etc.)?

---

Pending oracle review for architecture recommendations.

[igor53627]

Oracle Architecture Review

TL;DR

• Keep the current token → (chainId → slugHash) design and add a simple mapTokensBatch that just writes mappings
• Reuse the same slug across chains for the "same asset" where appropriate (contract already supports this)
• Use token list standards off-chain as the canonical source of truth; rely on existing slug-based icon versioning

---

Recommended Contract Changes

1. Validate slug exists in mapToken

function mapToken(address token, uint256 chainId, string calldata slug) external onlyOwner {
    bytes32 slugHash = _hashSlug(slug);
    Icon storage icon = icons[slugHash];
    if (icon.pointer == address(0)) revert IconNotFound(); // prevents mapping to non-existent slug

    tokenToIcon[token][chainId] = slugHash;
    emit TokenMapped(token, chainId, slugHash);
}

2. Add mapTokensBatch

function mapTokensBatch(
    address[] calldata tokens,
    uint256[] calldata chainIds,
    string[] calldata slugs
) external onlyOwner {
    uint256 len = tokens.length;
    if (chainIds.length != len || slugs.length != len) revert LengthMismatch();

    for (uint256 i; i < len;) {
        bytes32 slugHash = _hashSlug(slugs[i]);
        Icon storage icon = icons[slugHash];
        if (icon.pointer == address(0)) revert IconNotFound();

        tokenToIcon[tokens[i]][chainIds[i]] = slugHash;
        emit TokenMapped(tokens[i], chainIds[i], slugHash);

        unchecked { ++i; }
    }
}

3. (Optional) Hash-based batch for cheaper calldata

function mapTokensHashBatch(
    address[] calldata tokens,
    uint256[] calldata chainIds,
    bytes32[] calldata slugHashes
) external onlyOwner

---

Off-chain Architecture

Canonical Asset Model

• Define a canonical asset entity off-chain (CoinGecko/DefiLlama ID)
• Maintain mapping: (chainId, tokenAddress) -> assetId -> iconSlug
• On-chain just stores (tokenAddress, chainId) -> slugHash

Slug Naming

Use stable slug names representing assets, not specific deployments:

• tokens/usd-coin, tokens/tether, tokens/wrapped-bitcoin
• Multiple token addresses across chains can point to the same slug

Batch Size

• Recommended: 100-200 mappings per tx
• Each mapping ~30-50k gas depending on fresh write vs overwrite
• 200 × 50k ≈ 10M gas, safely below block limits
• Use estimateGas dynamically in scripts

---

Answers to Open Questions

Q1: Same token on different chains?
✅ Yes, reuse the same slug. USDC on Ethereum and Arbitrum should both map to tokens/usd-coin.

Q2: Optimal batch size?
✅ 100-200 per tx, or dynamically sized based on gas estimation.

Q3: Token list standards?
✅ Yes, use Uniswap Token Lists (or aggregated superset) as off-chain data source. Normalize to your assetId -> slug mapping.

Q4: Security considerations?

• Ensure mapToken reverts if slug doesnt exist (prevent mapping to non-existent icon)
• Use multisig/Turnkey for owner key
• Consider monitoring TokenMapped events for major tokens

Q5: Icon updates/versioning?
✅ Current design is correct:

• Tokens map to slugHash, not specific version
• When icon is updated via setIcon, all tokens automatically see new version
• Historical versions remain accessible via getIconVersion

---

Risks & Guardrails

1. Mapping correctness - Use dry-run mode, human review for large batches
2. Stable slugs - Tie to assetId, avoid reusing for different visual identities
3. Gas limits - Use estimateGas, cap at 15-20M target

---

This review provided by oracle (GPT-5). Implementation effort estimated at 1-2 days including testing & deployment.

[igor53627]

Implementation Complete

Token mapping infrastructure is now ready:

Scripts Created

• scripts/sync-token-mappings.ts - Fetches stablecoin data from DefiLlama and generates mappings
• scripts/setup-token-mappings.ts - Deploys token mappings to contract

GitHub Workflow

• .github/workflows/setup-token-mappings.yml - Manual trigger for deploying mappings

Documentation

• docs/TOKEN-MAPPINGS.md - Usage guide
• docs/token-mappings.json - 86 initial mappings (mostly stablecoins)

Status

• Contract already has mapTokensBatch with slug validation ✓
• Initial mappings generated (86 tokens, 7 chains)
• Dry run verified - ready to deploy

Next Steps

1. Run the workflow with dry_run=false to deploy initial mappings
2. Add more token sources (CoinGecko, Trust Wallet) for broader coverage
3. Consider automating sync on new icon uploads

[igor53627]

Progress Update

Status: Implementation Complete, Deployment Pending

Completed:

• ✅ Contract already has mapTokensBatch() function (line 267 in IconRegistry.sol)
• ✅ Created sync-token-mappings.ts - fetches token data from CoinGecko/DefiLlama
• ✅ Created setup-token-mappings.ts - deployment script using Turnkey signing
• ✅ Chain ID mappings already set up (184 chains)

Pending:

• ⏳ Generate canonical token-mappings.json from data sources
• ⏳ Test deployment on testnet
• ⏳ Execute mainnet deployment

Next Steps:

1. Run sync-token-mappings.ts to build token mapping dataset
2. Review and curate the mappings
3. Deploy via setup-token-mappings.ts