Migrate from JSON-RPC to gRPC
Sui has deprecated JSON-RPC. Current Walrus clients already reach Sui over gRPC at the same full node URL your configuration lists, so migrating means upgrading your tooling rather than rewriting your configuration. For the Sui API surface itself, see the Sui API reference.
What changes, and what stays
| Component | What you do |
|---|---|
| Walrus CLI | Upgrade to a current release |
site-builder | Upgrade to a current build |
Client configuration (rpc_urls) | Nothing, the values stay as they are |
sites-config.yaml (rpc_url) | Nothing, the value stays as it is |
| A full node you operate | Enable its gRPC API |
No setting selects gRPC. One URL per network serves both protocols, which is why upgrading fixes a broken deployment and reconfiguring does not. For the transport itself, see Transport: JSON-RPC deprecation.
Migrate
Upgrading your tooling is the migration. To move to another form of data access instead, see Transport: JSON-RPC deprecation.
Older releases still build a JSON-RPC client, so they break against a full node that no longer serves JSON-RPC. Upgrade to the current release:
$ suiup install walrus
$ suiup install site-builder # only if you publish Walrus Sites
$ walrus --version
$ site-builder --version
Your configuration needs no changes. If you want to be certain yours matches, pull the pre-filled file:
$ curl --create-dirs https://docs.wal.app/setup/client_config.yaml -o ~/.config/walrus/client_config.yaml
The optional rpc_url field in sites-config.yaml needs no change either, because site-builder reaches that same node over gRPC. For the full file, see the Site Builder Reference.
Then rerun whatever failed. If it still fails against a public endpoint, you are running an older binary than walrus --version reports, so check your PATH.
Migration for full node operators
A full node you operate has to enable the gRPC API. The public endpoints in the Network Reference already serve it. Nothing changes on the Walrus side once yours does.
Migration troubleshooting
Each of these means the same thing: a client that still speaks JSON-RPC, or a node that does not serve gRPC.
| What you see | What it means |
|---|---|
A walrus command fails against a full node that stopped serving JSON-RPC | The installed release still builds a JSON-RPC client |
site-builder fails the same way | The installed build still builds a JSON-RPC client |
| You cannot find the setting that selects gRPC | No such setting exists |
| A full node you operate rejects Walrus client traffic | The node does not serve the gRPC API |
One symptom means nothing is wrong. The public nodes serve Sui client and SDK traffic rather than JSON-RPC method discovery, so normal calls against the same URL succeed. If rpc.discover returns 404 against a working full node, drive the node through sui client and the Walrus configuration file instead of calling JSON-RPC methods by hand.
Do not force the old code paths
WALRUS_GRPC_MIGRATION_LEVEL exists as a temporary escape hatch for debugging the migration. If you set it below the client's default, the client falls back to the older JSON-RPC code paths that Sui full nodes are removing, which reintroduces every failure above.
Do not set WALRUS_GRPC_MIGRATION_LEVEL in production. If you set it while debugging, unset it before you deploy.