diff --git a/methods/websocket/voteSubscribe.md b/methods/websocket/voteSubscribe.md new file mode 100644 index 0000000..a467c7f --- /dev/null +++ b/methods/websocket/voteSubscribe.md @@ -0,0 +1,15 @@ +# voteSubscribe + +WebSocket-only. Subscribe to vote messages. The request returns a numeric subscription id. Agave then sends `voteNotification` 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. Agave returns `MethodNotFound` unless the validator enables `--rpc-pubsub-enable-vote-subscription`. + +## 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#L223). diff --git a/methods/websocket/voteSubscribe.yaml b/methods/websocket/voteSubscribe.yaml new file mode 100644 index 0000000..9c19926 --- /dev/null +++ b/methods/websocket/voteSubscribe.yaml @@ -0,0 +1,39 @@ +name: voteSubscribe +status: standard +summary: Subscribe to vote messages. +params: [] +result: + name: subscriptionId + summary: Identifier for this connection's subscription. + schema: { $ref: '#/components/schemas/U64' } +errors: + - $ref: '#/components/errors/MethodNotFound' + - $ref: '#/components/errors/InternalError' +examples: + - name: basic + summary: Create the subscription. + params: [] + result: + name: subscriptionId + value: 1 +notification: + name: voteNotification + description: Notification payload sent for this subscription. + schema: + type: object + required: [subscription, result] + properties: + subscription: { $ref: '#/components/schemas/U64' } + result: + type: object + required: [votePubkey, slots, hash, timestamp, signature] + properties: + votePubkey: { $ref: '#/components/schemas/Pubkey' } + slots: { type: array, items: { $ref: '#/components/schemas/Slot' } } + hash: { $ref: '#/components/schemas/Hash' } + timestamp: { oneOf: [{ $ref: '#/components/schemas/I64' }, { type: 'null' }] } + signature: { $ref: '#/components/schemas/Signature' } +implementations: + agave: { status: full } + cloudbreak: { status: none } + superbank: { status: none } diff --git a/proposals/0059-vote-subscribe.md b/proposals/0059-vote-subscribe.md new file mode 100644 index 0000000..d48196c --- /dev/null +++ b/proposals/0059-vote-subscribe.md @@ -0,0 +1,38 @@ +--- +number: 0059 +title: Add voteSubscribe +authors: [rpcpool] +status: draft +created: 2026-09-14 +reference-implementations: [https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L223] +--- + +# Add voteSubscribe + +## Summary + +Add the voteSubscribe WebSocket RPC method and its voteNotification 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#L223) + +## 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/