@mysten/sui 2.17.0 → 2.19.0

package/docs/transactions/offline.md

@@ -0,0 +1,192 @@
+# Building Offline
+
+> Build transactions without a network connection
+
+Normally the SDK resolves object versions, estimates gas, and fills in other details by querying the
+network. For offline building of backend services, air-gapped signing, or pre-built transactions,
+you must provide this information yourself. See also the Sui documentation on
+[offline signing](https://docs.sui.io/guides/developer/transactions/transaction-auth/offline-signing)
+for the protocol-level details.
+
+## Transactions without owned object inputs
+
+When your transaction only uses shared objects, party objects, and/or address balance withdrawals,
+there are no owned object versions to look up. Use `tx.withdrawal()` directly instead of `tx.coin()`
+or `coinWithBalance` because they require a client to resolve coin objects at build time.
+
+```typescript
+
+const tx = new Transaction();
+
+// Use tx.withdrawal() + coin::redeem_funds to withdraw from address balance.
+// No coin object lookups needed — fully offline.
+const [coin] = tx.moveCall({
+	target: '0x2::coin::redeem_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.withdrawal({ amount: 1_000_000_000 })],
+});
+tx.transferObjects([coin], '0xRecipientAddress');
+
+// Shared/party objects only need objectId + initialSharedVersion (both stable)
+tx.moveCall({
+	target: '0xPackage::module::function',
+	arguments: [
+		tx.sharedObjectRef({
+			objectId: '0xSharedObjectId',
+			initialSharedVersion: '1',
+			mutable: true,
+		}),
+	],
+});
+
+// Required configuration for all offline builds
+tx.setSender('0xSenderAddress');
+tx.setGasPrice(1000); // query getReferenceGasPrice() beforehand, or use a known value
+tx.setGasBudget(50_000_000);
+tx.setGasPayment([]); // empty array = pay gas from address balance
+
+// Expiration is required when there are no owned objects for gas or inputs
+tx.setExpiration({
+	ValidDuring: {
+		minEpoch: 100, // current epoch
+		maxEpoch: 101, // current epoch + 1
+		minTimestamp: null,
+		maxTimestamp: null,
+		chain: 'mainnet', // or 'testnet', 'devnet'
+		nonce: 0,
+	},
+});
+
+// Build without a client
+const bytes = await tx.build();
+```
+
+This enables fully stateless construction. You only need the sender address, reference gas price,
+epoch, and chain identifier.
+
+## Party objects
+
+Party objects are address-owned but consensus-versioned, with per-address permissions. They are
+referenced the same way as shared objects:
+
+```typescript
+tx.sharedObjectRef({
+	objectId: '0xPartyObjectId',
+	initialSharedVersion: '1',
+	mutable: true,
+});
+```
+
+Key properties for offline building:
+
+- **No version lookup needed**: `initialSharedVersion` is stable and set once when the object
+  becomes a party object
+- **Enable pipelining**: Submit multiple transactions on the same party object without waiting for
+  each one to finalize
+- **Cannot be used for gas**: Use address balance for gas payment (`setGasPayment([])`)
+
+## Transactions with owned object inputs
+
+When your transaction uses owned or immutable objects, you must provide the exact version and digest
+for each one:
+
+```typescript
+
+const tx = new Transaction();
+
+// Owned objects need exact version and digest
+tx.transferObjects(
+	[
+		tx.objectRef({
+			objectId: '0xOwnedObjectId',
+			version: '42',
+			digest: 'abc123...',
+		}),
+	],
+	'0xRecipientAddress',
+);
+
+// Receiving objects also need exact version and digest
+tx.moveCall({
+	target: '0xPackage::module::receive',
+	arguments: [
+		tx.objectRef({
+			objectId: '0xParentId',
+			version: '10',
+			digest: 'def456...',
+		}),
+		tx.receivingRef({
+			objectId: '0xReceivingId',
+			version: '5',
+			digest: 'ghi789...',
+		}),
+	],
+});
+
+// Gas payment with specific coin objects
+tx.setGasPayment([{ objectId: '0xGasCoinId', version: '3', digest: 'jkl012...' }]);
+
+tx.setSender('0xSenderAddress');
+tx.setGasPrice(1000);
+tx.setGasBudget(50_000_000);
+
+const bytes = await tx.build();
+```
+
+## Required configuration for all offline builds
+
+Every offline-built transaction must have the following:
+
+| Method            | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
+| `setSender()`     | The address executing the transaction                           |
+| `setGasPrice()`   | Reference gas price (query `getReferenceGasPrice()` beforehand) |
+| `setGasBudget()`  | Maximum gas to spend (in MIST)                                  |
+| `setGasPayment()` | Coin object references, or `[]` for address balance             |
+
+### Expiration
+
+Set an expiration when your transaction uses no owned objects for gas or inputs. This applies when
+you use address balances for gas (`setGasPayment([])`) with only shared and party object inputs:
+
+```typescript
+tx.setExpiration({
+	ValidDuring: {
+		minEpoch: 100, // current epoch
+		maxEpoch: 101, // typically current epoch + 1
+		minTimestamp: null,
+		maxTimestamp: null,
+		chain: 'mainnet',
+		nonce: 0, // increment for multiple transactions in the same epoch
+	},
+});
+```
+
+You can also use epoch-based expiration:
+
+```typescript
+tx.setExpiration({ Epoch: 100 });
+```
+
+> **Note:** When building with a client, the SDK sets expiration automatically. You only need the manual
+> configuration above for fully offline builds.
+
+## Serialization
+
+### Building to bytes
+
+```typescript
+// Build to BCS bytes (Uint8Array) — fully offline, all data must be provided
+const bytes = await tx.build();
+
+// Build with a client — only makes network requests when there is unresolved data to look up
+const bytes = await tx.build({ client: grpcClient });
+```
+
+### Converting bytes back to a Transaction
+
+```typescript
+const tx = Transaction.from(bytes);
+```
+
+This works with BCS byte arrays, base64-encoded strings, and JSON strings (from `toJSON()`).

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);
+```