What are bundled transaction simulations?

Written by Alchemy

Reviewed by Brady Werkheiser

Published on January 25, 20234 min read

---

Bundled transaction simulations enable previewing sequential transactions, where the output of the first simulated transaction is the input of the second simulated transaction. Bundled simulations ensure that people can accurately predict the outcome of a transaction whose results are predicated on the results of a previous transaction. This is often necessary to confirm that assets are available to be transferred and are not staked or locked in another smart contract. 

Alchemy's new Transaction Simulation API, which is one part of a larger suite of web3 transaction products, includes support for simulating asset changes, single transaction simulations, and bundle transaction simulations.

In this article, we’ll cover: 

• What are bundled transaction simulations? 

• How do bundled transactions work?

• How are bundled transactions different from call and trace endpoints?  

• How is the Bundle Simulation API used?

• How to use Alchemy’s Bundle Transaction Simulation API? 

What are bundled transaction simulations? 

Bundled transaction simulations preview how multiple, sequential transactions will behave before they are published on the blockchain. 

Compared to standard simulations that simulate a single transaction, previewing a bundle of transactions previews an ordered set of transactions that are dependent on a previous transaction preview’s result. 

By previewing bundled transactions, users can determine which (if any) of the batched transactions will revert, thereby knowing transaction results ahead of time.

Generally, transaction simulations improve security and offer developers ways to help their web3 users protect themselves against fraudulent transactions and scammers.

How do bundled transactions work? 

With alchemy_simulateBundle, developers pass in an array of transactions to accurately preview sequential transactions, and after each transaction preview, the previous transaction’s state changes are persisted, which allows developers to preview the behavior of multiple contingent transactions.

Here’s an example of how simulating bundles on transactions work:

1. Simulate modifying the chain, without really modifying it to return output 1

2. Input the chain state from simulation 1 (i.e. output 1) to see if a transfer would be successful

Bundle simulation uses more robust infrastructure to sequentially simulate transactions (using outputs of initial transactions as the input of follow-on transactions).

How is the Bundle Transaction API better than eth_call and debug_traceCalls?

It is hard to simulate transactions and preview how your transactions will affect the chain. Existing solutions, e.g., eth_call or debug_traceCall suffer from important limitations:

• Methods only allow simulation of one transaction

• Method outputs are hard-to-parse

• Methods are limited by the data they return 

For example, methods only return results of the executed contract call, but not internal transactions, logs, etc.

Alchemy’s Bundled Transaction Simulation API endpoint solves both limitations, by enabling developers to simulate multiple, sequential transactions, with robust data outputs including logs, events and trace data. 

How is the Bundle Simulation API different from other Transaction Simulation endpoints?

Asset Changes and Execution Simulation can call the simulation API multiple times, but it never persists the state changes that would enable running sequential transactions, whereas with the Bundle Simulation API simulates multiple dependent simulations with persistent state changes after each simulation.

1. Asset Changes

With alchemy_simulateAssetChanges, any transaction can be simulated, and the simulation output will provide clean, simple data showing the changes and approvals of token balances after the transaction is confirmed. 

The Bundle Transaction API endpoint includes this information, but also includes detailed trace data, logs, and event information to give builders and traders a more thorough understanding of how transactions will behave.

2. Execution Simulation 

With alchemy_simulateExecution, developers receive an end-to-end simulation of a single transaction’s EVM execution, inclusive of decoded ABI data, logs, events, and trace data.

While the Execution Simulation API endpoint is more robust than the Asset Changes API, it only displays information for a single transaction. 

Although a single transaction preview is helpful for simple types of transactions, advanced developers and traders running complex transactions will require the robustness of the Bundle Transaction API endpoint to see how a series of transactions behave on the blockchain.

How is the Bundle Simulation API used? 

The general use case for Bundled Simulation is fraud detection and transaction security, ensuring that sequences of transactions are executable by the signer. 

Bundled Simulation will have multiple real-world applications, including but not limited to NFT marketplaces and decentralized exchanges (DEXs).

1. NFT Marketplaces

Bundled Simulations are necessary to detect potential fraud during NFT listings. When a NFT is listed for sale in a NFT auction, it doesn’t guarantee that the NFT is actually transferable in a purchase. The ERC721 token can be staked or locked in another contract, making its “for sale” listing inherently false and misleading. When a purchaser goes to buy the NFT, the transaction would revert. 

Bundled simulations would prevent this with two simulation calls: 

1. Simulation 1: Approve use of NFT by marketplace contract

2. Simulation 2: Call marketplace method to list or transfer NFT

2. Decentralized Exchanges (DEXs)

Bundled Simulations are necessary to prevent one-way swaps. On decentralized exchanges (DEXs) or swapping websites, tokens can be covertly “one-way swappable,” which means that signers can swap a token in, but not swap an token out, thereby, risking and actualizing significant asset loss in the process. 

Bundled simulations would prevent this with multiple simulation calls: 

1. Simulation 1: Confirm token A is swappable

2. Simulation 2: Confirm token B is swappable

3. Simulation 3: Confirm token A will be swapped for token B, from address 1 to address 2

How to Start Using Bundled Transaction Simulations on Alchemy 

Head to our Transaction Simulation Quickstart Guide to get started, and sign up for an Alchemy account to start building today.