[docs-agent] Sui JSON-RPC deprecation: banners + migration-guide scaffold - #1589
Merged
Merged
Conversation
…fold Deprecation of Sui JSON-RPC in favor of Sui gRPC, with end-of-support September 25, 2026. Adds visible warnings on every Sui JSON-RPC touchpoint and scaffolds the new migration-guide page. Changes: - Add <Warning title="Deprecation notice"> banner to the top of the description field for all 51 Sui JSON-RPC methods (24 in _components/sui/methods.yaml, 13 in _components/sui_unsafe/methods.yaml, 14 in _components/suix/methods.yaml). Descriptions switch from folded (>) to literal (|) block scalars so the MDX block's newlines survive. The inline one-liner suix_getCoinMetadata description also moves to the literal block. Precedent: src/openrpc/alchemy/transaction-simulation/transaction-simulation.yaml:18. - Add the same banner to content/api-reference/sui/sui-api-quickstart.mdx (top of body, below frontmatter). - New content/api-reference/sui/sui-json-rpc-migration-guide.mdx placeholder page at slug /docs/reference/sui-json-rpc-migration-guide. Body is currently a stub — the requester will provide the final content (Notion source, docs-agent lacks access). Placeholder Warning callout inside the page flags this and links to DOCS-214. - content/docs.yml: insert the new page above Quickstart in the Sui section sidebar. This PR is intentionally a DRAFT until the requester pastes the migration-guide content in-thread; the surrounding structure is reviewable now. Validation: `pnpm run validate:rpc` and `pnpm run validate:docs-yml` both pass. Generated content/api-specs/chains/sui.json has the deprecation Warning in all 51 method descriptions (gitignored, verified locally). Refs DOCS-214 Requested-by: @silviavl
🔗 Preview Mode
|
Silvia dropped the Notion source as a .md attachment in the Slack thread. Content pasted into the placeholder verbatim modulo two markup adaptations flagged in the PR body:
1. Dropped the duplicate H1 ("# SUI JSON-RPC to gRPC Migration Guide") since the frontmatter title renders the page header on Alchemy docs. Convention across the sibling migration guides (privy/react-migration.mdx, privy/jwt-auth-migration.mdx, etc.).
2. Converted two Notion-export <aside> callouts to <Warning> and <Note> MDX components. The docs-site has no <aside> styling — leaving them as raw HTML would render as unstyled paragraphs, not the visual callouts the Notion source intended. First aside (⚠️ about grpcurl reflection) -> <Warning>; second aside (🔧 about unsafe_* family) -> <Note>. Emoji lines dropped since MDX callouts have their own iconography. Flagged in PR for revert if Silvia disagrees.
Year confirmed as 2026 by Silvia in the same message.
Validation: pnpm run validate:docs-yml passes. Warning/Note tag counts balanced (2 Warning blocks + 1 Note block).
Refs DOCS-214
Requested-by: @silviavl
alchemy-bot
marked this pull request as ready for review
September 1, 2026 16:26
![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: 45610012df
ℹ️ 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".
|
|
||
| Sui is retiring JSON-RPC across the network. Please **migrate** your application to **Sui gRPC** by **September 25, 2026** to avoid any disruption. | ||
|
|
||
| **Sui gRPC** is a Protocol Buffers API that covers reads, streaming, and transaction execution. This guide maps every JSON-RPC method to its gRPC equivalent and calls out the behavior differences that break a naive port. |
There was a problem hiding this comment.
This promises a mapping for every JSON-RPC method, but the published Sui specs also contain suix_getLatestSuiSystemState, sui_tryMultiGetPastObjects, sui_getProtocolConfig, and suix_getCommitteeInfo, none of which appears anywhere in the guide. Users relying on any of those endpoints therefore cannot complete the later checklist instruction to swap every call; add their gRPC equivalents or explicitly list them among the methods without equivalents.
Useful? React with 👍 / 👎.
Contributor
Author
There was a problem hiding this comment.
Verified — all four methods exist in this repo's Sui JSON-RPC spec at src/openrpc/chains/_components/{sui,suix}/methods.yaml:
suix_getLatestSuiSystemState—_components/sui/methods.yaml:736sui_tryMultiGetPastObjects—_components/sui/methods.yaml:1639sui_getProtocolConfig—_components/sui/methods.yaml:2045suix_getCommitteeInfo—_components/suix/methods.yaml:364
None appear in the migration guide's mapping tables or in the "no gRPC equivalent" section, so the guide's implicit "map every JSON-RPC method" contract is broken for these four.
Deferring the addition to Silvia (@silviavl) because her ask was "do not modify the content." Adding four new rows is a genuine content extension, not a typo fix, so this feels like a call for her to make. Flagging in the Slack thread.
Contributor
Author
There was a problem hiding this comment.
Not applying — Oskar declined this one in Slack ("skip comment 2"). The 4 methods (suix_getLatestSuiSystemState, sui_tryMultiGetPastObjects, sui_getProtocolConfig, suix_getCommitteeInfo) stay out of the migration guide for now; adding rows was a content extension the requester chose not to do in this PR.
…cklist The 9 task-list items in the '## Migration checklist' section were paseted from the Notion export as `* [ ] Item`. remark-lint's no-undefined-references rule (from remark-preset-lint-recommended) parses the `[ ]` as an undefined shortcut link reference and warned on every line (R308–R316 in CI). The linter's own suggestion is to escape the opening bracket. Precedent for the same fix on a comparable checklist: content/wallets/CONTRIBUTING.md L344-360 uses `* \[ ] Item` verbatim. Applied 's/^\* \[ \] /\* \\[ ] /' across the 9 checklist rows. Prose unchanged. Refs DOCS-214 Requested-by: @silviavl
…e page itself Per Silvia in Slack: the migration guide is the destination the banner links to, so having the banner also sit atop the guide is self-referential and redundant. Kept the deprecation banner in place on the Sui Quickstart page and on every Sui JSON-RPC endpoint description (unchanged). This only removes the top-of-page <Warning title="Deprecation notice"> block from content/api-reference/sui/sui-json-rpc-migration-guide.mdx. The migration guide's other callouts (Warning about grpcurl reflection, Note about the unsafe_* family) remain in place. Refs DOCS-214 Requested-by: @silviavl
Codex P2 flagged that the migration guide referenced sui_subscribeTransaction and sui_subscribeEvent, which don't exist. Sui's subscription methods live in the suix_ extended namespace, and this repo's own content/api-reference/sui-grpc/overview.mdx:86-87 already documents them as suix_subscribeTransaction / suix_subscribeEvent. Applied a targeted sed across the 4 occurrences in the migration guide (L75 Transactions table row, L108 Events table row, L165 prose paragraph mentioning both, L290 worked-example intro): sui_subscribeTransaction -> suix_subscribeTransaction sui_subscribeEvent -> suix_subscribeEvent Oskar green-lit the fix in Slack (docs-team owner on the Sui section). Skipped Codex's other P2 comment (adding 4 methods missing from the mapping tables) per the same message — that's a content extension the requester declined. Refs DOCS-214 Requested-by: @oskarciupider-alchemy
SahilAujla
approved these changes
Sep 1, 2026
Per Oskar in Slack after previewing the PR: the escaped bracket prefixes (`* \[ ] Item`) I added in cd70af4 to appease remark-lint's no-undefined-references rule are rendering as literal `[ ]` text on the docs site because remark-gfm isn't enabled. Simplest fix: drop the `\[ ] ` prefix entirely so each row is a plain bullet. The checklist is a static reference list, not an interactive task list, so the visible checkbox glyph adds no value. Applied 's/^\* \\[ \] /\* /' across all 9 rows (L304-L312). remark-lint is happy (no undefined-reference triggered because there's no `[` anymore), preview renders as clean bullets. Refs DOCS-214 Requested-by: @oskarciupider-alchemy
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Deprecation of Sui JSON-RPC in favor of Sui gRPC, with end-of-support September 25, 2026.
Adds visible warnings on every Sui JSON-RPC touchpoint and ships the new migration-guide page with the content Silvia provided from Notion.
Changes
New migration-guide page —
content/api-reference/sui/sui-json-rpc-migration-guide.mdxat slug/docs/reference/sui-json-rpc-migration-guide. Content pasted verbatim from the Notion export Silvia attached in the Slack thread, modulo two markup adaptations flagged below.51 Sui JSON-RPC endpoint pages —
<Warning title="Deprecation notice">prepended to the description of every method that feedscontent/docs.ymlunderapi: Sui API Endpoints, api-name: sui. Split across the three method component files:src/openrpc/chains/_components/sui/methods.yaml— 24 methodssrc/openrpc/chains/_components/sui_unsafe/methods.yaml— 13 methodssrc/openrpc/chains/_components/suix/methods.yaml— 14 methodsDescriptions switch from folded (
>) to literal (|) block scalars so the MDX block's newlines are preserved. Follows the precedent atsrc/openrpc/alchemy/transaction-simulation/transaction-simulation.yaml:18.content/api-reference/sui/sui-api-quickstart.mdx— same banner added at the top of the body (below frontmatter).content/docs.yml— new page inserted above Quickstart in the Sui section sidebar, per the ask.Banner text
Year confirmed as 2026 by Silvia in-thread.
Notion → MDX adaptations (flagged for revert if Silvia disagrees)
The Notion export is pasted verbatim on prose, tables, code samples, and links. Two small markup adaptations were necessary for the docs site to render correctly:
# SUI JSON-RPC to gRPC Migration Guide). The docs site emits the page header from the frontmattertitlefield, so keeping the body H1 would show the title twice. This matches the convention in sibling migration guides (privy/react-migration.mdx,privy/jwt-auth-migration.mdx, etc.).<aside>blocks to MDX callouts. Notion's<aside>renders as unstyled<aside>HTML on this docs site (no callout styling). Left as-is, the reader would see plain paragraphs where the source intended a visual callout.⚠️about grpcurl reflection not working) →<Warning>🔧about theunsafe_*family) →<Note>Both are markup-only changes; the prose inside each callout is unchanged. Easy to revert if you prefer raw
<aside>or a different mapping — happy to swap in a follow-up commit.Validation
pnpm run validate:rpc— passespnpm run validate:docs-yml— passescontent/api-specs/chains/sui.json(gitignored) verified locally: 51 method descriptions contain the Warning block.<Warning>/<Note>open/close tag counts balanced in the new migration-guide file.Linear
DOCS-214 — https://linear.app/alchemyapi/issue/DOCS-214/sui-json-rpc-deprecation-migration-guide-page-banners-across
Requested by
@silviavl (via Slack thread)