diff --git a/methods/websocket/signatureSubscribe.md b/methods/websocket/signatureSubscribe.md new file mode 100644 index 0000000..9beabaf --- /dev/null +++ b/methods/websocket/signatureSubscribe.md @@ -0,0 +1,15 @@ +# signatureSubscribe + +WebSocket-only. Subscribe to the status of a transaction signature. The request returns a numeric subscription id. Agave then sends `signatureNotification` 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#L138). diff --git a/methods/websocket/signatureSubscribe.yaml b/methods/websocket/signatureSubscribe.yaml new file mode 100644 index 0000000..d994c9b --- /dev/null +++ b/methods/websocket/signatureSubscribe.yaml @@ -0,0 +1,60 @@ +name: signatureSubscribe +status: standard +summary: Subscribe to the status of a transaction signature. +params: + - name: signature + required: true + summary: Transaction signature to watch. + schema: { $ref: '#/components/schemas/Signature' } + - name: config + required: false + summary: Commitment and received-notification options. + schema: + type: object + properties: + commitment: { $ref: '#/components/schemas/Commitment' } + enableReceivedNotification: { type: boolean } +result: + name: subscriptionId + summary: Identifier for this connection's subscription. + schema: { $ref: '#/components/schemas/U64' } +errors: + - $ref: '#/components/errors/InvalidParams' + - $ref: '#/components/errors/InternalError' +examples: + - name: basic + summary: Create the subscription. + params: + - name: signature + value: '5NfHk6JxqzQ54zk5cYBkiM7mj9XodPFdJNbB4z8zTETSV4gTWjSQm3yYAxT9Y7DkVMwq3siB1oX7nWdTUkzHd4Wq' + result: + name: subscriptionId + value: 1 +notification: + name: signatureNotification + description: Notification payload sent for this subscription. + schema: + type: object + required: [subscription, result] + properties: + subscription: { $ref: '#/components/schemas/U64' } + result: + type: object + required: [context, value] + properties: + context: { $ref: '#/components/schemas/RpcResponseContext' } + value: + oneOf: + - type: object + required: [err] + properties: + err: + oneOf: + - $ref: '#/components/schemas/TransactionError' + - type: 'null' + - type: string + enum: [receivedSignature] +implementations: + agave: { status: full } + cloudbreak: { status: none } + superbank: { status: none } diff --git a/proposals/0051-signature-subscribe.md b/proposals/0051-signature-subscribe.md new file mode 100644 index 0000000..9648548 --- /dev/null +++ b/proposals/0051-signature-subscribe.md @@ -0,0 +1,38 @@ +--- +number: 0051 +title: Add signatureSubscribe +authors: [rpcpool] +status: draft +created: 2026-09-14 +reference-implementations: [https://github.com/anza-xyz/agave/blob/6dd9d38771e46103b9680357a855804165612602/rpc/src/rpc_pubsub.rs#L138] +--- + +# Add signatureSubscribe + +## Summary + +Add the signatureSubscribe WebSocket RPC method and its signatureNotification 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#L138) + +## 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/