org.stellar.sdk

Class TransactionBuilder

java.lang.Object

org.stellar.sdk.TransactionBuilder

public class TransactionBuilder
extends java.lang.Object

Builds a new Transaction object.

Constructor Summary

Constructors

Constructor and Description
TransactionBuilder(@NonNull TransactionBuilderAccount sourceAccount, @NonNull Network network) Construct a new transaction builder.

Method Summary

Modifier and Type	Method and Description
TransactionBuilder	addMemo(@NonNull Memo memo) Adds a memo to this transaction.
TransactionBuilder	addOperation(@NonNull Operation operation) Adds a new operation to this transaction.
TransactionBuilder	addOperations(@NonNull java.util.Collection<Operation> operations) Adds operation to this transaction.
TransactionBuilder	addPreconditions(@NonNull TransactionPreconditions preconditions) Adds preconditions.
Transaction	build() Builds a transaction and increments the sequence number on the source account after transaction is constructed.
Transaction	buildPaymentToContractTransaction(java.lang.String destination, Asset asset, java.math.BigDecimal amount, SorobanDataBuilder.Resources resources, java.lang.Long resourceFee, java.lang.String source) Builds a transaction to send asset to a contract.
Transaction	buildPaymentToContractTransaction(java.lang.String destination, Asset asset, java.math.BigDecimal amount, java.lang.String source) An alias for buildRestoreAssetBalanceEntryTransaction(String, Asset, SorobanDataBuilder.Resources, Long, String) with resources set to new SorobanDataBuilder.Resources(400_000L, 1_000L, 1_000L) and resourceFee set to 5_000_000L.
Transaction	buildRestoreAssetBalanceEntryTransaction(java.lang.String balanceOwner, Asset asset, SorobanDataBuilder.Resources resources, java.lang.Long resourceFee, java.lang.String source) Builds a transaction to restore the asset balance entry.
Transaction	buildRestoreAssetBalanceEntryTransaction(java.lang.String balanceOwner, Asset asset, java.lang.String source) An alias for buildRestoreAssetBalanceEntryTransaction(String, Asset, SorobanDataBuilder.Resources, Long, String) with resources set to new SorobanDataBuilder.Resources(0L, 500L, 500L) and resourceFee set to 4_000_000L.
java.lang.Long	getBaseFee()
Network	getNetwork()
int	getOperationsCount()
TransactionBuilderAccount	getSourceAccount()
TransactionBuilder	setBaseFee(long baseFee)
TransactionBuilder	setSorobanData(SorobanTransactionData sorobanData) Sets the transaction's internal Soroban transaction data (resources, footprint, etc.).
TransactionBuilder	setSorobanData(java.lang.String sorobanData) Sets the transaction's internal Soroban transaction data (resources, footprint, etc.).
TransactionBuilder	setTimeout(java.math.BigInteger timeout) Because of the distributed nature of the Stellar network it is possible that the status of your transaction will be determined after a long time if the network is highly congested.
TransactionBuilder	setTimeout(long timeout) An alias for setTimeout(BigInteger) with timeout in seconds.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TransactionBuilder

public TransactionBuilder(@NonNull
                          @NonNull TransactionBuilderAccount sourceAccount,
                          @NonNull
                          @NonNull Network network)

Construct a new transaction builder.

Parameters:

sourceAccount - the source account for this transaction. This account is the account who will use a sequence number. When build() is called, the account object's sequence number will be incremented.

network - the testnet or pubnet network to use

Method Detail

getOperationsCount

public int getOperationsCount()

addOperation

public TransactionBuilder addOperation(@NonNull
                                       @NonNull Operation operation)

Adds a new operation to this transaction.

Parameters:

operation - the operation to add

Returns:

Builder object so you can chain methods.

See Also:

Operation

addOperations

public TransactionBuilder addOperations(@NonNull
                                        @NonNull java.util.Collection<Operation> operations)

Adds operation to this transaction.

Parameters:

operations - list of operations

Returns:

Builder object so you can chain methods.

See Also:

Operation

addPreconditions

public TransactionBuilder addPreconditions(@NonNull
                                           @NonNull TransactionPreconditions preconditions)

Adds preconditions. For details of all preconditions on transaction refer to CAP-21

Parameters:

preconditions - the tx PreConditions

Returns:

updated Builder object

addMemo

public TransactionBuilder addMemo(@NonNull
                                  @NonNull Memo memo)

Adds a memo to this transaction.

Parameters:

memo - memo to add

Returns:

Builder object so you can chain methods.

See Also:

Memo

setTimeout

public TransactionBuilder setTimeout(java.math.BigInteger timeout)

Because of the distributed nature of the Stellar network it is possible that the status of your transaction will be determined after a long time if the network is highly congested. If you want to be sure to receive the status of the transaction within a given period you should set the TimeBounds with maxTime on the transaction (this is what setTimeout does internally; if there's minTime set but no maxTime it will be added). Call to Builder.setTimeout is required if Transaction does not have max_time set. If you don't want to set timeout, use TIMEOUT_INFINITE. In general, you should set TIMEOUT_INFINITE only in smart contracts. Please note that Horizon may still return 504 Gateway Timeout error, even for short timeouts. In such case you need to resubmit the same transaction again without making any changes to receive a status. This method is using the machine system time (UTC), make sure it is set correctly.

Parameters:

timeout - Timeout in seconds.

Returns:

updated Builder

See Also:

TimeBounds

setTimeout

public TransactionBuilder setTimeout(long timeout)

An alias for setTimeout(BigInteger) with timeout in seconds.

Parameters:

timeout - Timeout in seconds.

Returns:

updated Builder

setBaseFee

public TransactionBuilder setBaseFee(long baseFee)

build

public Transaction build()

Builds a transaction and increments the sequence number on the source account after transaction is constructed.

setSorobanData

public TransactionBuilder setSorobanData(SorobanTransactionData sorobanData)

Sets the transaction's internal Soroban transaction data (resources, footprint, etc.).

For non-contract(non-Soroban) transactions, this setting has no effect. In the case of Soroban transactions, this is either an instance of SorobanTransactionData or a base64-encoded string of said structure. This is usually obtained from the simulation response based on a transaction with a Soroban operation (e.g. InvokeHostFunctionOperation, providing necessary resource and storage footprint estimations for contract invocation.

Parameters:

sorobanData - Soroban data to set

Returns:

Builder object so you can chain methods.

setSorobanData

public TransactionBuilder setSorobanData(java.lang.String sorobanData)

Sets the transaction's internal Soroban transaction data (resources, footprint, etc.).

For non-contract(non-Soroban) transactions, this setting has no effect. In the case of Soroban transactions, this is either an instance of SorobanTransactionData or a base64-encoded string of said structure. This is usually obtained from the simulation response based on a transaction with a Soroban operation (e.g. InvokeHostFunctionOperation, providing necessary resource and storage footprint estimations for contract invocation.

Parameters:

sorobanData - Soroban data to set

Returns:

Builder object so you can chain methods.

buildPaymentToContractTransaction

public Transaction buildPaymentToContractTransaction(java.lang.String destination,
                                                     Asset asset,
                                                     java.math.BigDecimal amount,
                                                     @Nullable
                                                     java.lang.String source)

An alias for buildRestoreAssetBalanceEntryTransaction(String, Asset, SorobanDataBuilder.Resources, Long, String) with resources set to new SorobanDataBuilder.Resources(400_000L, 1_000L, 1_000L) and resourceFee set to 5_000_000L.

Parameters:

destination - The contract to send the assets to. (starting with 'C')

asset - The asset to send.

amount - The amount of the asset to send.

source - The source account for the transaction.

Returns:

The transaction.

buildPaymentToContractTransaction

public Transaction buildPaymentToContractTransaction(java.lang.String destination,
                                                     Asset asset,
                                                     java.math.BigDecimal amount,
                                                     SorobanDataBuilder.Resources resources,
                                                     java.lang.Long resourceFee,
                                                     @Nullable
                                                     java.lang.String source)

Builds a transaction to send asset to a contract.

The original intention of this interface design is to send assets to the contract account when the Stellar RPC server is inaccessible. Without Stellar RPC, we cannot accurately estimate the required resources, so we have preset some values that may be slightly higher than the actual resource consumption.

If you encounter the entry_archived error when submitting this transaction, you should consider calling the buildRestoreAssetBalanceEntryTransaction(String, Asset, SorobanDataBuilder.Resources, Long, String) method to restore the entry, and then use the method to send assets again.

Note:

1. This method should only be used to send assets to a contract (starting with 'C'). For sending assets to regular account addresses (starting with 'G'), please use the PaymentOperation.
2. This method is suitable for sending assets to a contract account when you don't have access to a Stellar RPC server. If you have access to a Stellar RPC server, it is recommended to use the ContractClient to build transactions for sending tokens to contracts.
3. This method may consume slightly more transaction fee than actually required. Under Protocol 22, if the destination is receiving the asset for the first time, it will actually consume about 0.25 XLM in resource fees; if it has received the asset before, it will actually consume about 0.006 XLM in resource fees.

Parameters:

destination - The contract to send the assets to. (starting with 'C')

asset - The asset to send.

amount - The amount of the asset to send.

resources - The resources required for the transaction.

resourceFee - The maximum fee (in stroops) that can be paid for the transaction.

source - The source account for the transaction.

Returns:

The transaction.

buildRestoreAssetBalanceEntryTransaction

public Transaction buildRestoreAssetBalanceEntryTransaction(java.lang.String balanceOwner,
                                                            Asset asset,
                                                            @Nullable
                                                            java.lang.String source)

An alias for buildRestoreAssetBalanceEntryTransaction(String, Asset, SorobanDataBuilder.Resources, Long, String) with resources set to new SorobanDataBuilder.Resources(0L, 500L, 500L) and resourceFee set to 4_000_000L.

Parameters:

balanceOwner - The owner of the asset, it should be the same as the `destination` address in the buildPaymentToContractTransaction(String, Asset, BigDecimal, SorobanDataBuilder.Resources, Long, String) method.

asset - The asset

source - The source account for the transaction.

Returns:

The transaction.

buildRestoreAssetBalanceEntryTransaction

public Transaction buildRestoreAssetBalanceEntryTransaction(java.lang.String balanceOwner,
                                                            Asset asset,
                                                            SorobanDataBuilder.Resources resources,
                                                            java.lang.Long resourceFee,
                                                            @Nullable
                                                            java.lang.String source)

Builds a transaction to restore the asset balance entry.

This method is designed to be used in conjunction with the buildPaymentToContractTransaction(String, Asset, BigDecimal, SorobanDataBuilder.Resources, Long, String) method.

Under Protocol 22, if the entry really needs to be restored, then this method will consume about 0.25 XLM in resource fees.

Parameters:

balanceOwner - The owner of the asset, it should be the same as the `destination` address in the buildPaymentToContractTransaction(String, Asset, BigDecimal, SorobanDataBuilder.Resources, Long, String) method.

asset - The asset

resources - The resources required for the transaction.

resourceFee - The maximum fee (in stroops) that can be paid for the transaction.

source - The source account for the transaction.

Returns:

The transaction.

getSourceAccount

public TransactionBuilderAccount getSourceAccount()

getBaseFee

public java.lang.Long getBaseFee()

getNetwork

public Network getNetwork()