@mysten/sui
Version:
Sui TypeScript API
342 lines (255 loc) • 10.2 kB
Markdown
# /sui
> Migrate /sui from 1.x to 2.0
## Removal of SuiClient Exports
The `/sui/client` export path has been removed. All JSON-RPC client functionality is now
exported from `/sui/jsonRpc`.
**Removed exports:**
- `SuiClient` (use `SuiJsonRpcClient` instead)
- `SuiClientOptions` (use `SuiJsonRpcClientOptions` instead)
- `isSuiClient` (use `isSuiJsonRpcClient` instead)
- `SuiTransport` (use `JsonRpcTransport` instead)
- `SuiTransportRequestOptions` (use `JsonRpcTransportRequestOptions` instead)
- `SuiTransportSubscribeOptions` (use `JsonRpcTransportSubscribeOptions` instead)
- `SuiHTTPTransportOptions` (use `JsonRpcHTTPTransportOptions` instead)
- `SuiHTTPTransport` (use `JsonRpcHTTPTransport` instead)
- `getFullnodeUrl` (use `getJsonRpcFullnodeUrl` instead)
- All JSON-RPC types (now exported from `/sui/jsonRpc`)
**Migration:**
```diff
- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
- const client = new SuiClient({
- url: getFullnodeUrl('devnet'),
+ const client = new SuiJsonRpcClient({
+ url: getJsonRpcFullnodeUrl('devnet'),
network: 'devnet',
});
```
## Network Parameter Required
When creating a new `SuiGraphQLClient` or `SuiJsonRpcClient`, you must now provide a `network`
parameter:
```ts
const client = new SuiGraphQLClient({
url: 'https://...',
network: 'mainnet', // Required
});
const client = new SuiJsonRpcClient({
url: 'https://...',
network: 'mainnet', // Required
});
```
## BCS Schema Changes
Several BCS schemas in `/sui/bcs` have been updated to align exactly with the Rust
implementation. These changes affect serialization and deserialization of transaction effects and
objects.
### ExecutionStatus Changes
**BCS Schema** (when parsing raw effects): The variant was renamed from `Failed` to `Failure`:
```diff
- effects.status.Failed.error
+ effects.status.Failure.error
```
**Core API** (gRPC/GraphQL responses): Uses a simplified structure with a `success` boolean:
```typescript
// Core API returns this structure
const result = await client.core.getTransaction({ digest, include: { effects: true } });
const tx = result.Transaction ?? result.FailedTransaction;
if (tx.effects.status.success) {
// Transaction succeeded
} else {
const error = tx.effects.status.error;
}
```
### Object BCS Schema Changes
Several changes to object BCS schemas:
```diff
// Renamed Owner enum variant
const owner = {
- ConsensusV2: { owner: addr, startVersion: 1 }
+ ConsensusAddressOwner: { startVersion: 1, owner: addr }
};
// Renamed Data enum variant
const data = {
- MoveObject: { ... }
+ Move: { ... }
};
// Renamed exported schema
- import { ObjectBcs } from '/sui/bcs';
+ import { bcs } from '/sui/bcs';
- const bytes = ObjectBcs.serialize(obj);
+ const bytes = bcs.Object.serialize(obj);
```
**This affects serialization.** Any existing serialized data with `ConsensusV2` will need to be
re-serialized with the new `ConsensusAddressOwner` variant.
### UnchangedSharedKind to UnchangedConsensusKind
Transaction effects field renamed:
```diff
// Field name change
- effects.unchangedSharedObjects
+ effects.unchangedConsensusObjects
```
**Removed variants:** `MutateDeleted`, `ReadDeleted`
**New variants:** `MutateConsensusStreamEnded`, `ReadConsensusStreamEnded`, `Cancelled`,
`PerEpochConfig`
## Experimental Client API Stabilization
The experimental client API has been stabilized and moved from `/sui/experimental` to
`/sui/client`. All `Experimental_` prefixes have been removed.
**Breaking changes:**
- The `/sui/experimental` module has been removed
- All `Experimental_` prefixed types and classes have been renamed
- Client types namespace changed from `Experimental_SuiClientTypes` to `SuiClientTypes`
**Migration:**
```diff
- import {
- Experimental_BaseClient,
- Experimental_CoreClient,
- type Experimental_SuiClientTypes,
- type Experimental_CoreClientOptions,
- } from '/sui/experimental';
+ import {
+ BaseClient,
+ CoreClient,
+ type SuiClientTypes,
+ type CoreClientOptions,
+ } from '/sui/client';
// Update class extensions
- class MyClient extends Experimental_CoreClient {
+ class MyClient extends CoreClient {
async getObjects(
- options: Experimental_SuiClientTypes.GetObjectsOptions,
- ): Promise<Experimental_SuiClientTypes.GetObjectsResponse> {
+ options: SuiClientTypes.GetObjectsOptions,
+ ): Promise<SuiClientTypes.GetObjectsResponse> {
// ...
}
}
```
**Common renames:**
| Old Name | New Name |
| -------------------------------- | ------------------- |
| `Experimental_BaseClient` | `BaseClient` |
| `Experimental_CoreClient` | `CoreClient` |
| `Experimental_SuiClientTypes` | `SuiClientTypes` |
| `Experimental_CoreClientOptions` | `CoreClientOptions` |
## Commands Renamed to TransactionCommands
The `Commands` type exported from `/sui/transactions` has been renamed to
`TransactionCommands` because `Commands` is a reserved keyword in React Native.
```diff
- import { Commands } from '@mysten/sui/transactions';
+ import { TransactionCommands } from '@mysten/sui/transactions';
- const coin = tx.add(Commands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
+ const coin = tx.add(TransactionCommands.SplitCoins(tx.gas, [tx.pure.u64(100)]));
- tx.add(Commands.TransferObjects([coin], recipient));
+ tx.add(TransactionCommands.TransferObjects([coin], recipient));
```
## GraphQL Schema Consolidation
The SDK now exports a single unified GraphQL schema instead of multiple versioned schemas.
**Removed exports:**
- `/sui/graphql/schemas/2024.1`
- `/sui/graphql/schemas/2024.4`
- `/sui/graphql/schemas/latest`
**Migration:**
```diff
- import { graphql } from '@mysten/sui/graphql/schemas/latest';
- import { graphql } from '@mysten/sui/graphql/schemas/2024.4';
- import { graphql } from '@mysten/sui/graphql/schemas/2024.1';
+ import { graphql } from '@mysten/sui/graphql/schema';
```
## Named Packages Plugin Removed
The `namedPackagesPlugin` and global plugin registry APIs have been removed. MVR (Move Registry)
resolution is now built directly into the core client.
**Removed:**
- `namedPackagesPlugin` function
- `NamedPackagesPluginOptions` type (from `/sui/transactions`)
- `Transaction.registerGlobalSerializationPlugin()` static method
- `Transaction.unregisterGlobalSerializationPlugin()` static method
- `Transaction.registerGlobalBuildPlugin()` static method
- `Transaction.unregisterGlobalBuildPlugin()` static method
**How it works now:**
MVR name resolution happens automatically during transaction building. The SDK detects `.move` names
(like `/package::module::Type`) and resolves them using the client's MVR resolver.
**Migration:**
```diff
- import { Transaction, namedPackagesPlugin } from '@mysten/sui/transactions';
-
- Transaction.registerGlobalSerializationPlugin(
- 'namedPackages',
- namedPackagesPlugin({
- url: 'https://mainnet.mvr.mystenlabs.com',
- overrides: myOverrides,
- })
- );
+ import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
+ import type { NamedPackagesOverrides } from '@mysten/sui/client';
+
+ const client = new SuiJsonRpcClient({
+ url: 'https://fullnode.mainnet.sui.io:443',
+ network: 'mainnet',
+ mvr: {
+ overrides: myOverrides,
+ },
+ });
```
## Transaction Executors Now Accept Any Client
The transaction executor classes now accept any client implementing `ClientWithCoreApi` instead of
requiring `SuiJsonRpcClient` specifically.
**Affected classes:**
- `CachingTransactionExecutor`
- `SerialTransactionExecutor`
- `ParallelTransactionExecutor`
**Breaking changes:**
- Constructor `client` parameter type changed from `SuiJsonRpcClient` to `ClientWithCoreApi`
- Return type of `executeTransaction()`: `data` property renamed to `result`
- The second parameter changed from JSON-RPC options to core API include options
**Migration:**
```diff
- import { SuiJsonRpcClient } from '@mysten/sui/jsonRpc';
+ // Works with any client: SuiJsonRpcClient, SuiGrpcClient, or SuiGraphQLClient
const executor = new SerialTransactionExecutor({
- client: jsonRpcClient,
+ client, // Any ClientWithCoreApi-compatible client
signer,
});
const result = await executor.executeTransaction(tx);
// Accessing the transaction result (changed)
- console.log(result.data.effects?.status.status);
+ const tx = result.Transaction ?? result.FailedTransaction;
+ console.log(tx.effects.status.success);
```
Include options have also changed:
```diff
- const result = await executor.executeTransaction(tx, {
- showEffects: true,
- showEvents: true,
- });
+ const result = await executor.executeTransaction(tx, {
+ effects: true,
+ events: true,
+ });
```
## ZkLogin Changes
### legacyAddress Parameter Required
The `legacyAddress` parameter is now **required** for all zkLogin address computation functions.
**Migration (to preserve existing behavior):**
```diff
// computeZkLoginAddressFromSeed (previous default: true)
- computeZkLoginAddressFromSeed(seed, iss)
+ computeZkLoginAddressFromSeed(seed, iss, true)
// jwtToAddress (previous default: false)
- jwtToAddress(jwt, userSalt)
+ jwtToAddress(jwt, userSalt, false)
// computeZkLoginAddress (previous default: false)
- computeZkLoginAddress({ claimName, claimValue, iss, aud, userSalt })
+ computeZkLoginAddress({ claimName, claimValue, iss, aud, userSalt, legacyAddress: false })
// toZkLoginPublicIdentifier (no previous default)
- toZkLoginPublicIdentifier(addressSeed, iss)
+ toZkLoginPublicIdentifier(addressSeed, iss, { legacyAddress: false })
```
## Default Transaction Expiration
Transactions now default the expiration to the current epoch + 1 using `ValidDuring` when built with
a client. This provides replay protection for all transactions without requiring explicit
configuration.
**To preserve the old behavior** (no expiration), explicitly set the expiration to `None`:
```typescript
const tx = new Transaction();
tx.setExpiration({ None: true });
```