@mysten/sui 2.16.3 → 2.18.0

package/docs/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/docs/plugins.md

@@ -148,7 +148,7 @@ Adding an intent is similar to adding any other command to a transaction:
 const transaction = new Transaction();
 
 transaction.add(
-	Commands.Intent({
+	TransactionCommands.Intent({
 		name: 'TransferToSender',
 		inputs: {
 			objects: [transaction.object(someId)],
@@ -166,7 +166,7 @@ current transaction instance. This allows us to create a helper that automatical
 function transferToSender(objects: TransactionObjectInput[]) {
 	return (tx: Transaction) => {
 		tx.add(
-			Commands.Intent({
+			TransactionCommands.Intent({
 				name: 'TransferToSender',
 				inputs: {
 					objects: objects.map((obj) => tx.object(obj)),
@@ -214,7 +214,7 @@ async function resolveTransferToSender(
 
 		// This will replace the intent command with the correct TransferObjects command
 		transactionData.replaceCommand(index, [
-			Commands.TransferObjects(
+			TransactionCommands.TransferObjects(
 				// The inputs for intents are not currently typed, so we need to cast to the correct type here
 				transaction.$Intent.inputs.objects as Extract<
 					TransactionObjectArgument,
@@ -243,7 +243,7 @@ function transferToSender(objects: TransactionObjectInput[]) {
 		// As long as we are adding the same function reference, it will only be added once
 		tx.addIntentResolver('TransferToSender', resolveTransferToSender);
 		tx.add(
-			Commands.Intent({
+			TransactionCommands.Intent({
 				name: 'TransferToSender',
 				inputs: {
 					objects: objects.map((obj) => tx.object(obj)),
@@ -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/docs/transactions/basics.md

@@ -0,0 +1,279 @@
+# Building Transactions
+
+> Construct programmable transaction blocks with the Transaction API
+
+Every interaction with the Sui network goes through a transaction. Sui transactions are a sequence
+of commands called
+[programmable transaction blocks (PTBs)](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks)
+that execute on inputs to produce a result. Commands within a transaction can call Move functions,
+transfer objects, split and merge coins, and more. You can chain the result of one command into a
+subsequent command, composing complex operations in a single transaction.
+
+All commands in a transaction execute atomically. If any command fails, the entire transaction is
+rolled back and none of its effects are applied.
+
+For more information on transaction model, see the
+[Sui documentation on PTBs](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks) and
+[inputs and results](https://docs.sui.io/concepts/transactions/inputs-and-results).
+
+## Creating a transaction
+
+Import the `Transaction` class and create a new instance:
+
+```typescript
+
+const tx = new Transaction();
+```
+
+## Sending SUI
+
+Use `tx.balance()` and `balance::send_funds` to send SUI; this deposits directly into the
+recipient's address balance:
+
+```typescript
+
+const tx = new Transaction();
+
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.balance({ balance: 1n * MIST_PER_SUI }), tx.pure.address('0xRecipientAddress')],
+});
+```
+
+If the recipient needs a `Coin<T>` object, use `tx.coin()` with `transferObjects` instead:
+
+```typescript
+tx.transferObjects([tx.coin({ balance: 1n * MIST_PER_SUI })], '0xRecipientAddress');
+```
+
+Both `tx.balance()` and `tx.coin()` automatically draw from your coin objects and address balances.
+You don't need to manage individual coins yourself. See [Coins and Balances](./coins-and-balances)
+for full details.
+
+## Sending other tokens
+
+For non-SUI tokens, use the same patterns for passing the coin type:
+
+```typescript
+const tx = new Transaction();
+
+// Send to address balance (preferred)
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0xPackageId::module::CoinType'],
+	arguments: [
+		tx.balance({ balance: 1_000_000, type: '0xPackageId::module::CoinType' }),
+		tx.pure.address('0xRecipientAddress'),
+	],
+});
+
+// Or send as a coin object
+tx.transferObjects(
+	[tx.coin({ balance: 1_000_000, type: '0xPackageId::module::CoinType' })],
+	'0xRecipientAddress',
+);
+```
+
+## Calling Move functions
+
+Use `moveCall` to call any function in a published Move package. The Sui framework at `0x2` provides
+many built-in functions you can call directly. For example, to split a coin:
+
+```typescript
+const tx = new Transaction();
+
+const [newCoin] = tx.moveCall({
+	target: '0x2::coin::split',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.object('0xCoinId'), tx.pure.u64(1000)],
+});
+
+tx.transferObjects([newCoin], '0xRecipientAddress');
+```
+
+The `target` format is `packageId::moduleName::functionName`.
+
+To call functions in your own published packages, use the same pattern with your package ID:
+
+```typescript
+tx.moveCall({
+	target: '0xYourPackageId::module::function_name',
+	arguments: [tx.pure.string('hello'), tx.object('0xSomeObjectId')],
+});
+```
+
+### Using codegen for type-safe calls
+
+The [`@mysten/codegen`](/codegen) package generates type-safe TypeScript functions from your Move
+packages. Instead of writing `moveCall` with string targets and manual argument construction, use
+`tx.add()` with generated functions:
+
+```typescript
+
+const tx = new Transaction();
+tx.add(
+	counter.increment({
+		arguments: {
+			counter: '0x123...', // Counter object ID
+		},
+	}),
+);
+```
+
+This gives you IDE autocompletion, compile-time type checking for arguments, and eliminates
+incorrect target strings. See the [codegen documentation](/codegen) for setup instructions.
+
+### Return values
+
+Commands return results that you can use as input to subsequent commands. For example, `splitCoins`
+returns the new coins it creates:
+
+```typescript
+const tx = new Transaction();
+
+// splitCoins returns one result per amount
+const [coin] = tx.splitCoins(tx.gas, [1_000_000]);
+
+// Use that result as input to another command
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+`moveCall` works the same way. When a Move function returns a value, you can capture it and pass it
+to the next command:
+
+```typescript
+const [nft] = tx.moveCall({
+	target: '0xPackageId::nft::mint',
+	arguments: [tx.pure.string('My NFT'), tx.pure.string('Description')],
+});
+
+tx.transferObjects([nft], '0xRecipientAddress');
+```
+
+When a command returns multiple values, destructure or index into the result:
+
+```typescript
+// Destructuring
+const [nft1, nft2] = tx.moveCall({ target: '0xPackageId::nft::mint_pair' });
+
+// Or indexing
+const result = tx.moveCall({ target: '0xPackageId::nft::mint_pair' });
+const firstNft = result[0];
+const secondNft = result[1];
+```
+
+> **Warning:** Always access elements by index or destructuring. Do not use the spread operator (`...result`) or
+> pass results to `Array.from()`, which causes an infinite loop.
+
+### Type arguments
+
+Some Move functions have generic type parameters. Pass them with `typeArguments`:
+
+```typescript
+tx.moveCall({
+	target: '0x2::coin::split',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.object('0xCoinId'), tx.pure.u64(1000)],
+});
+```
+
+## Chaining commands
+
+The result of any command can be used as input to a subsequent command. This is what makes
+transactions **programmable**. You can compose multiple operations into a single atomic transaction:
+
+```typescript
+const tx = new Transaction();
+
+// Mint an NFT
+const [nft] = tx.moveCall({
+	target: '0xPackageId::nft::mint',
+	arguments: [tx.pure.string('My NFT')],
+});
+
+// Set a property on it
+tx.moveCall({
+	target: '0xPackageId::nft::set_description',
+	arguments: [nft, tx.pure.string('A nice NFT')],
+});
+
+// Transfer it to someone
+tx.transferObjects([nft], '0xRecipientAddress');
+```
+
+## Batch transfers
+
+Send tokens to multiple recipients in a single transaction:
+
+```typescript
+
+const transfers = [
+	{ to: '0xAlice', amount: 1_000_000_000 },
+	{ to: '0xBob', amount: 2_000_000_000 },
+	{ to: '0xCarol', amount: 500_000_000 },
+];
+
+const tx = new Transaction();
+
+for (const transfer of transfers) {
+	// Send to address balances (preferred)
+	tx.moveCall({
+		target: '0x2::balance::send_funds',
+		typeArguments: ['0x2::sui::SUI'],
+		arguments: [tx.balance({ balance: transfer.amount }), tx.pure.address(transfer.to)],
+	});
+}
+
+// Or send as coin objects
+for (const transfer of transfers) {
+	tx.transferObjects([tx.coin({ balance: transfer.amount })], transfer.to);
+}
+```
+
+## Composable transaction building with thunks
+
+The `tx.add()` method accepts thunks, which are functions that receive the transaction and add
+commands to it. This enables building reusable, composable transaction pieces:
+
+```typescript
+function mintNft(name: string) {
+	return (tx: Transaction) => {
+		return tx.moveCall({
+			target: '0xPackage::nft::mint',
+			arguments: [tx.pure.string(name)],
+		});
+	};
+}
+
+const tx = new Transaction();
+const [nft] = tx.add(mintNft('My NFT'));
+tx.transferObjects([nft], '0xRecipientAddress');
+```
+
+See [SDK Building](/sui/sdk-building) for more information on building composable transaction
+libraries.
+
+## Serializing transactions
+
+Serialize a transaction to JSON for storage, transmission, or later reconstruction:
+
+```typescript
+// Serialize to JSON — with a client, resolves any unresolved data first
+const json = await tx.toJSON({ client: grpcClient });
+
+// Serialize without a client — intents like tx.coin() are preserved as-is
+const json = await tx.toJSON();
+
+// Reconstruct from JSON
+const tx = Transaction.from(json);
+```
+
+This is useful for passing transactions between a frontend and backend, or for storing pre-built
+transactions.
+
+## Executing transactions
+
+Once you've built a transaction, see [Signing and Execution](./signing-and-execution) for all the
+ways to sign and submit it, such as keypairs, [`dapp-kit`](/dapp-kit) hooks, sponsored transactions,
+and more.