flashbots

README

flashbots ⚡🤖

Package flashbots implements RPC API bindings for the Flashbots relay and mev-geth for use with the w3 package.

Install

go get github.com/lmittmann/flashbots

Getting Started

Connect to the Flashbots relay. The AuthTransport adds the X-Flashbots-Signature header to every request from the client.

// Private key for request authentication
var privKey *ecdsa.PrivateKey

// Connect to Flashbots relay
rpcClient, err := rpc.DialHTTPWithClient(
	"https://relay.flashbots.net",
	&http.Client{
		Transport: flashbots.AuthTransport(privKey),
	},
)

// Create w3 client form rpc client
client := w3.NewClient(rpcClient)
defer client.Close()

Send a bundle to the Flashbots relay.

var (
	bundle types.Transactions // list of signed transactions

	bundleHash common.Hash
)

err := client.Call(
	flashbots.SendBundle(&flashbots.SendBundleRequest{
		Transactions: bundle,
		BlockNumber:  big.NewInt(999_999_999),
	}).Returns(&bundleHash),
)

Note that the Flashbots relay does not support batch requests. Thus, sending more than one request in Client.Call will result in a server error.

RPC Methods

List of supported RPC methods.

Method	Go Code
eth_sendBundle	flashbots.SendBundle(r *flashbots.SendBundleRequest).Returns(bundleHash *common.Hash)
eth_callBundle	flashbots.CallBundle(r *flashbots.CallBundleRequest).Returns(resp *flashbots.CallBundleResponse)
flashbots_getUserStats	flashbots.UserStats(blockNumber *big.Int).Returns(resp *flashbots.UserStatsResponse)
flashbots_getBundleStats	flashbots.BundleStats(bundleHash common.Hash, blockNumber *big.Int).Returns(resp *flashbots.BundleStatsResponse)

Documentation

Overview

Package flashbots implements RPC API bindings for the Flashbots relay and mev-geth for use with the w3 package (github.com/lmittmann/w3).

Example

package main

import (
	"crypto/ecdsa"
	"fmt"
	"math/big"
	"net/http"

	"github.com/ethereum/go-ethereum/common"
	"github.com/ethereum/go-ethereum/core/types"
	"github.com/ethereum/go-ethereum/rpc"
	"github.com/lmittmann/flashbots"
	"github.com/lmittmann/w3"
)

func main() {
	// Private key for request authentication
	var privKey *ecdsa.PrivateKey

	// Connect to relay
	rpcClient, err := rpc.DialHTTPWithClient(
		"https://relay.flashbots.net",
		&http.Client{
			Transport: flashbots.AuthTransport(privKey),
		},
	)
	if err != nil {
		fmt.Printf("Failed to connect to Flashbots relay: %v\n", err)
		return
	}

	client := w3.NewClient(rpcClient)
	defer client.Close()

	// Send bundle
	var (
		bundle types.Transactions // list of signed transactions

		bundleHash common.Hash
	)
	if err := client.Call(
		flashbots.SendBundle(&flashbots.SendBundleRequest{
			Transactions: bundle,
			BlockNumber:  big.NewInt(999_999_999),
		}).Returns(&bundleHash),
	); err != nil {
		fmt.Printf("Failed to send bundle to Flashbots relay: %v\n", err)
		return
	}
	fmt.Printf("Sent bundle successfully: %s\n", bundleHash)
}

Index

• func AuthTransport(privKey *ecdsa.PrivateKey) http.RoundTripper
• func BundleStats(bundleHash common.Hash, blockNumber *big.Int) core.CallFactoryReturns[BundleStatsResponse]
• func CallBundle(r *CallBundleRequest) core.CallFactoryReturns[CallBundleResponse]
• func SendBundle(r *SendBundleRequest) core.CallFactoryReturns[common.Hash]
• func UserStats(blockNumber *big.Int) core.CallFactoryReturns[UserStatsResponse]
• type BundleStatsResponse
• type CallBundleRequest
  • func (c CallBundleRequest) MarshalJSON() ([]byte, error)
• type CallBundleResponse
  • func (c *CallBundleResponse) UnmarshalJSON(input []byte) error
• type CallBundleResult
• type SendBundleRequest
  • func (s SendBundleRequest) MarshalJSON() ([]byte, error)
• type UserStatsResponse
  • func (u *UserStatsResponse) UnmarshalJSON(input []byte) error

Examples

• Package

Functions

func AuthTransport

func AuthTransport(privKey *ecdsa.PrivateKey) http.RoundTripper

AuthTransport returns a http.RoundTripper that adds the 'X-Flashbots-Signature' header to every request.

func BundleStats

func BundleStats(bundleHash common.Hash, blockNumber *big.Int) core.CallFactoryReturns[BundleStatsResponse]

BundleStats requests the bundles Flashbots relay stats. The given block number must be within 20 blocks of the current chain tip.

func CallBundle

func CallBundle(r *CallBundleRequest) core.CallFactoryReturns[CallBundleResponse]

CallBundle simulates a bundle.

func SendBundle

func SendBundle(r *SendBundleRequest) core.CallFactoryReturns[common.Hash]

SendBundle sends the bundle to the client's endpoint.

func UserStats

func UserStats(blockNumber *big.Int) core.CallFactoryReturns[UserStatsResponse]

UserStats requests the users Flashbots relay stats. The given block number must be within 20 blocks of the current chain tip.

Types

type BundleStatsResponse

type BundleStatsResponse struct {
	IsSimulated    bool
	IsSentToMiners bool
	IsHighPriority bool
	SimulatedAt    time.Time
	SubmittedAt    time.Time
	SentToMinersAt time.Time
}

type CallBundleRequest

type CallBundleRequest struct {
	Transactions     types.Transactions // List of signed transactions to simulate in a bundle.
	RawTransactions  [][]byte           // List of signed raw transactions to simulate in a bundle.
	BlockNumber      *big.Int           // Block number for which the bundle is valid.
	StateBlockNumber *big.Int           // Block number of state to use for simulation, "latest" if nil.
	Timestamp        *big.Int           // Timestamp of block used for simulation (Optional).
}

func (CallBundleRequest) MarshalJSON

func (c CallBundleRequest) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

type CallBundleResponse

type CallBundleResponse struct {
	BundleGasPrice    *big.Int
	BundleHash        common.Hash
	CoinbaseDiff      *big.Int
	EthSentToCoinbase *big.Int
	GasFees           *big.Int
	StateBlockNumber  *big.Int
	TotalGasUsed      uint64
	Results           []CallBundleResult
}

func (*CallBundleResponse) UnmarshalJSON

func (c *CallBundleResponse) UnmarshalJSON(input []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.

type CallBundleResult

type CallBundleResult struct {
	CoinbaseDiff      *big.Int
	EthSentToCoinbase *big.Int
	FromAddress       common.Address
	GasFees           *big.Int
	GasPrice          *big.Int
	GasUsed           uint64
	ToAddress         *common.Address
	TxHash            common.Hash
	Value             []byte // Output

	Error  error
	Revert string // Revert reason
}

type SendBundleRequest

type SendBundleRequest struct {
	Transactions      types.Transactions // List of signed transactions to execute in a bundle.
	RawTransactions   [][]byte           // List of signed raw transactions to execute in a bundle.
	BlockNumber       *big.Int           // Block number for which the bundle is valid
	MinTimestamp      *big.Int           // Minimum Unix Timestamp for which the bundle is valid
	MaxTimestamp      *big.Int           // Maximum Unix Timestamp for which the bundle is valid
	RevertingTxHashes []common.Hash      // List of tx hashes in bundle that are allowed to revert.
}

func (SendBundleRequest) MarshalJSON

func (s SendBundleRequest) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

type UserStatsResponse

type UserStatsResponse struct {
	IsHighPriority       bool     // True if the searcher has an high enough reputation to be in the high priority queue.
	AllTimeMinerPayments *big.Int // Total amount paid to miners over all time.
	AllTimeGasSimulated  *big.Int // Total amount of gas simulated across all bundles submitted to the relay.
	Last7dMinerPayments  *big.Int // Total amount paid to miners over the last 7 days.
	Last7dGasSimulated   *big.Int // Total amount of gas simulated across all bundles submitted to the relay in the last 7 days.
	Last1dMinerPayments  *big.Int // Total amount paid to miners over the last day.
	Last1dGasSimulated   *big.Int // Total amount of gas simulated across all bundles submitted to the relay in the last day.
}

func (*UserStatsResponse) UnmarshalJSON

func (u *UserStatsResponse) UnmarshalJSON(input []byte) error

UnmarshalJSON implements the json.Unmarshaler interface.