Refactor & harden the nonce-aware tx mempool (stacked on #971)

cmd/run/cmd.go

@@ -323,6 +323,7 @@ func init() {
 	Cmd.Flags().DurationVar(&cfg.TxSubmissionSpacing, "tx-submission-spacing", 1200*time.Millisecond, "Minimum gap between consecutive Cadence submissions for the same EOA in the transaction mempool; also serves as the flush deadline for a continuously-fed collection window. Recommended ~1.5x the block production rate.")
 	Cmd.Flags().DurationVar(&cfg.TxPoolTTL, "tx-pool-ttl", 30*time.Second, "How long the transaction mempool holds an out-of-order transaction waiting for its nonce gap to fill, before submitting it anyway.")
 	Cmd.Flags().IntVar(&cfg.TxMaxBatchSize, "tx-max-batch-size", 5, "Maximum number of EVM transactions per EVM.batchRun Cadence transaction in the transaction mempool.")
+	Cmd.Flags().Uint64Var(&cfg.TxMaxNonceGap, "tx-max-nonce-gap", 500, "How far ahead of an EOA's on-chain nonce the transaction mempool accepts a nonce; nonces beyond indexedNonce+gap are rejected as nonce-too-high. 0 means no upper bound. A nonce below the indexed nonce is always rejected as nonce-too-low regardless of this setting.")
 	Cmd.Flags().DurationVar(&cfg.RpcRequestTimeout, "rpc-request-timeout", time.Second*120, "Sets the maximum duration at which JSON-RPC requests should generate a response, before they timeout. The default is 120 seconds.")
 
 	err := Cmd.Flags().MarkDeprecated("init-cadence-height", "This flag is no longer necessary and will be removed in future version. The initial Cadence height is known for testnet/mainnet and this was only required for fresh deployments of EVM Gateway. Once the DB has been initialized, the latest index Cadence height will be used upon start-up.")

config/config.go

@@ -147,6 +147,14 @@ type Config struct {
 	// single EVM.batchRun Cadence transaction by the transaction mempool,
 	// bounded by the Cadence transaction computation limit.
 	TxMaxBatchSize int
+	// TxMaxNonceGap is how far ahead of an EOA's on-chain nonce the transaction
+	// mempool will accept a nonce. A transaction whose nonce exceeds
+	// indexedNonce + TxMaxNonceGap is rejected up front with ErrNonceTooHigh,
+	// giving the client immediate feedback instead of holding an unexecutable tx
+	// until TTL. 0 means no upper bound (any future nonce is accepted). This
+	// bounds only the upper end: a nonce below the indexed nonce is always
+	// rejected with ErrNonceTooLow regardless of this setting.
+	TxMaxNonceGap uint64
 	// RpcRequestTimeout is the maximum duration at which JSON-RPC requests should generate
 	// a response, before they timeout.
 	RpcRequestTimeout time.Duration

models/errors/errors.go

@@ -36,6 +36,13 @@ var (
 	// already been submitted to the network and is awaiting execution. Letting
 	// it through would burn Flow fees on a guaranteed nonce-mismatch failure.
 	ErrInFlightNonce = fmt.Errorf("%w: %s", ErrInvalid, "transaction with the same nonce already submitted")
+	// ErrNonceTooLow is returned when a transaction's nonce is below the EOA's
+	// current on-chain nonce: it has already been used and can never execute.
+	ErrNonceTooLow = fmt.Errorf("%w: %s", ErrInvalid, "nonce too low")
+	// ErrNonceTooHigh is returned when a transaction's nonce is more than the
+	// configured maximum gap ahead of the EOA's on-chain nonce. Such a tx cannot
+	// execute until the gap fills, so it is rejected up front for fast feedback.
+	ErrNonceTooHigh = fmt.Errorf("%w: %s", ErrInvalid, "nonce too high")
 
 	// Storage errors
 

services/requester/nonce_provider.go

@@ -1,6 +1,8 @@
 package requester
 
 import (
+	"sync"
+
 	gethCommon "github.com/ethereum/go-ethereum/common"
 	"github.com/onflow/flow-go/fvm/evm"
 	"github.com/onflow/flow-go/fvm/evm/offchain/query"
@@ -10,25 +12,49 @@ import (
 	"github.com/onflow/flow-evm-gateway/storage/pebble"
 )
 
-// NonceProvider returns the current nonce of the given EOA address.
-// The transaction mempool uses it to determine the expected next nonce.
+// NonceView reads EOA nonces at a single, fixed EVM state (one built block
+// view). The mempool reads many EOAs' nonces from one view per flush tick
+// rather than rebuilding the (expensive) view per address. It is an interface
+// so tests can fake it without constructing a real query.View.
+type NonceView interface {
+	// GetNonce returns the EOA's account nonce (the next nonce to use) at this
+	// view's state. Named GetNonce — not GetNextNonce — because this interface is
+	// satisfied directly by flow-go's query.View, whose method is GetNonce.
+	GetNonce(address gethCommon.Address) (uint64, error)
+}
+
+// NonceProvider returns the next nonce of the given EOA address. The transaction
+// mempool uses it to determine the expected next nonce.
 type NonceProvider interface {
-	// GetNonce returns the current nonce of the given EOA address.
+	// GetNextNonce returns the account nonce of the given EOA — its transaction
+	// count, i.e. the next nonce the EOA should use (matches eth_getTransactionCount).
 	//
 	// A non-nil error represents an EXCEPTION, not an expected condition:
 	// the underlying read is a local state-index lookup that should not
 	// fail under normal operation. Callers must therefore treat an error
 	// as a hard failure (reject the transaction / abort the operation)
 	// rather than a routine, recoverable condition to swallow.
-	GetNonce(address gethCommon.Address) (uint64, error)
+	GetNextNonce(address gethCommon.Address) (uint64, error)
+
+	// GetBlockView returns a NonceView over the latest indexed EVM state. A
+	// non-nil error is an EXCEPTION, same contract as GetNextNonce.
+	GetBlockView() (NonceView, error)
 }
 
 // LocalNonceProvider reads the EOA nonce from the latest height of the
-// local state index.
+// local state index. It caches the built block view and reuses it while the
+// indexed height is unchanged (see GetBlockView).
 type LocalNonceProvider struct {
 	chainID       flowGo.ChainID
 	registerStore *pebble.RegisterStorage
 	blocks        storage.BlockIndexer
+
+	// mu guards the cached view below. The cached view is shared across reads;
+	// callers that read it concurrently must serialize (the mempool does, via
+	// its queueMux).
+	mu           sync.Mutex
+	cachedView   NonceView
+	cachedHeight uint64
 }
 
 var _ NonceProvider = &LocalNonceProvider{}
@@ -45,10 +71,23 @@ func NewLocalNonceProvider(
 	}
 }
 
-func (p *LocalNonceProvider) GetNonce(address gethCommon.Address) (uint64, error) {
+// GetBlockView returns a NonceView over the latest indexed EVM height. The view
+// is cached and reused while the indexed height is unchanged, so a burst of
+// reads within one block — many Add calls, or a collectDueBatches pass — builds
+// the (expensive) view only once. It is rebuilt when a new block is indexed.
+// Reuse is safe because an EOA's on-chain nonce cannot change without a new
+// block being indexed.
+func (p *LocalNonceProvider) GetBlockView() (NonceView, error) {
 	height, err := p.blocks.LatestEVMHeight()
 	if err != nil {
-		return 0, err
+		return nil, err
+	}
+
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.cachedView != nil && p.cachedHeight == height {
+		return p.cachedView, nil
 	}
 
 	viewProvider := query.NewViewProvider(
@@ -60,6 +99,18 @@ func (p *LocalNonceProvider) GetNonce(address gethCommon.Address) (uint64, error
 	)
 
 	view, err := viewProvider.GetBlockView(height)
+	if err != nil {
+		return nil, err
+	}
+
+	p.cachedView = view
+	p.cachedHeight = height
+
+	return view, nil
+}
+
+func (p *LocalNonceProvider) GetNextNonce(address gethCommon.Address) (uint64, error) {
+	view, err := p.GetBlockView()
 	if err != nil {
 		return 0, err
 	}