bundlerpc

README

Flashbots Bundle RPC

BundleRPC implements Flashbots JSON-RPC client that is compatible with the standard Go-Ethereum data types.

For more information about Flashbots RPC, please visit their documentation website.

Quick Start by Example

The following code snippet is incomplete and cannot be run as-is. However, it can be used as the starting point for interacting with the Flashbots RPC.

package main

import (
    "fmt"

    "github.com/adzil/bundlerpc"
    "github.com/ethereum/go-ethereum/core/types"
    "github.com/ethereum/go-ethereum/crypto"
    "github.com/ethereum/go-ethereum/ethclient"
    "github.com/ethereum/go-ethereum/rpc"
)

func main() {
    // Create random private key for signing the Flashbots JSON-RPC payload.
    // Consider using stored private key for long-term usage to build
    // reputation with the Flashbots relay.
    flashbotsKey, err := crypto.GenerateKey()
    if err != nil {
        panic(err)
    }

    // Create new JSON-RPC client using the previously generated private key.
    flashbots, err := bundlerpc.Dial("https://relay.flashbots.net", flashbotsKey)
    if err != nil {
        panic(err)
    }

    // Instantiate the Eth client to obtain the latest block number.
    ethrpc, err := rpc.Dial("http://localhost:8545")
    if err != nil {
        panic(err)
    }
    defer ethrpc.Close()
    eth := ethclient.NewClient(ethrpc)

    // ...Build the actual transactions here...
    var txOne, txTwo *types.Transaction

    // Get the latest block number.
    blockNumber, err := eth.BlockNumber(context.Background())
    if err != nil {
        panic(err)
    }

    // Send transaction bundle of txOne and txTwo using Flashbots relay. Note
    // that you must explicitly set NoSend field in the bind.TransactionOpts to
    // prevent sending them into the public mempool.
    bundle, err := flashbots.SendBundle(context.Background(), bundlerpc.SendBundleParam{
        Txs: []*types.Transaction{
            txOne,
            txTwo,
        },
        BlockNumber: blockNumber,
    })
    if err != nil {
        panic(err)
    }

    // Print the resulting bundle hash.
    fmt.Printf("%#v\n", bundle)
}

Documentation

Index

• type BundleIdentifier
• type BundleStats
• type CallBundleParam
• type CalledBundle
  • func (b *CalledBundle) Identifier() (hash common.Hash, blockNumber uint64)
• type Client
  • func Dial(uri string, privkey *ecdsa.PrivateKey) (*Client, error)
  • func DialWithSigner(uri string, address common.Address, signer HashSigner) (*Client, error)
  • func DialWithSignerFunc(uri string, signerFn SignerFunc) (*Client, error)
  • func (c *Client) Call(ctx context.Context, result interface{}, method string, params ...interface{}) error
  • func (c *Client) CallBundle(ctx context.Context, req CallBundleParam) (*CalledBundle, error)
  • func (c *Client) CancelPrivateTransaction(ctx context.Context, hash common.Hash) (bool, error)
  • func (c *Client) GetBundleStats(ctx context.Context, bundle BundleIdentifier) (*BundleStats, error)
  • func (c *Client) GetUserStats(ctx context.Context, blockNumber uint64) (*UserStats, error)
  • func (c *Client) SendBundle(ctx context.Context, req SendBundleParam) (*SentBundle, error)
  • func (c *Client) SendPrivateTransaction(ctx context.Context, tx *types.Transaction, maxBlockNumber uint64, ...) (common.Hash, error)
• type HashSigner
• type RPCError
  • func (e *RPCError) Error() string
• type SendBundleParam
• type SentBundle
  • func (b *SentBundle) Identifier() (hash common.Hash, blockNumber uint64)
• type SignerFunc
• type TxResult
• type UserStats

Types

type BundleIdentifier

type BundleIdentifier interface {
	Identifier() (hash common.Hash, blockNumber uint64)
}

BundleIdentifier abstracts bundle identification that can be used to fetch its status using GetBundleStats.

type BundleStats

type BundleStats struct {
	IsSimulated    bool      `json:"isSimulated"`
	IsSentToMiners bool      `json:"isSentToMiners"`
	IsHighPriority bool      `json:"isHighPriority"`
	SimulatedAt    time.Time `json:"simulatedAt"`
	SubmittedAt    time.Time `json:"submittedAt"`
	SentToMinersAt time.Time `json:"sentToMinersAt"`
}

type CallBundleParam

type CallBundleParam struct {
	Txs              []*types.Transaction
	BlockNumber      uint64
	StateBlockNumber rpc.BlockNumber
	Timestamp        time.Time
}

type CalledBundle

type CalledBundle struct {
	BundleHash        common.Hash `json:"bundleHash"`
	BlockNumber       uint64      `json:"-"`
	CoinbaseDiff      *big.Int    `json:"coinbaseDiff"`
	ETHSentToCoinbase *big.Int    `json:"ethSentToCoinbase"`
	GasFees           *big.Int    `json:"gasFees"`
	TotalGasUsed      uint64      `json:"totalGasUsed"`
	StateBlockNumber  uint64      `json:"stateBlockNumber"`
	Results           []TxResult  `json:"results"`
	FirstRevert       *TxResult   `json:"firstRevert"`
}

func (*CalledBundle) Identifier

func (b *CalledBundle) Identifier() (hash common.Hash, blockNumber uint64)

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client implements the Flashbots RPC client. Use Dial or DialWithSigner to instantiate a new Client.

func Dial

func Dial(uri string, privkey *ecdsa.PrivateKey) (*Client, error)

Dial creates new Flashbots RPC client using private key to sign the payload.

func DialWithSigner

func DialWithSigner(uri string, address common.Address, signer HashSigner) (*Client, error)

DialWithSigner creates new Flashbots RPC client using an external hash signer.

func DialWithSignerFunc

func DialWithSignerFunc(uri string, signerFn SignerFunc) (*Client, error)

DialWithSignerFunc creates new Flashbots RPC client using custom hash signer function.

func (*Client) Call

func (c *Client) Call(ctx context.Context, result interface{}, method string, params ...interface{}) error

Call arbitrary RPC method with params and optional result interface. If result set to nil it will not decode returned values from the server. Any errors generated from the RPC server will be returned as *RPCError.

func (*Client) CallBundle

func (c *Client) CallBundle(ctx context.Context, req CallBundleParam) (*CalledBundle, error)

CallBundle simulates the transaction bundle and returns the execution result in CalledBundle.

func (*Client) CancelPrivateTransaction

func (c *Client) CancelPrivateTransaction(ctx context.Context, hash common.Hash) (bool, error)

CancelPrivateTransaction cancels the ongoing private transaction inside the Flashbots relay.

func (*Client) GetBundleStats

func (c *Client) GetBundleStats(ctx context.Context, bundle BundleIdentifier) (*BundleStats, error)

GetBundleStats returns the bundle status.

func (*Client) GetUserStats

func (c *Client) GetUserStats(ctx context.Context, blockNumber uint64) (*UserStats, error)

GetUserStats returns the current user status.

func (*Client) SendBundle

func (c *Client) SendBundle(ctx context.Context, req SendBundleParam) (*SentBundle, error)

SendBundle sends signed transaction bundle to the Flashbots relay. The returned SentBundle can be passed to GetBundleStats to check the bundle status inside the relay.

func (*Client) SendPrivateTransaction

func (c *Client) SendPrivateTransaction(
	ctx context.Context, tx *types.Transaction, maxBlockNumber uint64, fastMode bool,
) (common.Hash, error)

SendPrivateTransaction sends private transaction to the Flashbots RPC. The returned transaction hash can be used to cancel the transaction using the CancelPrivateTransaction.

type HashSigner

type HashSigner interface {
	SignHash(acc accounts.Account, hash []byte) ([]byte, error)
}

HashSigner abstracts an external hash signer.

type RPCError

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

RPCError represents error that is returned from the RPC server.

func (*RPCError) Error

func (e *RPCError) Error() string

type SendBundleParam

type SendBundleParam struct {
	Txs            []*types.Transaction
	BlockNumber    uint64
	MinTimestamp   time.Time
	MaxTimestamp   time.Time
	AllowRevertTxs []*types.Transaction
}

type SentBundle

type SentBundle struct {
	BundleHash  common.Hash `json:"bundleHash"`
	BlockNumber uint64      `json:"-"`
}

func (*SentBundle) Identifier

func (b *SentBundle) Identifier() (hash common.Hash, blockNumber uint64)

type SignerFunc

type SignerFunc func(hash []byte) ([]byte, error)

SignerFunc is a generic hash signer function placeholder to support custom keystore implementation.

type TxResult

type TxResult struct {
	CoinbaseDiff      *big.Int       `json:"coinbaseDiff"`
	ETHSentToCoinbase *big.Int       `json:"ethSentToCoinbase"`
	GasFees           *big.Int       `json:"gasFees"`
	GasPrice          *big.Int       `json:"gasPrice"`
	GasUsed           uint64         `json:"gasUsed"`
	From              common.Address `json:"fromAddress"`
	To                common.Address `json:"toAddress"`
	Hash              common.Hash    `json:"txHash"`
	Value             *big.Int       `json:"value"`
	Error             string         `json:"error"`
	Revert            string         `json:"revert"`
}

type UserStats

type UserStats struct {
	IsHighPriority         bool     `json:"is_high_priority"`
	AllTimeMinerPayments   *big.Int `json:"all_time_miner_payments"`
	AllTimeGasSimulated    *big.Int `json:"all_time_gas_simulated"`
	Last7DaysMinerPayments *big.Int `json:"last_7d_miner_payments"`
	Last7DaysGasSimulated  *big.Int `json:"last_7d_gas_simulated"`
	Last1DayMinerPayments  *big.Int `json:"last_1d_miner_payments"`
	Last1DayGasSimulated   *big.Int `json:"last_1d_gas_simulated"`
}