relay

Documentation

Overview

Package relay implements a module for private bundlers to send batches to the EntryPoint through regular EOA transactions.

Index

• Constants
• type Relayer
  • func New(db *badger.DB, eoa *signer.EOA, eth *ethclient.Client, chainID *big.Int, ...) *Relayer
  • func (r *Relayer) FilterByClientID() gin.HandlerFunc
  • func (r *Relayer) MapUserOpHashToClientID() gin.HandlerFunc
  • func (r *Relayer) SendUserOperation() modules.BatchHandlerFunc
  • func (r *Relayer) SetBannedThreshold(limit int)
  • func (r *Relayer) SetBannedTimeWindow(limit time.Duration)

Constants

const DefaultBanThreshold = 3

const DefaultBanTimeWindow = 7 * 24 * time.Hour

const NoBanThreshold = 0

Types

type Relayer

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

Relayer provides a module that can relay batches with a regular EOA. Relaying batches to the EntryPoint through a regular transaction comes with several important notes:

• The bundler will NOT be operating as a block builder.
• This opens the bundler up to frontrunning.
• In a naive solution, attackers can send a valid op and frontrun the batch to make that op invalid.
• This invalidates the entire batch and the bundler will have to pay for the failed transaction.

In this case, the mitigation strategy is to throttle the sender by a unique identifier or IP address. If a sender submits a UserOperation that causes the batch to revert, then its ID is banned from sending anymore ops to the mempool. This is optimistic in the sense that it will not prevent every case but will mitigate malicious senders spamming the mempool.

This will only work in the case of a private mempool and will not work in the P2P case where ops are propagated through the network and it is impossible to trust a sender's identifier.

func New

func New(
	db *badger.DB,
	eoa *signer.EOA,
	eth *ethclient.Client,
	chainID *big.Int,
	beneficiary common.Address,
	l logr.Logger,
) *Relayer

New initializes a new EOA relayer for sending batches to the EntryPoint with IP throttling protection.

func (*Relayer) FilterByClientID

func (r *Relayer) FilterByClientID() gin.HandlerFunc

FilterByClientID is a custom Gin middleware used to prevent requests from banned clients from adding their userOps to the mempool. Identifiers are prioritized by the following values:

1. X-Forwarded-By header: The first IP address in the array which is assumed to be the client
2. Request.RemoteAddr: The remote IP address

This should be the first middleware on the RPC path.

func (*Relayer) MapUserOpHashToClientID

func (r *Relayer) MapUserOpHashToClientID() gin.HandlerFunc

MapUserOpHashToClientID is a custom Gin middleware used to map a userOpHash to a clientID. This should be placed after the main method call on the RPC path.

func (*Relayer) SendUserOperation

func (r *Relayer) SendUserOperation() modules.BatchHandlerFunc

SendUserOperation returns a BatchHandler that is used by the Bundler to send batches in a regular EOA transaction. It uses the mapping of userOpHash to client ID created by the Gin middleware in order to mitigate DoS attacks.

func (*Relayer) SetBannedThreshold

func (r *Relayer) SetBannedThreshold(limit int)

SetBannedThreshold sets the limit for how many ops can be seen from a client without being included in a batch before it is banned. Default value is 3. A value of 0 will effectively disable client banning, which is useful for debugging.

func (*Relayer) SetBannedTimeWindow

func (r *Relayer) SetBannedTimeWindow(limit time.Duration)

SetBannedTimeWindow sets the limit for how long a banned client will be rejected for. The default value is 24 hours.