# 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
might 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 might 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`, for example
`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.

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