@mysten/sui 2.17.0 → 2.18.0

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.

package/docs/transactions/coins-and-balances.md

@@ -0,0 +1,293 @@
+# Coins and Balances
+
+> Work with coin objects and address balances in transactions
+
+Sui has two systems for holding fungible token balances: coin objects and address balances.
+
+**Coin objects** are individual onchain objects, each with its own ID, version, and balance. You own
+specific coin objects and need to split, merge, and track them.
+
+**Address balances** are an accumulator per address per coin type. There are no objects to manage
+because deposits automatically merge into a single balance, and you withdraw from it as needed.
+
+Both systems coexist. An address's total balance for a given coin type is the sum of its coin object
+balances and its address balance.
+
+Address balances have no object versions. When a transaction has no versioned object inputs (for
+example, a balance transfer built entirely from address balance withdrawals), it won't be
+invalidated by other transactions from the same address executing concurrently.
+
+## `tx.coin` and `tx.balance`
+
+`tx.coin()` and `tx.balance()` are the recommended ways to get tokens in a transaction. They
+automatically draw from both coin objects and address balances.
+
+### Getting a `Coin`
+
+`tx.coin()` produces a `Coin<T>`. Use it for transfers and most operations:
+
+```tsx
+
+const tx = new Transaction();
+
+// SUI (balance is in MIST — 1 SUI = 1,000,000,000 MIST)
+tx.transferObjects([tx.coin({ balance: 1_000_000_000n })], '0xRecipientAddress');
+
+// Another coin type
+tx.transferObjects(
+	[tx.coin({ balance: 1_000_000n, type: '0xPackageId::module::CoinType' })],
+	'0xRecipientAddress',
+);
+```
+
+### Getting a `Balance`
+
+`tx.balance()` produces a `Balance<T>`. Use it for Move functions that expect a balance directly, or
+for gasless transactions:
+
+```tsx
+const tx = new Transaction();
+
+tx.moveCall({
+	target: '0xPackage::module::deposit',
+	arguments: [tx.object('0xPoolId'), tx.balance({ balance: 1_000_000_000n })],
+});
+```
+
+### Sending to address balances
+
+To deposit tokens into a recipient's address balance (instead of creating a coin object), use
+`tx.balance()` with `balance::send_funds`:
+
+```tsx
+const tx = new Transaction();
+
+tx.moveCall({
+	target: '0x2::balance::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.balance({ balance: 1_000_000_000n }), tx.pure.address('0xRecipientAddress')],
+});
+```
+
+> **Note:** Transactions built entirely from `tx.balance()` and gasless-eligible Move calls like `send_funds`
+> and `redeem_funds` might qualify as [gasless transactions](#gasless-transactions).
+
+### Options
+
+| Option       | Type               | Default    | Description                                                              |
+| ------------ | ------------------ | ---------- | ------------------------------------------------------------------------ |
+| `balance`    | `bigint \| number` | _required_ | Amount in base units (MIST for SUI)                                      |
+| `type`       | `string`           | SUI        | Coin type. Defaults to `0x2::sui::SUI`                                   |
+| `useGasCoin` | `boolean`          | `true`     | For SUI, split from the gas coin. Set `false` for sponsored transactions |
+
+For SUI, `tx.coin()` splits from the gas coin by default. For sponsored transactions where the gas
+coin belongs to the sponsor, set `useGasCoin: false`:
+
+```tsx
+tx.transferObjects([tx.coin({ balance: 100n, useGasCoin: false })], recipient);
+```
+
+### `coinWithBalance`
+
+`coinWithBalance()` is a standalone alias for `tx.coin()`:
+
+```tsx
+
+const tx = new Transaction();
+tx.transferObjects([coinWithBalance({ balance: 1_000_000_000 })], recipient);
+```
+
+## How resolution works
+
+When you call `tx.coin()` or `tx.balance()`, the SDK adds a placeholder intent to the transaction.
+At build time, the resolver replaces it with concrete commands based on the sender's funds:
+
+- **`tx.balance()` with sufficient address balance:** Uses a direct `FundsWithdrawal` through
+  `balance::redeem_funds`. No coin objects are used, so the transaction has no versioned object
+  inputs from this intent, keeping it eligible for parallel execution.
+
+- **Otherwise, coins are needed:** Fetches the sender's coin objects and address balance in
+  parallel. Merges available coins (topping up from address balance if needed), then splits the
+  exact amounts. For `tx.balance()` intents, the split results are converted to `Balance<T>` through
+  `coin::into_balance`, and any remainder is returned to the sender's address balance through
+  `coin::send_funds`.
+
+The resolver prefers address balances when possible to avoid introducing versioned object
+dependencies.
+
+Zero-balance requests resolve to `balance::zero` or `coin::zero` with no network lookups.
+
+## Checking balances
+
+Use `getBalance` to see both coin objects and address balance:
+
+```tsx
+const { balance } = await grpcClient.getBalance({
+	owner: '0xMyAddress',
+});
+
+console.log(balance.balance); // total balance as string (coin objects + address balance)
+console.log(balance.coinBalance); // balance from coin objects only
+console.log(balance.addressBalance); // balance from address balance only
+console.log(balance.coinType); // e.g. "0x2::sui::SUI"
+```
+
+All balance values are returned as strings. Use `BigInt(balance.balance)` for arithmetic.
+
+## Manual coin operations
+
+For fine-grained control, you can split and merge coins manually.
+
+### Splitting coins
+
+`splitCoins` creates new coins from an existing coin:
+
+```tsx
+const tx = new Transaction();
+
+// Split specific amounts from a coin you own
+const [coin1, coin2] = tx.splitCoins('0xMyCoinId', [1_000_000, 2_000_000]);
+
+tx.transferObjects([coin1], '0xAlice');
+tx.transferObjects([coin2], '0xBob');
+```
+
+Split the gas coin for SUI:
+
+```tsx
+const [coin] = tx.splitCoins(tx.gas, [1_000_000_000]);
+tx.transferObjects([coin], '0xRecipientAddress');
+```
+
+### Merging coins
+
+`mergeCoins` combines multiple coins into one:
+
+```tsx
+const tx = new Transaction();
+
+tx.mergeCoins('0xCoin1', ['0xCoin2', '0xCoin3']);
+```
+
+## Working with address balances directly
+
+### Withdrawing from address balance
+
+Create a withdrawal input and redeem it to get a `Coin<T>`:
+
+```tsx
+const tx = new Transaction();
+
+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');
+```
+
+Or get a `Balance<T>` directly:
+
+```tsx
+const [balance] = tx.moveCall({
+	target: '0x2::balance::redeem_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.withdrawal({ amount: 1_000_000_000 })],
+});
+```
+
+For non-SUI coin types, pass the `type` parameter:
+
+```tsx
+const [coin] = tx.moveCall({
+	target: '0x2::coin::redeem_funds',
+	typeArguments: ['0xPackageId::module::USDC'],
+	arguments: [tx.withdrawal({ amount: 1_000_000, type: '0xPackageId::module::USDC' })],
+});
+```
+
+### Depositing into address balances
+
+Use `coin::send_funds` to deposit a coin into a recipient's address balance:
+
+```tsx
+const tx = new Transaction();
+
+tx.moveCall({
+	target: '0x2::coin::send_funds',
+	typeArguments: ['0x2::sui::SUI'],
+	arguments: [tx.object('0xMyCoinObjectId'), tx.pure.address('0xRecipientAddress')],
+});
+```
+
+## Listing coin objects
+
+Use `listCoins` to see specific coin objects:
+
+```tsx
+const { objects, hasNextPage, cursor } = await grpcClient.listCoins({
+	owner: '0xMyAddress',
+});
+
+for (const coin of objects) {
+	console.log(coin.objectId, coin.balance);
+}
+```
+
+## Gasless transactions
+
+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/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
+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)
+
+When using the gRPC or GraphQL transports, transactions that qualify are automatically detected, and
+the gas price is set when the transaction is built.
+
+```tsx
+
+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: [USDC],
+	arguments: [tx.balance({ type: USDC, balance: 1_000_000 }), tx.pure.address(recipient)],
+});
+
+const result = await client.signAndExecuteTransaction({
+	transaction: tx,
+	signer: keypair,
+});
+```
+
+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 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:** 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:
+> 
+> ```tsx
+> const bytes = await tx.build({ client: grpcClient });
+> ```