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/jsonRpcno longer supports JSON-RPC. Code that imports it still loads, butSuiJsonRpcClient,JsonRpcHTTPTransportand the JSON-RPC error classes throw when constructed, andisSuiJsonRpcClientreturnsfalse. Its types, such asObjectOwner, are deprecated aliases ofany. Follow Migrating from JSON-RPC, and use theSuiClientTypesequivalents from@mysten/sui/clientfor the types.getJsonRpcFullnodeUrlthrows. Pass the full node URL (for examplehttps://fullnode.mainnet.sui.io:443) toSuiGrpcClient'sbaseUrl.normalizedTypeToMoveTypeSignatureis removed.getMoveFunctionalready returnsOpenSignatures.- Untyped pure values are no longer supported.
SuiJsonRpcClientserializedUnresolvedPureinputs, such as raw Move call arguments in v1 transaction JSON restored withTransaction.from, from the Move function signature;SuiGrpcClientandSuiGraphQLClientreject them. Pass typed values such astx.pure.u64(...)instead.
Core API
listDynamicFieldspagination loops may need a type annotation. If a loop that passes the cursor back in fails withTS7022, annotate the page asSuiClientTypes.ListDynamicFieldsResponse.- On
SuiGrpcClient,listDynamicFieldswithinclude: { value: true }returns a dynamic object field's child object as its value, matchingSuiGraphQLClient:value.bcsis the child object's BCS contents instead of its ID. Read the child's ID fromchildId. - On
SuiGraphQLClient, an empty last page oflistTransactionsorlistEventshasnullcursors, as onSuiGrpcClient. When polling, keep your previous cursor (cursor = page.endCursor ?? cursor). - On
SuiGraphQLClient, a transaction'seventstakepackageIdandmodulefrom the Move call that emitted the event, aslistEventsandSuiGrpcClientdo, rather than from the event type.
Transaction data and BCS
- Transaction data (
include: { transaction: true }) has akind. Inputs and commands carry$kind, so narrow withinput.$kind === 'Pure'rather than'Pure' in input. Decode transaction bytes into this type withparseTransactionBcs. See transaction data. It is no longer the builder's serialized type, so to rebuild aTransactionfrom a query result, requestinclude: { bcs: true }and pass the result'sbcstoTransaction.from. bcs.Ownerhas aPartyvariant, andbcs.MoveObjectType'sAccumulatorBalanceWrapperis renamed toSuiBalanceAccumulatorField.- System transaction kinds decoded with
bcs.TransactionKinduse named fields instead of tuples, andauthenticatorObjInitialSharedVersionandrandomnessObjInitialSharedVersionare renamed toauthenticatorObjectInitialSharedVersionandrandomnessObjectInitialSharedVersion. SuiClientTypes.MoveLocation.function(the function index) is removed. Uselocation.functionName.bcs.TransactionEffectstuples are structs with named fields, for examplechangedObjectsentries ({ objectId, inputState, outputState, idOperation }),IntegerTuple({ first, second }) and V1modifiedAtVersionsentries ({ objectId, version }).InsufficientBalanceForWithdrawis renamed toInsufficientFundsForWithdrawandcongested_objectstocongestedObjects. The encoded bytes are unchanged.- Multisig BCS fields are camelCase:
multisigPkinstead ofmultisig_pkandpkMapinstead ofpk_map. The old names still work onparseSerializedSignatureresults but are deprecated. - Execution error names in
effects.statusmatchSuiGrpcClienteverywhere, includingSuiGraphQLClientand dApp Kit wallet results:InvalidBcsBytes,InvalidUsageOfPureArgument,ConsensusObjectOperationNotAllowedandPackageIdDoesNotMatchreplaceInvalidBCSBytes,InvalidUsageOfPureArg,SharedObjectOperationNotAllowedandPackageIDDoesNotMatch. parseGrpcTransactionResponseneedstransaction.senderin the read mask.- Building or serializing a transaction that calls
0x2::address_aliasthrows. PassrestrictedMoveCalls: []to the client constructor, or tobuildortoJSON, 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, passformat: 'text'. - Client URLs are checked at construction. A GraphQL
urlor gRPCbaseUrlthat is neither an absolute http(s) URL nor a path starting with/throws when the client is created. - Network errors changed.
SuiGrpcClientreportsUNAVAILABLEinstead ofINTERNAL, andSuiGraphQLClientthrowsSuiGraphQLRequestError, with the original error ascause, for network failures and malformed or unreadable bodies. - The raw gRPC
GetPackageRequesttype requires aselector. Existingclient.movePackageService.getPackage({ packageId })calls still work at runtime. To satisfy the type, passselector: { oneofKind: undefined }or build the request withGrpcTypes.GetPackageRequest.create({ packageId }).
Signature verification
verifyPersonalMessageSignature,verifyTransactionSignature,isValidPersonalMessageSignatureandisValidTransactionSignaturerequire aclientoroffline: 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; withaddress, it also accepts the address's address aliases, and throws on nodes that can't check them unless you passcheckAddressAliases: false. Withoffline: 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, notpublicKey.toSuiAddress(), as the account's identity. verifyZkLoginSignatureaccepts signatures from the address's aliases and throws on nodes that can't check address aliases. It's deprecated: useclient.core.verifySignature.
Other packages
@mysten-incubation/sponsor'suserSignatureMatchesSenderverifies on the node, and fails withANALYSIS_FAILEDif the node can't be reached.@mysten/wallet-sdk'srestrictedMoveCallsand@mysten-incubation/sponsor'snoRestrictedMoveCallstake{ restrictedMoveCalls }(package,package::moduleorpackage::module::functionentries) instead ofaddressAliasesandtargets, 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 alevel, andmatchedByis a single entry instead of an array.@mysten/wallet-standardand@mysten/kioskno longer use JSON-RPC types. Import legacy response types from theSuiJsonRpcTypesnamespace in@mysten/wallet-standard.TransferPolicy.ownerin@mysten/kioskis aSuiClientTypes.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 itsinstanceofchecks on SDK classes. A package that acceptsClientWithCoreApiand doesn't useinstanceofon 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:
{
"overrides": {
"@mysten/sui": "$@mysten/sui"
}
}$@mysten/sui reuses the version in your own dependencies.
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.
{
"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@^3inpeerDependencies, notdependencies, so apps keep a single copy. See Building SDKs. - Doesn't import
@mysten/sui/jsonRpc. On 3.0 its classes andgetJsonRpcFullnodeUrlthrow, and its types areany. - Accepts
ClientWithCoreApifrom@mysten/sui/clientinstead of a specific client class, and reads throughclient.core. - Doesn't use
instanceofon SDK classes, which fails for values from another copy of@mysten/sui. UseisTransactionfrom@mysten/sui/transactions,isSuiGrpcClientfrom@mysten/sui/grpcandisSuiGraphQLClientfrom@mysten/sui/graphql.
New in 3.0
listTransactionsfilters acceptaffectedAddressandaffectedObject, andsendercombines with other predicates.listTransactionsandlistEventsacceptstartCheckpointandendCheckpoint, andafterandbeforecan be combined to read a window.doGasSelectionis available on every client'ssimulateTransaction.- A
listCheckpointsmethod for paging through checkpoints. SuiGraphQLClient.subscriberuns GraphQL subscriptions;subscriptionUrlsets their endpoint.- Resumable checkpoint, transaction, and event streams on
SuiGrpcClientandSuiGraphQLClient. 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, andclient.core.getAddressAliases.