Fixes CSHLD-976. Supersedes the handoff reference #8959 (closed by @zahin-mohammad — "will let the coins team take this forward"); this adopts that PR's hasTokenAddressConflict design.

Problem

The AMS↔static merge in createTokenMapUsingConfigDetails (and the …Trimmed… variant that calls it) dedups via isCoinPresentInCoinMap (coins.ts:434), which only matches on name / id / alias — never the contract address:

export function isCoinPresentInCoinMap({ name, id, alias }) {
  return Boolean(coins.has(name) || (id && coins.has(id)) || (alias && coins.has(alias)));
}

But CoinMap.fromCoins → addCoin (map.ts:62-68) also dedups by contract address (family:network.type:contractAddress) and NFT collection id. An AMS-served token reusing a contract a static token already claims under a different name slips the guard and throws DuplicateContractAddressDefinitionError, aborting the entire token-map build for every consumer (bitgo-retail hydration, bitgo-admin, bitgo-microservices, indexerdb, prime, client-admin, bitgo.ts, …).

Surfaced by the static eth:at bot token (0x0581ccdf…, eth testnet, added in #8885 / @bitgo/statics@58.43.0) colliding with the live AMS token at the same address under a different name.

Fix

Add CoinMap.hasTokenAddressConflict(coin) — reusing the map's own private contractAddressKey / nftCollectionIdKey derivation against its populated _coinByContractAddress / _coinByNftCollectionID indexes — and use it in the merge loop:

const token = createToken(tokenConfig);
if (token && !coins.hasTokenAddressConflict(token)) {
  BaseCoins.set(token.name, token);
}

Statics coins are seeded first, so statics stays the source of truth and the colliding AMS token is the one skipped. Checking the built coin against the map's own indexes means the key derivation/normalization always matches addCoin (no parallel bookkeeping, no public key-builder surface). Covers contract-address and NFT-collection-id collisions. Strict statics self-construction is unchanged (still throws on genuine duplicates at build/test time).

Acceptance criteria (CSHLD-976)

• AMS token sharing a contract address with a static token is skipped (no throw)
• Same protection for NFT collection id collisions (nftCollectionIdKey)
• Unit test reproducing the duplicate-contract / different-name case asserting no throw
• UI no longer crashes (companion bitgo-retail chore: update mainnet api url for plasma and kavaevm #6934 + this root-cause fix)

Scope note

Targets the static↔AMS collision (the incident). A hypothetical AMS↔AMS duplicate (two server tokens at the same address, neither in statics) is a separate, pre-existing AMS data-integrity concern — left to surface rather than be silently masked here; the bitgo-retail guard (#6934) keeps it from crashing the UI.

Verification

• npx mocha test/unit/coins.ts → 28768 passing (incl. new test)
• tsc --build clean, prettier --check clean

Related

• Companion (UI defense-in-depth): bitgo-retail chore: update mainnet api url for plasma and kavaevm #6934
• Data follow-up (AMS-side, not statics — statics is canonical): reconcile the live AMS record sharing eth:testnet:0x0581ccdf… under a different name. (Earlier statics-removal PR fix(statics): remove stale eth:at bot token colliding with live AMS #8960 was closed for this reason.)

🤖 Generated with Claude Code