From ce49da77b3c0376f1900fed797bbd9d9fa545121 Mon Sep 17 00:00:00 2001
From: Linus Kendall <5172293+linuskendall@users.noreply.github.com>
Date: Mon, 14 Sep 2026 06:20:44 +0000
Subject: [PATCH 1/2] feat(websocket): add slotsUpdatesSubscribe specification

---
 methods/websocket/slotsUpdatesSubscribe.md   | 15 ++++++++
 methods/websocket/slotsUpdatesSubscribe.yaml | 39 ++++++++++++++++++++
 proposals/0055-slots-updates-subscribe.md    | 38 +++++++++++++++++++
 spec-info.yaml                               |  2 +-
 4 files changed, 93 insertions(+), 1 deletion(-)
 create mode 100644 methods/websocket/slotsUpdatesSubscribe.md
 create mode 100644 methods/websocket/slotsUpdatesSubscribe.yaml
 create mode 100644 proposals/0055-slots-updates-subscribe.md

diff --git a/methods/websocket/slotsUpdatesSubscribe.md b/methods/websocket/slotsUpdatesSubscribe.md
new file mode 100644
index 0000000..0364f87
--- /dev/null
+++ b/methods/websocket/slotsUpdatesSubscribe.md
@@ -0,0 +1,15 @@
+# slotsUpdatesSubscribe
+
+WebSocket-only. Subscribe to lifecycle updates for slots. The request returns a numeric subscription id. Agave then sends `slotsUpdatesNotification` notifications on the same connection.
+
+## Notification wire format
+
+The notification uses JSON-RPC 2.0 with `params.result` as the payload declared in the paired YAML and `params.subscription` as the id returned by this method.
+
+## Semantics
+
+Subscriptions are scoped to the WebSocket connection. Closing the connection cancels them. The reference handler deduplicates compatible active subscriptions and rejects new subscriptions when the node limit is reached.
+
+## Implementation notes
+
+[**Agave**](../../implementations/agave.md) implements this method in the [pinned PubSub trait](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L180). Cloudbreak and Superbank do not serve WebSocket subscriptions.
diff --git a/methods/websocket/slotsUpdatesSubscribe.yaml b/methods/websocket/slotsUpdatesSubscribe.yaml
new file mode 100644
index 0000000..e6e9f32
--- /dev/null
+++ b/methods/websocket/slotsUpdatesSubscribe.yaml
@@ -0,0 +1,39 @@
+name: slotsUpdatesSubscribe
+status: standard
+summary: Subscribe to lifecycle updates for slots.
+params: []
+result:
+  name: subscriptionId
+  summary: Identifier for this connection's subscription.
+  schema: { $ref: '#/components/schemas/U64' }
+errors:
+  - $ref: '#/components/errors/InternalError'
+examples:
+  - name: basic
+    summary: Create the subscription.
+    params: []
+    result:
+      name: subscriptionId
+      value: 1
+notification:
+  name: slotsUpdatesNotification
+  description: Notification payload sent for this subscription.
+  schema:
+    type: object
+    required: [subscription, result]
+    properties:
+      subscription: { $ref: '#/components/schemas/U64' }
+      result:
+        type: object
+        required: [type, slot, timestamp]
+        properties:
+          type: { type: string, enum: [firstShredReceived, completed, createdBank, frozen, dead, optimisticConfirmation, root] }
+          slot: { $ref: '#/components/schemas/Slot' }
+          parent: { $ref: '#/components/schemas/Slot' }
+          timestamp: { $ref: '#/components/schemas/U64' }
+          err: { type: string }
+          stats: { type: object }
+implementations:
+  agave: { status: full }
+  cloudbreak: { status: none }
+  superbank: { status: none }
diff --git a/proposals/0055-slots-updates-subscribe.md b/proposals/0055-slots-updates-subscribe.md
new file mode 100644
index 0000000..324dcf2
--- /dev/null
+++ b/proposals/0055-slots-updates-subscribe.md
@@ -0,0 +1,38 @@
+---
+number: 0055
+title: Add slotsUpdatesSubscribe
+authors: [rpcpool]
+status: draft
+created: 2026-09-14
+reference-implementations: [https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L180]
+---
+
+# Add slotsUpdatesSubscribe
+
+## Summary
+
+Add the slotsUpdatesSubscribe WebSocket RPC method and its slotsUpdatesNotification notification.
+
+## Motivation
+
+Agave exposes this public PubSub method. A standard method page lets clients and alternative implementations use one contract.
+
+## Specification
+
+Add the paired WebSocket method page. It defines the request, subscription id, notification name and payload, and the connection-scoped lifecycle.
+
+## Return-type impact
+
+The subscribe response is a numeric subscription id. Notifications carry the method-specific payload.
+
+## Compatibility
+
+This is additive. Agave implements it. Cloudbreak and Superbank do not currently implement WebSocket PubSub.
+
+## Reference implementation
+
+[Agave pinned handler](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L180)
+
+## Security considerations
+
+Servers must bound active subscriptions and release them when the connection closes.
diff --git a/spec-info.yaml b/spec-info.yaml
index 892ea85..bca4391 100644
--- a/spec-info.yaml
+++ b/spec-info.yaml
@@ -1,5 +1,5 @@
 title: Solana JSON-RPC API
-version: 0.1.0
+version: 0.2.0
 license:
   name: MIT
   url: https://opensource.org/license/mit/

From 4172ffad31dca4232632b33fc6954bbed82c1c46 Mon Sep 17 00:00:00 2001
From: Linus Kendall <5172293+linuskendall@users.noreply.github.com>
Date: Mon, 14 Sep 2026 06:43:43 +0000
Subject: [PATCH 2/2] docs(agave): focus implementation note

---
 methods/websocket/slotsUpdatesSubscribe.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/methods/websocket/slotsUpdatesSubscribe.md b/methods/websocket/slotsUpdatesSubscribe.md
index 0364f87..2088020 100644
--- a/methods/websocket/slotsUpdatesSubscribe.md
+++ b/methods/websocket/slotsUpdatesSubscribe.md
@@ -12,4 +12,4 @@ Subscriptions are scoped to the WebSocket connection. Closing the connection can
 
 ## Implementation notes
 
-[**Agave**](../../implementations/agave.md) implements this method in the [pinned PubSub trait](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L180). Cloudbreak and Superbank do not serve WebSocket subscriptions.
+[**Agave**](../../implementations/agave.md) implements this method in the [pinned PubSub trait](https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L180).