Skip to main content

TransactionBuilder

Namespace: IotaSdk

A builder for creating transactions. Use finish to finalize the transaction data.

public class TransactionBuilder : ITransactionBuilder, System.IDisposable

Inheritance Object → TransactionBuilder
Implements ITransactionBuilder, IDisposable
Attributes NullableContextAttribute, NullableAttribute

Constructors​

TransactionBuilder(UInt64)​

public TransactionBuilder(ulong pointer)

Parameters​

pointer UInt64

TransactionBuilder(Address)​

Create a new transaction builder and initialize its elements to default.

public TransactionBuilder(Address sender)

Parameters​

sender Address

Methods​

Destroy()​

public void Destroy()

Dispose()​

public void Dispose()

ExecuteWithGasStation(TransactionSigner)​

Execute the transaction using the gas station and return the JSON transaction effects. This will fail unless data is set with the gas_station_sponsor function.

NOTE: These effects are not necessarily compatible with TransactionEffects

public async Task<string> ExecuteWithGasStation(TransactionSigner signer)

Parameters​

signer TransactionSigner

Returns​

Task<String>

Exceptions​

SdkFfiException

Expiration(UInt64)​

Set the expiration of the transaction to be a specific epoch.

public TransactionBuilder Expiration(ulong epoch)

Parameters​

epoch UInt64

Returns​

TransactionBuilder

Finish()​

Convert this builder into a transaction.

public Transaction Finish()

Returns​

Transaction

Exceptions​

SdkFfiException

Gas(ObjectReference[])​

Add gas coins that will be consumed. Optional.

public TransactionBuilder Gas(ObjectReference[] objectRefs)

Parameters​

objectRefs ObjectReference[]

Returns​

TransactionBuilder

GasBudget(UInt64)​

Set the gas budget for the transaction.

public TransactionBuilder GasBudget(ulong budget)

Parameters​

budget UInt64

Returns​

TransactionBuilder

GasPrice(UInt64)​

Set the gas price for the transaction.

public TransactionBuilder GasPrice(ulong price)

Parameters​

price UInt64

Returns​

TransactionBuilder

GasStationSponsor(String, TimeSpan?, Dictionary<String, String[]>)​

Set the gas station sponsor.

public TransactionBuilder GasStationSponsor(string url, TimeSpan? duration = null, Dictionary<string, String[]>? headers = null)

Parameters​

url String

duration TimeSpan?

headers Dictionary<String, String[]>?

Returns​

TransactionBuilder

MakeMoveVec(MoveArg[], TypeTag, String)​

Make a move vector from a list of elements. The elements must all be of the type indicated by type_tag.

public TransactionBuilder MakeMoveVec(MoveArg[] elements, TypeTag typeTag, string name)

Parameters​

elements MoveArg[]

typeTag TypeTag

name String

Returns​

TransactionBuilder

MergeCoins(PtbArgument, PtbArgument[])​

Merge multiple coins into one.

This method combines the balances of multiple coins of the same coin type into a single coin. The primary_coin will receive the balances from all consumed_coins. After merging, the consumed_coins will be consumed and no longer exist.

public TransactionBuilder MergeCoins(PtbArgument primaryCoin, PtbArgument[] consumedCoins)

Parameters​

primaryCoin PtbArgument

consumedCoins PtbArgument[]

Returns​

TransactionBuilder

MoveCall(Address, Identifier, Identifier, PtbArgument[], TypeTag[], String[])​

Call a Move function with the given arguments.

public TransactionBuilder MoveCall(Address package, Identifier module, Identifier function, PtbArgument[] arguments = null, TypeTag[] typeArgs = null, String[] names = null)

Parameters​

package Address

module Identifier

function Identifier

arguments PtbArgument[]

typeArgs TypeTag[]

names String[]

Returns​

TransactionBuilder

Pay(PtbArgument[], Payment[])​

Send coins to multiple recipients, each paired with the amount to send.

The amounts specify quantities in the coins' smallest unit (NANOS for IOTA coins, where 1 IOTA equals 1_000_000_000 NANOS).

The coins are merged into the first one, the amounts are split off it in a single command, and each split coin is transferred to its corresponding recipient, with one transfer command per unique recipient. The remainder stays in the first coin.

All provided coins must have the same coin type. Mixing coins of different types will result in an error.

To pay IOTA directly from the gas coin, use TransactionBuilder::pay_iota() instead.

For a single recipient, consider using TransactionBuilder::send_coins() or TransactionBuilder::send_iota() instead.

public TransactionBuilder Pay(PtbArgument[] coins, Payment[] payments)

Parameters​

coins PtbArgument[]

payments Payment[]

Returns​

TransactionBuilder

PayIota(Payment[])​

Send IOTA to multiple recipients, each paired with the amount to send.

The amounts specify quantities in NANOS, where 1 IOTA equals 1_000_000_000 NANOS. They are split off the gas coin in a single command, and each split coin is transferred to its corresponding recipient, with one transfer command per unique recipient.

To pay with specific coins, or with a coin type other than IOTA, use TransactionBuilder::pay(). For a single recipient, consider using TransactionBuilder::send_iota() instead.

public TransactionBuilder PayIota(Payment[] payments)

Parameters​

payments Payment[]

Returns​

TransactionBuilder

PublishPackage(MovePackageData, String)​

Publish a list of modules with the given dependencies. The result assigned to upgrade_cap_name 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
public TransactionBuilder PublishPackage(MovePackageData packageData, string upgradeCapName)

Parameters​

packageData MovePackageData

upgradeCapName String

Returns​

TransactionBuilder

SendCoins(PtbArgument[], Address, PtbArgument)​

Transfer some coins to a recipient address. If multiple coins are provided then they will be merged.

The amount parameter specifies the quantity in NANOS, where 1 IOTA equals 1_000_000_000 NANOS. If amount is provided, that amount is split from the provided coins and sent. If amount is None, the entire coins are transferred.

All provided coins must have the same coin type. Mixing coins of different types will result in an error.

If you intend to transfer all provided coins to another address in a single transaction, consider using TransactionBuilder::transfer_objects() instead.

public TransactionBuilder SendCoins(PtbArgument[] coins, Address recipient, PtbArgument? amount = null)

Parameters​

coins PtbArgument[]

recipient Address

amount PtbArgument?

Returns​

TransactionBuilder

SendIota(Address, PtbArgument)​

Send IOTA to a recipient address.

The amount parameter specifies the quantity in NANOS, where 1 IOTA equals 1_000_000_000 NANOS. That amount is split from the gas coin and sent.

public TransactionBuilder SendIota(Address recipient, PtbArgument amount)

Parameters​

recipient Address

amount PtbArgument

Returns​

TransactionBuilder

SetSender(Address)​

Set the sender address.

public void SetSender(Address sender)

Parameters​

sender Address

SplitCoins(PtbArgument, PtbArgument[], String[])​

Split a coin by the provided amounts.

public TransactionBuilder SplitCoins(PtbArgument coin, PtbArgument[] amounts, String[] names = null)

Parameters​

coin PtbArgument

amounts PtbArgument[]

names String[]

Returns​

TransactionBuilder

Sponsor(Address)​

Set the sponsor of the transaction.

public TransactionBuilder Sponsor(Address sponsor)

Parameters​

sponsor Address

Returns​

TransactionBuilder

Stake(PtbArgument, Address)​

Add stake to a validator's staking pool.

This is a high-level function which will split the provided stake amount from the gas coin and then stake using the resulting coin.

public TransactionBuilder Stake(PtbArgument stake, Address validatorAddress)

Parameters​

stake PtbArgument

validatorAddress Address

Returns​

TransactionBuilder

TransferObjects(Address, PtbArgument[])​

Transfer a list of objects to the given address, without producing any result.

public TransactionBuilder TransferObjects(Address recipient, PtbArgument[] objects)

Parameters​

recipient Address

objects PtbArgument[]

Returns​

TransactionBuilder

Unstake(PtbArgument)​

Withdraw stake from a validator's staking pool.

public TransactionBuilder Unstake(PtbArgument stakedIota)

Parameters​

stakedIota PtbArgument

Returns​

TransactionBuilder

Upgrade(ObjectId, MovePackageData, PtbArgument, String)​

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.

public TransactionBuilder Upgrade(ObjectId packageId, MovePackageData packageData, PtbArgument upgradeTicket, string? name = null)

Parameters​

packageId ObjectId

packageData MovePackageData

upgradeTicket PtbArgument

name String?

Returns​

TransactionBuilder

WithClient(GraphQlClient)​

public ClientTransactionBuilder WithClient(GraphQlClient client)

Parameters​

client GraphQlClient

Returns​

ClientTransactionBuilder

FromProgrammableTransaction(ProgrammableTransaction)​

Create a transaction builder from a programmable transaction.

The returned builder has the original inputs and commands but no sender, gas payment, sponsor, or expiration; the sender defaults to the zero address and must be set via set_sender before finish is called.

public static TransactionBuilder FromProgrammableTransaction(ProgrammableTransaction ptb)

Parameters​

ptb ProgrammableTransaction

Returns​

TransactionBuilder

FromTransaction(Transaction)​

Reconstruct a transaction builder from a finalized transaction. Calling finish on the returned builder produces a transaction equal to the input.

Only programmable transactions are supported; other transaction kinds will return an error.

public static TransactionBuilder FromTransaction(Transaction transaction)

Parameters​

transaction Transaction

Returns​

TransactionBuilder

Exceptions​

SdkFfiException