Package org.stellar.sdk

Class TransactionBuilder

java.lang.Object
org.stellar.sdk.TransactionBuilder
public class TransactionBuilder extends Object
Builds a new Transaction object.

  • Constructor Details

    • 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 Details

    • 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:

    • addOperations

      public TransactionBuilder addOperations(@NonNull @NonNull Collection<Operation> operations)
      Adds operation to this transaction.
      Parameters:
      operations - list of operations
      Returns:
      Builder object so you can chain methods.
      See Also:

    • 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:

    • setTimeout

      public TransactionBuilder setTimeout(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:

    • 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(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(String destination, Asset asset, BigDecimal amount, @Nullable 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(String destination, Asset asset, BigDecimal amount, SorobanDataBuilder.Resources resources, Long resourceFee, @Nullable 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(String balanceOwner, Asset asset, @Nullable 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(String balanceOwner, Asset asset, SorobanDataBuilder.Resources resources, Long resourceFee, @Nullable 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 Long getBaseFee()

    • getNetwork

      public Network getNetwork()