@mysten/sui 2.16.1 → 2.16.2

package/docs/migrations/sui-2.0/json-rpc-migration.md

@@ -0,0 +1,408 @@
+# Migrating from JSON-RPC
+
+> Migrate from JSON-RPC to the new Core API using SuiGrpcClient or SuiGraphQLClient.
+
+This guide covers migrating from `SuiJsonRpcClient` to the new client APIs. The JSON-RPC API is
+being deprecated in favor of `SuiGrpcClient` and `SuiGraphQLClient`.
+
+> **Note:** We recommend using `SuiGrpcClient` for most operations and `SuiGraphQLClient` for complex queries
+> like filtering transactions and events.
+
+## Choosing a client
+
+| Client             | Best For                                                        |
+| ------------------ | --------------------------------------------------------------- |
+| `SuiGrpcClient`    | Most operations, SDK integrations, real-time data               |
+| `SuiGraphQLClient` | Complex queries, filtering transactions/events, historical data |
+
+## Quick migration to gRPC
+
+For most use cases, migrate to `SuiGrpcClient`:
+
+```diff
+- import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
++ import { SuiGrpcClient } from '@mysten/sui/grpc';
+
+- const client = new SuiJsonRpcClient({
+-   url: getJsonRpcFullnodeUrl('mainnet'),
+-   network: 'mainnet',
+- });
++ const client = new SuiGrpcClient({
++   baseUrl: 'https://fullnode.mainnet.sui.io:443',
++   network: 'mainnet',
++ });
+```
+
+Both clients use the same full node URLs, so you can use the same endpoint when migrating.
+
+## Core API methods
+
+The gRPC client should work with almost all mysten SDKs as a drop in replacement for the JSON-RPC
+client. When using the client directly, the methods and data returned will not be exactly the same
+as what was available in JSON-RPC.
+
+## Methods replaced by core API
+
+These JSON-RPC methods have direct replacements in the core API:
+
+| JSON-RPC Method              | Core API Replacement                              |
+| ---------------------------- | ------------------------------------------------- |
+| `getCoins`                   | `listCoins`                                       |
+| `getAllCoins`                | `listOwnedObjects` with `type: '0x2::coin::Coin'` |
+| `getAllBalances`             | `listBalances`                                    |
+| `getOwnedObjects`            | `listOwnedObjects`                                |
+| `multiGetObjects`            | `getObjects`                                      |
+| `getDynamicFields`           | `listDynamicFields`                               |
+| `getDynamicFieldObject`      | `getDynamicField`                                 |
+| `devInspectTransactionBlock` | `simulateTransaction` with `checksEnabled: false` |
+| `dryRunTransactionBlock`     | `simulateTransaction`                             |
+| `getNormalizedMoveFunction`  | `getMoveFunction`                                 |
+| `getMoveFunctionArgTypes`    | `getMoveFunction`                                 |
+
+### Example: Migrating devInspectTransactionBlock
+
+```diff
+- const result = await jsonRpcClient.devInspectTransactionBlock({
+-   sender: '0xabc...',
+-   transactionBlock: tx,
+- });
+- const returnValues = result.results?.[0]?.returnValues;
++ const result = await client.core.simulateTransaction({
++   transaction: tx,
++   checksEnabled: false,
++   include: { commandResults: true },
++ });
++ const returnValues = result.commandResults?.[0]?.returnValues;
+```
+
+### Example: Migrating getOwnedObjects
+
+```diff
+- const { data } = await jsonRpcClient.getOwnedObjects({
+-   owner: '0xabc...',
+-   options: { showContent: true },
+- });
++ const { objects } = await grpcClient.listOwnedObjects({
++   owner: '0xabc...',
++   include: { content: true },
++ });
+```
+
+## Methods replaced by gRPC services
+
+These JSON-RPC methods can be replaced by calling gRPC service clients directly:
+
+| JSON-RPC Method                     | gRPC Service Replacement                                        |
+| ----------------------------------- | --------------------------------------------------------------- |
+| `getCheckpoint`                     | `ledgerService.getCheckpoint`                                   |
+| `getCheckpoints`                    | `ledgerService.listCheckpoints`                                 |
+| `getLatestCheckpointSequenceNumber` | `ledgerService.getCheckpoint`                                   |
+| `getEpochs`                         | `ledgerService.listEpochs`                                      |
+| `getCurrentEpoch`                   | `ledgerService.getEpoch`                                        |
+| `getLatestSuiSystemState`           | `ledgerService.getSystemState`                                  |
+| `getCommitteeInfo`                  | `ledgerService.getCommittee`                                    |
+| `getValidatorsApy`                  | `ledgerService.getValidators`                                   |
+| `getProtocolConfig`                 | `ledgerService.getProtocolConfig`                               |
+| `getNormalizedMoveModule`           | `movePackageService.getPackage` (response includes all modules) |
+| `getNormalizedMoveModulesByPackage` | `movePackageService.getPackage`                                 |
+| `getNormalizedMoveStruct`           | `movePackageService.getDatatype`                                |
+| `resolveNameServiceAddress`         | `nameService.lookupName`                                        |
+| `resolveNameServiceNames`           | `nameService.reverseLookupName`                                 |
+
+### Example: using gRPC service clients
+
+```typescript
+
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+	network: 'mainnet',
+});
+
+// Get checkpoint information
+const { response } = await client.ledgerService.getCheckpoint({
+	sequenceNumber: 12345n,
+});
+
+// Get current epoch
+const { response: epoch } = await client.ledgerService.getEpoch({});
+
+// Get Move package information (includes all modules)
+const { response: pkg } = await client.movePackageService.getPackage({
+	packageId: '0x2',
+});
+
+// Get a specific Move datatype (struct or enum)
+const { response: datatype } = await client.movePackageService.getDatatype({
+	packageId: '0x2',
+	moduleName: 'coin',
+	name: 'Coin',
+});
+
+// Resolve SuiNS name
+const { response: address } = await client.nameService.lookupName({
+	name: 'example.sui',
+});
+```
+
+## Methods requiring GraphQL
+
+Some JSON-RPC methods don't have gRPC equivalents and require using `SuiGraphQLClient` instead:
+
+| JSON-RPC Method             | GraphQL Alternative                |
+| --------------------------- | ---------------------------------- |
+| `queryTransactionBlocks`    | `transactions` query               |
+| `multiGetTransactionBlocks` | `multiGetTransactionEffects` query |
+| `queryEvents`               | `events` query                     |
+| `getCoinMetadata`           | `coinMetadata` query               |
+| `getTotalSupply`            | `coinMetadata` query               |
+| `getStakes`                 | `address.stakedSuis` query         |
+| `getStakesByIds`            | `multiGetObjects` query            |
+| `tryGetPastObject`          | Historical object queries          |
+| `getNetworkMetrics`         | Use indexer                        |
+| `getAddressMetrics`         | Use indexer                        |
+| `getMoveCallMetrics`        | Use indexer                        |
+
+### Setting up GraphQL client
+
+```typescript
+
+const graphqlClient = new SuiGraphQLClient({
+	url: 'https://sui-mainnet.mystenlabs.com/graphql',
+	network: 'mainnet',
+});
+```
+
+### Querying transactions
+
+Replace `queryTransactionBlocks` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query QueryTransactions($sender: SuiAddress, $first: Int, $after: String) {
+      transactions(
+        first: $first
+        after: $after
+        filter: { sentAddress: $sender }
+      ) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          digest
+          effects {
+            status
+            epoch { epochId }
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		sender: '0xabc...',
+		first: 10,
+	},
+});
+```
+
+**Available transaction filters:**
+
+- `sentAddress`: Filter by sender address
+- `affectedAddress`: Filter by any address involved in the transaction
+- `affectedObject`: Filter by object ID that was affected
+- `function`: Filter by Move function called (for example, `0x2::coin::transfer`)
+- `kind`: Filter by transaction kind (`SYSTEM` or `PROGRAMMABLE`)
+- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint` - Filter by checkpoint
+
+### Querying events
+
+Replace `queryEvents` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query QueryEvents($type: String, $first: Int, $after: String) {
+      events(
+        first: $first
+        after: $after
+        filter: { type: $type }
+      ) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          transactionModule {
+            package { address }
+            name
+          }
+          sender { address }
+          contents {
+            type { repr }
+            bcs
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		type: '0x2::coin::CoinCreated',
+		first: 10,
+	},
+});
+```
+
+**Available event filters:**
+
+- `type`: Filter by event type (package, package::module, or full type)
+- `module`: Filter by emitting module
+- `sender`: Filter by transaction sender
+- `atCheckpoint` / `beforeCheckpoint` / `afterCheckpoint`: Filter by checkpoint
+
+### Fetching multiple transactions
+
+Replace `multiGetTransactionBlocks` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query MultiGetTransactions($digests: [String!]!) {
+      multiGetTransactionEffects(keys: $digests) {
+        transaction {
+          digest
+          transactionBcs
+        }
+        status
+        epoch { epochId }
+      }
+    }
+  `,
+	variables: {
+		digests: ['digest1', 'digest2', 'digest3'],
+	},
+});
+```
+
+### Querying historical objects
+
+Replace `tryGetPastObject` with a GraphQL query specifying a version:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetObjectAtVersion($id: SuiAddress!, $version: UInt53!) {
+      object(address: $id, version: $version) {
+        address
+        version
+        digest
+        asMoveObject {
+          contents {
+            type { repr }
+            bcs
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		id: '0x123...',
+		version: 42,
+	},
+});
+```
+
+### Querying coin metadata
+
+Replace `getCoinMetadata` and `getTotalSupply` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetCoinMetadata($coinType: String!) {
+      coinMetadata(coinType: $coinType) {
+        name
+        symbol
+        description
+        decimals
+        iconUrl
+        supply
+      }
+    }
+  `,
+	variables: {
+		coinType: '0x2::sui::SUI',
+	},
+});
+```
+
+### Querying staked SUI
+
+Replace `getStakes` with a GraphQL query:
+
+```typescript
+const result = await graphqlClient.query({
+	query: `
+    query GetStakes($owner: SuiAddress!) {
+      address(address: $owner) {
+        stakedSuis {
+          nodes {
+            principal
+            stakeActivationEpoch
+            estimatedReward
+            contents {
+              bcs
+            }
+          }
+        }
+      }
+    }
+  `,
+	variables: {
+		owner: '0xabc...',
+	},
+});
+```
+
+## Response format differences
+
+The gRPC client uses the core API response format, which differs from JSON-RPC responses. See the
+[`@mysten/sui` migration guide](/sui/migrations/sui-2.0/sui#transaction-executors-now-accept-any-client)
+for details on the new response format.
+
+Key differences:
+
+```diff
+// Transaction result access
+- const status = result.effects?.status?.status;
++ const tx = result.Transaction ?? result.FailedTransaction;
++ const status = tx.effects.status.success;
+
+// Include options
+- { showEffects: true, showEvents: true }
++ { effects: true, events: true }
+```
+
+## Client extensions
+
+Client extensions work the same way with both clients:
+
+```typescript
+
+const client = new SuiGrpcClient({
+	baseUrl: 'https://fullnode.mainnet.sui.io:443',
+	network: 'mainnet',
+}).$extend(deepbook({ address: myAddress }), suins());
+
+// Use extended functionality
+await client.deepbook.checkManagerBalance(manager, asset);
+await client.suins.getName('0xabc...');
+```
+
+## See also
+
+- [SuiGrpcClient Documentation](/sui/clients/grpc) - Full gRPC client documentation
+- [SuiGraphQLClient Documentation](/sui/clients/graphql) - GraphQL client documentation
+- [Core API](/sui/clients/core) - Transport-agnostic API methods
+- [gRPC Overview](https://docs.sui.io/concepts/data-access/grpc-overview) - Sui gRPC API
+  documentation

package/docs/migrations/sui-2.0/kiosk.md

@@ -0,0 +1,120 @@
+# @mysten/kiosk
+
+> Migrate @mysten/kiosk to 2.0 with client extension pattern and KioskTransaction.
+
+This package now exports a client extension that integrates with Sui clients.
+
+> **Note:** The Kiosk SDK requires `SuiJsonRpcClient` or `SuiGraphQLClient`. It does not work with
+> `SuiGrpcClient` because it uses event queries that are not available in gRPC.
+
+```diff
+- import { SuiClient, getFullnodeUrl } from '@mysten/sui/client';
+- import { KioskClient, Network } from '@mysten/kiosk';
++ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc'; // or SuiGraphQLClient
++ import { kiosk } from '@mysten/kiosk';
+
+- const suiClient = new SuiClient({ url: getFullnodeUrl('mainnet') });
+- const kioskClient = new KioskClient({
+-   client: suiClient,
+-   network: Network.MAINNET,
+- });
++ const client = new SuiJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('mainnet'),
++   network: 'mainnet',
++ }).$extend(kiosk());
+
+- const ownedKiosks = await kioskClient.getOwnedKiosks({ address: myAddress });
++ const ownedKiosks = await client.kiosk.getOwnedKiosks({ address: myAddress });
+```
+
+## Removed: `transactionBlock` parameter
+
+The deprecated `transactionBlock` parameter has been removed from `KioskTransaction`,
+`TransferPolicyTransaction`, and rule resolving functions. Use `transaction` instead:
+
+```diff
+const kioskTx = new KioskTransaction({
+-  transactionBlock: tx,
++  transaction: tx,
+   kioskClient,
+   cap,
+});
+
+const tpTx = new TransferPolicyTransaction({
+-  transactionBlock: tx,
++  transaction: tx,
+   kioskClient,
+   cap,
+});
+```
+
+## Removed: low-level helper functions
+
+The low-level helper functions have been removed in favor of the `KioskTransaction` and
+`TransferPolicyTransaction` builder classes.
+
+### Kiosk functions
+
+| Removed Function    | Use Instead              |
+| ------------------- | ------------------------ |
+| `createKiosk`       | `kioskTx.create()`       |
+| `shareKiosk`        | `kioskTx.share()`        |
+| `place`             | `kioskTx.place()`        |
+| `lock`              | `kioskTx.lock()`         |
+| `take`              | `kioskTx.take()`         |
+| `list`              | `kioskTx.list()`         |
+| `delist`            | `kioskTx.delist()`       |
+| `placeAndList`      | `kioskTx.placeAndList()` |
+| `purchase`          | `kioskTx.purchase()`     |
+| `withdrawFromKiosk` | `kioskTx.withdraw()`     |
+| `borrowValue`       | `kioskTx.borrow()`       |
+| `returnValue`       | `kioskTx.return()`       |
+
+### Transfer policy functions
+
+| Removed Function                     | Use Instead                                             |
+| ------------------------------------ | ------------------------------------------------------- |
+| `createTransferPolicyWithoutSharing` | `tpTx.create()`                                         |
+| `shareTransferPolicy`                | `tpTx.shareAndTransferCap()`                            |
+| `confirmRequest`                     | Handled automatically by `kioskTx.purchaseAndResolve()` |
+| `removeTransferPolicyRule`           | `tpTx.removeRule()`                                     |
+
+### Personal Kiosk functions
+
+| Removed Function        | Use Instead                                   |
+| ----------------------- | --------------------------------------------- |
+| `convertToPersonalTx`   | `kioskTx.convertToPersonal()`                 |
+| `transferPersonalCapTx` | Handled automatically by `kioskTx.finalize()` |
+
+### Rule attachment functions
+
+| Removed Function            | Use Instead                   |
+| --------------------------- | ----------------------------- |
+| `attachKioskLockRuleTx`     | `tpTx.addLockRule()`          |
+| `attachRoyaltyRuleTx`       | `tpTx.addRoyaltyRule()`       |
+| `attachPersonalKioskRuleTx` | `tpTx.addPersonalKioskRule()` |
+| `attachFloorPriceRuleTx`    | `tpTx.addFloorPriceRule()`    |
+
+## Migration example
+
+```diff
+- import { createKiosk, shareKiosk, placeAndList } from '@mysten/kiosk';
++ import { kiosk, KioskTransaction } from '@mysten/kiosk';
++ import { SuiJsonRpcClient, getJsonRpcFullnodeUrl } from '@mysten/sui/jsonRpc';
+
+- const [kiosk, cap] = createKiosk(tx);
+- shareKiosk(tx, kiosk);
+- placeAndList(tx, itemType, kiosk, cap, item, price);
+
++ const client = new SuiJsonRpcClient({
++   url: getJsonRpcFullnodeUrl('mainnet'),
++   network: 'mainnet',
++ }).$extend(kiosk());
++
++ const kioskTx = new KioskTransaction({ transaction: tx, kioskClient: client.kiosk });
++ kioskTx
++   .create()
++   .placeAndList({ itemType, item, price })
++   .shareAndTransferCap(address)
++   .finalize();
+```

package/docs/migrations/sui-2.0/sdk-maintainers.md

@@ -0,0 +1,90 @@
+# SDK Maintainers
+
+> Migration guide for SDK maintainers and library authors upgrading to 2.0.
+
+# 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](/sui/sdk-building).
+
+## Use `ClientWithCoreApi`
+
+Accept `ClientWithCoreApi` instead of `SuiClient` to support all 3 Sui clients (JSON-RPC, GraphQL,
+gRPC):
+
+```diff
+- import { SuiClient } from '@mysten/sui/client';
++ import type { ClientWithCoreApi } from '@mysten/sui/client';
+
+-   client: SuiClient;
++   client: ClientWithCoreApi;
+}
+```
+
+## Access data through `client.core` methods
+
+All data access methods are namespaced under `client.core`:
+
+```diff
+- 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 });
+```
+
+| v1.x Method                      | v2.0 Method                       |
+| -------------------------------- | --------------------------------- |
+| `client.getObject()`             | `client.core.getObject()`         |
+| `client.getOwnedObjects()`       | `client.core.listOwnedObjects()`  |
+| `client.getDynamicFieldObject()` | `client.core.getDynamicField()`   |
+| `client.getDynamicFields()`      | `client.core.listDynamicFields()` |
+| `client.multiGetObjects()`       | `client.core.getObjects()`        |
+
+See the [Core API documentation](/sui/clients/core) for all available methods.
+
+## Use peer dependencies
+
+Declare `@mysten/*` packages as peer dependencies:
+
+```json
+{
+	"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:
+
+```typescript
+
+	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](/sui/sdk-building#client-extensions) for the complete extension
+pattern.
+
+## Code generation
+
+Use [`@mysten/codegen`](/codegen) to generate type-safe TypeScript bindings from your Move packages.
+See the [codegen documentation](/codegen) for setup instructions.
+
+For complete SDK development patterns including client extensions, transaction thunks, and best
+practices, see the [Building SDKs guide](/sui/sdk-building).

package/docs/migrations/sui-2.0/seal.md

@@ -0,0 +1,14 @@
+# @mysten/seal
+
+> Migrate @mysten/seal to 2.0 with the new registration function pattern.
+
+The deprecated `SealClient.asClientExtension()` static method has been removed. Use the `seal()`
+registration function instead:
+
+```diff
+- import { SealClient } from '@mysten/seal';
++ import { seal } from '@mysten/seal';
+
+- const client = suiClient.$extend(SealClient.asClientExtension());
++ const client = suiClient.$extend(seal());
+```