@mysten/docs 0.1.28 → 0.1.29

package/dist/codegen/index.md

@@ -296,8 +296,9 @@ they don't affect serialization. The generated type is a constant rather than a
 This works correctly for parsing onchain data because phantom types don't change the binary layout.
 
 > **Note:** With the default behavior, phantom parameters appear as literals in the type name (for example,
-> `Balance<phantom T>`). These names are useful for debugging but are not valid onchain type tags. If
-> you need valid type names with resolved phantom parameters, enable `includePhantomTypeParameters`.
+> `Balance<phantom T>`). These names are useful for debugging but are not valid onchain type tags. Use
+> the [`typeTag` method](#getting-type-tags) to build valid type tags with the phantom parameters
+> filled in.
 
 ### Including phantom type parameters
 
@@ -372,6 +373,69 @@ async function readCounter(client: ClientWithCoreApi, id: string) {
 > contains a full object envelope with additional metadata that will cause parsing to fail. See the
 > [Core API docs](/sui/clients/core#objectbcs) for details.
 
+### Getting type tags
+
+Generated types build their own type tag strings with the `typeTag` method, so you don't hand-write
+strings like `` `${packageId}::module::Name<${coinType}>` ``. By default the tag uses the package
+the type was generated from — a real address for framework types, or the configured name for a local
+or MVR package:
+
+```typescript
+
+Balance.typeTag({ typeArguments: ['0x2::sui::SUI'] });
+// '0x2::balance::Balance<0x2::sui::SUI>'
+
+Counter.typeTag();
+// '@local-pkg/counter::counter::Counter'
+```
+
+Types with phantom type parameters require `typeArguments`; types without them take none. This is
+enforced at compile time:
+
+```typescript
+Counter.typeTag(); // ok — no type parameters
+Balance.typeTag({ typeArguments: ['0x2::sui::SUI'] }); // ok
+
+// @ts-expect-error — Balance has a phantom parameter, typeArguments is required
+Balance.typeTag();
+```
+
+`typeArguments` is the full positional list, in Move declaration order. Each entry is a type tag
+string, another `typeTag()` result, or a BCS type (its `name` is used):
+
+```typescript
+
+Balance.typeTag({ typeArguments: [bcs.u64()] });
+// '0x2::balance::Balance<u64>'
+```
+
+To override the package identifier — for example, to pin a specific published address — pass
+`package`:
+
+```typescript
+Counter.typeTag({ package: '0xPACKAGE_ID' });
+// '0xPACKAGE_ID::counter::Counter'
+```
+
+### Resolving type tags
+
+For a local or MVR package, `typeTag` returns the configured name (`@local-pkg/counter::…`). That is
+valid in transaction `typeArguments` — it resolves automatically when the transaction is built — but
+query filters and comparisons against onchain data need a resolved, address-only tag.
+`resolveTypeTag` takes the same options as `typeTag` plus a `client`, resolves any names through it,
+and normalizes the result:
+
+```typescript
+const counterType = await Counter.resolveTypeTag({ client });
+// '0x0000…0123::counter::Counter'
+
+const balanceType = await Balance.resolveTypeTag({
+	client,
+	typeArguments: ['0x2::sui::SUI'],
+});
+// '0x0000…0002::balance::Balance<0x0000…0002::sui::SUI>'
+```
+
 ## Client configuration
 
 ### Using with MVR (Move Version Registry)

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

@@ -92,22 +92,26 @@ These JSON-RPC methods have direct replacements in the core API:
 
 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`                                 |
+| JSON-RPC Method                     | gRPC Service Replacement                                         |
+| ----------------------------------- | ---------------------------------------------------------------- |
+| `getCheckpoint`                     | `ledgerService.getCheckpoint`                                    |
+| `getLatestCheckpointSequenceNumber` | `ledgerService.getServiceInfo` (read `checkpointHeight`)         |
+| `getCurrentEpoch`                   | `ledgerService.getEpoch` (omit `epoch` for the current)          |
+| `getLatestSuiSystemState`           | `ledgerService.getEpoch` with `system_state` in the read mask    |
+| `getCommitteeInfo`                  | `ledgerService.getEpoch` with `committee` in the read mask       |
+| `getProtocolConfig`                 | `ledgerService.getEpoch` with `protocol_config` in the read mask |
+| `getCoinMetadata`                   | `stateService.getCoinInfo` (response includes `metadata`)        |
+| `getTotalSupply`                    | `stateService.getCoinInfo` (response includes `treasury`)        |
+| `getNormalizedMoveModule`           | `movePackageService.getPackage` (response includes all modules)  |
+| `getNormalizedMoveModulesByPackage` | `movePackageService.getPackage`                                  |
+| `getNormalizedMoveStruct`           | `movePackageService.getDatatype`                                 |
+| `resolveNameServiceAddress`         | `nameService.lookupName`                                         |
+| `resolveNameServiceNames`           | `nameService.reverseLookupName`                                  |
+
+> **Warning:** `getCheckpoints` and `getEpochs` (paginated listings) have no gRPC equivalent — use the
+> `checkpoints` / `epochs` GraphQL queries instead. `getValidatorsApy` also has no replacement:
+> there is no canonical definition of validator APY, so it must be computed client-side from
+> validator exchange rates (see [Validator APY](#validator-apy) below).
 
 ### Example: using gRPC service clients
 
@@ -118,13 +122,32 @@ const client = new SuiGrpcClient({
 	network: 'mainnet',
 });
 
-// Get checkpoint information
+// Get the latest checkpoint sequence number (replaces getLatestCheckpointSequenceNumber)
+const { response: info } = await client.ledgerService.getServiceInfo({});
+const latestCheckpoint = info.checkpointHeight;
+
+// Get a specific checkpoint by sequence number. `checkpointId` is required (a oneof);
+// the read mask defaults to `sequence_number,digest`, so request more fields as needed.
 const { response } = await client.ledgerService.getCheckpoint({
-	sequenceNumber: 12345n,
+	checkpointId: { oneofKind: 'sequenceNumber', sequenceNumber: latestCheckpoint },
 });
 
-// Get current epoch
-const { response: epoch } = await client.ledgerService.getEpoch({});
+// Get the current epoch (omit `epoch` for the current one). The system state,
+// committee, and protocol config are NOT returned by default — you must request
+// them via the read mask (the default mask is just `epoch`).
+const { response: epoch } = await client.ledgerService.getEpoch({
+	readMask: { paths: ['epoch', 'system_state', 'committee', 'protocol_config'] },
+});
+const systemState = epoch.epoch?.systemState;
+const committee = epoch.epoch?.committee;
+const protocolConfig = epoch.epoch?.protocolConfig;
+
+// Get coin metadata and total supply in one call
+const { response: coinInfo } = await client.stateService.getCoinInfo({
+	coinType: '0x2::sui::SUI',
+});
+const metadata = coinInfo.metadata;
+const totalSupply = coinInfo.treasury?.totalSupply;
 
 // Get Move package information (includes all modules)
 const { response: pkg } = await client.movePackageService.getPackage({
@@ -148,19 +171,21 @@ const { response: address } = await client.nameService.lookupName({
 
 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                        |
+| JSON-RPC Method             | GraphQL Alternative                                       |
+| --------------------------- | --------------------------------------------------------- |
+| `queryTransactionBlocks`    | `transactions` query                                      |
+| `multiGetTransactionBlocks` | `multiGetTransactionEffects` query                        |
+| `queryEvents`               | `events` query                                            |
+| `getCheckpoints`            | `checkpoints` query                                       |
+| `getEpochs`                 | `epochs` query                                            |
+| `getCoinMetadata`           | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
+| `getTotalSupply`            | `coinMetadata` query (or gRPC `stateService.getCoinInfo`) |
+| `getStakes`                 | `address.stakedSuis` query                                |
+| `getStakesByIds`            | `multiGetObjects` query                                   |
+| `tryGetPastObject`          | Historical object queries                                 |
+| `getNetworkMetrics`         | Use indexer                                               |
+| `getAddressMetrics`         | Use indexer                                               |
+| `getMoveCallMetrics`        | Use indexer                                               |
 
 ### Setting up GraphQL client
 
@@ -364,6 +389,24 @@ const result = await graphqlClient.query({
 });
 ```
 
+## Validator APY
+
+There is **no replacement** for `getValidatorsApy`, and one will not be added. There is no canonical
+definition of validator APY — no other chain's core/general-purpose RPCs offer this endpoint — so it
+must be computed client-side from validator staking-pool exchange rates.
+
+The general approach: read each validator's `exchangeRates` (a table of `pool_token_amount` /
+`sui_amount` per epoch) and estimate the annualized rate from the change in exchange rate over the
+trailing epochs. Two concrete reference implementations:
+
+- The `jsonrpc-alt` implementation in
+  [`sui-indexer-alt-jsonrpc`](https://github.com/MystenLabs/sui/blob/31537d4d9235b9f61dc07a3a71b05ed61a2bda7b/crates/sui-indexer-alt-jsonrpc/src/api/governance.rs#L422-L440),
+  which is compact and readable.
+- [This GraphQL approach](https://github.com/MystenLabs/sui/issues/23832#issuecomment-4437791087),
+  which fetches the precursor exchange-rate information in a single query.
+
+Treat whichever formula you adopt as _a_ definition of validator APY, not _the_ definition.
+
 ## Response format differences
 
 The gRPC client uses the core API response format, which differs from JSON-RPC responses. See the

package/dist/sui/plugins.md

@@ -255,4 +255,28 @@ function transferToSender(objects: TransactionObjectInput[]) {
 
 const transaction = new Transaction();
 transaction.add(transferToSender(['0x1234']));
-```
+```
+
+## Copying transactions that use custom intents
+
+`Transaction.from` creates a deep copy of a transaction. Copying is synchronous, so any unresolved
+intents are carried over as-is and resolved later when the copy is built or serialized. To do that,
+the copy needs the intent resolvers, but resolvers are functions and cannot be represented in the
+serialized transaction data.
+
+Built-in intents (such as the `CoinWithBalance` intent added by `tx.coin()`) are re-attached
+automatically. For custom intents, pass the resolvers through the `intentResolvers` option so the
+copy knows how to resolve them:
+
+```typescript
+
+const copy = Transaction.from(transaction, {
+	intentResolvers: {
+		TransferToSender: resolveTransferToSender,
+	},
+});
+```
+
+Without this, `Transaction.from` throws if the transaction still contains unresolved custom intents.
+Alternatively, you can `await transaction.prepareForSerialization()` first to resolve the intents
+before copying, but that requires an async call and (for some intents) a client.

package/dist/sui/transactions/coins-and-balances.md

@@ -240,14 +240,16 @@ for (const coin of objects) {
 Gasless transactions enable peer-to-peer payments of qualified stablecoins to execute without paying
 gas fees in SUI. The sender does not need to hold SUI in their wallet. Gasless transactions are an
 extension of
-[address balances](https://docs.sui.io/guides/developer/digital-assets/address-balances), using
-`send_funds()` with `gas=0` and `gas_budget=0`. See the
-[Sui gasless transactions guide](https://docs.sui.io/guides/developer/transactions/gasless-transactions)
-for full details.
+[address balances](https://docs.sui.io/onchain-finance/asset-custody/address-balances/using-address-balances),
+built around `0x2::balance::send_funds` with `gasPrice = 0` and `gasBudget = 0` on the transaction.
+See the
+[Sui gasless stablecoin transfers guide](https://docs.sui.io/develop/transaction-payment/gasless-stablecoin-transfers)
+for full details, including the current
+[allowlist of eligible stablecoins](https://docs.sui.io/develop/transaction-payment/gasless-stablecoin-transfers#eligible-stablecoins).
 
 Gasless transactions are limited to transactions that send funds as balances for specific
-stablecoins. Using `0x2::balance::send_funds` with `tx.balance()` is the recommended way to build
-gasless transactions with the Typescript SDK.
+allowlisted stablecoins. Using `0x2::balance::send_funds` with `tx.balance()` is the recommended way
+to build gasless transactions with the TypeScript SDK.
 
 ### SDK support (gRPC and GraphQL)
 
@@ -258,16 +260,17 @@ the gas price is set when the transaction is built.
 
 const client = new SuiGrpcClient({ url: 'https://grpc.mainnet.sui.io:443' });
 
+// Mainnet USDC. For the full set of allowlisted gasless stablecoins, see:
+// https://docs.sui.io/develop/transaction-payment/gasless-stablecoin-transfers#eligible-stablecoins
+const USDC = '0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC';
+
 const tx = new Transaction();
 tx.setSender(keypair.toSuiAddress());
 
 tx.moveCall({
 	target: '0x2::balance::send_funds',
-	typeArguments: ['0x...::usdc::USDC'],
-	arguments: [
-		tx.balance({ type: '0x...::usdc::USDC', balance: 1_000_000 }),
-		tx.pure.address(recipient),
-	],
+	typeArguments: [USDC],
+	arguments: [tx.balance({ type: USDC, balance: 1_000_000 }), tx.pure.address(recipient)],
 });
 
 const result = await client.signAndExecuteTransaction({
@@ -277,11 +280,14 @@ const result = await client.signAndExecuteTransaction({
 ```
 
 The JSON-RPC transport does not automatically detect gasless eligibility. You can opt in by setting
-the gas price to zero with `tx.setGasPrice(0)`, but this causes the transaction to fail if it is not
-actually gasless-eligible.
+the gas price to zero with `tx.setGasPrice(0)`, but only after confirming the coin type is on the
+[allowlist](https://docs.sui.io/develop/transaction-payment/gasless-stablecoin-transfers#eligible-stablecoins)
+and the PTB shape is eligible. Otherwise the transaction fails at validation.
 
-> **Warning:** When executing through a wallet (using dapp-kit), you might need to build the transaction first if
-> the wallet itself is still using JSON-RPC to execute transactions.
+> **Warning:** If your wallet builds transactions with gRPC but executes through a different transport (for
+> example, dapp-kit wallets that still execute over JSON-RPC), pass the gRPC client to `build` so
+> the gas price still gets set correctly:
 > 
-> Call `tx.build({ client: grpcClient })` to use your grpc client to set the gas price
-> correctly for your transaction.
+> ```tsx
+> const bytes = await tx.build({ client: grpcClient });
+> ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mysten/docs",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "LLM-friendly documentation for the Sui TypeScript SDK ecosystem",
   "license": "Apache-2.0",
   "repository": {
@@ -18,50 +18,50 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.90.16",
+    "@tanstack/react-query": "^5.101.0",
     "fast-glob": "^3.3.3",
-    "fumadocs-core": "16.4.7",
-    "fumadocs-docgen": "^3.0.5",
-    "fumadocs-mdx": "14.2.5",
-    "fumadocs-typescript": "^5.2.0",
-    "fumadocs-ui": "16.4.7",
-    "next": "^16.2.6",
-    "react": "^19.2.3",
-    "react-dom": "^19.2.3",
-    "@mysten/aws-kms-signer": "0.1.2",
-    "@mysten/bcs": "2.0.5",
-    "@mysten/dapp-kit": "1.0.6",
-    "@mysten/dapp-kit-core": "1.3.2",
-    "@mysten/dapp-kit-react": "2.0.3",
-    "@mysten/enoki-connect": "1.0.4",
-    "@mysten/enoki": "1.0.8",
-    "@mysten/deepbook-v3": "1.4.1",
-    "@mysten/gcp-kms-signer": "0.1.2",
-    "@mysten/kiosk": "1.2.6",
-    "@mysten/payment-kit": "0.1.11",
-    "@mysten/seal": "1.1.3",
-    "@mysten/slush-wallet": "1.0.5",
-    "@mysten/ledger-signer": "0.1.2",
-    "@mysten/signers": "1.0.5",
-    "@mysten/sui": "2.17.0",
-    "@mysten/utils": "0.3.3",
-    "@mysten/wallet-standard": "0.20.3",
-    "@mysten/walrus": "1.1.7",
-    "@mysten/webcrypto-signer": "0.1.2",
-    "@mysten/zksend": "1.1.2",
-    "@mysten/suins": "1.1.4"
+    "fumadocs-core": "16.10.2",
+    "fumadocs-docgen": "^3.0.10",
+    "fumadocs-mdx": "15.0.12",
+    "fumadocs-typescript": "^5.2.6",
+    "fumadocs-ui": "16.10.2",
+    "next": "^16.2.9",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "@mysten/aws-kms-signer": "0.2.0",
+    "@mysten/bcs": "2.1.0",
+    "@mysten/dapp-kit": "1.1.0",
+    "@mysten/dapp-kit-core": "1.4.0",
+    "@mysten/dapp-kit-react": "2.1.0",
+    "@mysten/deepbook-v3": "1.5.0",
+    "@mysten/enoki": "1.1.0",
+    "@mysten/enoki-connect": "1.1.0",
+    "@mysten/kiosk": "1.3.0",
+    "@mysten/ledger-signer": "0.2.0",
+    "@mysten/payment-kit": "0.2.0",
+    "@mysten/seal": "1.2.0",
+    "@mysten/gcp-kms-signer": "0.2.0",
+    "@mysten/signers": "1.1.0",
+    "@mysten/slush-wallet": "1.1.0",
+    "@mysten/sui": "2.18.0",
+    "@mysten/suins": "1.2.0",
+    "@mysten/wallet-standard": "0.21.0",
+    "@mysten/walrus": "1.2.0",
+    "@mysten/zksend": "1.2.0",
+    "@mysten/utils": "0.4.0",
+    "@mysten/webcrypto-signer": "0.2.0"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.18",
-    "@types/mdx": "^2.0.13",
-    "@types/node": "^25.0.8",
-    "@types/react": "^19.2.8",
+    "@tailwindcss/postcss": "^4.3.1",
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^25.9.3",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "postcss": "^8.5.14",
-    "tailwindcss": "^4.1.18",
-    "typedoc": "^0.28.16",
+    "postcss": ">=8.5.10",
+    "tailwindcss": "^4.3.1",
+    "typedoc": "^0.28.19",
     "typedoc-plugin-mermaid": "^1.12.0",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   },
   "scripts": {
     "build": "typedoc && next build && pnpm run build:docs",