[docs-agent] Add Solana blockSubscribe reference page - #1566
Conversation
Adds `blockSubscribe` under Solana Subscription API Endpoints. Method is only exposed on Alchemy's Solana streaming endpoint (`wss://solana-mainnet.streaming.alchemy.com`), not on the regular `solana-mainnet.g.alchemy.com` WebSocket endpoint — flagged with a warning callout at the top of the page. Live-verified against `docs-demo`. Refs DOCS-205 Requested-by: @clinder777
🔗 Preview Mode
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a5f5834583
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| * `config` (optional): `object` - Configuration object containing: | ||
|
|
||
| * `commitment`: `string` - The commitment level. One of `confirmed`, `finalized`. Defaults to `finalized`. `processed` is not supported for this subscription. | ||
| * `encoding`: `string` - Encoding for account and instruction data. One of `base58`, `base64`, `base64+zstd`, `jsonParsed`. Defaults to `base64`. |
There was a problem hiding this comment.
When a reader selects the documented base64+zstd value, the subscription request is rejected because blockSubscribe uses transaction encodings, which do not support the account-data-only base64+zstd format. The accepted list should include json instead, alongside base58, base64, and jsonParsed.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Good catch. Live-verified against wss://solana-mainnet.streaming.alchemy.com/v2/docs-demo: sending encoding: base64+zstd returns -32602 unknown variant \base64+zstd`, expected one of `binary`, `base64`, `base58`, `json`, `jsonParsed``.
Fixed in 114970f8 — updated the encoding list to json, jsonParsed, base58, base64 (matching the server's accepted set for transaction encodings), changed the default to json, and added a short note that base64+zstd is not supported by blockSubscribe (it's an account-data encoding only). Not adding binary since it's the deprecated alias for base58.
`base64+zstd` is not a valid encoding for `blockSubscribe` — it's an account-data encoding only. Live-verified against `wss://solana-mainnet.streaming.alchemy.com/v2/docs-demo`: sending `encoding: base64+zstd` returns `-32602 unknown variant \`base64+zstd\`, expected one of \`binary\`, \`base64\`, \`base58\`, \`json\`, \`jsonParsed\``. Updated the encoding list on `block-subscribe.mdx` to `json`, `jsonParsed`, `base58`, `base64` (Solana's default for transaction encoding is `json`), and added a short note that `base64+zstd` is not supported here. Addresses codex review comment on PR #1566. Refs DOCS-205 Requested-by: @clinder777
Per requester feedback, remove the Solana upstream 'unstable method' warning callout from the top of the page. The streaming-endpoint callout stays. Refs DOCS-205 Requested-by: @clinder777
2 participants
Summary
Adds a
blockSubscribereference page to the Solana Subscription API Endpoints section, modeled after the existingaccountSubscribe/programSubscribepages.blockSubscribeis only exposed on Alchemy's Solana streaming endpoint (wss://solana-mainnet.streaming.alchemy.com), not on the standardwss://solana-mainnet.g.alchemy.comWebSocket endpoint. The page opens with a Warning callout making this explicit, plus a second callout carrying over Solana's upstream "unstable method" warning. Method behavior was live-verified againstdocs-demoon the streaming endpoint before writing:blockNotificationpayloads captured withcommitment: confirmed,encoding: base64,transactionDetails: signatures,showRewards: false,maxSupportedTransactionVersion: 0— used as the example values in the page.maxSupportedTransactionVersionreturnsblock: nullwitherr: { UnsupportedTransactionVersion: 0 }— surfaced as an Info callout after the Result section.g.alchemy.comWebSocket endpoint returns-32601 Method 'blockSubscribe' not foundfor the same request.Changes
content/api-reference/websockets/solana-subscription-api-endpoints/block-subscribe.mdx— new page.content/api-reference/websockets/solana-subscription-api-endpoints/solana-subscription-api-endpoints.mdx— added a row to the Cluster table with an inline note that the method requires the streaming endpoint.content/docs.yml— added the nav entry under Solana Subscription API Endpoints, immediately afterslotSubscribe.Notes
@solana/web3.jsdoes not wrapblockSubscribe, so the JS example uses a rawwsWebSocket instead of aConnection.on*helper.topconfig.ymlfromOMGWINNING/chain-config, which docs-agent cannot read.blockSubscribealso works onwss://solana-devnet.streaming.alchemy.com/v2/<key>. The current callout only mentions the mainnet streaming endpoint per the requester's explicit ask; happy to add a devnet line if reviewers want it.Linear
DOCS-205 — https://linear.app/alchemyapi/issue/DOCS-205/add-solana-blocksubscribe-page-streaming-endpoint
Requested by
@clinder777 (via Slack thread)