PLT-819: Wire fail-closed rate limiter + MethodParser into EVM JSON-RPC HTTP (:8545)

evmrpc/config/config.go

@@ -7,6 +7,7 @@ import (
 	"time"
 
 	"github.com/ethereum/go-ethereum/rpc"
+	"github.com/sei-protocol/sei-chain/ratelimiter"
 	servertypes "github.com/sei-protocol/sei-chain/sei-cosmos/server/types"
 	"github.com/sei-protocol/sei-chain/sei-db/ledger_db/receipt"
 	"github.com/spf13/cast"
@@ -236,12 +237,26 @@ type Config struct {
 	TraceBakeSnapshotWindow int64 `mapstructure:"trace_bake_snapshot_window"` // recent snapshots to keep (default 64)
 
 	// IPRateLimitRPS is the per-IP sustained request rate in requests/second.
-	// Zero disables per-IP rate limiting (all requests pass through).
+	// Zero disables the token bucket (no HTTP 429 rejections). When
+	// rate_limiting_enabled is true, the admission middleware still runs: bodies
+	// are parsed and oversize/malformed requests are rejected before dispatch.
 	IPRateLimitRPS float64 `mapstructure:"ip_rate_limit_rps"`
 
-	// IPRateLimitBurst is the maximum per-IP burst size.
+	// IPRateLimitBurst is the maximum per-IP burst size. Zero disables the token
+	// bucket (same effect as ip_rate_limit_rps = 0) and does not bypass the
+	// admission middleware when rate_limiting_enabled is true. Should be at least
+	// batch_request_limit because the rate limiter charges one token per batch element.
 	IPRateLimitBurst int `mapstructure:"ip_rate_limit_burst"`
 
+	// RateLimitingEnabled is the master switch for the rate-limit admission
+	// middleware on the EVM HTTP plane. When false, requests bypass method
+	// extraction and all rejections from that layer (HTTP 400/413/429).
+	RateLimitingEnabled bool `mapstructure:"rate_limiting_enabled"`
+
+	// TrustedProxyCIDRs lists CIDRs whose X-Forwarded-For headers are trusted when
+	// resolving the client IP for rate limiting. Empty means trust no proxy.
+	TrustedProxyCIDRs []string `mapstructure:"trusted_proxy_cidrs"`
+
 	// BatchRequestLimit is the maximum number of requests allowed in a single
 	// JSON-RPC batch (HTTP and WebSocket). Set to 0 to disable the limit.
 	BatchRequestLimit int `mapstructure:"batch_request_limit"`
@@ -252,8 +267,8 @@ type Config struct {
 
 	// MaxRequestBodyBytes is the maximum size, in bytes, of a single HTTP
 	// JSON-RPC request body. Requests larger than this are rejected (HTTP 413)
-	// before the body is buffered or JSON-decoded. 0 uses the go-ethereum
-	// default (5 MiB).
+	// before the body is buffered or JSON-decoded, including at the rate limiter
+	// method-extraction layer. 0 uses the go-ethereum default (5 MiB).
 	MaxRequestBodyBytes int64 `mapstructure:"max_request_body_bytes"`
 
 	// MaxConcurrentRequestBytes bounds the total size, in bytes, of HTTP
@@ -270,6 +285,8 @@ type Config struct {
 	MaxOpenConnections int `mapstructure:"max_open_connections"`
 }
 
+const defaultBatchRequestLimit = 1000
+
 var DefaultConfig = Config{
 	HTTPEnabled:                  true,
 	HTTPPort:                     8545,
@@ -321,8 +338,10 @@ var DefaultConfig = Config{
 	TraceBakeUseSnapshot:      false,
 	TraceBakeSnapshotWindow:   64,
 	IPRateLimitRPS:            200,
-	IPRateLimitBurst:          400,
-	BatchRequestLimit:         1000,
+	IPRateLimitBurst:          defaultBatchRequestLimit,
+	RateLimitingEnabled:       false,
+	TrustedProxyCIDRs:         nil,
+	BatchRequestLimit:         defaultBatchRequestLimit,
 	BatchResponseMaxSize:      25 * 1000 * 1000,  // 25MB
 	MaxRequestBodyBytes:       5 * 1024 * 1024,   // 5 MiB (matches go-ethereum rpc default body limit)
 	MaxConcurrentRequestBytes: 128 * 1024 * 1024, // 128 MiB of request bodies admitted concurrently
@@ -377,6 +396,8 @@ const (
 	flagTraceBakeSnapshotWindow      = "evm.trace_bake_snapshot_window"
 	flagIPRateLimitRPS               = "evm.ip_rate_limit_rps"
 	flagIPRateLimitBurst             = "evm.ip_rate_limit_burst"
+	flagRateLimitingEnabled          = "evm.rate_limiting_enabled"
+	flagTrustedProxyCIDRs            = "evm.trusted_proxy_cidrs"
 	flagBatchRequestLimit            = "evm.batch_request_limit"
 	flagBatchResponseMaxSize         = "evm.batch_response_max_size"
 	flagMaxRequestBodyBytes          = "evm.max_request_body_bytes"
@@ -631,6 +652,16 @@ func ReadConfig(opts servertypes.AppOptions) (Config, error) {
 			return cfg, err
 		}
 	}
+	if v := opts.Get(flagRateLimitingEnabled); v != nil {
+		if cfg.RateLimitingEnabled, err = cast.ToBoolE(v); err != nil {
+			return cfg, err
+		}
+	}
+	if v := opts.Get(flagTrustedProxyCIDRs); v != nil {
+		if cfg.TrustedProxyCIDRs, err = cast.ToStringSliceE(v); err != nil {
+			return cfg, err
+		}
+	}
 	if v := opts.Get(flagBatchRequestLimit); v != nil {
 		if cfg.BatchRequestLimit, err = cast.ToIntE(v); err != nil {
 			return cfg, err
@@ -659,6 +690,14 @@ func ReadConfig(opts servertypes.AppOptions) (Config, error) {
 			return cfg, fmt.Errorf("%s must be >= 0 (0 disables the limit), got %d", flagMaxOpenConnections, cfg.MaxOpenConnections)
 		}
 	}
+	if cfg.RateLimitingEnabled && cfg.IPRateLimitBurst > 0 && cfg.BatchRequestLimit > 0 &&
+		cfg.IPRateLimitBurst < cfg.BatchRequestLimit {
+		return cfg, fmt.Errorf(
+			"%s (%d) must be >= %s (%d): the rate limiter charges one token per batch element, "+
+				"so a lower burst would permanently reject any full-size batch",
+			flagIPRateLimitBurst, cfg.IPRateLimitBurst, flagBatchRequestLimit, cfg.BatchRequestLimit,
+		)
+	}
 	return cfg, nil
 }
 
@@ -682,6 +721,15 @@ func normalizeNativeTracerNames(flagName string, names []string) ([]string, erro
 	return out, nil
 }
 
+// RateLimiterConfig builds the ratelimiter.Config used by EVM JSON-RPC admission.
+func (c Config) RateLimiterConfig() ratelimiter.Config {
+	return ratelimiter.Config{
+		RPS:               c.IPRateLimitRPS,
+		Burst:             c.IPRateLimitBurst,
+		TrustedProxyCIDRs: c.TrustedProxyCIDRs,
+	}
+}
+
 // ConfigTemplate defines the TOML configuration template for EVM RPC
 const ConfigTemplate = `
 ###############################################################################
@@ -902,12 +950,28 @@ trace_bake_use_snapshot = {{ .EVM.TraceBakeUseSnapshot }}
 trace_bake_snapshot_window = {{ .EVM.TraceBakeSnapshotWindow }}
 
 # ip_rate_limit_rps is the per-IP sustained request rate in requests/second.
-# Set to 0 to disable per-IP rate limiting (all requests pass through).
+# Set to 0 to disable per-IP throttling (no HTTP 429). Does not bypass the
+# admission middleware; set rate_limiting_enabled = false for a full bypass.
 ip_rate_limit_rps = {{ .EVM.IPRateLimitRPS }}
 
 # ip_rate_limit_burst is the maximum per-IP burst above the sustained rate.
+# Set to 0 to disable per-IP throttling (same effect as ip_rate_limit_rps = 0).
+# Must be at least batch_request_limit when both are positive and rate_limiting_enabled
+# is true (one token is charged per batch element) - enforced at startup.
 ip_rate_limit_burst = {{ .EVM.IPRateLimitBurst }}
 
+# rate_limiting_enabled is the master switch for the rate-limit admission
+# middleware on the EVM HTTP plane (:8545). When false, requests bypass method
+# extraction and all rejections from that layer (HTTP 400/413/429).
+rate_limiting_enabled = {{ .EVM.RateLimitingEnabled }}
+
+# trusted_proxy_cidrs lists CIDRs whose X-Forwarded-For headers are trusted when
+# resolving the client IP for rate limiting. Empty means trust no proxy — set
+# this to your ingress/LB CIDRs when the node sits behind a reverse proxy.
+# Do NOT use the full RFC-1918 private ranges unless every address in them is
+# your own controlled infrastructure.
+trusted_proxy_cidrs = [{{- range $i, $c := .EVM.TrustedProxyCIDRs }}{{- if $i }}, {{ end }}"{{ $c }}"{{- end }}]
+
 # batch_request_limit is the maximum number of requests allowed in a single
 # JSON-RPC batch (HTTP and WebSocket). Set to 0 to disable the limit.
 batch_request_limit = {{ .EVM.BatchRequestLimit }}
@@ -918,7 +982,8 @@ batch_response_max_size = {{ .EVM.BatchResponseMaxSize }}
 
 # max_request_body_bytes is the maximum size, in bytes, of a single HTTP
 # JSON-RPC request body. Larger requests are rejected (HTTP 413) before the body
-# is buffered or JSON-decoded. Set to 0 to use the default (5 MiB).
+# is buffered or JSON-decoded, including at the rate limiter method-extraction
+# layer. Set to 0 to use the default (5 MiB).
 max_request_body_bytes = {{ .EVM.MaxRequestBodyBytes }}
 
 # max_concurrent_request_bytes bounds the total size, in bytes, of HTTP JSON-RPC

evmrpc/config/config_fuzz_test.go

@@ -89,6 +89,8 @@ var evmKeys = []configtest.KeySpec{
 	{Key: "evm.trace_bake_snapshot_window", Path: "TraceBakeSnapshotWindow", Cast: configtest.CastInt64, Checked: true},
 	{Key: "evm.ip_rate_limit_rps", Path: "IPRateLimitRPS", Cast: configtest.CastFloat64, Checked: true},
 	{Key: "evm.ip_rate_limit_burst", Path: "IPRateLimitBurst", Cast: configtest.CastInt, Checked: true},
+	{Key: "evm.rate_limiting_enabled", Path: "RateLimitingEnabled", Cast: configtest.CastBool, Checked: true},
+	{Key: "evm.trusted_proxy_cidrs", Path: "TrustedProxyCIDRs", Cast: configtest.CastStringSlice, Checked: true},
 	{Key: "evm.batch_request_limit", Path: "BatchRequestLimit", Cast: configtest.CastInt, Checked: true},
 	{Key: "evm.batch_response_max_size", Path: "BatchResponseMaxSize", Cast: configtest.CastInt, Checked: true},
 	{Key: "evm.max_request_body_bytes", Path: "MaxRequestBodyBytes", Cast: configtest.CastInt64, Checked: true},

evmrpc/config/config_test.go

@@ -44,6 +44,8 @@ type opts struct {
 	workerQueueSize              interface{}
 	ipRateLimitRPS               interface{}
 	ipRateLimitBurst             interface{}
+	rateLimitingEnabled          interface{}
+	trustedProxyCIDRs            interface{}
 	batchRequestLimit            interface{}
 	batchResponseMaxSize         interface{}
 	maxRequestBodyBytes          interface{}
@@ -177,6 +179,12 @@ func (o *opts) Get(k string) interface{} {
 	if k == "evm.ip_rate_limit_burst" {
 		return o.ipRateLimitBurst
 	}
+	if k == "evm.rate_limiting_enabled" {
+		return o.rateLimitingEnabled
+	}
+	if k == "evm.trusted_proxy_cidrs" {
+		return o.trustedProxyCIDRs
+	}
 	if k == "evm.batch_request_limit" {
 		return o.batchRequestLimit
 	}
@@ -247,7 +255,9 @@ func getDefaultOpts() opts {
 		32,
 		1000,
 		200.0,
-		400,
+		1000,
+		nil,
+		nil,
 		1000,
 		25 * 1000 * 1000,
 		int64(5 * 1024 * 1024),
@@ -632,3 +642,61 @@ func TestReadConfigMaxSubscriptionsLogs(t *testing.T) {
 	_, err = config.ReadConfig(&opts)
 	require.Error(t, err)
 }
+
+func TestReadConfigRateLimiting(t *testing.T) {
+	cfg, err := config.ReadConfig(&opts{})
+	require.NoError(t, err)
+	require.False(t, cfg.RateLimitingEnabled)
+	require.Nil(t, cfg.TrustedProxyCIDRs)
+	require.Equal(t, config.DefaultConfig.IPRateLimitRPS, cfg.IPRateLimitRPS)
+	require.Equal(t, config.DefaultConfig.IPRateLimitBurst, cfg.IPRateLimitBurst)
+	require.GreaterOrEqual(t, cfg.IPRateLimitBurst, cfg.BatchRequestLimit)
+
+	o := getDefaultOpts()
+	o.rateLimitingEnabled = false
+	o.trustedProxyCIDRs = []string{"10.0.0.0/8", "203.0.113.0/24"}
+	cfg, err = config.ReadConfig(&o)
+	require.NoError(t, err)
+	require.False(t, cfg.RateLimitingEnabled)
+	require.Equal(t, []string{"10.0.0.0/8", "203.0.113.0/24"}, cfg.TrustedProxyCIDRs)
+
+	rlCfg := cfg.RateLimiterConfig()
+	require.Equal(t, cfg.IPRateLimitRPS, rlCfg.RPS)
+	require.Equal(t, cfg.IPRateLimitBurst, rlCfg.Burst)
+	require.Equal(t, cfg.TrustedProxyCIDRs, rlCfg.TrustedProxyCIDRs)
+}
+
+func TestReadConfigRateLimitingBurstBelowBatchLimitRejected(t *testing.T) {
+	// A burst below batch_request_limit would permanently reject full-size
+	// batches (one token is charged per batch element), so ReadConfig refuses
+	// it outright rather than letting an operator discover it in production.
+	o := getDefaultOpts()
+	o.rateLimitingEnabled = true
+	o.ipRateLimitBurst = 400
+	o.batchRequestLimit = 1000
+	_, err := config.ReadConfig(&o)
+	require.Error(t, err)
+
+	// Equal burst and batch limit is allowed.
+	o.ipRateLimitBurst = 1000
+	_, err = config.ReadConfig(&o)
+	require.NoError(t, err)
+
+	// The check is skipped when rate limiting is disabled...
+	o.rateLimitingEnabled = false
+	o.ipRateLimitBurst = 400
+	_, err = config.ReadConfig(&o)
+	require.NoError(t, err)
+
+	// ...when the token bucket itself is disabled (burst <= 0)...
+	o.rateLimitingEnabled = true
+	o.ipRateLimitBurst = 0
+	_, err = config.ReadConfig(&o)
+	require.NoError(t, err)
+
+	// ...and when the batch limit is unbounded (batch_request_limit <= 0).
+	o.ipRateLimitBurst = 400
+	o.batchRequestLimit = 0
+	_, err = config.ReadConfig(&o)
+	require.NoError(t, err)
+}

evmrpc/config/testdata/evm.golden

@@ -51,7 +51,9 @@ TraceBakeWindowBlocks = int64(0)
 TraceBakeUseSnapshot = bool(false)
 TraceBakeSnapshotWindow = int64(64)
 IPRateLimitRPS = float64(200)
-IPRateLimitBurst = int(400)
+IPRateLimitBurst = int(1000)
+RateLimitingEnabled = bool(false)
+TrustedProxyCIDRs = <nil-slice>
 BatchRequestLimit = int(1000)
 BatchResponseMaxSize = int(25000000)
 MaxRequestBodyBytes = int64(5242880)

evmrpc/metrics.go

@@ -19,8 +19,10 @@ const (
 	jsonrpcCodeKey  = "jsonrpc_code"
 	rejectReasonKey = "reason"
 	// reject reason values for requestRejectedCount.
-	rejectReasonOversize = "oversize" // body exceeded max_request_body_bytes
-	rejectReasonBusy     = "busy"     // max_concurrent_request_bytes budget exhausted
+	rejectReasonOversize    = "oversize"     // body exceeded max_request_body_bytes
+	rejectReasonBusy        = "busy"         // max_concurrent_request_bytes budget exhausted
+	rejectReasonRateLimited = "rate_limited" // per-IP token bucket exhausted
+	rejectReasonUnparseable = "unparseable"  // rate-limit method parse failed (malformed JSON-RPC)
 	// error_class values; empty string ("") means success.
 	errorClassPanic              = "panic"
 	errorClassExecutionReverted  = "execution_reverted"
@@ -167,7 +169,8 @@ func recordHistoricalDebugTraceAttempt(ctx context.Context, endpoint, connection
 }
 
 // recordRequestRejected counts an HTTP JSON-RPC request dropped by pre-decode
-// admission control. reason is one of rejectReasonOversize / rejectReasonBusy.
+// admission control. reason is one of rejectReasonOversize / rejectReasonBusy /
+// rejectReasonRateLimited / rejectReasonUnparseable.
 // No endpoint dimension is recorded: the rejection happens before the JSON-RPC
 // method is decoded, so it is not yet known.
 func recordRequestRejected(ctx context.Context, reason string) {

evmrpc/rate_limit.go

@@ -0,0 +1,66 @@
+package evmrpc
+
+import (
+	"context"
+	"io"
+	"math"
+
+	"github.com/sei-protocol/sei-chain/ratelimiter"
+)
+
+// RateLimitGate applies per-IP token-bucket rate limiting after extracting JSON-RPC
+// method names from the entire request body (bounded by max_request_body_bytes).
+// When enabled, method extraction and fail-closed rejection (HTTP 400/413) run even
+// if the registry is configured with RPS or burst zero (no HTTP 429 only).
+type RateLimitGate struct {
+	registry     *ratelimiter.Registry
+	parser       *ratelimiter.MethodParser
+	maxBodyBytes int64
+	enabled      bool
+	plane        string
+}
+
+// NewRateLimitGate returns a gate for the given plane ("evm"). registry must be non-nil.
+// maxBodyBytes is the same cap as max_request_body_bytes; non-positive values use
+// defaultMaxRequestBodyBytes.
+func NewRateLimitGate(registry *ratelimiter.Registry, maxBodyBytes int64, enabled bool, plane string) *RateLimitGate {
+	if maxBodyBytes <= 0 {
+		maxBodyBytes = defaultMaxRequestBodyBytes
+	}
+	if maxBodyBytes == math.MaxInt64 {
+		maxBodyBytes = math.MaxInt64 - 1
+	}
+	return &RateLimitGate{
+		registry:     registry,
+		parser:       ratelimiter.NewMethodParser(maxBodyBytes),
+		maxBodyBytes: maxBodyBytes,
+		enabled:      enabled,
+		plane:        plane,
+	}
+}
+
+// Check parses body for JSON-RPC method names and applies per-IP rate limits.
+// rejectMethod is the method that exhausted the bucket when allowed=false.
+// Parse errors still charge the bucket under ratelimiter.MethodInvalid so
+// malformed bodies can't bypass rate limiting; if that exhausts the bucket,
+// Check reports a rate-limit rejection instead of returning the parse error.
+func (g *RateLimitGate) Check(ctx context.Context, ip string, body io.Reader) (allowed bool, rejectMethod string, err error) {
+	if !g.enabled {
+		return true, "", nil
+	}
+
+	methods, _, parseErr := g.parser.Parse(body)
+	if parseErr != nil {
+		if !g.registry.Allow(ctx, ip, g.plane, ratelimiter.MethodInvalid) {
+			return false, ratelimiter.MethodInvalid, nil
+		}
+		return false, "", parseErr
+	}
+
+	for _, method := range methods {
+		if !g.registry.Allow(ctx, ip, g.plane, method) {
+			return false, method, nil
+		}
+	}
+	return true, "", nil
+}