USDT0 - wrong related assets for most flavours

[gomesalexandre]

Overview

See USDT0 on Polygon:

vs. USDT0 on Arb/Op:

References and additional details

N/A

Acceptance Criteria

• All USDT/0 asset pages display all USDT/0 related assets including canonical/bridged

Need By Date

No response

Screenshots/Mockups

No response

Estimated effort

No response

[gomesalexandre]

Robots writeup:

Issue #11113: USDT/USDT0 Related Assets Asymmetry - Technical Analysis

Summary

USDT (Tether) and USDT0 (a different bridged token) are incorrectly creating asymmetric related asset groupings. USDT pages show USDT0 variants as related, but USDT0 pages don't show USDT variants back, violating the bidirectional relationship expectation.

The Problem

Current Behavior (Incorrect)

On ETH USDT page (assetId: eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7):
Related assets show:

• ✅ Avalanche USDT (0x9702...f4a8c7)
• ✅ BSC USDT (0x55d3...197955)
• ✅ Gnosis USDT (0x4eca...d605c6)
• ✅ Optimism USDT (0x94b0...e58e58)
• ✅ Solana USDT (Es9vM...wNYB)
• ❌ Arbitrum USDT0 (0xfd08...fcbb9) - Shows as "USDT0"
• ❌ Polygon USDT0 (0xc213...8e8f) - Shows as "USDT0"

On Polygon USDT0 page (assetId: eip155:137/erc20:0xc2132d05d31c914a87c6611c10748aeb04b58e8f):
Related assets show:

• ✅ Arbitrum USDT0 (0xfd08...fcbb9)
• ✅ Optimism USDT0 (0x01bf...c1071)
• ❌ Does NOT show ETH USDT or other real USDT variants

Expected Behavior

Option A - Single Unified Group:
All USDT and USDT0 variants should be in ONE group. Every asset page shows the same complete list.

Option B - Separate Clean Groups:

• USDT Group: Only real Tether USDT (ETH, Arbitrum, Polygon, Avalanche, BSC, Optimism, Gnosis, Solana)
• USDT0 Group: Only USDT0 variants (standalone tokens on newer chains)
• No mixing - distinct tokens remain distinct

Root Cause Analysis

What is USDT vs USDT0?

• Tether (USDT): Official Tether stablecoin by Tether Limited

  • Coingecko ID: tether
  • Symbol: USDT

• USDT0: A different wrapped/bridged USDT variant

  • Coingecko ID: usdt0
  • Symbol: USDT0
  • These are DIFFERENT tokens per Coingecko

The Data Corruption

Coingecko API Issue:
When querying different coin IDs, Coingecko returns OVERLAPPING contract addresses:

Query: /coins/tether (Real USDT)

{
  "platforms": {
    "ethereum": "0xdac17f958d2ee523a2206206994597c13d831ec7",
    "arbitrum-one": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",
    "polygon-pos": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",
    "optimistic-ethereum": "0x94b008aa00579c1307b0ef2c499ad98a8ce58e58",
    ...
  }
}

Query: /coins/usdt0 (USDT0 token)

{
  "platforms": {
    "arbitrum-one": "0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9",    // SAME!
    "polygon-pos": "0xc2132d05d31c914a87c6611c10748aeb04b58e8f",     // SAME!
    "optimistic-ethereum": "0x01bff41798a0bcf287b996046ca68b395dbc1071", // Different
    "monad": "0xe7cd86e13ac4309349f30b3435a9d337750fc82d",
    ...
  }
}

The conflict: Contracts 0xfd08... (Arbitrum) and 0xc213... (Polygon) are claimed by BOTH coins!

How Our Generation Script Processes This

File: scripts/generateAssetData/generateRelatedAssetIndex/generateRelatedAssetIndex.ts

The script processes ALL assets sequentially and builds two data structures:

1. assetData - Each asset gets a relatedAssetKey property (which group it belongs to)
2. relatedAssetIndex - Maps relatedAssetKey → [array of related assetIds]

Processing Flow:

// Processes assets in market cap order
for (assetId in sortedAssets) {
  const platforms = await fetchCoingeckoPlatforms(assetId)
  const relatedAssetIds = mapPlatformsToAssetIds(platforms)
  const relatedAssetKey = relatedAssetIds[0] // Primary implementation
  
  // Update ALL related assets to point to this key
  for (relatedAssetId of relatedAssetIds) {
    assetData[relatedAssetId].relatedAssetKey = relatedAssetKey  // OVERWRITES!
  }
  
  relatedAssetIndex[relatedAssetKey] = relatedAssetIds
}

What Actually Happens:

Step 1: Process ETH USDT (market cap rank ~3)

• Fetch /coins/tether platforms
• Find: Arbitrum 0xfd08..., Polygon 0xc213..., etc.
• Set arbitrumUsdt.relatedAssetKey = 'eth_usdt' ✅
• Set polygonUsdt.relatedAssetKey = 'eth_usdt' ✅
• Set relatedAssetIndex['eth_usdt'] = [eth, arbitrum, polygon, avalanche, ...] ✅

Step 2: Process some USDT0 variant (market cap rank ~5000)

• Fetch /coins/usdt0 platforms
• Find: SAME Arbitrum 0xfd08..., SAME Polygon 0xc213..., Monad, Optimism
• OVERWRITES arbitrumUsdt.relatedAssetKey = 'usdt0_primary' ❌
• OVERWRITES polygonUsdt.relatedAssetKey = 'usdt0_primary' ❌
• Set relatedAssetIndex['usdt0_primary'] = [usdt0, arbitrum, polygon, monad, ...] ❌

Step 3: Display Rendering

// On ETH USDT page:
const relatedIds = relatedAssetIndex['eth_usdt']  
// Returns: [eth, arbitrum, polygon, avalanche, ...]
// Shows all of these, including arbitrum/polygon which now say "USDT0" 
// because their asset data was overwritten!

// On Arbitrum USDT page:
const key = arbitrumAsset.relatedAssetKey  // 'usdt0_primary'
const relatedIds = relatedAssetIndex['usdt0_primary']
// Returns: [usdt0_variants_only]
// Shows different list!

The Asymmetry

• Old index entry for ETH USDT still references Arbitrum/Polygon
• Asset metadata for Arbitrum/Polygon now points to USDT0 group
• Result: One direction shows mixed, other direction shows pure

Investigation: Which Approach?

Option A: Merge Into Single USDT Group

Approach: Treat USDT and USDT0 as the same token, merge all variants.

Implementation:

• When detecting Arbitrum/Polygon contracts appear in both groups
• Merge the groups together
• All USDT/USDT0 variants share one relatedAssetKey

Pros:

• Users see all USDT-like tokens together
• Simpler for users - one comprehensive list
• Reflects that USDT0 is "1:1 backed by USDT"

Cons:

• They ARE different tokens per Coingecko (different IDs, different market data)
• Mixing canonical with bridged/wrapped variants
• Could confuse users about which is "real" USDT
• If USDT0 has different properties (fees, trust model), hiding the distinction is misleading

Risk Assessment:

• Medium - Might mislead users about token differences
• Coingecko considers them separate for a reason

Option B: Keep Separate, Prevent Stealing (Recommended)

Approach: Enforce strict separation - USDT and USDT0 are different tokens that cannot share assets.

Implementation:
Add validation in processRelatedAssetIds():

// After fetching related assets from Coingecko/Zerion
const cleanedRelatedAssetIds = mergedRelatedAssetIds.filter(candidateAssetId => {
  const existingKey = assetData[candidateAssetId]?.relatedAssetKey
  
  // Asset has no group yet, or already in this group - OK
  if (!existingKey || existingKey === relatedAssetKey) {
    return true
  }
  
  // Asset already belongs to a different group - conflict!
  console.warn(
    `[Related Asset Conflict] ${candidateAssetId} already belongs to group ${existingKey}, ` +
    `refusing to add to ${relatedAssetKey}. ` +
    `Coingecko returned the same contract for multiple coin IDs - data quality issue.`
  )
  return false
})

// Only create group if still have multiple assets after filtering
if (cleanedRelatedAssetIds.length > 1) {
  relatedAssetIndex[relatedAssetKey] = cleanedRelatedAssetIds
  for (const relatedAssetId of cleanedRelatedAssetIds) {
    assetData[relatedAssetId].relatedAssetKey = relatedAssetKey
  }
} else {
  assetData[assetId].relatedAssetKey = null
}

Pros:

• Respects Coingecko's distinction between tokens
• Prevents contract address conflicts
• First-come-first-served: Higher market cap (real USDT) wins
• Protects data integrity
• Future-proof against similar issues with other tokens

Cons:

• Users won't see USDT0 variants when viewing USDT
• Requires understanding that USDT ≠ USDT0

Risk Assessment:

• Low - Maintains data accuracy and prevents corruption

Processing Order Ensures Correctness

Assets are processed by getSortedAssetIds() which orders by:

1. Market cap ranking (descending)
2. Asset name (ascending)

Market Cap Ranks:

• Tether (USDT): Rank ~3 → Processes FIRST
• USDT0: Rank ~5000+ → Processes LATER

With first-come-first-served validation:

1. ETH USDT processes, claims Arbitrum 0xfd08... and Polygon 0xc213...
2. Later, USDT0 tries to claim them → validation detects conflict → removes them
3. USDT0 ends up with only its actual unique contracts
4. Result: Clean separation, no mixing

Recommended Solution

Implement Option B - Keep separate groups with conflict prevention.

Rationale:

1. Coingecko maintains separate coin IDs for a reason - they are different tokens
2. Prevents data corruption from bad upstream data
3. Higher market cap token (real USDT) correctly takes precedence
4. Bidirectional consistency: A→B shows same as B→A
5. Protects against similar issues with other token pairs

Implementation:

1. Add conflict detection in processRelatedAssetIds()
2. Filter out assets already claimed by other groups
3. Log warnings for debugging
4. Regenerate asset data

Expected Result:

• USDT Group: ETH, Arbitrum, Polygon, Avalanche, BSC, Optimism, Gnosis, Solana (all real USDT)
• USDT0 Group: Only unique USDT0 contracts on chains where it's distinct
• No overlap, clean separation
• Bidirectional consistency restored

Files To Modify

• scripts/generateAssetData/generateRelatedAssetIndex/generateRelatedAssetIndex.ts - Add conflict validation

Testing Steps

Before Fix

1. Navigate to ETH USDT asset page
2. Expand related assets → See Arbitrum USDT0, Polygon USDT0 mixed in ❌
3. Click "Arbitrum USDT0"
4. Check related assets → See ONLY USDT0 variants ❌
5. Asymmetry detected - different lists depending on navigation direction

After Fix

1. Navigate to ETH USDT asset page
2. Expand related assets → See ONLY real USDT variants (no USDT0) ✅
3. Click any variant → All show identical list ✅
4. Navigate to any USDT0 page → Shows only USDT0 variants ✅
5. Symmetry restored - bidirectional consistency

Technical Details

Data Structures

• assetData[assetId].relatedAssetKey - Which group this asset belongs to
• relatedAssetIndex[relatedAssetKey] - Array of all assetIds in this group

Selector Logic

// In selectRelatedAssetIdsInclusive:
const relatedAssetKey = asset.relatedAssetKey
const relatedAssetIds = relatedAssetIndex[relatedAssetKey]
return [relatedAssetKey, ...relatedAssetIds]  // All variants

Contract Address Evidence

The same Arbitrum/Polygon contracts appear in Coingecko data for BOTH coins:

Real USDT (Coingecko: tether):

• Arbitrum: 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9
• Polygon: 0xc2132d05d31c914a87c6611c10748aeb04b58e8f

USDT0 (Coingecko: usdt0):

• Arbitrum: 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9 ← SAME CONTRACT!
• Polygon: 0xc2132d05d31c914a87c6611c10748aeb04b58e8f ← SAME CONTRACT!

This is a Coingecko data quality issue - they're listing the official Tether contracts under a different coin ID.

Why Overwrites Happen

Current code in processRelatedAssetIds() line 291-295:

for (const relatedAssetId of mergedRelatedAssetIds) {
  if (assetData[relatedAssetId]) {
    assetData[relatedAssetId].relatedAssetKey = relatedAssetKey  // No validation!
  }
}

This blindly overwrites without checking if the asset already belongs to another group.

Proposed Fix - Option B Implementation

Add Conflict Detection

const processRelatedAssetIds = async (...) => {
  // ... fetch related assets from Coingecko/Zerion ...
  
  const { relatedAssetIds, relatedAssetKey } = result
  
  // NEW: Filter out assets that already belong to a different group
  const cleanedRelatedAssetIds = relatedAssetIds.filter(candidateAssetId => {
    const existingKey = assetData[candidateAssetId]?.relatedAssetKey
    
    // No existing group, or already in current group - OK
    if (!existingKey || existingKey === relatedAssetKey) {
      return true
    }
    
    // Already claimed by a different group - conflict!
    console.warn(
      `[Related Asset Conflict] Asset ${candidateAssetId} already belongs to group ${existingKey}, ` +
      `refusing to add to ${relatedAssetKey}. ` +
      `Coingecko/Zerion returned the same contract for different coin IDs. ` +
      `Higher market cap coin takes precedence.`
    )
    return false
  })
  
  // Only proceed if we have multiple assets after conflict resolution
  const hasRelatedAssets = cleanedRelatedAssetIds.length > 1
  
  if (hasRelatedAssets) {
    relatedAssetIndex[relatedAssetKey] = cleanedRelatedAssetIds
    
    for (const relatedAssetId of cleanedRelatedAssetIds) {
      if (assetData[relatedAssetId]) {
        assetData[relatedAssetId].relatedAssetKey = relatedAssetKey
      }
    }
  } else {
    // No related assets after filtering conflicts
    assetData[assetId].relatedAssetKey = null
  }
  
  await throttle()
}

Why This Works

Processing Order (by market cap):

1. ETH USDT (rank ~3) processes first

   • Claims: Arbitrum 0xfd08..., Polygon 0xc213..., Avalanche, BSC, etc.
   • Sets their relatedAssetKey = 'eth_usdt'
   • Creates relatedAssetIndex['eth_usdt'] = [all real USDT variants]

2. USDT0 (rank ~5000) processes later

   • Coingecko claims: Arbitrum 0xfd08..., Polygon 0xc213..., Monad, Optimism
   • Validation detects: Arbitrum/Polygon already have relatedAssetKey = 'eth_usdt'
   • Filters them out from USDT0 group
   • Creates relatedAssetIndex['usdt0_primary'] = [monad, optimism_different_contract, ...]

3. Result:

   • Real USDT keeps Arbitrum/Polygon
   • USDT0 only gets its unique contracts
   • No overlap, clean separation

Edge Cases

Q: What if usdt0 processes before tether somehow?
A: Market cap sorting ensures higher rank processes first. We could add explicit ordering if needed.

Q: What if they SHOULD be grouped?
A: Then Coingecko should use the SAME coin ID. Different IDs = different tokens.

Q: What about manual overrides?
A: Check manualRelatedAssetIndex first (line 52) - it takes precedence over Coingecko data.

Alternative: Option A Analysis

To merge everything into one group:

// When detecting contract overlap
const isUsdtVariant = (coingeckoId) => 
  ['tether', 'usdt0', 'bridged-usdt', ...].includes(coingeckoId)

if (isUsdtVariant(currentCoinId) && isUsdtVariant(existingGroupCoinId)) {
  // Merge groups instead of filtering
  const mergedGroup = [...existingGroup, ...newGroup]
  relatedAssetIndex[primaryKey] = mergedGroup
}

Why NOT recommended:

• Requires maintaining a hardcoded list of USDT variants
• Doesn't scale to other tokens with similar issues
• Hides important distinctions between canonical and bridged tokens
• Could break if Coingecko data changes

Conclusion

Recommended: Option B - Enforce separation with conflict detection.

This fix:

• ✅ Prevents contract stealing
• ✅ Maintains data accuracy
• ✅ Respects Coingecko's token distinctions
• ✅ Provides bidirectional consistency
• ✅ Future-proof against similar issues
• ✅ Logs conflicts for debugging

Implementation: Add ~15 lines of validation in processRelatedAssetIds().

Testing: Regenerate assets and verify USDT/USDT0 are cleanly separated with no asymmetry.