Migrate to 2.0

This guide covers the breaking changes across the latest release of all the @mysten/* packages.

The primary goal of this release is to support the new GRPC and GraphQL APIs across all the mysten SDKs. These releases also include removals of deprecated APIs, some renaming for better consistency, and significant internal refactoring to improve maintainability. Starting with this release, Mysten packages will now be published as ESM only packages.

Quick Reference

Common Migration Patterns

ESM Migration

All @mysten/* packages are now ESM only. If you are using moduleResolution "Node", "Classic", or "Node10", you will need to update your tsconfig.json to use "NodeNext", "Node16", or "Bundler":

{
	"compilerOptions": {
		"moduleResolution": "NodeNext",
		"module": "NodeNext"
	}
}

This enables proper resolution of the SDK's subpath exports (e.g., @mysten/sui/client, @mysten/sui/transactions).

If you maintain a library that depends on any of the @mysten/* packages, you may also need to update your library to be ESM only to ensure it works correctly everywhere.

Applications using bundlers and recent Node.js versions (>=22) may still work when using require to load ESM packages, but we recommend migrating to ESM.

Why ESM only? Many packages in the ecosystem (specifically critical cryptography dependencies) are now published as ESM only. Supporting CommonJS has prevented us from using the latest versions of these dependencies, making our SDKs harder to maintain and risking missing critical security updates.

Client Migration

The most common change across all SDKs is migrating from SuiClient to SuiJsonRpcClient:

- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';

- const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
+ const client = new SuiJsonRpcClient({
+   url: getJsonRpcFullnodeUrl('mainnet'),
+   network: 'mainnet',
+ });

We also recommend moving from the deprecated JSON RPC Apis to the new gRPC API as soon as possible:

- import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
+ import { SuiGrpcClient } from '@mysten/sui/grpc';

- const client = new SuiJsonRpcClient({ url, network: 'mainnet' });
+ const client = new SuiGrpcClient({ baseUrl, network: 'mainnet' });

The gRPC runs on full nodes so in most cases you should be able to use the same URLs when migrating to gRPC.

Network Parameter Required

All client constructors now require an explicit network parameter:

const client = new SuiJsonRpcClient({
	url: getJsonRpcFullnodeUrl('mainnet'),
	network: 'mainnet', // Required
});

const graphqlClient = new SuiGraphQLClient({
	url: 'https://sui-mainnet.mystenlabs.com/graphql',
	network: 'mainnet', // Required
});

const grpcClient = new SuiGrpcClient({
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
	network: 'mainnet', // Required
});

ClientWithCoreApi Interface

Many SDK methods now accept any client implementing ClientWithCoreApi, enabling use with JSON-RPC, GraphQL, or gRPC transports:

import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
import { SuiGraphQLClient } from '@mysten/sui/graphql';
import { SuiGrpcClient } from '@mysten/sui/grpc';

// All of these work with APIs that accept ClientWithCoreApi
const jsonRpcClient = new SuiJsonRpcClient({ url, network: 'mainnet' });
const graphqlClient = new SuiGraphQLClient({ url, network: 'mainnet' });
const grpcClient = new SuiGrpcClient({ baseUrl, network: 'mainnet' });

Package-Specific Guides

For detailed migration instructions, see the SDK-specific guides:

• @mysten/sui - Core SDK changes including client API, BCS schemas, transactions, zkLogin, and GraphQL
• @mysten/dapp-kit - Complete migration guide for the new dApp Kit architecture
• @mysten/kiosk - Kiosk SDK now exports a client extension, low-level helpers removed
• @mysten/zksend - zkSend SDK now exports a client extension
• @mysten/suins - SuiNS now exports a client extension
• @mysten/deepbook-v3 - DeepBook DEX now exports a client extension
• @mysten/walrus - Walrus storage now exports a client extension
• @mysten/seal - Seal encryption now exports a client extension

Transport Migration

• Migrating from JSON-RPC - Migrate from the deprecated JSON-RPC client to gRPC and GraphQL

Ecosystem Migration Guides

For wallet builders and SDK maintainers building on the Sui ecosystem:

• Wallet Builders - Guide for wallet implementations adapting to reportTransactionEffects removal and new core API response format
• SDK Maintainers - Guide for SDK authors migrating to ClientWithCoreApi and the new transport-agnostic architecture