llms.txt
@mysten/sui v2.0 and a new dApp Kit are here! Check out the migration guide
Mysten Labs SDKs
Migrations

Migrate to 3.0

Breaking changes in @mysten/sui 3.0, which removes the deprecated JSON-RPC transport

@mysten/sui 3.0 removes the JSON-RPC transport. If you still use SuiJsonRpcClient, move to SuiGrpcClient (recommended) or SuiGraphQLClient by following Migrating from JSON-RPC, which maps every JSON-RPC method to its replacement. Code that already runs on gRPC or GraphQL needs few or no changes.

Every @mysten/* package with a peer dependency on @mysten/sui, except the legacy @mysten/dapp-kit, gets a new release that requires @mysten/sui@^3: a major release, or a minor release for packages still on 0.x. @mysten/dapp-kit-react also gets a major release, because it depends on @mysten/dapp-kit-core 2.0. Apart from the items below, these releases have no breaking changes: upgrade them together with @mysten/sui.

The legacy @mysten/dapp-kit has a peer dependency on @mysten/sui and uses JSON-RPC, so it can't run on 3.0 or keep a 2.x copy of its own. Migrate to @mysten/dapp-kit-react before upgrading.

Breaking changes

Removed JSON-RPC APIs

  • @mysten/sui/jsonRpc no longer supports JSON-RPC. Code that imports it still loads, but SuiJsonRpcClient, JsonRpcHTTPTransport and the JSON-RPC error classes throw when constructed, and isSuiJsonRpcClient returns false. Its types, such as ObjectOwner, are deprecated aliases of any. Follow Migrating from JSON-RPC, and use the SuiClientTypes equivalents from @mysten/sui/client for the types.
  • getJsonRpcFullnodeUrl throws. Pass the full node URL (for example https://fullnode.mainnet.sui.io:443) to SuiGrpcClient's baseUrl.
  • normalizedTypeToMoveTypeSignature is removed. getMoveFunction already returns OpenSignatures.
  • Untyped pure values are no longer supported. SuiJsonRpcClient serialized UnresolvedPure inputs, such as raw Move call arguments in v1 transaction JSON restored with Transaction.from, from the Move function signature; SuiGrpcClient and SuiGraphQLClient reject them. Pass typed values such as tx.pure.u64(...) instead.

Core API

  • listDynamicFields pagination loops may need a type annotation. If a loop that passes the cursor back in fails with TS7022, annotate the page as SuiClientTypes.ListDynamicFieldsResponse.
  • On SuiGrpcClient, listDynamicFields with include: { value: true } returns a dynamic object field's child object as its value, matching SuiGraphQLClient: value.bcs is the child object's BCS contents instead of its ID. Read the child's ID from childId.
  • On SuiGraphQLClient, an empty last page of listTransactions or listEvents has null cursors, as on SuiGrpcClient. When polling, keep your previous cursor (cursor = page.endCursor ?? cursor).
  • On SuiGraphQLClient, a transaction's events take packageId and module from the Move call that emitted the event, as listEvents and SuiGrpcClient do, rather than from the event type.

Transaction data and BCS

  • Transaction data (include: { transaction: true }) has a kind. Inputs and commands carry $kind, so narrow with input.$kind === 'Pure' rather than 'Pure' in input. Decode transaction bytes into this type with parseTransactionBcs. See transaction data. It is no longer the builder's serialized type, so to rebuild a Transaction from a query result, request include: { bcs: true } and pass the result's bcs to Transaction.from.
  • bcs.Owner has a Party variant, and bcs.MoveObjectType's AccumulatorBalanceWrapper is renamed to SuiBalanceAccumulatorField.
  • System transaction kinds decoded with bcs.TransactionKind use named fields instead of tuples, and authenticatorObjInitialSharedVersion and randomnessObjInitialSharedVersion are renamed to authenticatorObjectInitialSharedVersion and randomnessObjectInitialSharedVersion.
  • SuiClientTypes.MoveLocation.function (the function index) is removed. Use location.functionName.
  • bcs.TransactionEffects tuples are structs with named fields, for example changedObjects entries ({ objectId, inputState, outputState, idOperation }), IntegerTuple ({ first, second }) and V1 modifiedAtVersions entries ({ objectId, version }). InsufficientBalanceForWithdraw is renamed to InsufficientFundsForWithdraw and congested_objects to congestedObjects. The encoded bytes are unchanged.
  • Multisig BCS fields are camelCase: multisigPk instead of multisig_pk and pkMap instead of pk_map. The old names still work on parseSerializedSignature results but are deprecated.
  • Execution error names in effects.status match SuiGrpcClient everywhere, including SuiGraphQLClient and dApp Kit wallet results: InvalidBcsBytes, InvalidUsageOfPureArgument, ConsensusObjectOperationNotAllowed and PackageIdDoesNotMatch replace InvalidBCSBytes, InvalidUsageOfPureArg, SharedObjectOperationNotAllowed and PackageIDDoesNotMatch.
  • parseGrpcTransactionResponse needs transaction.sender in the read mask.
  • Building or serializing a transaction that calls 0x2::address_alias throws. Pass restrictedMoveCalls: [] to the client constructor, or to build or toJSON, to allow it. See Restricted Move calls.

Transports

  • gRPC-web uses the binary format by default. If a proxy in front of your full node only supports application/grpc-web-text, pass format: 'text'.
  • Client URLs are checked at construction. A GraphQL url or gRPC baseUrl that is neither an absolute http(s) URL nor a path starting with / throws when the client is created.
  • Network errors changed. SuiGrpcClient reports UNAVAILABLE instead of INTERNAL, and SuiGraphQLClient throws SuiGraphQLRequestError, with the original error as cause, for network failures and malformed or unreadable bodies.
  • The raw gRPC GetPackageRequest type requires a selector. Existing client.movePackageService.getPackage({ packageId }) calls still work at runtime. To satisfy the type, pass selector: { oneofKind: undefined } or build the request with GrpcTypes.GetPackageRequest.create({ packageId }).

Signature verification

  • verifyPersonalMessageSignature, verifyTransactionSignature, isValidPersonalMessageSignature and isValidTransactionSignature require a client or offline: true. Without either it's a type error; at runtime they verify offline and log a warning. With a client, the node verifies the signature and checks zkLogin signatures; with address, it also accepts the address's address aliases, and throws on nodes that can't check them unless you pass checkAddressAliases: false. With offline: true, zkLogin signatures throw. See Online or offline for which to choose.
  • With a client, the public key the verify helpers return may belong to one of the address's aliases. Use address, not publicKey.toSuiAddress(), as the account's identity.
  • verifyZkLoginSignature accepts signatures from the address's aliases and throws on nodes that can't check address aliases. It's deprecated: use client.core.verifySignature.

Other packages

  • @mysten-incubation/sponsor's userSignatureMatchesSender verifies on the node, and fails with ANALYSIS_FAILED if the node can't be reached.
  • @mysten/wallet-sdk's restrictedMoveCalls and @mysten-incubation/sponsor's noRestrictedMoveCalls take { restrictedMoveCalls } (package, package::module or package::module::function entries) instead of addressAliases and targets, and throw on any other option. The list replaces the default, so keep '0x2::address_alias' in it to keep flagging alias changes. Results no longer have a level, and matchedBy is a single entry instead of an array.
  • @mysten/wallet-standard and @mysten/kiosk no longer use JSON-RPC types. Import legacy response types from the SuiJsonRpcTypes namespace in @mysten/wallet-standard. TransferPolicy.owner in @mysten/kiosk is a SuiClientTypes.ObjectOwner.

Wallets that still implement the deprecated sui:signAndExecuteTransactionBlock feature can build its legacy response from a gRPC or GraphQL execution with @mysten/wallet-sdk/json-rpc-compat:

import {
	mappableIncludeFor,
	transactionBlockResponseFromExecution,
} from '@mysten/wallet-sdk/json-rpc-compat';

// `input` is the dApp's `sui:signAndExecuteTransactionBlock` input; `bytes` (a `Uint8Array`) and
// `signature` are what the wallet signed.
const result = await client.core.executeTransaction({
	transaction: bytes,
	signatures: [signature],
	include: mappableIncludeFor(input.options),
});

return transactionBlockResponseFromExecution(result.Transaction ?? result.FailedTransaction, {
	bytes,
	signatures: [signature],
	options: input.options,
});

For wallet code that still reads the JSON-RPC dry-run shape, dryRunFromSimulation builds a DryRunTransactionBlockResponse from the simulated transaction (result.Transaction ?? result.FailedTransaction) of a simulateTransaction call made with include: { balanceChanges: true, effects: true, events: true, objectTypes: true, transaction: true }.

Dependencies that still require 2.x

You can upgrade before your dependencies release versions for 3.0. How a dependency lists @mysten/sui decides which copy it uses:

  • A regular dependency on 2.x: it installs its own 2.x copy and keeps working on it. Transactions built by its copy skip the restricted Move calls check.
  • A peer dependency on ^2: npm refuses to install it next to 3.0. pnpm and Yarn print a warning and give it your 3.0 copy.

Run npm ls @mysten/sui or pnpm why @mysten/sui to see which copies you have.

Let packages keep their own 2.x copy where you can. Only values that cross between your code and the package are affected:

  • Clients, Transactions and signers from your copy may not type-check where its API expects its own, and fail its instanceof checks on SDK classes. A package that accepts ClientWithCoreApi and doesn't use instanceof on SDK classes accepts them at runtime.
  • A package that calls methods on your 3.0 client gets 3.0 results, with the Core API and transaction data changes above.

If a package needs to use your copy, for example a peer dependency that npm won't install, add an override:

package.json (npm)
{
	"overrides": {
		"@mysten/sui": "$@mysten/sui"
	}
}

$@mysten/sui reuses the version in your own dependencies.

pnpm-workspace.yaml (pnpm 10.5 and later)
overrides:
  '@mysten/sui': '$@mysten/sui'

Earlier pnpm versions ignore overrides in pnpm-workspace.yaml: put the same entry under pnpm.overrides in package.json instead. pnpm resolves $@mysten/sui from the root package.json, so if only a workspace package depends on @mysten/sui, write the range instead, for example ^3.0.0.

package.json (Yarn, Bun)
{
	"resolutions": {
		"@mysten/sui": "^3.0.0"
	}
}

Yarn still prints a peer dependency warning, which you can ignore.

An override applies to every package, so all of them run on 3.0, as does a peer dependency that pnpm or Yarn gives your copy. The breaking changes above affect these packages as they affect your code. Most often, a package that imports @mysten/sui/jsonRpc loads, but throws when it uses JSON-RPC. It needs a release for 3.0; until then, don't add an override, so that a regular dependency keeps its own 2.x copy.

Test the flows that use each dependency, and remove the override once every dependency supports 3.0.

Libraries built on @mysten/sui

If you publish a package that uses @mysten/sui, release a version for 3.0 that:

  • Lists @mysten/sui@^3 in peerDependencies, not dependencies, so apps keep a single copy. See Building SDKs.
  • Doesn't import @mysten/sui/jsonRpc. On 3.0 its classes and getJsonRpcFullnodeUrl throw, and its types are any.
  • Accepts ClientWithCoreApi from @mysten/sui/client instead of a specific client class, and reads through client.core.
  • Doesn't use instanceof on SDK classes, which fails for values from another copy of @mysten/sui. Use isTransaction from @mysten/sui/transactions, isSuiGrpcClient from @mysten/sui/grpc and isSuiGraphQLClient from @mysten/sui/graphql.

New in 3.0

  • listTransactions filters accept affectedAddress and affectedObject, and sender combines with other predicates.
  • listTransactions and listEvents accept startCheckpoint and endCheckpoint, and after and before can be combined to read a window.
  • doGasSelection is available on every client's simulateTransaction.
  • A listCheckpoints method for paging through checkpoints.
  • SuiGraphQLClient.subscribe runs GraphQL subscriptions; subscriptionUrl sets their endpoint.
  • Resumable checkpoint, transaction, and event streams on SuiGrpcClient and SuiGraphQLClient. See Resumable ledger streams.
  • client.core.listDynamicFields({ include: { value: true } }) returns each field's value with the listing, on every client.
  • client.core.verifySignature, which verifies a personal message or transaction signature on the node and checks address aliases, and client.core.getAddressAliases.

On this page