📕 How To Bundle

This page documents the steps to see through your first bundle!

Prerequisite

You must have a decent understanding of 💡 Core MEV Concepts before being able to effectively understand the bundling process to a level that lets you troubleshoot why your bundle wasn't included, or if it is likely to be included.

1️⃣ Step 1 - Task Creation

Click on "Add Task" and fill in the desired fields and trigger conditions as normal. There is one requirement: you must set a gas limit.

⚡️ Auto Flip Bundling

When Flip State + Match on Pending is ticked, the bot will automatically bundle your transaction with the pending flip state transaction. If you do not want this to happen, run a separate task with a "Revert Check + Simulate Pending Block" monitor.

🤖 MEV-Only Mode

By default, the bot will send your transactions to relays and the public mempool (via your node). Optionally tick the "MEV Bundle Only" mode if you wish to only send your transactions to private relays and hide your transactions from the mempool.

✍🏽 Whitelist/Signature Mints

Bundling requires sufficient time before the drop to lock in signatures. If signatures are live at the time the drop is live on-chain, bundling is less effective and there is likely not enough time to construct a complete bundle for all your wallets.

In the case you aren't likely to lock in signatures early, it is highly advised to not use "MEV Bundle Only" mode.

2️⃣ Step 2 - Checks & Modifications

In order to view your bundle, you will need to start your task (we will likely change this in the future, so you can preview your bundle before starting).

You can access the bundle view via the "Bundling" tab in your task view.

Bundling View

The bundle view is very powerful. It allows you to view your bundle's transactions, add bribes and other transactions to the bundle interactively, validate your bundle, execute it manually and change bundle validity duration.

Let's go through these one by one!

🤨 Basic Bundle Validation

Your first bundles may not be too easy to land. You need to ensure your transactions within the bundle are valid and won't revert as explained in 💡 Core MEV Concepts. We provide some basic validation/checks to help you identify two fatal issues:

  • Nonce overlaps

    • Checks if you have the same wallet in the bundle twice with the same nonce.

  • Insufficient balance.

    • Checks if your wallet have enough ETH balance to cover Max Fee * Gas Limit.

A more comprehensive validation framework will be introduced in the near future.

For now, simply click the "Validate" button to perform validation.

🤸‍♂️ Flip Bundling

If you have chosen a Flip State condition with Match On Pending enabled, a transaction with a dotted outline should appear in your bundle view, showing you that it expects a flip state transaction to be at the top of the bundle.

🎯 (Optional) Target Blocks

Non-competitive bundles may need multiple blocks until they're picked up/considered for block inclusion. You can choose how many blocks the bundle targets in the future by choosing the number of blocks in the future the bundle will target.

💵 (Optional) Bribing

You can easily add a bribe to your bundle via the "Add Transaction" button.

🤝 (Optional) Custom Transactions

Especially useful for white hat recovery operations, you can add a custom transaction of your choosing.

💎 Example: Gemesis Whitehat Recovery

The "custom transaction" feature was used in combination with our Gemesis signature module.

A specific wallet was compromised and any ETH sent to the wallet was immediately stolen (automated transfer by a malicious person with the private key to the wallet).

In order to claim the Gemesis NFT that wallet was eligible for, a Gemesis claim task was created with that wallet, and a custom transaction was added to the bundle. This transaction was a simple ETH transfer to the compromised wallet. This was placed before the claim transaction, which means that the bundle would:

  1. Send ETH to the compromised wallet

  2. Use that ETH to pay for the gas fee for the Gemesis claim

After this bundle landed on chain. A second custom bundle was sent that used transferFrom to transfer the claimed NFT out of the wallet!

🔁 (Optional) Reset Bundle

Messed up your bundle? Received new signatures that you can't see in the bundle? Simply click the "Reset" button.

This will reset the bundle to its starting state before any modifications were made to it.

3️⃣ Step 3 - Start Task

Start your task like normal!

If you have MEV-only mode enabled, your task will send the bundle when the conditions are met for your task. Otherwise, your task will send both the bundle to your relays, and transactions to your chosen node at the same time.

If you've created a bundle that's eligible and attractive enough, you should see it on chain soon!

👀 Simulation and Relay View

Only once your task has executed/triggered, will you be able to see this view

Those numbers in the headers of the relay status table and simulation table are the target block numbers. Each bundle is submitted for a given target block.

⏰ Relay Status

As your bundle is sent to relays you'll see this in real time. If your bundle is acknowledged by relays, this is a good sign! It means they've received your bundle and will consider it when building their next block.

🤔 Simulation

Alongside submitting your bundle, we run a simulation that does even further checks into your bundle's eligibility. If it says "ACKNOWLEDGED" this is another good sign. It does similar checks to 🤨 Basic Bundle Validationthough, so it's not too indicative of your success chances.

If the simulation fails, you'll be told why if you hover over the error. You can also copy the error for further 🧐 Troubleshooting.

In this case, the bundle had a transaction including a wallet with 0 balance. It has the familiar error:

err: insufficient funds for gas * price + value: address 0x4D2D5a63cf34668919818d23C75C558a104641e1 have 883448998 want 4140005258625000; txhash 0x9024233637c9553bf2c178605943fb5aa5718f85a68a519e72edebf3f2f809cc

✅ Wallet View

If you switch to the "Executors" tab, you will see the bundle transactions within each respective wallet view.

For a MEV-only task, you should see something like this for a succesful bundle!

For a bundle + node task you would see two hashes, one corresponding to the transaction sent via the node, and one which is part of the bundle.

Parallel Node + Relay Execution

Note that both these transactions have the same nonce, which means that there can never be double-spending or overlapping. Either the bundle transaction or initial transaction will be included!

Last updated