Feature/update mobula ea v2 (#4136)

* feat(mobula): Update to v2 API with asset_ids subscription format

- Replace symbol-based firehose with targeted asset_id subscriptions
- Add includes.json for symbol-to-asset-ID mapping (EZETH→102478632, GHO→2921, ETH→100004304)
- Switch to PriceAdapter + CryptoPriceEndpoint for proper includes support
- Implement WebsocketReverseMappingTransport for parameter matching
- Support multi-quote pairs (USD, ETH)
- Real-time WebSocket streaming from wss://production-feed.mobula.io

Tested pairs:
- EZETH/USD ✅
- GHO/USD ✅
- ETH/USD ✅
- EZETH/ETH ✅

* chore: add changeset for mobula v2 updates

* Add hardcoded quote currency mappings for BTC, ETH, SOL, HYPE, and S

* Fix critical bug: Use composite key for WebSocket reverse mapping

- Fixed issue where multiple quote currencies for same base asset overwrote each other
- Changed from baseID-only key to baseID-quoteID composite key
- Prevents EZETH/ETH returning USD price instead of ETH ratio
- Now EZETH/ETH correctly returns ~1.06 instead of ~4,233

* Add comprehensive DeFi asset mappings and BBSOL quote support

- Added 207 new symbol mappings to includes.json (211 total entries)
- Added BBSOL (Bybit Staked SOL) hardcoded quote currency: 102484775
- Supports major DeFi pairs: CBETH/ETH, LBTC/BTC, SOLVBTC/BTC, OS/S, etc.
- Added 7 BBSOL pairs: VSOL/BBSOL, MSOL/BBSOL, JITOSOL/BBSOL, etc.
- Comprehensive coverage of liquid staking tokens, Bitcoin variants, Solana ecosystem
- Ready for production with 6 quote currencies: USD, BTC, ETH, SOL, HYPE, S, BBSOL

* Add comprehensive v2 test suite with overrides and direct asset ID support

- Updated integration tests to validate v2 functionality instead of old ETH/USD pairs
- Added mock WebSocket responses with baseID/quoteID for composite key testing
- Added test cases for includes.json mapping (EZETH, CBETH, LBTC, GHO)
- Added test cases for hardcoded quote currencies (BTC, ETH, SOL validation)
- Added override functionality tests (base/quote overrides with custom asset IDs)
- Added direct asset ID tests (bypass symbol resolution entirely)
- Updated test-payload.json with realistic v2 examples
- Comprehensive coverage: static mappings, dynamic overrides, direct IDs
- Tests all 3 asset resolution methods + 6 quote currencies + error handling

* docs(mobula): Add comment explaining CryptoPriceEndpoint 'market' alias requirement

Clarifies that 'market' must be in quote aliases due to TypeScript type constraints
in CryptoPriceEndpoint, not runtime validation. This is a compile-time requirement
from the framework.

* fix(mobula): Resolve CI test failures and timestamp warnings

- Fix timestamp values in test fixtures (use 4040ms instead of Sep 2024 timestamps)
- Update Jest snapshots to match v2 response format changes
- Remove debug logging for clean production code
- All 18 integration tests now pass with proper snapshot validation

Fixes CI job 53290359217 failures

* fix(mobula): Update Jest snapshots to resolve CI test failures

- Update all 18 integration test snapshots for v2 API format
- Fix timestamp handling in test fixtures using Date.now() + offset
- All snapshot tests now pass successfully
- Resolve job 53315497853 failures

Tests: 18 passed, 7 snapshots updated, 11 passed

* fix(mobula): Final snapshot update to resolve CI test failures

- Use timestamp 1514764861500 that meets framework minimum requirements
- Update all 18 integration test snapshots for consistent CI/local behavior
- All tests pass: 18 passed, 7 snapshots updated, 11 passed
- Resolves job 53316053810 snapshot failures

The timestamp warnings are expected due to FakeTimer test environment but don't affect test success.

* fix(mobula): Update to framework v2.8.0 and fix CI snapshot mismatches

- Update @chainlink/external-adapter-framework from 2.7.0 → 2.8.0 to match CI
- Update 9 Jest snapshots to exclude meta field when METRICS_ENABLED=false
- All 18 integration tests now pass and match CI environment exactly
- Resolves job 53316053810 snapshot failures

Framework v2.8.0 + METRICS_ENABLED=false removes meta field from test responses,
matching the CI environment behavior and eliminating snapshot mismatches.

* fix(mobula): Address Copilot feedback - asset ID consistency and type safety

1. Fix SOL asset ID inconsistency:
   - Correct SOL mapping from 102484775 → 100010811 in includes.json
   - 102484775 is BBSOL (Bybit Staked SOL), not SOL (Solana)
   - Ensures consistency between base currency and quote currency mappings

2. Improve TypeScript type safety:
   - Replace 'any' type with proper MobulaSubscribeMessage interface
   - Define structure for WebSocket subscription messages
   - Maintains type safety throughout transport logic

All hardcoded quote currencies now match includes.json mappings:
✅ BTC: 100001656, ETH: 100004304, SOL: 100010811

* Update packages/sources/mobula-state/src/endpoint/price.ts

Co-authored-by: Copilot <[email protected]>

* fix(mobula): Address PR review feedback

- Refactor USD handling: Moved USD logic entirely into getQuoteId function
  - getQuoteId now returns number | 'USD' instead of number | undefined
  - Simplified composite key creation by removing || 'USD' fallback

- Keep hardcoded quote currencies in transport (optimal for architecture)
  - Restored QUOTE_ASSET_IDS constant with BTC, ETH, SOL, HYPE, S, BBSOL
  - Faster O(1) lookups for common quotes vs iterating includes.json
  - includes.json-derived map serves as fallback for less common quotes
  - Maintains separation: includes.json for base symbols, QUOTE_ASSET_IDS for quote resolution

- Update changeset with simplified upgrade instructions
  - 'Do not upgrade to this version until instructed to do so.'

- Evaluate requestTransforms suggestion
  - Documented decision to keep ID resolution in transport layer
  - Maintains better support for overrides and direct asset ID usage
  - Preserves logical cohesion with WebSocket subscription logic

All tests passing (18/18). Framework updated to v2.8.0.

* fix(mobula): Update framework to 2.11.0 to match monorepo requirement

* docs(mobula): Clarify NOP upgrade requirements in changeset

* fix(mobula): Remove manual includes.json parsing - let framework handle it

Framework's PriceAdapter handles includes.json resolution for exact base/quote pairs.
We only need hardcoded QUOTE_ASSET_IDS for common crypto quotes (BTC, ETH, SOL, etc).
Removed buildSymbolToAssetIdMap() and SYMBOL_TO_ASSET_ID fallback lookup.

* fix(mobula): Add includes.json entries for override test cases

Added proper includes.json mappings for test asset pairs:
- TESTCOIN/USD (999888777/USD) - base override test
- ANOTHERCOIN/BTC (111222333/100001656) - base override with BTC quote
- CUSTOMTOKEN/ETH (444555666/100004304) - base override with ETH quote
- EZETH/CUSTOMQUOTE (102478632/100004304) - quote override test

Also fixed adapter name in override tests from 'mobula-state' to 'MOBULA_STATE'.

All 18 tests now passing with successful override test cases.

* test: refactor mock server to use v2 targeted subscription pattern

- Changed fixtures from firehose pattern (send all data) to v2 API pattern (parse subscription, send targeted responses)
- This matches cfbenchmarks approach and the real Mobula v2 API behavior
- Fixes override tests which now correctly return success instead of 504 errors
- All 18 tests now passing with proper data handling

* fix(mobula): Fix funding rate test mock to properly handle subscription messages

- Changed mock to check parsed.type === 'funding' instead of parsed.kind === 'funding-rate'
- The actual funding rate transport sends subscriptions with type: 'funding', not kind: 'funding-rate'
- This fixes the funding rate tests that were broken in the previous v2 mock refactor
- Funding rate tests now return 200 success (with actual data) instead of 504 errors

* fix(mobula): Fix override tests by removing conflicting includes.json entries

- Removed TESTCOIN, ANOTHERCOIN, and CUSTOMTOKEN from includes.json
- These test entries were preventing the override mechanism from working correctly
- Override tests now properly use the overrides mechanism instead of includes.json
- All override tests now return 200 success instead of 504 errors
- Updated snapshots to reflect successful responses with actual data

This resolves all test contradictions where tests named 'should return success' were returning 504 errors.

* fix(mobula): Prime cache with all test pairs to fix CI timing issues

- CI was failing because override tests ran before mock WebSocket sent data
- Now beforeAll primes cache with TESTCOIN, ANOTHERCOIN, and CUSTOMTOKEN
- This ensures all test data is cached before tests run
- Updated snapshots with new timestamps due to additional cache priming

* fix(mobula): Add missing direct asset ID tests to cache priming

- Added GHO/BTC (2921/100001656) and LBTC/SOL (102484658/100010811) to cache priming
- These direct asset ID tests were returning 504s in CI due to missing cache data
- All 14 success tests now properly return 200 with data
- All 3 failure tests correctly return 504 errors

* fix(mobula): Update snapshot timestamps after adding more cache priming

- Adding GHO/BTC and LBTC/SOL cache priming shifted timing for all subsequent tests
- Updated 16 snapshots to match new timing (tests now run 2 seconds later)
- This is expected behavior - more cache priming = later timestamps

* run yarn && yarn setup to fix build dep issue

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Matthew McAllister <[email protected]>

Author: 3 people

.changeset/large-cycles-admire.md

@@ -0,0 +1,11 @@
+---
+'@chainlink/mobula-state-adapter': major
+---
+
+**BREAKING CHANGE:** Migrated from v1 firehose WebSocket API to v2 targeted asset_id-based subscriptions.
+
+## Upgrade Instructions
+
+No changes are required on the NOPs part in order to upgrade.
+
+**Do not upgrade to this version until instructed to do so.**

.pnp.cjs

@@ -36,7 +36,7 @@
     "typescript": "5.8.3"
   },
   "dependencies": {
-    "@chainlink/external-adapter-framework": "2.8.0",
+    "@chainlink/external-adapter-framework": "2.11.0",
     "tslib": "2.4.1"
   }
 }