@mysten/sui 2.6.0 → 2.8.0

package/docs/transaction-building/basics.md

@@ -0,0 +1,297 @@
+# Sui Programmable Transaction Basics
+
+> Construct programmable transaction blocks with the Transaction API
+
+This example starts by constructing a transaction to send SUI. To construct transactions, import the
+`Transaction` class and construct it:
+
+```tsx
+const tx = new Transaction();
+```
+
+You can then add commands to the transaction .
+
+```tsx
+// create a new coin with balance 100, based on the coins used as gas payment
+// you can define any balance here
+const [coin] = tx.splitCoins(tx.gas, [100]);
+
+// transfer the split coin to a specific address
+tx.transferObjects([coin], '0xSomeSuiAddress');
+```
+
+You can attach multiple commands of the same type to a transaction, as well. For example, to get a
+list of transfers and iterate over them to transfer coins to each of them:
+
+```tsx
+interface Transfer {
+	to: string;
+	amount: number;
+}
+
+// procure a list of some Sui transfers to make
+const transfers: Transfer[] = getTransfers();
+
+const tx = new Transaction();
+
+// first, split the gas coin into multiple coins
+const coins = tx.splitCoins(
+	tx.gas,
+	transfers.map((transfer) => transfer.amount),
+);
+
+// next, create a transfer command for each coin
+transfers.forEach((transfer, index) => {
+	tx.transferObjects([coins[index]], transfer.to);
+});
+```
+
+After you have the transaction defined, you can directly execute it with a signer using
+`signAndExecuteTransaction`.
+
+```tsx
+const result = await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
+
+// IMPORTANT: Always check the transaction status
+// Transactions can execute but still fail (e.g., insufficient gas, move errors)
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+```
+
+## Observing the results of a transaction
+
+When you use `client.signAndExecuteTransaction` or `client.executeTransactionBlock`, the transaction
+will be finalized on the blockchain before the function resolves, but the effects of the transaction
+may not be immediately observable.
+
+There are 2 ways to observe the results of a transaction. Methods like
+`client.signAndExecuteTransaction` accept an `options` object with options like `showObjectChanges`
+and `showBalanceChanges` (see
+[the SuiJsonRpcClient docs for more details](/sui/clients/json-rpc#arguments)). These options will
+cause the request to contain additional details about the effects of the transaction that can be
+immediately displayed to the user, or used for further processing in your application.
+
+The other way effects of transactions can be observed is by querying other RPC methods like
+`client.getBalances` that return objects or balances owned by a specific address. These RPC calls
+depend on the RPC node having indexed the effects of the transaction, which may not have happened
+immediately after a transaction has been executed. To ensure that effects of a transaction are
+represented in future RPC calls, you can use the `waitForTransaction` method on the client:
+
+```typescript
+const result = await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
+
+// Check transaction status
+if (result.$kind === 'FailedTransaction') {
+	throw new Error(`Transaction failed: ${result.FailedTransaction.status.error?.message}`);
+}
+
+await client.waitForTransaction({ result });
+```
+
+Once `waitForTransaction` resolves, any future RPC calls will be guaranteed to reflect the effects
+of the transaction.
+
+## Transactions
+
+Programmable Transactions have two key concepts: inputs and commands.
+
+Commands are steps of execution in the transaction. Each command in a Transaction takes a set of
+inputs, and produces results. The inputs for a transaction depend on the kind of command. Sui
+supports following commands:
+
+- `tx.splitCoins(coin, amounts)` - Creates new coins with the defined amounts, split from the
+  provided coin. Returns the coins so that it can be used in subsequent transactions.
+  - Example: `tx.splitCoins(tx.gas, [100, 200])`
+- `tx.mergeCoins(destinationCoin, sourceCoins)` - Merges the sourceCoins into the destinationCoin.
+  - Example: `tx.mergeCoins(tx.object(coin1), [tx.object(coin2), tx.object(coin3)])`
+- `tx.transferObjects(objects, address)` - Transfers a list of objects to the specified address.
+  - Example: `tx.transferObjects([tx.object(thing1), tx.object(thing2)], myAddress)`
+- `tx.moveCall({ target, arguments, typeArguments  })` - Executes a Move call. Returns whatever the
+  Sui Move call returns.
+  - Example:
+    `tx.moveCall({ target: '0x2::devnet_nft::mint', arguments: [tx.pure.string(name), tx.pure.string(description), tx.pure.string(image)] })`
+- `tx.makeMoveVec({ type, elements })` - Constructs a vector of objects that can be passed into a
+  `moveCall`. This is required as there’s no way to define a vector as an input.
+  - Example: `tx.makeMoveVec({ elements: [tx.object(id1), tx.object(id2)] })`
+- `tx.publish(modules, dependencies)` - Publishes a Move package. Returns the upgrade capability
+  object.
+
+## Passing inputs to a command
+
+Command inputs can be provided in a number of different ways, depending on the command, and the type
+of value being provided.
+
+#### JavaScript values
+
+For specific command arguments (`amounts` in `splitCoins`, and `address` in `transferObjects`) the
+expected type is known ahead of time, and you can directly pass raw javascript values when calling
+the command method. appropriate Move type automatically.
+
+```ts
+// the amount to split off the gas coin is provided as a pure javascript number
+const [coin] = tx.splitCoins(tx.gas, [100]);
+// the address for the transfer is provided as a pure javascript string
+tx.transferObjects([coin], '0xSomeSuiAddress');
+```
+
+#### Pure values
+
+When providing inputs that are not on chain objects, the values must be serialized as
+
+[BCS](https://sdk.mystenlabs.com/bcs), which can be done using `tx.pure` eg,
+`tx.pure.address(address)` or `tx.pure(bcs.vector(bcs.U8).serialize(bytes))`.
+
+`tx.pure` can be called as a function that accepts a SerializedBcs object, or as a namespace that
+contains functions for each of the supported types.
+
+```ts
+const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(100)]);
+const [coin] = tx.splitCoins(tx.gas, [tx.pure(bcs.U64.serialize(100))]);
+tx.transferObjects([coin], tx.pure.address('0xSomeSuiAddress'));
+tx.transferObjects([coin], tx.pure(bcs.Address.serialize('0xSomeSuiAddress')));
+```
+
+To pass `vector` or `option` types, you can pass use the corresponding methods on `tx.pure`, use
+tx.pure as a function with a type argument, or serialize the value before passing it to tx.pure
+using the bcs sdk:
+
+```ts
+tx.moveCall({
+	target: '0x2::foo::bar',
+	arguments: [
+		// using vector and option methods
+		tx.pure.vector('u8', [1, 2, 3]),
+		tx.pure.option('u8', 1),
+		tx.pure.option('u8', null),
+
+		// Using pure with type arguments
+		tx.pure('vector<u8>', [1, 2, 3]),
+		tx.pure('option<u8>', 1),
+		tx.pure('option<u8>', null),
+		tx.pure('vector<option<u8>>', [1, null, 2]),
+
+		// Using bcs.serialize
+		tx.pure(bcs.vector(bcs.U8).serialize([1, 2, 3])),
+		tx.pure(bcs.option(bcs.U8).serialize(1)),
+		tx.pure(bcs.option(bcs.U8).serialize(null)),
+		tx.pure(bcs.vector(bcs.option(bcs.U8)).serialize([1, null, 2])),
+	],
+});
+```
+
+#### Object references
+
+To use an on chain object as a transaction input, you must pass a reference to that object. This can
+be done by calling `tx.object` with the object id. Transaction arguments that only accept objects
+(like `objects` in `transferObjects`) will automatically treat any provided strings as objects ids.
+For methods like `moveCall` that accept both objects and other types, you must explicitly call
+`tx.object` to convert the id to an object reference.
+
+```ts
+// Object IDs can be passed to some methods like (transferObjects) directly
+tx.transferObjects(['0xSomeObject'], 'OxSomeAddress');
+// tx.object can be used anywhere an object is accepted
+tx.transferObjects([tx.object('0xSomeObject')], 'OxSomeAddress');
+
+tx.moveCall({
+	target: '0x2::nft::mint',
+	// object IDs must be wrapped in moveCall arguments
+	arguments: [tx.object('0xSomeObject')],
+});
+
+// tx.object automatically converts the object ID to receiving transaction arguments if the moveCall expects it
+tx.moveCall({
+	target: '0xSomeAddress::example::receive_object',
+	// 0xSomeAddress::example::receive_object expects a receiving argument and has a Move definition that looks like this:
+	// public fun receive_object<T: key>(parent_object: &mut ParentObjectType, receiving_object: Receiving<ChildObjectType>) { ... }
+	arguments: [tx.object('0xParentObjectID'), tx.object('0xReceivingObjectID')],
+});
+```
+
+When building a transaction, Sui expects all objects to be fully resolved, including the object
+version. The SDK automatically looks up the current version of objects for any provided object
+reference when building a transaction. If the object reference is used as a receiving argument to a
+`moveCall`, the object reference is automatically converted to a receiving transaction argument.
+This greatly simplifies building transactions, but requires additional RPC calls. You can optimize
+this process by providing a fully resolved object reference instead:
+
+```ts
+// for owned or immutable objects
+tx.object(Inputs.ObjectRef({ digest, objectId, version }));
+
+// for shared objects
+tx.object(Inputs.SharedObjectRef({ objectId, initialSharedVersion, mutable }));
+
+// for receiving objects
+tx.object(Inputs.ReceivingRef({ digest, objectId, version }));
+```
+
+##### Object helpers
+
+There are a handful of specific object types that can be referenced through helper methods on
+tx.object:
+
+```ts
+tx.object.system(),
+tx.object.clock(),
+tx.object.random(),
+tx.object.denyList(),
+
+tx.object.option({
+	type: '0x123::example::Thing',
+	// value can be an Object ID, or any other object reference, or null for `none`
+	value: '0x456',
+}),
+```
+
+#### Transaction results
+
+You can also use the result of a command as an argument in a subsequent commands. Each method on the
+transaction builder returns a reference to the transaction result.
+
+```tsx
+// split a coin object off of the gas object
+const [coin] = tx.splitCoins(tx.gas, [100]);
+// transfer the resulting coin object
+tx.transferObjects([coin], address);
+```
+
+When a command returns multiple results, you can access the result at a specific index either using
+destructuring, or array indexes.
+
+```tsx
+// destructuring (preferred, as it gives you logical local names)
+const [nft1, nft2] = tx.moveCall({ target: '0x2::nft::mint_many' });
+tx.transferObjects([nft1, nft2], address);
+
+// array indexes
+const mintMany = tx.moveCall({ target: '0x2::nft::mint_many' });
+tx.transferObjects([mintMany[0], mintMany[1]], address);
+```
+
+## Get transaction bytes
+
+If you need the transaction bytes, instead of signing or executing the transaction, you can use the
+`build` method on the transaction builder itself.
+
+**Important:** You might need to explicitly call `setSender()` on the transaction to ensure that the
+`sender` field is populated. This is normally done by the signer before signing the transaction, but
+will not be done automatically if you’re building the transaction bytes yourself.
+
+```tsx
+const tx = new Transaction();
+
+// ... add some transactions...
+
+await tx.build({ client });
+```
+
+In most cases, building requires your SuiJsonRpcClient to fully resolve input values.
+
+If you have transaction bytes, you can also convert them back into a `Transaction` class:
+
+```tsx
+const bytes = getTransactionBytesFromSomewhere();
+const tx = Transaction.from(bytes);
+```

package/docs/transaction-building/gas.md

@@ -0,0 +1,62 @@
+# Paying for Sui Transactions with Gas Coins
+
+> Configure gas budget, price, and coin selection for transactions
+
+With Programmable Transactions, you can use the gas payment coin to construct coins with a set
+balance using `splitCoin`. This is useful for Sui payments, and avoids the need for up-front coin
+selection. You can use `tx.gas` to access the gas coin in a transaction, and it is valid as input
+for any arguments, as long as it is used
+[by-reference](https://docs.sui.io/guides/developer/sui-101/simulating-refs). Practically speaking,
+this means you can also add to the gas coin with `mergeCoins` and borrow it for Move functions with
+`moveCall`.
+
+You can also transfer the gas coin using `transferObjects`, in the event that you want to transfer
+all of your coin balance to another address.
+
+## Gas configuration
+
+The new transaction builder comes with default behavior for all gas logic, including automatically
+setting the gas price, budget, and selecting coins to be used as gas. This behavior can be
+customized.
+
+### Gas price
+
+By default, the gas price is set to the reference gas price of the network. You can also explicitly
+set the gas price of the transaction by calling `setGasPrice` on the transaction builder.
+
+```tsx
+tx.setGasPrice(gasPrice);
+```
+
+### Budget
+
+By default, the gas budget is automatically derived by executing a dry-run of the transaction
+beforehand. The dry run gas consumption is then used to determine a balance for the transaction. You
+can override this behavior by explicitly setting a gas budget for the transaction, by calling
+`setGasBudget` on the transaction builder.
+
+**Note:** The gas budget is represented in Sui, and should take the gas price of the transaction
+into account.
+
+```tsx
+tx.setGasBudget(gasBudgetAmount);
+```
+
+### Gas payment
+
+By default, the gas payment is automatically determined by the SDK. The SDK selects all of the users
+coins that are not used as inputs in the transaction.
+
+The list of coins used as gas payment will be merged down into a single gas coin before executing
+the transaction, and all but one of the gas objects will be deleted. The gas coin at the 0-index
+will be the coin that all others are merged into.
+
+```tsx
+// you need to ensure that the coins do not overlap with any
+// of the input objects for the transaction
+tx.setGasPayment([coin1, coin2]);
+```
+
+Gas coins should be objects containing the coins objectId, version, and digest.
+
+<auto-type-table type="{ objectId: string, version: string | number, digest: string }" />

package/docs/transaction-building/intents.md

@@ -0,0 +1,61 @@
+# Transaction Intents
+
+> Use high-level intents to simplify transaction building
+
+Transaction Intents enable 3rd party SDKs and [Transaction Plugins](../plugins) to more easily add
+complex operations to a Transaction. The Typescript SDK currently only includes a single Intent
+(CoinWithBalance), but more will be added in the future.
+
+## The CoinWithBalance intent
+
+The `CoinWithBalance` intent makes it easy to get a coin with a specific balance. For SUI, this has
+generally been done by splitting the gas coin:
+
+```typescript
+const tx = new Transaction();
+
+const [coin] = tx.splitCoins(tx.gas, [100]);
+
+tx.transferObjects([coin], recipient);
+```
+
+This approach works well for SUI, but can't be used for other coin types. The CoinWithBalance intent
+solves this by providing a helper function that automatically adds the correct SplitCoins and
+MergeCoins commands to the transaction:
+
+```typescript
+const tx = new Transaction();
+
+// Setting the sender is required for the CoinWithBalance intent to resolve coins when not using the gas coin
+tx.setSender(keypair.toSuiAddress());
+
+tx.transferObjects(
+	[
+		// Create a SUI coin (balance is in MIST)
+		coinWithBalance({ balance: 100 }),
+		// Create a coin of another type
+		coinWithBalance({ balance: 100, type: '0x123::foo:Bar' }),
+	],
+	recipient,
+);
+```
+
+Splitting the gas coin also causes problems for sponsored transactions. When sponsoring
+transactions, the gas coin comes from the sponsor instead of the transaction sender. Transaction
+sponsors usually do not sponsor transactions that use the gas coin for anything other than gas. To
+transfer SUI that does not use the gas coin, you can set the `useGasCoin` option to `false`:
+
+```typescript
+const tx = new Transaction();
+tx.transferObjects([coinWithBalance({ balance: 100, useGasCoin: false })], recipient);
+```
+
+It's important to only set `useGasCoin` option to false for sponsored transactions, otherwise the
+coinWithBalance intent may use all the SUI coins, leaving no coins to use for gas.
+
+## How it works
+
+When the `CoinWithBalance` intent is resolved, it will look up the senders owned coins for each type
+that needs to be created. It will then find a set of coins with sufficient balance to cover the
+desired balance, to combine them into a single coin. This coin is then used in a `SplitCoins`
+command to create the desired coin.

package/docs/transaction-building/offline.md

@@ -0,0 +1,71 @@
+# Building Offline
+
+> Build transactions without a network connection
+
+To build a transaction offline (with no `client` required), you need to fully define all of your
+inputs, gas configuration, and expiration.
+
+## Required Configuration
+
+When building offline, you must set the following:
+
+- **Sender address** - The address that will execute the transaction
+- **Gas price** - The price per gas unit (can be obtained from the network beforehand)
+- **Gas budget** - The maximum gas to spend on this transaction
+- **Gas payment** - One or more coin object references to use for gas, or an empty array for Address
+  Balances
+- **Expiration** - Only needed when using address balances for gas
+
+```tsx
+const { referenceGasPrice } = await client.getReferenceGasPrice();
+
+const tx = new Transaction();
+
+tx.setSender('0x<your-address>');
+tx.setGasPrice(referenceGasPrice);
+tx.setGasBudget(50_000_000);
+tx.setGasPayment([
+	{
+		objectId: '0x<gas-coin-object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	},
+]);
+
+// Build the transaction without a client
+const bytes = await tx.build();
+```
+
+## Object References
+
+For objects used in your transaction, you must provide full object references using the `Inputs`
+helper:
+
+```tsx
+// For owned or immutable objects
+tx.object(
+	Inputs.ObjectRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+
+// For shared objects
+tx.object(
+	Inputs.SharedObjectRef({
+		objectId: '0x<object-id>',
+		initialSharedVersion: '<initial-shared-version>',
+		mutable: true,
+	}),
+);
+
+// For receiving objects (objects being received by another object)
+tx.object(
+	Inputs.ReceivingRef({
+		objectId: '0x<object-id>',
+		version: '<object-version>',
+		digest: '<object-digest>',
+	}),
+);
+```

package/docs/transaction-building/sponsored-transactions.md

@@ -0,0 +1,22 @@
+# Sponsored Transactions
+
+> Pay gas fees on behalf of other users with sponsored transactions
+
+The transaction builder can support sponsored transactions by using the `onlyTransactionKind` flag
+when building the transaction.
+
+```tsx
+const tx = new Transaction();
+
+// ... add some transactions...
+
+const kindBytes = await tx.build({ provider, onlyTransactionKind: true });
+
+// construct a sponsored transaction from the kind bytes
+const sponsoredtx = Transaction.fromKind(kindBytes);
+
+// you can now set the sponsored transaction data that is required
+sponsoredtx.setSender(sender);
+sponsoredtx.setGasOwner(sponsor);
+sponsoredtx.setGasPayment(sponsorCoins);
+```

package/docs/utils/derived_objects.md

@@ -0,0 +1,59 @@
+# Derived Objects
+
+> Compute derived object IDs from parent objects
+
+Derived objects enable deterministic IDs for objects, enabling offline derivation of object IDs.
+[Click here to read more.](https://docs.sui.io/concepts/sui-move-concepts/derived-objects)
+
+To derive an object ID, you can import `deriveObjectID` function exposed from utils.
+
+```typescript
+
+```
+
+To derive any object, you need to have its parent's ID (the object from which it was derived), and
+the key used to generate it.
+
+> **Warning:** It is recommended to verify the on-chain `derived_object::derive_address` match your
+> off-chain calculation (at least once when implementing offline calculations), especially for
+> critical cases like transferring assets.
+
+## Deriving using primitive keys
+
+To derive the IDs using primitive types, you can use the built-in types like this, assuming you have
+a parent object with ID `0xc0ffee`.
+
+```typescript
+// Example 1: On-chain derivation for `0xc0ffee + vector<u8>([0,1,2])
+deriveObjectID('0xc0ffee', 'vector<u8>', bcs.vector(bcs.u8()).serialize([0, 1, 2]).toBytes());
+
+// Example 2: On-chain derivation for `0xc0ffee + address('0x111')`
+deriveObjectID('0xc0ffee', 'address', bcs.Address.serialize('0x111').toBytes());
+
+// Example 3: On-chain derivation for `0xc0ffee + non-ascii string ("foo")`
+deriveObjectID('0xc0ffee', '0x1::string::String', bcs.String.serialize('foo').toBytes());
+```
+
+## Deriving using custom types
+
+To derive IDs using your custom objects, you can use BCS & the known type IDs.
+
+Assuming a custom struct on-chain (for the key) being:
+
+```move
+public struct DemoStruct has copy, store, drop { value: u64 }
+```
+
+you can derive it by doing:
+
+```typescript
+// Assuming we wanted to derive for key `DemoStruct { value: 1 }`.
+const bcsType = bcs.struct('DemoStruct', {
+	value: bcs.u64(),
+});
+
+const key = bcsType.serialize({ value: 1 }).toBytes();
+
+// Derive the object ID for the key `DemoStruct { value: 1 }`.
+deriveObjectID('0xc0ffee', `0xc0ffee::demo::DemoStruct`, key);
+```

package/docs/utils/index.md

@@ -0,0 +1,52 @@
+# The `@mysten/sui/utils` package
+
+> Utility functions for addresses, coins, and common operations
+
+This package contains some utilities that simplify common operations when working with the Sui
+TypeScript SDK.
+
+## Constants
+
+A set of constants exported for common uses cases:
+
+- `MIST_PER_SUI`: The conversion rate for MIST to SUI (1,000,000,000)
+- `SUI_DECIMALS`: the number of decimals you must shift a MIST value to convert it to SUI (`9`)
+- `SUI_ADDRESS_LENGTH`: The number of bytes in a Sui address (32)
+- `MOVE_STDLIB_ADDRESS`: The address for the Sui Move standard library
+- `SUI_FRAMEWORK_ADDRESS`: The address for the Sui Framework
+- `SUI_SYSTEM_ADDRESS`: The address for the Sui System module
+- `SUI_CLOCK_OBJECT_ID`: The address for the `sui::clock::Clock` object
+- `SUI_SYSTEM_STATE_OBJECT_ID`: The address for the `SuiSystemState` object
+- `SUI_RANDOM_OBJECT_ID`: The address for the `0x2::random::Random` object
+
+## Formatters
+
+You can use the following helpers to format various values:
+
+- `formatAddress`
+- `formatDigest`
+- `normalizeStructTag`
+- `normalizeSuiAddress`
+- `normalizeSuiObjectId`
+- `normalizeSuiNSName`
+- `normalizeSuiNSName`
+
+## Validators
+
+You can use the following helpers to validate the format of various values (this only validates that
+the value is in the correct format, but does not validate the value is valid for a specific use
+case, or exists on chain).
+
+- `isValidSuiAddress`
+- `isValidSuiObjectId`
+- `isValidTransactionDigest`
+- `isValidSuiNSName`
+
+## Encoding
+
+The following methods are re-exported to help with converting between commonly used encodings
+
+- `fromHex`: Deserializes a hex string to a Uint8Array
+- `toHex`: Serializes a Uint8Array to a hex string
+- `fromBase64`: Deserializes a base64 string to a Uint8Array
+- `toBase64`: Serializes a Uint8Array to a base64 string