Skip to content

node: Add watcher interface and refactor observation checks#4761

Draft
johnsaigle wants to merge 4 commits into
wormhole-foundation:mainfrom
johnsaigle:feat-valid-obs
Draft

node: Add watcher interface and refactor observation checks#4761
johnsaigle wants to merge 4 commits into
wormhole-foundation:mainfrom
johnsaigle:feat-valid-obs

Conversation

@johnsaigle

@johnsaigle johnsaigle commented Apr 21, 2026

Copy link
Copy Markdown
Contributor

This PR is getting split into smaller PRs to help with code review.


Summary

  • Consolidates observation-request validation into watcher Validate(...) methods and shared helpers, so fundamental request-shape and chain checks now happen in one consistent place instead of being scattered across reobservation handlers.
  • Refactors watcher publication paths around PublishMessage(...) / PublishReobservation(...), folding older ad hoc patterns like verifyAndPublish into the new structure without changing the underlying message-processing control flow.
  • Adds focused unit coverage for the new validation and publishing surface, making the watcher code easier to review, pattern-match across chains, and extend safely.

Watcher Interface

  • A new central watcher contract now lives in node/pkg/watchers/watcher.go.
  • It is intentionally narrow and captures the shared security-sensitive boundary across watchers:
    • ChainID()
    • Validate(...)
    • PublishMessage(...)
    • PublishReobservation(...)
  • Reviewers will probably have the easiest time starting there before looking at the chain-specific watcher changes, since the rest of the PR mostly applies that pattern consistently across watchers.

Building and validating message publications has been left out of the design (at least for now) because the watchers all have very different ways of converting the on-chain data into MessagePublications such that I don't feel that it makes sense to generalize it into the interface.
However, the documentation in the interface notes that the watchers should also implement these methods in a consistent way.

Reviewer Notes

  • This PR is intended as a structural hardening/refactor, not a behaviour change. Message processing flow should remain the same: the main change is where safety checks live and how reobservation publication is routed.
  • One explicit improvement is that watcher-side panic(...) cases on invalid observation requests were removed in favor of validated rejection and structured logging.
  • The new structure should make it easier to reason about watcher correctness across chains because the same core pattern now exists in each watcher:
    • Validate(...)
    • optional watcher-specific verification/parsing
    • PublishMessage(...)
    • PublishReobservation(...) (which always calls PublishMessage()
  • The transfer-verifier-era verifyAndPublish pattern in EVM/Sui is now subsumed into this architecture: verification remains, but publication flows through the common publish methods instead of a hybrid helper. (See node: Integrate Transfer Verifier into the Ethereum watcher #4233, node: Integrate Transfer Verifier into Sui Watcher #4324)

If reviewers would be more comfortable with a smaller rollout, this change could be split into follow-up PRs per watcher or per watcher family. I kept it together because the repeated pattern is easier to validate side-by-side, and the targeted watcher test suite should help demonstrate that the refactor is safe.

@djb15

djb15 commented Apr 29, 2026

Copy link
Copy Markdown
Collaborator

I would strongly prefer having this split into per watcher PRs that we can review independently. We can keep this open as a draft to reference against and for easier comparison, but I think it's too meaty to garner prompt reviews. I would suggest maybe starting with the Solana watcher given the recent attention

@johnsaigle

Copy link
Copy Markdown
Contributor Author

@djb15 I think I'll start with Aptos or Sui given that there are several other PRs open right now that modify the EVM and SVM watchers. if the idea is to split this into smaller chunks so we can move faster, I think that's the best way.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants