Flashbot-sdk NPM

flashbot-sdk

A simple wrapper for the Flashbots API with TypeScript support and latest ethers.js compatibility.

!CAUTION This is a work in progress. It is not yet ready for production use. Some parts of the API are not yet implemented.

List of API endpoints that are implemented:

eth_sendBundle (sendBundle)
eth_callBundle (simulate)
eth_sendPrivateTransaction
eth_sendPrivateRawTransaction
eth_cancelBundle
eth_cancelPrivateTransaction
flashbots_getUserStatsV2 (getUserStats)
flashbots_getBundleStatsV2 (getBundleStatsV2)
flashbots_getSbundleStats
flashbots_setFeeRefundRecipient

Installation

npm install flashbot-sdk # any package manager will do

Usage

import { Flashbot, Relay } from "flashbot-sdk";
import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider("RPC_URL");
const wallet = new Wallet("PRIVATE_KEY", provider);
const flashbot = new Flashbot(Relay.mainnet, provider, wallet);

Functions

sendBundle - Sends a bundle to the Flashbots relay.

Parameters:

Array<{
    txs: Transaction[];
    blockNumber: HexString;
    minTimestamp?: number;
    maxTimestamp?: number;
    revertingTxHashes?: HexString[];
    replacementUuid?: string;
    builders?: FlashbotBuilders[];
}>

simulate - Simulates a bundle on the Flashbots relay.

Parameters:

Array<{
    txs: Transaction[];
    blockNumber: HexString;
    stateBlockNumber: HexString | "latest";
    timestamp?: number;
}>

getBundleStatsV2 - Gets the stats of a bundle on the Flashbots relay.
Parameters:
```
Array<{
    bundleHash: HexString;
    blockNumber: HexString;
}>
```
waitForInclusion - Waits for a bundle to be included in a block.
Parameters:
```
(
    targetBlock: number;
    hashes: HexString[];
)
```
getUserStats - Gets the stats of a user on the Flashbots relay.
Parameters:
```
Array<{
    blockNumber: HexString;
}>
```

Example

Simple example of sending a bundle to the Flashbots relay:

import { Flashbot, Relays, type HexString } from "../core";
import { JsonRpcProvider, parseEther, parseUnits, Wallet, Transaction } from 'ethers';
import { env } from "bun";

const provider = new JsonRpcProvider(env.RPC!);
const user = new Wallet(env.PK!, provider);
const fb = new Flashbot(Relays.SEPOLIA, user, provider);

(async () => {
    const userNonce = await provider.getTransactionCount(user.address);
    const currentBlock = await provider.getBlock("latest");
    if (!currentBlock?.number) throw new Error("Failed to get current block number");
    if (!currentBlock.baseFeePerGas) throw new Error("Failed to get current block base fee");

    const { number: blockNumber, baseFeePerGas } = currentBlock;
    const maxPriority = parseUnits("20", "gwei");
    const maxFee = fb.calculateEffectiveGas(baseFeePerGas, maxPriority);
    const targetBlock = blockNumber + 2;

    const target = [
        Wallet.createRandom(provider),
        Wallet.createRandom(provider),
    ];

    // Incase you want to get your ethers back.
    // for (const t of target) {
    //     console.log(t.address);
    //     console.log(t.privateKey);
    // }

    const sendAmount = parseEther("0.01");

    const txs = await Promise.all(target.map(async (t, i) => {
        const tx = new Transaction();

        tx.to = t.address;
        tx.value = sendAmount;
        tx.chainId = provider._network.chainId;
        tx.nonce = userNonce + i;
        tx.maxFeePerGas = maxFee;
        tx.maxPriorityFeePerGas = maxPriority;

        const gasLimit = await user.estimateGas(tx);
        tx.gasLimit = gasLimit;

        const signedTx = await user.signTransaction(tx);
        return signedTx;
    })) as HexString[];

    const simulate = await fb.simulate([{
        txs,
        blockNumber: `0x${(targetBlock).toString(16)}`,
        stateBlockNumber: `latest`
    }]);

    await simulate.send();

    console.log(JSON.stringify(simulate.simulationResult, null, 2));

    const hashes = simulate.simulationResult.results.map((r) => r.txHash) as HexString[];
    const inclusion = await fb.waitForInclusion(targetBlock, hashes);

    console.log(inclusion);
})().catch(console.error);

You can find more examples in the examples folder.