@mysten/sui 2.16.3 → 2.18.0

package/docs/transactions/reference.md

@@ -0,0 +1,380 @@
+# Commands and Inputs Reference
+
+> Complete reference for transaction commands and input types
+
+A
+[programmable transaction block](https://docs.sui.io/guides/developer/transactions/prog-txn-blocks)
+has two parts: **inputs** (objects and pure values) and **commands** (operations that execute on
+those inputs). This page is a complete reference for all input types and commands available in the
+SDK. For task-oriented guides, see [Building Transactions](./basics).
+
+See also the [Sui documentation on PTB commands](https://docs.sui.io/references/ptb-commands) and
+[inputs and results](https://docs.sui.io/concepts/transactions/inputs-and-results).
+
+## Passing inputs
+
+### Object references
+
+Commands that accept objects (like `splitCoins`, `mergeCoins`, `transferObjects`, and `moveCall`)
+accept any of the following as an object reference:
+
+- **String object ID**:`'0xObjectId'`, SDK looks up version and digest at build time
+- **`tx.object('0xObjectId')`**: Equivalent to a string ID, but explicit
+- **`tx.objectRef({...})`**: Fully-resolved owned or immutable object (no lookup needed)
+- **`tx.sharedObjectRef({...})`**: Fully-resolved shared object (no lookup needed)
+- **`tx.receivingRef({...})`**: Fully-resolved receiving object (no lookup needed)
+- **Transaction result**: The return value of a previous command (for example, from `splitCoins`)
+- **`tx.coin({...})`** or **`coinWithBalance({...})`**: A coin intent resolved at build time
+- **`tx.gas`**: The gas coin (when gas is paid from coin objects)
+
+### JavaScript value shortcuts
+
+For arguments where the expected type is known, you can pass plain JavaScript values. The SDK
+coerces them to the correct Move type automatically.
+
+```typescript
+// amounts in splitCoins are coerced to u64
+tx.splitCoins(tx.gas, [100, 200]);
+
+// addresses in transferObjects are coerced to address
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+### Pure values
+
+For Move primitive types, use `tx.pure` to serialize values as BCS:
+
+```typescript
+tx.pure.u8(255);
+tx.pure.u16(65535);
+tx.pure.u32(4294967295);
+tx.pure.u64(100);
+tx.pure.u128(100n);
+tx.pure.u256(100n);
+tx.pure.bool(true);
+tx.pure.string('hello');
+tx.pure.address('0xSomeAddress');
+tx.pure.id('0xSomeObjectId');
+```
+
+### Vectors and options
+
+```typescript
+// Using type-specific methods
+tx.pure.vector('u8', [1, 2, 3]);
+tx.pure.option('u8', 1);
+tx.pure.option('u8', null); // None
+
+// Using type string syntax
+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]);
+```
+
+### BCS serialization
+
+For complex types, use the BCS library directly:
+
+```typescript
+
+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));
+```
+
+### Address balance withdrawals
+
+> **Warning:** Address balances are currently only available on Devnet and Testnet. They are not yet supported on
+> Mainnet.
+
+Use `tx.withdrawal()` to create an input that withdraws from your address balance:
+
+```typescript
+// Withdraw SUI
+const withdrawal = tx.withdrawal({ amount: 1_000_000_000 });
+
+// Withdraw another coin type
+const withdrawal = tx.withdrawal({ amount: 1_000_000, type: '0xPackageId::module::CoinType' });
+```
+
+See [Coins and Balances](./coins-and-balances#withdrawing-from-address-balance) for usage examples.
+
+### The gas coin
+
+`tx.gas` references the coin used for gas payment. It can be used as an input to commands:
+
+```typescript
+const [coin] = tx.splitCoins(tx.gas, [1_000_000_000]);
+```
+
+> **Warning:** `tx.gas` is not available when gas is paid from address balances. Use `tx.coin()` instead for
+> portable code.
+
+## Object inputs
+
+Objects on Sui have different
+[ownership types](https://docs.sui.io/guides/developer/objects/object-ownership), including
+address-owned, shared, immutable, and object-owned (receiving). Each type requires different
+metadata when used as a transaction input, but the SDK handles most of this automatically.
+
+### tx.object(id)
+
+The simplest way to reference an onchain object. The SDK automatically looks up the object's
+version, digest, and type when the transaction is built:
+
+```typescript
+tx.moveCall({
+	target: '0xPackage::module::function',
+	arguments: [tx.object('0xSomeObjectId')],
+});
+```
+
+Object IDs can also be passed directly to commands that only accept objects:
+
+```typescript
+tx.transferObjects(['0xObjectId1', '0xObjectId2'], '0xRecipient');
+```
+
+When a Move function expects a `Receiving<T>` argument, `tx.object()` automatically converts the
+reference to a receiving input:
+
+```typescript
+tx.moveCall({
+	target: '0xPackage::module::receive',
+	// The SDK detects the function signature expects Receiving<T> and adjusts accordingly
+	arguments: [tx.object('0xParentId'), tx.object('0xReceivingObjectId')],
+});
+```
+
+### Fully-resolved object references
+
+To avoid the SDK's automatic lookup (for [offline building](./offline) or performance), provide the
+full object metadata directly:
+
+```typescript
+// Owned or immutable objects — need exact version and digest
+tx.objectRef({
+	objectId: '0xObjectId',
+	version: '42',
+	digest: 'abc123...',
+});
+
+// Shared objects — need initial shared version (stable, doesn't change)
+tx.sharedObjectRef({
+	objectId: '0xObjectId',
+	initialSharedVersion: '1',
+	mutable: true,
+});
+
+// Receiving objects — need exact version and digest
+tx.receivingRef({
+	objectId: '0xObjectId',
+	version: '42',
+	digest: 'abc123...',
+});
+```
+
+### Shared objects
+
+Shared objects are accessible by any transaction and are sequenced through consensus. When using
+`tx.object()` with a shared object ID, the SDK looks up the required metadata automatically. For
+offline building or performance, use `tx.sharedObjectRef()` with the `initialSharedVersion` (which
+is stable and never changes after the object is shared):
+
+```typescript
+tx.sharedObjectRef({
+	objectId: '0xSharedObjectId',
+	initialSharedVersion: '1',
+	mutable: true, // false for read-only access
+});
+```
+
+### Party objects
+
+Party objects are address-owned but consensus-versioned, with per-address permissions (read, write,
+delete, or transfer). They are referenced the same way as shared objects:
+
+```typescript
+tx.sharedObjectRef({
+	objectId: '0xPartyObjectId',
+	initialSharedVersion: '1',
+	mutable: true,
+});
+```
+
+Key differences from regular owned objects:
+
+- **Enable pipelining**: Multiple in-flight transactions on the same object
+- **No version lookup needed**: `initialSharedVersion` is stable
+- **Cannot be used for gas payment**: Use address balance for gas instead
+
+### Object helpers
+
+Common system objects have shorthand methods. Passing `mutable` skips the SDK's automatic mutability
+lookup:
+
+```typescript
+tx.object.system(); // Sui system state (SDK looks up mutability)
+tx.object.system({ mutable: true }); // Mutable system state (no lookup needed)
+tx.object.system({ mutable: false }); // Immutable system state (no lookup needed)
+tx.object.clock(); // On-chain clock (always immutable)
+tx.object.random(); // Random number generator
+tx.object.denyList(); // Coin deny list (SDK looks up mutability)
+tx.object.denyList({ mutable: true }); // Mutable deny list (no lookup needed)
+```
+
+`tx.object.option` wraps an object as a Move `Option<T>`. This adds a `moveCall` command to the
+transaction that constructs the option value:
+
+```typescript
+// Some — wraps the object in Option::some()
+tx.object.option({
+	type: '0xPackage::module::Thing',
+	value: '0xObjectId',
+});
+
+// None — creates Option::none()
+tx.object.option({
+	type: '0xPackage::module::Thing',
+	value: null,
+});
+```
+
+## Commands
+
+### `splitCoins`
+
+Creates new coins by splitting amounts from an existing coin. Returns one result per amount.
+
+```typescript
+const [coin1, coin2] = tx.splitCoins(coin, [amount1, amount2]);
+```
+
+| Parameter | Type                                               | Description               |
+| --------- | -------------------------------------------------- | ------------------------- |
+| `coin`    | [object reference](#object-references) or `tx.gas` | The coin to split from    |
+| `amounts` | `(number \| bigint \| string)[]`                   | Amounts for each new coin |
+
+### `mergeCoins`
+
+Merges one or more source coins into a destination coin. The source coins are destroyed.
+
+```typescript
+tx.mergeCoins(destinationCoin, [sourceCoin1, sourceCoin2]);
+```
+
+| Parameter     | Type                                     | Description                      |
+| ------------- | ---------------------------------------- | -------------------------------- |
+| `destination` | [object reference](#object-references)   | The coin to merge into           |
+| `sources`     | [object reference](#object-references)[] | Coins to merge (destroyed after) |
+
+### `transferObjects`
+
+Transfers one or more objects to a recipient address.
+
+```typescript
+tx.transferObjects([obj1, obj2], recipientAddress);
+```
+
+| Parameter | Type                                     | Description         |
+| --------- | ---------------------------------------- | ------------------- |
+| `objects` | [object reference](#object-references)[] | Objects to transfer |
+| `address` | `string`                                 | Recipient address   |
+
+### `moveCall`
+
+Calls a function in a published Move package. Returns whatever the Move function returns.
+
+```typescript
+const [result] = tx.moveCall({
+	target: '0xPackage::module::function',
+	arguments: [arg1, arg2],
+	typeArguments: ['0x2::sui::SUI'],
+});
+```
+
+| Parameter       | Type       | Description                                        |
+| --------------- | ---------- | -------------------------------------------------- |
+| `target`        | `string`   | `packageId::moduleName::functionName`              |
+| `arguments`     | `any[]`    | Function arguments (objects, pure values, results) |
+| `typeArguments` | `string[]` | Move type parameters                               |
+
+You can also pass `package`, `module`, and `function` separately instead of `target`:
+
+```typescript
+tx.moveCall({
+	package: '0xPackageId',
+	module: 'my_module',
+	function: 'my_function',
+	arguments: [],
+	typeArguments: [],
+});
+```
+
+### `makeMoveVec`
+
+Constructs a vector of objects for use in `moveCall`. Required because there's no other way to pass
+a vector of objects as a transaction input.
+
+```typescript
+const vec = tx.makeMoveVec({ elements: [obj1, obj2] });
+
+// Pass the vector to a Move function
+tx.moveCall({
+	target: '0xPackage::module::process_items',
+	arguments: [vec],
+});
+```
+
+| Parameter  | Type                                     | Description                      |
+| ---------- | ---------------------------------------- | -------------------------------- |
+| `elements` | [object reference](#object-references)[] | Objects to include in the vector |
+| `type`     | `string` (optional)                      | Move type of the elements        |
+
+### `publish`
+
+Publishes a new Move package. Returns the upgrade capability object.
+
+```typescript
+const [upgradeCap] = tx.publish({ modules, dependencies });
+```
+
+| Parameter      | Type                     | Description                                                                                                                                            |
+| -------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `modules`      | `number[][] \| string[]` | Compiled module bytecodes. Each module as a `number[]` (byte array) or base64-encoded `string`. To convert from `Uint8Array`, use `Array.from(bytes)`. |
+| `dependencies` | `string[]`               | Package IDs of dependencies                                                                                                                            |
+
+### `upgrade`
+
+Upgrades an existing Move package.
+
+```typescript
+const [upgradeReceipt] = tx.upgrade({ modules, dependencies, package: packageId, ticket });
+```
+
+| Parameter      | Type                                   | Description                                                                                                                                            |
+| -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `modules`      | `number[][] \| string[]`               | Compiled module bytecodes. Each module as a `number[]` (byte array) or base64-encoded `string`. To convert from `Uint8Array`, use `Array.from(bytes)`. |
+| `dependencies` | `string[]`                             | Package IDs of dependencies                                                                                                                            |
+| `package`      | `string`                               | ID of the package being upgraded                                                                                                                       |
+| `ticket`       | [object reference](#object-references) | The upgrade ticket                                                                                                                                     |
+
+## Transaction results
+
+Every command returns a `TransactionResult` that can be used as input to subsequent commands:
+
+```typescript
+const [coin] = tx.splitCoins(tx.gas, [100]);
+tx.transferObjects([coin], address);
+```
+
+When a command returns multiple values, use destructuring or indexing:
+
+```typescript
+const [a, b] = tx.moveCall({ target: '0xPkg::mod::returns_two' });
+
+// or
+const result = tx.moveCall({ target: '0xPkg::mod::returns_two' });
+tx.transferObjects([result[0], result[1]], address);
+```