Struct TransactionBuilder 

pub struct TransactionBuilder { /* private fields */ }

A builder for creating programmable transaction blocks.

Inputs and commands are added incrementally through methods like pure, object, move_call, and transfer_objects. Once all commands and metadata have been set, call try_build for offline building, or build (with the intents feature) to resolve intents and gas via an RPC client.

Example

use sui_sdk_types::Address;
use sui_sdk_types::Digest;
use sui_transaction_builder::ObjectInput;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();

let amount = tx.pure(&1_000_000_000u64);
let gas = tx.gas();
let coins = tx.split_coins(gas, vec![amount]);

let recipient = tx.pure(&Address::ZERO);
tx.transfer_objects(coins, recipient);

tx.set_sender(Address::ZERO);
tx.set_gas_budget(500_000_000);
tx.set_gas_price(1000);
tx.add_gas_objects([ObjectInput::owned(Address::ZERO, 1, Digest::ZERO)]);

let transaction = tx.try_build().expect("build should succeed");

Implementations

impl TransactionBuilder

pub fn new() -> Self

Create a new, empty transaction builder.

use sui_transaction_builder::TransactionBuilder;

let tx = TransactionBuilder::new();

pub fn gas(&mut self) -> Argument

Return an Argument referring to the gas coin.

The gas coin can be used as an input to commands such as split_coins.

Note: The gas coin cannot be used when using an account’s Address Balance to pay for gas fees.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let gas = tx.gas();

pub fn pure_bytes(&mut self, bytes: Vec<u8>) -> Argument

Add a pure input from raw BCS bytes.

If the same bytes have already been added, the existing Argument is returned (inputs are deduplicated). Use pure_bytes_unique when deduplication is not desired.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let a = tx.pure_bytes(vec![1, 0, 0, 0, 0, 0, 0, 0]);
let b = tx.pure_bytes(vec![1, 0, 0, 0, 0, 0, 0, 0]);
// `a` and `b` refer to the same input

pub fn pure<T: Serialize>(&mut self, value: &T) -> Argument

Add a pure input by serializing value to BCS.

Pure inputs are values like integers, addresses, and strings — anything that is not an on-chain object. Identical values are deduplicated; use pure_unique if each call must produce a distinct input.

use sui_sdk_types::Address;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let amount = tx.pure(&1_000_000_000u64);
let recipient = tx.pure(&Address::ZERO);

pub fn pure_bytes_unique(&mut self, bytes: Vec<u8>) -> Argument

Add a pure input from raw BCS bytes, always creating a new input.

Unlike pure_bytes, this method never deduplicates — each call produces a distinct input even if the bytes are identical.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let a = tx.pure_bytes_unique(vec![42]);
let b = tx.pure_bytes_unique(vec![42]);
// `a` and `b` are distinct inputs despite identical bytes

pub fn pure_unique<T: Serialize>(&mut self, value: &T) -> Argument

Add a pure input by serializing value to BCS, always creating a new input.

This is the non-deduplicating variant of pure.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let a = tx.pure_unique(&1u64);
let b = tx.pure_unique(&1u64);
// `a` and `b` are distinct inputs

pub fn object(&mut self, object: ObjectInput) -> Argument

Add an object input to the transaction.

If an object with the same ID has already been added, the existing Argument is returned and any additional metadata (version, digest, mutability) from the new ObjectInput is merged in.

use sui_sdk_types::Address;
use sui_sdk_types::Digest;
use sui_transaction_builder::ObjectInput;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let obj = tx.object(ObjectInput::owned(Address::ZERO, 1, Digest::ZERO));

pub fn funds_withdrawal(&mut self, coin_type: TypeTag, amount: u64) -> Argument

Add a funds-withdrawal input that requests amount of coin_type from the sender’s Address Balance.

The returned Argument represents the raw FundsWithdrawal input. In most cases you’ll want funds_withdrawal_coin or funds_withdrawal_balance which additionally call the appropriate redeem_funds function.

pub fn funds_withdrawal_coin( &mut self, coin_type: TypeTag, amount: u64, ) -> Argument

Withdraw funds from the sender’s Address Balance and redeem them as a Coin<T>.

This adds a FundsWithdrawal input and calls 0x2::coin::redeem_funds to convert it into a Coin<T>.

pub fn funds_withdrawal_balance( &mut self, coin_type: TypeTag, amount: u64, ) -> Argument

Withdraw funds from the sender’s Address Balance and redeem them as a Balance<T>.

This adds a FundsWithdrawal input and calls 0x2::balance::redeem_funds to convert it into a Balance<T>.

pub fn add_gas_objects<O, I>(&mut self, gas: I)

where O: Into<ObjectInput>, I: IntoIterator<Item = O>,

Add one or more gas objects to use to pay for the transaction.

use sui_sdk_types::Address;
use sui_sdk_types::Digest;
use sui_transaction_builder::ObjectInput;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
tx.add_gas_objects([ObjectInput::owned(Address::ZERO, 1, Digest::ZERO)]);

pub fn set_gas_budget(&mut self, budget: u64)

Set the gas budget for the transaction.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
tx.set_gas_budget(500_000_000);

pub fn set_gas_price(&mut self, price: u64)

Set the gas price for the transaction.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
tx.set_gas_price(1000);

pub fn set_sender(&mut self, sender: Address)

Set the sender of the transaction.

use sui_sdk_types::Address;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
tx.set_sender(Address::ZERO);

pub fn set_sponsor(&mut self, sponsor: Address)

Set the sponsor of the transaction.

If not set, the sender is used as the gas owner.

pub fn set_expiration(&mut self, expiration: TransactionExpiration)

Set the expiration of the transaction.

pub fn move_call( &mut self, function: Function, arguments: Vec<Argument>, ) -> Argument

Call a Move function with the given arguments.

function is a structured representation of a package::module::function, optionally with type arguments (see Function and Function::with_type_args).

The return value is a result argument that can be used in subsequent commands. If the Move call returns multiple results, access them with Argument::to_nested.

use sui_sdk_types::Address;
use sui_sdk_types::Identifier;
use sui_transaction_builder::Function;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let result = tx.move_call(
    Function::new(
        Address::TWO,
        Identifier::from_static("coin"),
        Identifier::from_static("zero"),
    )
    .with_type_args(vec!["0x2::sui::SUI".parse().unwrap()]),
    vec![],
);

pub fn transfer_objects(&mut self, objects: Vec<Argument>, address: Argument)

Transfer a list of objects to the given address.

use sui_sdk_types::Address;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let gas = tx.gas();
let amount = tx.pure(&1_000_000_000u64);
let coins = tx.split_coins(gas, vec![amount]);
let recipient = tx.pure(&Address::ZERO);
tx.transfer_objects(coins, recipient);

pub fn split_coins( &mut self, coin: Argument, amounts: Vec<Argument>, ) -> Vec<Argument>

Split a coin by the provided amounts, returning multiple results (as many as there are amounts). The returned vector of Arguments is guaranteed to be the same length as the provided amounts vector.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let gas = tx.gas();
let a = tx.pure(&1_000u64);
let b = tx.pure(&2_000u64);
let coins = tx.split_coins(gas, vec![a, b]);
assert_eq!(coins.len(), 2);

pub fn merge_coins(&mut self, coin: Argument, coins_to_merge: Vec<Argument>)

Merge a list of coins into a single coin.

use sui_sdk_types::Address;
use sui_sdk_types::Digest;
use sui_transaction_builder::ObjectInput;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let coin_a = tx.object(ObjectInput::owned(Address::ZERO, 1, Digest::ZERO));
let coin_b = tx.object(ObjectInput::owned(
    Address::from_static("0x1"),
    1,
    Digest::ZERO,
));
tx.merge_coins(coin_a, vec![coin_b]);

pub fn make_move_vec( &mut self, type_: Option<TypeTag>, elements: Vec<Argument>, ) -> Argument

Make a Move vector from a list of elements.

If the elements are not objects, or the vector is empty, a type_ must be supplied. Returns the Move vector as an argument that can be used in subsequent commands.

use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();
let a = tx.pure(&1u64);
let b = tx.pure(&2u64);
let vec = tx.make_move_vec(Some("u64".parse().unwrap()), vec![a, b]);

pub fn publish( &mut self, modules: Vec<Vec<u8>>, dependencies: Vec<Address>, ) -> Argument

Publish a list of modules with the given dependencies. The result is the 0x2::package::UpgradeCap Move type. Note that the upgrade capability needs to be handled after this call:

• transfer it to the transaction sender or another address
• burn it
• wrap it for access control
• discard the it to make a package immutable

The arguments required for this command are:

• modules: is the modules’ bytecode to be published
• dependencies: is the list of IDs of the transitive dependencies of the package

pub fn upgrade( &mut self, modules: Vec<Vec<u8>>, dependencies: Vec<Address>, package: Address, ticket: Argument, ) -> Argument

Upgrade a Move package.

• modules: is the modules’ bytecode for the modules to be published
• dependencies: is the list of IDs of the transitive dependencies of the package to be upgraded
• package: is the ID of the current package being upgraded
• ticket: is the upgrade ticket

To get the ticket, you have to call the 0x2::package::authorize_upgrade function, and pass the package ID, the upgrade policy, and package digest.

pub fn intent<I: Intent>(&mut self, intent: I) -> Argument

Available on crate feature intents only.

Register a transaction intent which is resolved later to either an input or a sequence of commands.

Intents are high-level descriptions of what the transaction needs (e.g., a coin of a certain value) that get resolved when build is called. See CoinWithBalance for an example of an Intent.

use sui_transaction_builder::TransactionBuilder;
use sui_transaction_builder::intent::CoinWithBalance;

let mut tx = TransactionBuilder::new();
let coin = tx.intent(CoinWithBalance::sui(1_000_000_000));
// `coin` can be passed to subsequent commands

pub fn try_build(self) -> Result<Transaction, Error>

Build the transaction offline.

All metadata (sender, gas budget, gas price, gas objects) and any object inputs must be fully specified before calling this method. Returns an Error if any required fields are missing or if unresolved intents remain.

use sui_sdk_types::Address;
use sui_sdk_types::Digest;
use sui_transaction_builder::ObjectInput;
use sui_transaction_builder::TransactionBuilder;

let mut tx = TransactionBuilder::new();

let gas = tx.gas();
let amount = tx.pure(&1_000_000_000u64);
let coins = tx.split_coins(gas, vec![amount]);
let recipient = tx.pure(&Address::ZERO);
tx.transfer_objects(coins, recipient);

tx.set_sender(Address::ZERO);
tx.set_gas_budget(500_000_000);
tx.set_gas_price(1000);
tx.add_gas_objects([ObjectInput::owned(Address::ZERO, 1, Digest::ZERO)]);

let transaction = tx.try_build().unwrap();

pub async fn build(self, client: &mut Client) -> Result<Transaction, Error>

Available on crate feature intents only.

Build the transaction by resolving intents and gas via an RPC client.

This method resolves any registered intents (e.g., CoinWithBalance), performs gas selection if needed, and simulates the transaction before returning the finalized [Transaction].

Errors

Returns an Error if the sender is not set, intent resolution fails, or the simulated execution fails.

Trait Implementations

impl Default for TransactionBuilder

fn default() -> TransactionBuilder

Returns the “default value” for a type.