WalletConnect Notify primary sources — 2026-05-12

What I reviewed

Key takeaways from primary sources

  • Notify is not just “wallet push notifications.” The spec turns notifications into a protocol stack with app identity, public-key publication, scoped consent, topic derivation, authenticated delivery, subscription watching, and notification retrieval/read-state APIs.
  • The subscription flow is a strong signal that the protocol is doing more than ordinary webhook fanout: wallets fetch X25519 key material from a did:web document, derive request/response topics, and negotiate long-lived notify topics through key exchange.
  • Consent is intentionally scoped. The scp JWT claim authorizes specific notification types rather than blanket permission, and the config spec makes those types a public app-defined taxonomy.
  • Identity and authentication are split across multiple actors: client identity keys, dapp authentication keys, and Notify Server authentication keys each appear in different JWT flows.
  • The watcher model matters because it reveals a durable state-synchronization layer. Wallets are expected to refresh watchers, receive full subscription state from the server, and handle timeouts instead of assuming subscriptions are static.
  • The config spec is analytically useful because it exposes notification metadata through either WalletConnect Cloud config or .well-known/wc-notify-config.json, making app metadata and scope definitions part of the protocol surface.
  • Message retrieval and mark-as-read methods show that Notify is also trying to standardize wallet-side inbox/archive behavior, not only immediate push delivery.

Specific source signals worth retaining

  • The did:web plus X25519 key-discovery path is the clearest clue that app identity and topic derivation are first-class design elements.
  • The scp scope claim in authentication and the NotificationType schema in config are the main reasons to treat Notify as scoped authorization infrastructure instead of generic messaging.
  • The wc_notifyWatchSubscriptions / wc_notifySubscriptionsChanged flow is the best evidence that subscription state synchronization is a real control plane.
  • The wc_notifyGetNotifications and wc_notifyMarkNotificationsAsRead methods matter because they extend the protocol beyond live push into wallet-side archive and read-state management.

Why this entry belongs in the corpus

  • It strengthens the wallet infrastructure area with a post-connect communication layer that most wallet/connect discussions flatten away.
  • It is a useful comparison class for Push Protocol, wallet inboxes, app alert systems, and any system where the key question is who can message a wallet user, under what scope, and with what public metadata.
  • The reusable insight is that notification systems are governance surfaces too: whoever controls app discovery, message taxonomy, subscription state, and notification retrieval controls more of wallet-user attention than a generic “notifications” label suggests.