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, digitalbits-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 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 XDB 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 nibbs)
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
memo Memo <optional>

memo for the transaction
networkPassphrase string <optional>

passphrase of the target DigitalBits network (e.g. "LiveNet Global DigitalBits Network ; February 2021" for the pubnet)
withMuxing bool <optional>

Indicates that the source account of every transaction created by this Builder can be interpreted as a proper muxed account (i.e. coming from an M... address). By default, this option is disabled until muxed accounts are mature.

Methods

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

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

Source:
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 Attributes 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 nibbs)
innerTx Transaction

Transaction to be bumped by the fee bump transaction
networkPassphrase string

passphrase of the target DigitalBits network (e.g. "LiveNet Global DigitalBits Network ; February 2021")
withMuxing bool <optional>

allows fee sources to be proper muxed accounts (i.e. coming from an M... address). By default, this option is disabled until muxed accounts are mature.
Returns:
Type:
FeeBumpTransaction

(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

networkPassphrase of the target DigitalBits network (e.g. "LiveNet Global DigitalBits Network ; February 2021").
Returns:
Type:
Transaction | FeeBumpTransaction

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.

enableMuxedAccounts() → {TransactionBuilder}

Enable support for muxed accounts for the Transaction that will be built.

Source:
Returns:
Type:
TransactionBuilder

setNetworkPassphrase(networkPassphraseopt) → {TransactionBuilder}

Set network nassphrase for the Transaction that will be built.

Source:
Parameters:
Name Type Attributes Description
networkPassphrase string <optional>

passphrase of the target DigitalBits network (e.g. "LiveNet Global DigitalBits Network ; February 2021").
Returns:
Type:
TransactionBuilder

setTimeout(timeout) → {TransactionBuilder}

Because of the distributed nature of the DigitalBits 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 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 Frontier 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
timeout number

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