Create a Batch Transaction

A transaction that allows multiple transactions to be executed atomically in a single network transaction. Batch transactions ensure that all operations either succeed together or fail together, providing ACID properties (atomicity, consistency, isolation, and durability). This feature enables complex transaction flows without requiring smart contracts, simplifying development and offering better user experiences.

When creating a new batch transaction using the BatchTransaction() API you will need an existing account to pay for the associated transaction fee for both the batch transaction itself and each inner transaction.

Transaction Properties

Transaction Integrity

  • Each inner transaction within a batch is treated as a self-contained transaction.

  • If an inner transaction fails, preceding transactions that succeeded will still incur fees, even though their effects are not committed.

  • Inner transactions are individually signed regular transactions.

Transaction Fees

  • The cost to run a batch transaction includes fees for the outer batch transaction and also fees for each inner transaction.

  • Outer and inner transactions are charged separately and may have different payers.

  • Inner transactions that are processed will be charged the regular fees for their transaction type, even if the batch fails.

  • Batch transaction fees are charged regardless of whether the transaction succeeds or fails.

Transaction Signing Requirements

  • The account paying for the batch transaction fee is required to sign the batch transaction.

  • Each inner transaction must be signed by its required signatories.

  • The batch transaction must be signed by all batchKey keys specified in the included transactions.

Limits on Batch Size

  • The maximum number of transactions in a batch is limited to 50 transactions.

  • The maximum size of the batch transaction must not exceed 6KB, including all inner transactions.

  • All inner transactions must execute within the standard transaction valid duration (typically 3 minutes).

Methods

Method
Type
Requirement

setInnerTransactions(<transactions>)

List<Transaction>

Optional

addInnterTransaction(<transaction>)

Transaction

Optional

setBatchKey(<key>)

Key

Required

BatchKey Mechanism

The batchKey that is set during the creation of an inner transaction is a required signature for the encompassing batch transaction. This key ensures only authorized users can submit the batch and keeps all transactions together. When you set a batchKey, the system automatically marks the transaction as part of a batch by setting nodeAccountId to 0.0.0, which helps the network process it correctly.

// Create and execute the batch transaction
BatchTransaction batchTx = new BatchTransaction()
    .addInnerTransaction(mintTx)       // Add first transaction
    .addInnerTransaction(transferTx)   // Add second transaction
    .freezeWith(client)
    .sign(batchKey);              // Sign with the batch key

TransactionResponse txResponse = batchTx.execute(client);

// Request the receipt of the transaction
TransactionReceipt receipt = txResponse.getReceipt(client);

// Get the inner transaction IDs
List<TransactionId> innerTxIds = batchTx.getInnerTransactionIds();

System.out.println("Batch transaction status: " + receipt.status);
for (TransactionId txId : innerTxIds) {
    System.out.println("Inner transaction ID: " + txId);
}

Batchify Helper Method

Get transaction values

Method
Type
Description

getInnerTransactions()

List<Transaction>

Returns the list of transactions in the batch

getInnerTransactionIds()

List<TransactionId>

Returns the generated IDs of the inner transactions

getBatchKey()

Key

Returns the batch key on an inner transaction

// Create a batch transaction
BatchTransaction transaction = new BatchTransaction()
    .addInnerTransaction(mintTx)
    .addInnerTransaction(transferTx);

// Return the transactions in the batch
List<Transaction> transactions = transaction.getTransactions();

// Get the inner transaction IDs (only available after execution)
List<TransactionId> innerTxIds = transaction.getInnerTransactionIds();

Last updated

Was this helpful?