@mysten/docs 0.1.1

package/dist/sui/migrations/sui-2.0/sui.md

@@ -0,0 +1,341 @@
+# @mysten/sui
+
+> Migrate @mysten/sui from 1.x to 2.0
+
+## Removal of SuiClient Exports
+
+The `@mysten/sui/client` export path has been removed. All JSON-RPC client functionality is now
+exported from `@mysten/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 `@mysten/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 `@mysten/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 '@mysten/sui/bcs';
++ import { bcs } from '@mysten/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 `@mysten/sui/experimental` to
+`@mysten/sui/client`. All `Experimental_` prefixes have been removed.
+
+**Breaking changes:**
+
+- The `@mysten/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 '@mysten/sui/experimental';
++ import {
++   BaseClient,
++   CoreClient,
++   type SuiClientTypes,
++   type CoreClientOptions,
++ } from '@mysten/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 `@mysten/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:**
+
+- `@mysten/sui/graphql/schemas/2024.1`
+- `@mysten/sui/graphql/schemas/2024.4`
+- `@mysten/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 `@mysten/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 `@org/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 });
+```

package/dist/sui/migrations/sui-2.0/suins.md

@@ -0,0 +1,43 @@
+# @mysten/suins
+
+> Migrate @mysten/suins to 2.0
+
+This package now exports a client extension that integrates with Sui clients.
+
+```diff
+- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+- import { SuinsClient } from '@mysten/suins';
++ import { SuiGrpcClient } from '@mysten/sui/grpc'; // or SuiJsonRpcClient, SuiGraphQLClient
++ import { suins } from '@mysten/suins';
+
+- const suiClient = new SuiClient({ url: getFullnodeUrl('mainnet') });
+- const suinsClient = new SuinsClient({
+-   client: suiClient,
+-   network: 'mainnet',
+- });
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.sui.io:443',
++   network: 'mainnet',
++ }).$extend(suins());
+
+- const nameRecord = await suinsClient.getNameRecord('example.sui');
++ const nameRecord = await client.suins.getNameRecord('example.sui');
+```
+
+## Custom Package IDs
+
+For custom deployments or networks other than mainnet/testnet, you can provide custom package info:
+
+```ts
+
+const customPackageInfo: PackageInfo = {
+	packageId: '0x...',
+	packageIdV1: '0x...',
+	// ... other required fields
+};
+
+const client = new SuiGrpcClient({
+	baseUrl: 'http://localhost:9000',
+	network: 'localnet',
+}).$extend(suins({ packageInfo: customPackageInfo }));
+```

package/dist/sui/migrations/sui-2.0/wallet-builders.md

@@ -0,0 +1,66 @@
+# Wallet Builders
+
+> Migration guide for wallet extension developers
+
+This guide covers the breaking changes for wallet builders implementing the
+`@mysten/wallet-standard` interface.
+
+## Key Changes
+
+### Removal of `sui:reportTransactionEffects`
+
+The `sui:reportTransactionEffects` feature has been removed entirely. If your wallet implements this
+feature, remove it.
+
+### New Core API Response Format
+
+The most significant change is how you obtain BCS-encoded effects for the
+`signAndExecuteTransaction` response. The new core API returns effects in a different structure.
+
+## Migrating `signAndExecuteTransaction`
+
+The wallet standard output format hasn't changed - what's different is how you obtain the BCS
+effects when using the new Sui client APIs.
+
+```diff
+#signAndExecuteTransaction: SuiSignAndExecuteTransactionMethod = async ({
+	transaction,
+	signal,
+}) => {
+-	const { bytes, signature } = await Transaction.from(
+-		await transaction.toJSON(),
+-	).sign({ client: suiClient, signer: keypair });
+-
+-	const { rawEffects, digest } = await suiClient.executeTransactionBlock({
+-		signature,
+-		transactionBlock: bytes,
+-		options: { showRawEffects: true },
+-	});
++	const parsedTransaction = Transaction.from(await transaction.toJSON());
++	const bytes = await parsedTransaction.build({ client });
++
++	const result = await this.#keypair.signAndExecuteTransaction({
++		transaction: parsedTransaction,
++		client,
++	});
++
++	const tx = result.Transaction ?? result.FailedTransaction;
+
+	return {
+-		bytes,
+-		signature,
+-		digest,
+-		effects: toBase64(new Uint8Array(rawEffects!)),
++		bytes: toBase64(bytes),
++		signature: tx.signatures[0],
++		digest: tx.digest,
++		effects: toBase64(tx.effects.bcs!),
+	};
+};
+```
+
+Key changes:
+
+- Use `signer.signAndExecuteTransaction()` instead of `suiClient.executeTransactionBlock()`
+- Response is a union type - unwrap with `result.Transaction ?? result.FailedTransaction`
+- BCS effects are in `tx.effects.bcs` (Uint8Array) instead of `rawEffects` (number array)

package/dist/sui/migrations/sui-2.0/walrus.md

@@ -0,0 +1,41 @@
+# @mysten/walrus
+
+> Migrate @mysten/walrus to 2.0
+
+## Breaking Changes
+
+- **Client required**: `WalrusClient` can no longer be created with just an RPC URL. You must pass a
+  Sui client.
+- **Network from client**: The `network` parameter has been removed from `walrus()`. The network is
+  now inferred from the client.
+- **Removed deprecated method**: `WalrusClient.experimental_asClientExtension()` has been removed.
+  Use the `walrus()` function instead.
+
+## Updated Usage
+
+If you were creating `WalrusClient` directly:
+
+```diff
+- import { WalrusClient } from '@mysten/walrus';
++ import { SuiGrpcClient } from '@mysten/sui/grpc'; // or SuiJsonRpcClient, SuiGraphQLClient
++ import { walrus } from '@mysten/walrus';
+
+- const walrusClient = new WalrusClient({
+-   suiRpcUrl: 'https://fullnode.testnet.sui.io:443',
+-   network: 'testnet',
+- });
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.testnet.sui.io:443',
++   network: 'testnet',
++ }).$extend(walrus());
+
+- await walrusClient.getBlob(blobId);
++ await client.walrus.getBlob(blobId);
+```
+
+If you were passing `network` to `walrus()`, remove it:
+
+```diff
+- client.$extend(walrus({ network: 'testnet' }));
++ client.$extend(walrus());
+```

package/dist/sui/migrations/sui-2.0/zksend.md

@@ -0,0 +1,95 @@
+# @mysten/zksend
+
+> Migrate @mysten/zksend to 2.0
+
+This package now exports a client extension that integrates with Sui clients, enabling compatibility
+with gRPC, GraphQL, and JSON RPC transports.
+
+## Breaking Changes
+
+- **Client extension**: The zkSend SDK is now a client extension (`client.$extend(zksend())`)
+- **Non-contract links removed**: Only contract-based links are now supported. The `contract` option
+  no longer accepts `null`
+- **`isContractLink` removed**: The `isContractLink` option has been removed from `ZkSendLink`
+- **`calculateGas` removed**: The `calculateGas` option has been removed from
+  `CreateZkSendLinkOptions`
+- **Data fetching helpers removed**: `getAssetsFromTransaction`, `isOwner`, and `ownedAfterChange`
+  are no longer exported
+
+## Migration
+
+Update your code to use the client extension:
+
+```diff
+- import { ZkSendLinkBuilder, ZkSendLink } from '@mysten/zksend';
++ import { zksend } from '@mysten/zksend';
++ import { SuiGrpcClient } from '@mysten/sui/grpc'; // or SuiJsonRpcClient, SuiGraphQLClient
+
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.testnet.sui.io:443',
++   network: 'testnet',
++ }).$extend(zksend());
+```
+
+### Creating a Link Builder
+
+```diff
+- const builder = new ZkSendLinkBuilder({
+-   client,
+-   sender: address,
+-   network: 'testnet',
+- });
++ const link = client.zksend.linkBuilder({
++   sender: address,
++ });
+```
+
+### Loading a Link
+
+```diff
+- const link = new ZkSendLink({
+-   client,
+-   keypair,
+-   network: 'testnet',
+- });
++ const link = await client.zksend.loadLink({
++   address: linkAddress,
++   // or: keypair: linkKeypair,
++ });
+```
+
+### Loading from URL
+
+```diff
+- const link = await ZkSendLink.fromUrl(url, {
+-   client,
+-   network: 'testnet',
+- });
++ const link = await client.zksend.loadLinkFromUrl(url);
+```
+
+## Complete Example
+
+```ts
+
+// Create client with zkSend extension
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.testnet.sui.io:443',
+	network: 'testnet',
+}).$extend(zksend());
+
+// Create a new link
+const linkBuilder = client.zksend.linkBuilder({
+	sender: myAddress,
+});
+
+// Add assets to the link
+linkBuilder.addSui(1_000_000_000n); // 1 SUI
+
+// Create the transaction
+const { tx, link } = await linkBuilder.build();
+
+// Later, load an existing link
+const existingLink = await client.zksend.loadLinkFromUrl(linkUrl);
+const assets = await existingLink.getAssets();
+```