> For the complete documentation index, see [llms.txt](/llms.txt) # Migrate to 2.0 Migration guide for Sui TypeScript SDK 2.0 covering all @mysten packages 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 [#quick-reference] | Package | Key Changes | | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | [`@mysten/sui`](/sui/migrations/sui-2.0/sui) | Client API stabilization, SuiClient removal, BCS schema alignment, transaction executors | | [`@mysten/dapp-kit`](/sui/migrations/sui-2.0/dapp-kit) | Complete rewrite with framework-agnostic core | | [`@mysten/kiosk`](/sui/migrations/sui-2.0/kiosk) | Client extension pattern, low-level helpers removed, KioskTransaction pattern | | [`@mysten/zksend`](/sui/migrations/sui-2.0/zksend) | Client extension pattern | | [`@mysten/suins`](/sui/migrations/sui-2.0/suins) | Client extension pattern | | [`@mysten/deepbook-v3`](/sui/migrations/sui-2.0/deepbook-v3) | Client extension pattern | | [`@mysten/walrus`](/sui/migrations/sui-2.0/walrus) | Client extension pattern, requires client instead of RPC URL | | [`@mysten/seal`](/sui/migrations/sui-2.0/seal) | Client extension pattern | | [`@mysten/wallet-standard`](/sui/migrations/sui-2.0/wallet-builders) | Removal of reportTransactionEffects, new core API response format | | [Migrating from JSON-RPC](/sui/migrations/sui-2.0/json-rpc-migration) | Migrate from deprecated JSON-RPC to gRPC and GraphQL | ## Common migration patterns [#common-migration-patterns] ### ESM migration [#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`: ```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"`: ```json { "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 [#client-migration] The recommended app migration is to create one `SuiGrpcClient` and use its top-level methods: ```diff - 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: ```diff - 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](/sui/migrations/sui-2.0/json-rpc-migration) for detailed replacements. ### Network parameter required [#network-parameter-required] All client constructors now require an explicit `network` parameter: ```ts 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 [#clientwithcoreapi-interface] Many SDK methods now accept any client implementing `ClientWithCoreApi`. SDKs use `client.core.()` so they can work across `SuiGrpcClient`, `SuiGraphQLClient`, and the deprecated `SuiJsonRpcClient` while apps keep using the top-level methods on their chosen client: ```ts 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 [#package-specific-guides] For detailed migration instructions, see the SDK-specific guides: * **[`@mysten/sui`](/sui/migrations/sui-2.0/sui):** Core SDK changes including client API, BCS schemas, transactions, zkLogin, and GraphQL * **[`@mysten/dapp-kit`](/sui/migrations/sui-2.0/dapp-kit):** Complete migration guide for the new dApp kit architecture * **[`@mysten/kiosk`](/sui/migrations/sui-2.0/kiosk):** Kiosk SDK now exports a client extension, low-level helpers removed * **[`@mysten/zksend`](/sui/migrations/sui-2.0/zksend):** zkSend SDK now exports a client extension * **[`@mysten/suins`](/sui/migrations/sui-2.0/suins):** SuiNS now exports a client extension * **[`@mysten/deepbook-v3`](/sui/migrations/sui-2.0/deepbook-v3):** DeepBook DEX now exports a client extension * **[`@mysten/walrus`](/sui/migrations/sui-2.0/walrus):** Walrus storage now exports a client extension * **[`@mysten/seal`](/sui/migrations/sui-2.0/seal):** Seal encryption now exports a client extension ## Transport migration [#transport-migration] * **[Migrating from JSON-RPC](/sui/migrations/sui-2.0/json-rpc-migration):** Migrate from the deprecated JSON-RPC client to gRPC and GraphQL ## Ecosystem migration guides [#ecosystem-migration-guides] For wallet builders and SDK maintainers building on the Sui ecosystem: * **[Wallet builders](/sui/migrations/sui-2.0/wallet-builders):** Guide for wallet implementations adapting to `reportTransactionEffects` removal and new core API response format * **[SDK maintainers](/sui/migrations/sui-2.0/sdk-maintainers):** Guide for SDK authors migrating to `ClientWithCoreApi` and the new transport-agnostic architecture ## Non-existent objects [#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.