Alchemy Plugin by samholmes · Pull Request #14 · EdgeApp/edge-change-server

samholmes · 2026-01-21T19:16:46Z

CHANGELOG

Does this branch warrant an entry to the CHANGELOG?

Yes
No

Dependencies

Sam/ws transport #12

Description

none

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

Note

High Risk
Adds a new externally reachable webhook HTTP surface and signature validation/auth logic, plus cluster-wide IPC relaying; failures here could drop or misroute activity updates or weaken webhook authentication.

Overview
Adds an Alchemy-based address activity pipeline: workers now host an Express HTTP endpoint for /webhook/* (with GET/HEAD health checks) and dispatch incoming webhooks through a new WebhookRegistry to per-plugin handlers.

Introduces a new alchemy plugin that creates/updates/deletes Alchemy Address Activity webhooks, validates X-Alchemy-Signature via HMAC using recovered signing keys, debounces subscription address updates, and broadcasts webhook activity across cluster workers via IPC so all workers emit updates consistently.

Updates configuration/deps to support this (new webhookHost/webhookPort and alchemyAuthToken, adds express + types, bumps cleaner-config), and wires plugin construction through makeAllPlugins(opts) with Alchemy enabled for multiple EVM networks plus Solana; includes comprehensive Jest tests for the plugin behavior and signature/auth paths.

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

We're not yet using these, so why have them enabled right now.

paullinator

Review Summary

The overall architecture is well-designed — clean separation between plugin, API client, signing key store, and webhook registry. The timing-safe HMAC signature validation is solid, and the debounced batch address management is a good approach.

However, there are several concurrency and error handling issues that could cause silent data loss in production:

Critical Issues (4)

Swallowed exceptions in webhookRegistry return 200 OK to Alchemy, preventing retries
Race condition in concurrent processBatchedChanges() — can create duplicate webhooks
No retry backoff — tight 1-second loop hammering Alchemy API during outages
destroy() doesn't cancel in-flight batch processing — can re-create timers on destroyed plugin

Critical Test Gap (1)

Batch processing is never exercised in tests — fake timers are never advanced, so the most important code path (Alchemy API integration) has zero test coverage. Signature validation rejection paths are also untested.

Warnings (4)

Initialization failure permanently prevents webhook discovery
Concurrent signing key recovery race condition (no promise deduplication)
14 concurrent getTeamWebhooks() API calls on startup
Unsafe (undefined as unknown) as T type casts in API client

Suggestions (2)

Cross-cased subscribe/unsubscribe can leave phantom entries in pending arrays
parseInt on hex block number can produce NaN checkpoint

Note: Cursor Bugbot already flagged the cluster multi-worker affinity issue, network-check-before-auth ordering, and @types/express placement — those are omitted from this review.

See inline comments for specific details and recommended fixes.

swansontec · 2026-02-19T03:18:25Z

+    pluginId: 'solana',
+    network: 'SOLANA_MAINNET',


Is this tested compatible with Solana? We do const normalizedAddress = address.toLowerCase(), which doesn't work with base58.

Client-side we have no chagne-server integration with Solana. No testing done with Solana, but I'll make sure to make normalization an option for the plugins rather then default.

swansontec · 2026-02-19T03:20:49Z

+  const logger: Logger = makeLogger('alchemy', pluginId)
+
+  // Track subscribed addresses (normalized lowercase address -> original address)
+  const subscribedAddresses = new Map<string, string>()


As mentioned, this normalization doesn't really work for base58 addresses. Can we come up with a design that doesn't require normalization?

swansontec · 2026-02-19T03:31:31Z

+// Create singleton instances
+export const notifyApi = makeAlchemyNotifyApi()
+export const signingKeyStore = makeSigningKeyStore({ notifyApi })
+export const webhookRegistry = makeWebhookRegistry()


I am not really a fan of this design, especially now that we have multiple process and IPC involved. I would rather have these things be dependency-injected into whoever needs them. This may involve some re-shuffling, but mostly in setup code.

For instance, export const allPlugins: AddressPlugin[] = [...] might need to turn into an export const getPlugins: ({ services... }) => ([...]). Then the various top-level processes can be in charge of setting up singletons and passing them in where they belong. This would also get rid of the need for await import('./server'), as the server would no longer have global state floating around.

Each process gets it's own singleton. The coupling of these services to the rest of the app is simpler to reason about (we're only having one instance of each service as part of the worker process anyway). I can see how dep-injection could make sense here though.

If we want to remove await import('./server') then we'd also have to call a server() function that is exported form ./server.ts.

swansontec · 2026-02-19T03:32:44Z

I think "server.ts" is a weird name. Which server is this? The websocket server for the core, or the webhook server for Alchemy? I'd like to have it named "websocketServer.ts"

worker.ts would be better. The file contains a websocket server and http server for the webhook.

cursor

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-19T23:13:22Z

+    initializingPromise = doInitialize()
+    await initializingPromise
+    initializingPromise = null
+  }


Initialization promise never reset on failure

High Severity

If doInitialize() rejects, the await on line 95 throws and line 96 (initializingPromise = null) is never reached. The rejected promise stays cached in initializingPromise. Every subsequent call to initialize() hits the initializingPromise != null check on line 92 and immediately re-throws the stale error. This permanently prevents the plugin from initializing, defeating the retry logic in processBatchedChanges. Compare with recoverSigningKeys in signingKeyStore.ts which correctly wraps the await in try/finally.

Additional Locations (1)

src/plugins/alchemy.ts#L297-L311

swansontec

One change, but I'm approving because it's trivial.

swansontec · 2026-02-20T23:28:25Z

-main().catch(error => {
-  logger.error({ err: error }, 'main error')
-  process.exit(1)
-})


I would leave this catch statement in place, since "the buck starts here". This is our last chance to log if anything goes wrong.

The function changed from async to sync

Implement a new plugin that uses Alchemy's Address Activity webhooks for real-time address monitoring on supported EVM chains. Features: - Batched address subscription updates (1s debounce) - HMAC-SHA256 webhook signature validation - Case-insensitive address matching with original case preservation - Support for all EVM-based that we support.

samholmes force-pushed the sam/alchemy-plugin branch from c4c3bd2 to f58d44d Compare February 3, 2026 23:15

samholmes added 2 commits February 10, 2026 15:24

Upgrade cleaner-config

dd8c0ae

Disable blockbook plugins

42f07cf

We're not yet using these, so why have them enabled right now.

samholmes force-pushed the sam/alchemy-plugin branch from f58d44d to 3cb4b1a Compare February 11, 2026 01:34

samholmes marked this pull request as ready for review February 11, 2026 01:35

cursor bot reviewed Feb 11, 2026

View reviewed changes

Comment thread src/server.ts Outdated

Comment thread src/plugins/alchemy.ts Outdated

Comment thread package.json Outdated

paullinator requested changes Feb 14, 2026

View reviewed changes

samholmes force-pushed the sam/alchemy-plugin branch from 3cb4b1a to 153c913 Compare February 18, 2026 22:39

cursor bot reviewed Feb 18, 2026

View reviewed changes

Comment thread src/plugins/allPlugins.ts Outdated

Comment thread src/plugins/alchemy.ts

Comment thread src/plugins/alchemy.ts

swansontec requested changes Feb 19, 2026

View reviewed changes

cursor bot reviewed Feb 19, 2026

View reviewed changes

swansontec reviewed Feb 20, 2026

View reviewed changes

Factor out server function to dedicated module

73031be

samholmes force-pushed the sam/alchemy-plugin branch from f0848cf to 566d67c Compare February 24, 2026 23:12

samholmes added 2 commits February 24, 2026 16:38

Add remaining evmRpc plugins

b3d41ce

samholmes force-pushed the sam/alchemy-plugin branch from 566d67c to b3d41ce Compare February 25, 2026 00:38

samholmes merged commit 7af5274 into main Feb 25, 2026
2 checks passed

Conversation

samholmes commented Jan 21, 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!

Uh oh!

Uh oh!

Uh oh!

paullinator left a comment

Choose a reason for hiding this comment

Review Summary

Critical Issues (4)

Critical Test Gap (1)

Warnings (4)

Suggestions (2)

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor bot Feb 19, 2026

Choose a reason for hiding this comment

Initialization promise never reset on failure

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

samholmes commented Jan 21, 2026 •

edited by cursor bot

Loading