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 gRPC and GraphQL APIs across all 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 your project does not already use ESM, you will need to add "type": "module" to your package.json:

{
	"type": "module"
}

If you are using TypeScript with 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 (for example, @mysten/sui/client, @mysten/sui/transactions).

If you maintain a library that depends on any of the @mysten/* packages, you might 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) might 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 recommended app migration is to create one SuiGrpcClient and use its top-level methods:

- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+ import { SuiGrpcClient } from '@mysten/sui/grpc';

- const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
+ const client = new SuiGrpcClient({
+   baseUrl: 'https://fullnode.mainnet.sui.io:443',
+   network: 'mainnet',
+ });

Then migrate old JSON-RPC method names to the gRPC top-level methods:

- const coins = await client.getCoins({ owner });
+ const coins = await client.listCoins({ owner });

- const txs = await client.queryTransactionBlocks({ filter, options });
+ const txs = await client.listTransactions({ filter, include });

- const events = await client.queryEvents({ query, order: 'descending' });
+ const events = await client.listEvents({ filter, order: 'descending' });

- const transaction = await client.getTransactionBlock({ digest, options });
+ const transaction = await client.getTransaction({ digest, include });

The gRPC API runs on full nodes, so in most cases you can use the same full node host when migrating from JSON-RPC to gRPC. Standard transaction and event queries are top-level methods on both SuiGrpcClient and SuiGraphQLClient. Use custom GraphQL queries for indexed data, historical object versions, or selection sets that are not covered by the shared methods.

SuiJsonRpcClient still exists under @mysten/sui/jsonRpc for legacy code, but JSON-RPC APIs are deprecated in the Sui TypeScript SDK. See Migrating from JSON-RPC for detailed replacements.

Network parameter required

All client constructors now require an explicit network parameter:

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

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

const jsonRpcClient = new SuiJsonRpcClient({
	url: 'https://fullnode.mainnet.sui.io:443',
	network: 'mainnet', // Required
});

ClientWithCoreApi Interface

Many SDK methods now accept any client implementing ClientWithCoreApi. SDKs use client.core.<method>() so they can work across SuiGrpcClient, SuiGraphQLClient, and the deprecated SuiJsonRpcClient while apps keep using the top-level methods on their chosen client:

import type { ClientWithCoreApi } from '@mysten/sui/client';
import { SuiGrpcClient } from '@mysten/sui/grpc';

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

// App code: use top-level methods.
const { balance } = await client.getBalance({ owner });

// SDK code: accept ClientWithCoreApi and use client.core.
async function readForSdk(client: ClientWithCoreApi, objectId: string) {
	return client.core.getObject({ objectId });
}

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

Non-existent objects

When migrating from the v1 SDK to the v2 SDK, review any code paths that read objects or dynamic fields that may not exist.

In v1, methods such as core.getObject and getDynamicField return null when the requested object or field does not exist. In v2, the same operations throw an exception instead. Applications that previously relied on null checks should be updated to handle exceptions appropriately, either through try/catch blocks or by validating object existence before attempting to read it.

This behavioral change may require updates to error handling logic to avoid unexpected runtime failures after migration.