feat(statics): add CoinMap.getOrUndefined() safe accessor

CoinMap.get() throws CoinNotDefinedError for unknown coins, meaning
optional-chaining (?.) provides no protection. Add getOrUndefined()
which returns undefined for unknown coins and delegates to it from
get(), making the missing-coin case explicit in the type system.

Ticket: CGD-255

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Session-Id: 6a81412d-5c4e-462d-959a-3eda803f708c
Task-Id: 562723cc-ae5d-41b5-96c7-d8a533be687c

Author: 2 people

modules/statics/src/map.ts

@@ -215,20 +215,30 @@ export class CoinMap {
    * @return {BaseCoin}
    */
   public get(key: string): Readonly<BaseCoin> {
-    const coin =
-      this._map.get(key) ||
-      this._coinByIds.get(key) ||
-      this._coinByAliases.get(key) ||
-      this._coinByContractAddress.get(key) ||
-      this._coinByNftCollectionID.get(key);
-
+    const coin = this.getOrUndefined(key);
     if (coin) {
       return coin;
     }
-
     throw new CoinNotDefinedError(key);
   }
 
+  /**
+   * Safe accessor that returns undefined instead of throwing when a coin is not found.
+   * Prefer this over `get` at call sites where the coin name is not guaranteed to be
+   * registered — it makes the missing-coin case explicit in the type system.
+   * @param {string} key
+   * @return {BaseCoin | undefined}
+   */
+  public getOrUndefined(key: string): Readonly<BaseCoin> | undefined {
+    return (
+      this._map.get(key) ||
+      this._coinByIds.get(key) ||
+      this._coinByAliases.get(key) ||
+      this._coinByContractAddress.get(key) ||
+      this._coinByNftCollectionID.get(key)
+    );
+  }
+
   public has(key: string): boolean {
     return (
       this._map.has(key) ||

modules/statics/test/unit/coins.ts

@@ -781,6 +781,24 @@ describe('CoinMap', function () {
     btcById.should.deepEqual(btc);
   });
 
+  it('getOrUndefined should return coin for known key', () => {
+    const btc = coins.getOrUndefined('btc');
+    should(btc).not.be.undefined();
+    btc!.name.should.equal('btc');
+  });
+
+  it('getOrUndefined should return undefined for unknown key', () => {
+    const result = coins.getOrUndefined('zzzz:TBD:no_such_coin');
+    should(result).be.undefined();
+  });
+
+  it('getOrUndefined should return coin by id', () => {
+    const btc = coins.get('btc');
+    const btcById = coins.getOrUndefined(btc.id);
+    should(btcById).not.be.undefined();
+    btcById!.should.deepEqual(btc);
+  });
+
   it('should get coin by address', () => {
     const weth = coins.get('weth');
     const wethByAddress = coins.get(`${weth.family}:${(weth as Erc20Coin).contractAddress}`);