[BCN] Multi Provider With Alchemy Adapter

[leolambo]

Description

Add multi-provider external chain state adapter with Alchemy integration, enabling failover between multiple indexed API providers for EVM chains.

Follow-up:

Moralis Adapter, API streaming improvements, Integration tests

Changelog

• Add adapter error taxonomy with health-affecting classification
• Add provider health tracker using consecutive-failure counter and cooldown
• Add IIndexedAPIAdapter interface, config types, and AdapterFactory
• Add AlchemyAdapter with asset transfer stream
• Add multi-provider chain state provider with round-robin failover and block-time caching
• Align provider config with Moralis patterns (dynamic URL resolution, isBreakerable → affectsHealth)

Testing Notes

cd packages/bitcore-node && npm run tests

---

Checklist

• I have read CONTRIBUTING.md and verified that this PR follows the guidelines and requirements outlined in it.
• I have added the appropriate package tag(s) (e.g. BWC if modifying the bitcore-wallet-client package, CLI if modifying the bitcore-cli package, etc.)
• I have verified that this is not an existing PR (open or closed)

[kajoseph]

Lots of lint errors, particularly with imports. Make sure you have the eslint extension installed and you may need to clear all your node_modules:

npx lerna exec rm -rf node_modules

Still functionally testing, but so far this is looking good!

[kajoseph]

is this type correct? I added to my config per this file and am getting a startup error.

bitcore.config.json:

      ...
      "MATIC": {
        "mainnet": {
          ...
          "externalProviders": [{
            "name": "alchemy",
            "priority": 0
          }]

error:

Unhandled Rejection at: Error: AlchemyAdapter: apiKey is required in config.externalProviders.alchemy
    at new AlchemyAdapter (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/providers/chain-state/external/adapters/alchemy.ts:37:24)
    at Function.createAdapter (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/providers/chain-state/external/adapters/factory.ts:18:12)
    at /home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/api/csp.ts:62:35
    at Array.map (<anonymous>)
    at MultiProviderEVMStateProvider.initializeProviders (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/api/csp.ts:61:10)
    at new MultiProviderEVMStateProvider (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/api/csp.ts:40:10)
    at new MultiProviderModule (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/index.ts:22:17)
    at ModuleManager.loadConfigured (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/index.ts:80:36)
    at ClusteredApiWorker (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/workers/api.ts:34:11)
    at Object.<anonymous> (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/workers/api.ts:66:21)

[kajoseph]

Well, I updated my config to fix that error, but now it's giving me another.

bitcore.config.json:

      ...
      "MATIC": {
        "mainnet": {
          ...
          "externalProviders": {
            "alchemy": {
              "apiKey": ""
            }
          }

error:

Unhandled Rejection at: TypeError: externalProviders.map is not a function
    at MultiProviderEVMStateProvider.initializeProviders (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/api/csp.ts:61:10)
    at new MultiProviderEVMStateProvider (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/api/csp.ts:40:10)
    at new MultiProviderModule (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/multiProvider/index.ts:22:17)
    at ModuleManager.loadConfigured (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/modules/index.ts:80:36)
    at ClusteredApiWorker (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/workers/api.ts:34:11)
    at Object.<anonymous> (/home/kjoseph/dev/bitcore/packages/bitcore-node/src/workers/api.ts:66:21)
    at Module._compile (node:internal/modules/cjs/loader:1730:14)
    at Object..js (node:internal/modules/cjs/loader:1895:10)
    at Module.load (node:internal/modules/cjs/loader:1465:32)
    at Function._load (node:internal/modules/cjs/loader:1282:12)

I'm confused about how this externalProviders field is supposed to look. One error makes it seems like it's supposed to be a map, the other suggest an array.

[kajoseph]

Nevermind - this was a lot of noise for nothing. I figured it out.

[kajoseph]

If anything's to be taken away from this, it's that having a field named "externalProviders" in two different places in the config can be confusing - especially when they're both needed when using the multi provider. Just 2c