TransactionBuilder

TransactionBuilder

Transaction builder helps constructs a new `Transaction` using the given Account as the transaction's "source account". The transaction will use the current sequence number of the given account as its sequence number and increment the given account's sequence number by one. The given source account must include a private key for signing the transaction or an error will be thrown.

Operations can be added to the transaction via their corresponding builder methods, and each returns the TransactionBuilder object so they can be chained together. After adding the desired operations, call the `build()` method on the `TransactionBuilder` to return a fully constructed `Transaction` that can be signed. The returned transaction will contain the sequence number of the source account and include the signature from the source account.

Be careful about unsubmitted transactions! When you build a transaction, `stellar-sdk` automatically increments the source account's sequence number. If you end up not submitting this transaction and submitting another one instead, it'll fail due to the sequence number being wrong. So if you decide not to use a built transaction, make sure to update the source account's sequence number with [Server.loadAccount](https://stellar.github.io/js-stellar-sdk/Server.html#loadAccount) before creating another transaction.

The following code example creates a new transaction with Operation.createAccount and Operation.payment operations. The Transaction's source account first funds `destinationA`, then sends a payment to `destinationB`. The built transaction is then signed by `sourceKeypair`.

var transaction = new TransactionBuilder(source, { fee, networkPassphrase: Networks.TESTNET })
.addOperation(Operation.createAccount({
    destination: destinationA,
    startingBalance: "20"
})) // <- funds and creates destinationA
.addOperation(Operation.payment({
    destination: destinationB,
    amount: "100",
    asset: Asset.native()
})) // <- sends 100 XLM to destinationB
.setTimeout(30)
.build();

transaction.sign(sourceKeypair);

Constructor

new TransactionBuilder(sourceAccount, opts)

Source:
Parameters:
Name Type Description
sourceAccount Account

source account for this transaction
opts object

Options object

Name Type Attributes Description
fee string

max fee you're willing to pay per operation in this transaction (in stroops)
timebounds object <optional>

timebounds for the validity of this transaction

Name Type Attributes Description
minTime number | string | Date <optional>

64-bit UNIX timestamp or Date object
maxTime number | string | Date <optional>

64-bit UNIX timestamp or Date object
ledgerbounds object <optional>

ledger bounds for the validity of this transaction

Name Type Attributes Description
minLedger number <optional>

number of the minimum ledger sequence
maxLedger number <optional>

number of the maximum ledger sequence
minAccountSequence string <optional>

number for the minimum account sequence
minAccountSequenceAge number <optional>

number of seconds for the minimum account sequence age
minAccountSequenceLedgerGap number <optional>

number of ledgers for the minimum account sequence ledger gap
extraSigners Array.<string> <optional>

list of the extra signers required for this transaction
memo Memo <optional>

memo for the transaction
networkPassphrase string <optional>

passphrase of the target Stellar network (e.g. "Public Global Stellar Network ; September 2015" for the pubnet)
sorobanData xdr.SorobanTransactionData | string <optional>

an optional instance of xdr.SorobanTransactionData to be set as the internal Transaction.Ext.SorobanData field (either the xdr object or a base64 string). In the case of Soroban transactions, this can be obtained from a prior simulation of the transaction with a contract invocation and provides necessary resource estimations. You can also use SorobanDataBuilder to construct complicated combinations of parameters without mucking with XDR directly. Note: For non-contract(non-Soroban) transactions, this has no effect.

Classes

TransactionBuilder

Methods

addMemo(memo) → {TransactionBuilder}

Adds a memo to the transaction.

Source:
Parameters:
Name Type Description
memo Memo

Memo object
Returns:
Type:
TransactionBuilder

addOperation(operation) → {TransactionBuilder}

Adds an operation to the transaction.

Source:
Parameters:
Name Type Description
operation xdr.Operation

The xdr operation object, use Operation static methods.
Returns:
Type:
TransactionBuilder

build() → {Transaction}

This will build the transaction. It will also increment the source account's sequence number by 1.

Source:
Returns:
Type:
Transaction

This method will return the built Transaction.

clearOperations() → {TransactionBuilder}

Removes the operations from the builder (useful when cloning).

Source:
Returns:
Type:
TransactionBuilder

this builder instance

setExtraSigners(extraSigners) → {TransactionBuilder}

For the transaction to be valid, there must be a signature corresponding to every Signer in this array, even if the signature is not otherwise required by the sourceAccount or operations. Internally this will set the extraSigners precondition.

Source:
Parameters:
Name Type Description
extraSigners Array.<string>

required extra signers (as StrKeys)
Returns:
Type:
TransactionBuilder

setLedgerbounds(minLedger, maxLedger) → {TransactionBuilder}

If you want to prepare a transaction which will only be valid within some range of ledgers, you can set a ledgerbounds precondition. Internally this will set the minLedger and maxLedger preconditions.

Source:
Parameters:
Name Type Description
minLedger number

The minimum ledger this transaction is valid at or after. Cannot be negative. If the value is 0 (the default), the transaction is valid immediately.
maxLedger number

The maximum ledger this transaction is valid before. Cannot be negative. If the value is 0, the transaction is valid indefinitely.
Returns:
Type:
TransactionBuilder

setMinAccountSequence(minAccountSequence) → {TransactionBuilder}

If you want to prepare a transaction which will be valid only while the account sequence number is

minAccountSequence <= sourceAccountSequence < tx.seqNum

Note that after execution the account's sequence number is always raised to tx.seqNum. Internally this will set the minAccountSequence precondition.

Source:
Parameters:
Name Type Description
minAccountSequence string

The minimum source account sequence number this transaction is valid for. If the value is 0 (the default), the transaction is valid when sourceAccount's sequence number == tx.seqNum- 1.
Returns:
Type:
TransactionBuilder

setMinAccountSequenceAge(durationInSeconds) → {TransactionBuilder}

For the transaction to be valid, the current ledger time must be at least minAccountSequenceAge greater than sourceAccount's sequenceTime. Internally this will set the minAccountSequenceAge precondition.

Source:
Parameters:
Name Type Description
durationInSeconds number

The minimum amount of time between source account sequence time and the ledger time when this transaction will become valid. If the value is 0, the transaction is unrestricted by the account sequence age. Cannot be negative.
Returns:
Type:
TransactionBuilder

setMinAccountSequenceLedgerGap(gap) → {TransactionBuilder}

For the transaction to be valid, the current ledger number must be at least minAccountSequenceLedgerGap greater than sourceAccount's ledger sequence. Internally this will set the minAccountSequenceLedgerGap precondition.

Source:
Parameters:
Name Type Description
gap number

The minimum number of ledgers between source account sequence and the ledger number when this transaction will become valid. If the value is 0, the transaction is unrestricted by the account sequence ledger. Cannot be negative.
Returns:
Type:
TransactionBuilder

setNetworkPassphrase(networkPassphrase) → {TransactionBuilder}

Set network nassphrase for the Transaction that will be built.

Source:
Parameters:
Name Type Description
networkPassphrase string

passphrase of the target Stellar network (e.g. "Public Global Stellar Network ; September 2015").
Returns:
Type:
TransactionBuilder

setSorobanData(sorobanData) → {TransactionBuilder}

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 xdr.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. Operation.invokeHostFunction, providing necessary resource and storage footprint estimations for contract invocation.

Source:
See:
Parameters:
Name Type Description
sorobanData xdr.SorobanTransactionData | string

the xdr.SorobanTransactionData as a raw xdr object or a base64 string to be decoded
Returns:
Type:
TransactionBuilder

setTimebounds(minEpochOrDate, maxEpochOrDate) → {TransactionBuilder}

If you want to prepare a transaction which will become valid at some point in the future, or be invalid after some time, you can set a timebounds precondition. Internally this will set the minTime, and maxTime preconditions. Conflicts with setTimeout, so use one or the other.

Source:
Parameters:
Name Type Description
minEpochOrDate Date | number

Either a JS Date object, or a number of UNIX epoch seconds. The transaction is valid after this timestamp. Can't be negative. If the value is 0, the transaction is valid immediately.
maxEpochOrDate Date | number

Either a JS Date object, or a number of UNIX epoch seconds. The transaction is valid until this timestamp. Can't be negative. If the value is 0, the transaction is valid indefinitely.
Returns:
Type:
TransactionBuilder

setTimeout(timeoutSeconds) → {TransactionBuilder}

Sets a timeout precondition on the transaction.

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).

A call to TransactionBuilder.setTimeout is required if Transaction does not have max_time set. If you don't want to set timeout, use TimeoutInfinite. In general you should set TimeoutInfinite 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.

Source:
See:
Parameters:
Name Type Description
timeoutSeconds number

Number of seconds the transaction is good. Can't be negative. If the value is TimeoutInfinite, the transaction is good indefinitely.
Returns:
Type:
TransactionBuilder

(static) buildFeeBumpTransaction(feeSource, baseFee, innerTx, networkPassphrase) → {FeeBumpTransaction}

Builds a FeeBumpTransaction, enabling you to resubmit an existing transaction with a higher fee.

Source:
See:
To Do:
  • Alongside the next major version bump, this type signature can be changed to be less awkward: accept a MuxedAccount as the `feeSource` rather than a keypair or string.
Parameters:
Name Type Description
feeSource Keypair | string

account paying for the transaction, in the form of either a Keypair (only the public key is used) or an account ID (in G... or M... form, but refer to withMuxing)
baseFee string

max fee willing to pay per operation in inner transaction (in stroops)
innerTx Transaction

Transaction to be bumped by the fee bump transaction
networkPassphrase string

passphrase of the target Stellar network (e.g. "Public Global Stellar Network ; September 2015", see Networks)
Returns:
Type:
FeeBumpTransaction

(static) cloneFrom(tx, optsopt) → {TransactionBuilder}

Creates a builder instance using an existing Transaction as a template, ignoring any existing envelope signatures.

Note that the sequence number WILL be cloned, so EITHER this transaction or the one it was cloned from will be valid. This is useful in situations where you are constructing a transaction in pieces and need to make adjustments as you go (for example, when filling out Soroban resource information).

Source:
To Do:
Parameters:
Name Type Attributes Description
tx Transaction

a "template" transaction to clone exactly
opts object <optional>

additional options to override the clone, e.g. {fee: '1000'} will override the existing base fee derived from tx (see the TransactionBuilder constructor for detailed options)
Returns:
Type:
TransactionBuilder

a "prepared" builder instance with the same configuration and operations as the given transaction

(static) fromXDR(envelope, networkPassphrase) → {Transaction|FeeBumpTransaction}

Build a Transaction or FeeBumpTransaction from an xdr.TransactionEnvelope.

Source:
Parameters:
Name Type Description
envelope string | xdr.TransactionEnvelope

The transaction envelope object or base64 encoded string.
networkPassphrase string

The network passphrase of the target Stellar network (e.g. "Public Global Stellar Network ; September 2015"), see Networks.
Returns:
Type:
Transaction | FeeBumpTransaction