Upgrading SDKs to @mysten/sui@2.0.0

This guide covers the key breaking changes for SDK maintainers building on top of @mysten/sui.

For comprehensive SDK development patterns, see the Building SDKs guide.

Use ClientWithCoreApi

Accept ClientWithCoreApi instead of SuiClient so applications can pass a SuiGrpcClient, SuiGraphQLClient, or a legacy SuiJsonRpcClient during migration:

- import { SuiClient } from '@mysten/sui/client';
+ import type { ClientWithCoreApi } from '@mysten/sui/client';

export class MySDKClient {
-   client: SuiClient;
+   client: ClientWithCoreApi;
}

Access data through client.core methods

SDKs should access shared client methods through client.core. Application code can use the same methods at the top level of its concrete client, but client.core is the stable contract for libraries that should work across transports:

- const result = await this.client.getObject({ objectId });
+ const result = await this.client.core.getObject({ objectId });

- const result = await this.client.getOwnedObjects({ owner });
+ const result = await this.client.core.listOwnedObjects({ owner });

Use getDynamicField() for regular dynamic fields and when you need the field entry or BCS-encoded value. Use getDynamicObjectField() only for dynamic object fields when you want the referenced child object returned directly.

See the Core API documentation for all available methods.

Use peer dependencies

Declare @mysten/* packages as peer dependencies:

{
	"peerDependencies": {
		"@mysten/sui": "^2.0.0"
	},
	"devDependencies": {
		"@mysten/sui": "^2.0.0"
	}
}

Client extensions

v2.0 introduces client extensions that let users add your SDK to any Sui client:

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

export function mySDK() {
	return {
		name: 'mySDK',
		register: (client: ClientWithCoreApi) => {
			return new MySDKClient({ client });
		},
	};
}

// Users can then extend any client
const client = new SuiGrpcClient({ ... }).$extend(mySDK());
await client.mySDK.doSomething();

See the Building SDKs guide for the complete extension pattern.

Code generation

Use @mysten/codegen to generate type-safe TypeScript bindings from your Move packages. See the codegen documentation for setup instructions.

For complete SDK development patterns including client extensions, transaction thunks, and best practices, see the Building SDKs guide.