Sam/ws transport #12

samholmes · 2026-01-17T00:14:34Z

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

Yes
No

Dependencies

none

Description

none

Note

Introduces structured JSON logging and auth templating, and enables WS RPC transports while simplifying supported networks.

Logging: Migrate to Pino with scoped child loggers; add docs/logging.md; replace console logs across src/index.ts, src/hub.ts, plugins/blockbook.ts, plugins/evmRpc.ts with structured events
Socket/IP handling: AddressHub.handleConnection now accepts ip; logs pid/sid/ip, bulk subscribe/unsubscribe, updates and errors; tests updated
Service keys & URL templating: Add src/util/serviceKeys.ts, replaceUrlParams, authenticateUrl; switch config to serviceKeys (remove nowNodesApiKey); adapters use keys resolved from URL host; add tests
EVM RPC: Support WebSocket transports via viem (createTransport with ws*/http*), improved error handling/logs, require scanAdapters; internal trace fallbacks logged
Blockbook: Use logger; metrics per url; improved block/tx handling and reconnection logs
Plugins: Replace NowNodes URLs with authenticateUrl; keep bitcoin family + select EVM chains (bsc, botanix, ethereum, optimism, polygon, zksync); remove many others
Misc: Add getAddressPrefix, make pickRandom return optional; add pino dependency and Jest setup for serviceKeys mock

^{Written by Cursor Bugbot for commit d9c897f. This will update automatically on new commits. Configure here.}

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1212754123530595

- Use Pino for performant logging - Use Pino's .child() pattern for efficient scoped logging - Add pino-pretty support for human-readable development output - Disable logging in tests via NODE_ENV check - Automatically rename conflicting fields (time → time_, scope → scope_)

Remove the following plugins to reduce load: - abstract, amoy, arbitrum, avalanche, base - bobevm, celo, ethereumclassic, ethereumpow, fantom - filecoinfevm, filecoinfevmcalibration, holesky, hyperevm - pulsechain, rsk, sepolia, sonic

Add serviceKeysFromUrl utility that matches API keys to URLs by hostname with subdomain fallback support (e.g., api.example.com → example.com). Keys can be configured with or without ports. - Add src/util/serviceKeys.ts with ServiceKeys type and matching logic - Add src/util/replaceUrlParams.ts for {{param}} placeholder substitution - Add src/util/authenticateUrl.ts to combine key lookup with URL templating - Add comprehensive tests for serviceKeysFromUrl Refactor RPC and scan adapter configuration: - Switch to authenticated RPC endpoints using {{apiKey}} templates - Make scanAdapters required in EvmRpcOptions - Update EtherscanV1/V2 adapters to use serviceKeysFromUrl - Fix pickRandom return type to T | undefined for empty arrays - Improve error handling when no URLs or API keys are configured

This reduces complexity and re-uses the new infrastructure. The only trade-off is to remove the logging of the URL without the key, which we can accept since these logs should be treated as company sensitive.

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

cursor · 2026-01-20T01:10:24Z

src/util/scanAdapters/EtherscanV1ScanAdapter.ts

-      logger.warn('No API key found for', host)
+    if (url == null) {
+      logger.error({ msg: 'No URLs for EtherscanV1ScanAdapter provided' })
+      return false


Scan adapters return false on config error

Medium Severity

When pickRandom(urls) returns undefined (empty URLs array), the new null check returns false, indicating "no changes detected." This is incorrect because we couldn't actually verify the address state. Returning false may cause clients to miss real updates. The safer fail-safe behavior (consistent with HTTP errors on the first request which return true) would be to return true to prompt client-side verification.

Additional Locations (1)

src/util/scanAdapters/EtherscanV2ScanAdapter.ts#L39-L43

Yeah, if we can't connect to any server, we generally return true, as there might be changes.

swansontec

Found a few small things.

swansontec · 2026-01-22T00:19:49Z

src/plugins/blockbook.ts

          .then(result => {
            if (result.subscribed) {
-              logger.log('Block connection initialized')
+              logger.info({ scope: 'foo' }, 'Block connection initialized')


Yup, { scope: 'foo' } needs to go.

swansontec · 2026-01-22T00:20:50Z

src/plugins/blockbook.ts

            .then(() => initBlockConnection())
            .catch(err => {
-              console.error('Failed to re-initialize block connection:', err)
+              logger.error({ err }, 'Failed to re-initialize block connection')


Below we did ${String(error}. Here we log the object. Should we standardize on one of the other?

swansontec · 2026-01-22T00:21:26Z

src/plugins/blockbook.ts

    pluginErrorCounter.inc({ pluginId, url: logUrl })

-    logger.warn('WebSocket error:', error)
+    logger.warn(`WebSocket error: ${String(error)}`)


Above we did { err }. Here we log the stringified version. Should we standardize on one of the other?

swansontec · 2026-01-22T00:36:39Z

docs/logging.md

+pluginLogger.error('message')
+
+// Pass an object with extra fields:
+pluginLogger.info({ ip: '1.2.3.4' }, 'connected')


You pass an object with a msg field in a ton of places, but your own docs suggest that this is the wrong approach. Should you be passing the msg field as a second string parameter? If so, that applies to a bunch of places.

swansontec · 2026-01-22T00:46:43Z

src/util/scanAdapters/EtherscanV1ScanAdapter.ts

-      logger.warn('No API key found for', host)
+    if (url == null) {
+      logger.error({ msg: 'No URLs for EtherscanV1ScanAdapter provided' })
+      return false


Yeah, if we can't connect to any server, we generally return true, as there might be changes.

swansontec · 2026-01-22T00:49:10Z

src/util/scanAdapters/EtherscanV2ScanAdapter.ts

-      logger.warn({ host, msg: 'No API key found' })
+    if (url == null) {
+      logger.error({ msg: 'No URLs for EtherscanV2ScanAdapter provided' })
+      return false


swansontec · 2026-01-22T00:53:07Z

src/plugins/blockbook.ts

    const socketReady = new Promise<void>(resolve => {
      ws.on('open', () => {
-        pluginConnectionCounter.inc({ pluginId, url: logUrl })
+        pluginConnectionCounter.inc({ pluginId, url: url })


url: url could be just url. There are a bunch of other places where this happens in this same commit.

samholmes force-pushed the sam/ws-transport branch from 5bf8600 to d4fde3b Compare January 17, 2026 00:18

This comment was marked as outdated.

Sign in to view

samholmes force-pushed the sam/ws-transport branch from d4fde3b to 0003e4a Compare January 19, 2026 23:41

samholmes added 5 commits January 19, 2026 17:02

Disable some chains

a4043d8

Remove the following plugins to reduce load: - abstract, amoy, arbitrum, avalanche, base - bobevm, celo, ethereumclassic, ethereumpow, fantom - filecoinfevm, filecoinfevmcalibration, holesky, hyperevm - pulsechain, rsk, sepolia, sonic

refactor: use service key URL matching for nownodes

c54808e

This reduces complexity and re-uses the new infrastructure. The only trade-off is to remove the logging of the URL without the key, which we can accept since these logs should be treated as company sensitive.

feat: add websocket RPC transport support for evmRpc plugin

d9c897f

samholmes force-pushed the sam/ws-transport branch from 0003e4a to d9c897f Compare January 20, 2026 01:02

cursor bot reviewed Jan 20, 2026

View reviewed changes

This was referenced Jan 21, 2026

Alchemy Plugin #14

Draft

Sam/correctness issues #13

Open

swansontec requested changes Jan 22, 2026

View reviewed changes

Sam/ws transport #12

Are you sure you want to change the base?

Sam/ws transport #12

Uh oh!

Conversation

samholmes commented Jan 17, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CHANGELOG

Dependencies

Description

Uh oh!

This comment was marked as outdated.

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Jan 20, 2026

Choose a reason for hiding this comment

Scan adapters return false on config error

Uh oh!

Choose a reason for hiding this comment

Uh oh!

swansontec left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

samholmes commented Jan 17, 2026 •

edited by cursor bot

Loading