[ralph-bitgo]

Description

Fixes CSHLD-1957. createToken() in @bitgo/statics refreshed any coin matched by an AMS entry — including known base chains — rebuilding it as a generic DynamicCoin. A LightningCoin such as tlnbtc was swapped out, so downstream @bitgo/abstract-lightning threw coin is not a lightning coin and getCoinSingletons() failed in every wallet-platform process on staging (regression from #9922, shipped via @bitgo-beta/statics@15.1.1-beta.2138).

What changed

• modules/statics/src/coins.ts — createToken() now refreshes a known coin only when both the existing record and the AMS entry are tokens; known base coins keep their static record.
• modules/statics/src/map.ts — CoinMap.replace() rejects a candidate whose coin class differs from the record it would replace (coin '<name>' cannot be replaced: coin class changed from <Class> to <Class>), checked after the existing immutable-field checks so identity mismatches keep their specific errors.
• modules/statics/test/unit/coins.ts — regression tests: valid-UUID AMS entries for tlnbtc (LightningCoin) and btc (UtxoCoin) preserve identity and class through createTokenUsingTrimmedConfigDetails and createTokenMapUsingTrimmedConfigDetails; a DynamicCoin can no longer replace btc; the same-class base-coin refresh fixture now keeps the candidate's prototype. This replaces the previous test that passed only because it used the invalid id 'btc'.

Why

Staging is broken for every wallet-platform process that builds coin singletons (/startupready client-constants check, market-data worker, ERC-7984 unwrap decrypt worker), and an ERC-7984 unshield journey is stuck in DECRYPT_PENDING, retrying every ~15 minutes until coin lookups work again. The commit that introduced CoinMap.replace documented that replacement "only swaps when both records are tokens", but the shipped code never enforced it, so an AMS entry for a known base chain could swap LightningCoin for DynamicCoin.

Issue Number

CSHLD-1957 (related: CSHLD-1936, CHALO-1809)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

• Full @bitgo/statics unit suite (npx mocha in modules/statics): 39702 passing, 0 failing.
• Throwaway repro of the ticket's minimal case (AMS entry with a valid UUID for tlnbtc via createTokenMapUsingTrimmedConfigDetails, and for btc via createTokenUsingTrimmedConfigDetails): before the fix both became DynamicCoin; after the fix LightningCoin / UtxoCoin and object identity are preserved. Repro script deleted after verification.
• yarn build (tsc) in modules/statics, plus eslint and prettier --check on the three changed files: 0 errors.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My code compiles correctly for both Node and Browser environments
• I have commented my code, particularly in hard-to-understand areas
• My commits follow Conventional Commits and I have properly described any BREAKING CHANGES
• The ticket or github issue was included in the commit message as a reference
• I have made corresponding changes to the documentation and on any new/updated functions and/or methods - jsdoc
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Ticket: CSHLD-1957

[linear-code]

CSHLD-1957

[github-actions]

⚠️ Unit tests are failing on Node 26.x (Current release line, non-blocking). This is not an LTS version yet, so it does not block merge, but it signals an incompatibility to fix before Node 26.x becomes LTS.

View run