proxyd

package module
v0.0.0-...-e3806a8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 12, 2026 License: MIT Imports: 60 Imported by: 0

README

rpc-proxy

This tool implements proxyd, an RPC request router and proxy. It does the following things:

  1. Whitelists RPC methods.
  2. Routes RPC methods to groups of backend services.
  3. Automatically retries failed backend requests.
  4. Track backend consensus (latest, safe, finalized blocks), peer count and sync state.
  5. Re-write requests and responses to enforce consensus.
  6. Load balance requests across backend services.
  7. Cache immutable responses from backends.
  8. Provides metrics to measure request latency, error rates, and the like.

Usage

Run make proxyd to build the binary. No additional dependencies are necessary.

To configure proxyd for use, you'll need to create a configuration file to define your proxy backends and routing rules. Check out example.config.toml for how to do this alongside a full list of all options with commentary.

Once you have a config file, start the daemon via proxyd <path-to-config>.toml.

WebSockets

WebSocket support is enabled with ws_port, ws_backend_group, and ws_method_whitelist. The whitelist controls which methods are accepted on the WS endpoint. By default, accepted WS methods are proxied directly to the selected upstream WS backend connection, which is the expected behavior for stateful methods such as eth_subscribe.

To enable a WS method to run through the intelligent filtering/load-balancing described below, also add it to rpc_method_mappings. Mapped WS methods use backend-group forwarding, so they can receive transaction filtering, rate limiting, retries, and consensus-aware routing. Transaction submission or validation methods that are whitelisted but unmapped are rejected instead of being forwarded directly over WS.

Consensus awareness

Starting on v4.0.0, proxyd is aware of the consensus state of its backends. This helps minimize chain reorgs experienced by clients.

To enable this behavior, you must set consensus_aware value to true in the backend group.

When consensus awareness is enabled, proxyd will poll the backends for their states and resolve a consensus group based on:

  • the common ancestor latest block, i.e. if a backend is experiencing a fork, the fork won't be visible to the clients
  • the lowest safe block
  • the lowest finalized block
  • peer count
  • sync state

The backend group then acts as a round-robin load balancer distributing traffic equally across healthy backends in the consensus group, increasing the availability of the proxy.

A backend is considered healthy if it meets the following criteria:

  • not banned
  • avg 1-min moving window error rate ≤ configurable threshold
  • avg 1-min moving window latency ≤ configurable threshold
  • peer count ≥ configurable threshold
  • latest block lag ≤ configurable threshold
  • last state update ≤ configurable threshold
  • not currently syncing

When a backend is experiencing inconsistent consensus, high error rates or high latency, the backend will be banned for a configurable amount of time (default 5 minutes) and won't receive any traffic during this period.

Tag rewrite

When consensus awareness is enabled, proxyd will enforce the consensus state transparently for all the clients.

For example, if a client requests the eth_getBlockByNumber method with the latest tag, proxyd will rewrite the request to use the resolved latest block from the consensus group and forward it to the backend.

The following request methods are rewritten:

  • eth_getLogs
  • eth_newFilter
  • eth_getBalance
  • eth_getCode
  • eth_getTransactionCount
  • eth_call
  • eth_getStorageAt
  • eth_getBlockTransactionCountByNumber
  • eth_getUncleCountByBlockNumber
  • eth_getBlockByNumber
  • eth_getTransactionByBlockNumberAndIndex
  • eth_getUncleByBlockNumberAndIndex
  • debug_getRawReceipts

And eth_blockNumber response is overridden with current block consensus.

Cacheable methods

Cache use Redis and can be enabled for the following immutable methods:

  • eth_chainId
  • net_version
  • eth_getBlockTransactionCountByHash
  • eth_getUncleCountByBlockHash
  • eth_getBlockByHash
  • eth_getTransactionByBlockHashAndIndex
  • eth_getUncleByBlockHashAndIndex
  • debug_getRawReceipts (block hash only)

Meta method consensus_getReceipts

To support backends with different specifications in the same backend group, proxyd exposes a convenient method to fetch receipts abstracting away what specific backend will serve the request.

Each backend specifies their preferred method to fetch receipts with consensus_receipts_target config, which will be translated from consensus_getReceipts.

This method takes a blockNumberOrHash (i.e. tag|qty|hash) and returns the receipts for all transactions in the block.

Request example

{
  "jsonrpc":"2.0",
  "id": 1,
  "params": ["0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b"]
}

It currently supports translation to the following targets:

  • debug_getRawReceipts(blockOrHash) (default)
  • alchemy_getTransactionReceipts(blockOrHash)
  • parity_getBlockReceipts(blockOrHash)
  • eth_getBlockReceipts(blockOrHash)

The selected target is returned in the response, in a wrapped result.

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "method": "debug_getRawReceipts",
    "result": {
      // the actual raw result from backend
    }
  }
}

See op-node receipt fetcher.

Transaction UX monitor (tx_monitor)

When [tx_monitor] is enabled, proxyd passively measures the latency from when an eth_sendRawTransaction request is received until the transaction becomes visible in a block (and, optionally, in a subblocks preconfirmation stream). The clock starts at request ingress, so the measured latency includes proxyd-internal handling and the forward round-trip, not just the backend-ack-to-block window. Transactions rejected by validation or by the backend node (e.g. nonce too low) are never enrolled and so never counted. Results are reported as proxyd_txmon_* metrics. The monitor is purely observational: observations are non-blocking and never affect request handling, and its state is in-memory and shared-nothing across replicas — each proxyd instance only tracks the transactions it forwarded itself. Setting subblocks_ws_url additionally measures preconfirmation latency from a sequencer's subblocks websocket stream.

Frontend rate limits

[rate_limit] configures the base request quota and per-method quotas. A call to a method with an override counts only against that method's quota; every other call counts against the base quota. By default, both are keyed by client IP, using X-Forwarded-For (or ip_header_override) with a fallback to the connection's remote IP.

Set use_auth_alias = true to key authenticated requests by their configured [authentication] alias instead:

[authentication]
"$CLIENT_A_KEY" = "client_a"
"$CLIENT_B_KEY" = "client_b"

[rate_limit]
use_auth_alias = true
base_rate = 100
base_interval = "1s"
use_redis = false

[rate_limit.method_overrides.debug_traceTransaction]
limit = 5
interval = "1s"

Different aliases have independent quotas even when they share an IP. Requests with the same alias share a quota across IPs and credentials, including mapped WebSocket calls and individual calls within HTTP batches. Unauthenticated requests keep their IP-based quotas, and existing exemptions still apply. An override's global = true disables Origin/User-Agent exemptions for that method; its quota still uses the selected IP or alias.

Per-alias overrides

With use_auth_alias = true, [rate_limit.alias_overrides.<alias>] replaces the global limits for a single alias. Each key must be an alias defined in [authentication], otherwise proxyd fails to start.

# Own base: replaces the global base and all global method overrides.
[rate_limit.alias_overrides.client_a]
base_rate = 1000
base_interval = "1s"

[rate_limit.alias_overrides.client_a.method_overrides.debug_traceTransaction]
limit = 50
interval = "1s"

# Method overrides only: keeps the global base and global method overrides while adding/replacing the following method-override.
[rate_limit.alias_overrides.client_b.method_overrides.eth_getLogs]
limit = 0 # blocks eth_getLogs for client_b
interval = "1s"

# Unlimited, except for the methods it overrides.
[rate_limit.alias_overrides.client_c]
infinite_rate_limit = true

[rate_limit.alias_overrides.client_c.method_overrides.debug_traceTransaction]
limit = 10
interval = "1s"
  • An alias has its own base when it sets both base_rate and base_interval, or infinite_rate_limit = true. Its limits are then only its own base and its own method overrides. Global method overrides no longer apply to it, so repeat any you still want under the alias.
  • Otherwise the alias keeps the global base and global method overrides, and its method overrides replace or add to them.
  • A method override sets both limit and interval, or infinite_rate_limit = true to leave that method unlimited for the alias. limit = 0 blocks the method.
  • base_rate must be greater than 0, intervals must be at least 1s, infinite_rate_limit cannot be combined with the rate or limit fields at the same level, and an override must set something.
  • use_redis, exemptions, global, ip_header_override and error_message stay global settings. Unknown keys under an override are ignored.

With use_redis = true, quotas are shared across proxyd instances using the same Redis and alias configuration. Alias buckets use rate_limit:auth_alias:<scope>:<alias>:<window> keys, where the scope is main or the method name; IP buckets keep their existing keys. Without Redis, or during fallback to memory, quotas are local to each instance.

Rate-limit rejections are attributed by alias in proxyd_rpc_errors_total{auth="client_a", backend_name="proxyd", error_code="-32016"}. Directly relayed WebSocket methods are outside frontend rate limiting; add a method to rpc_method_mappings as well as the WS whitelist to apply these limits.

Metrics

See metrics.go for a list of all available metrics.

The metrics port is configurable via the metrics.port and metrics.host keys in the config.

Adding Backend SSL Certificates in Docker

The Docker image includes the default Alpine CA certificate bundle. To add custom certificates, bind mount PEM files directly into /etc/ssl/certs/.

Documentation

Overview

backend_probe.go implements HTTP health check probing for backend servers.

The probe system is inspired by Kubernetes liveness/readiness probes and provides:

  • Periodic HTTP health checks against a configurable endpoint
  • Configurable success/failure thresholds to prevent flapping
  • Async operation via a background goroutine per backend

Usage

When a backend is configured with a probe_url, a ProbeWorker runs in the background, periodically checking the endpoint. The backend is only marked unhealthy after FailureThreshold consecutive failures, and only marked healthy after SuccessThreshold consecutive successes. This threshold behavior prevents health status from flapping due to transient network issues.

Configuration

ProbeSpec controls the probe behavior:

  • FailureThreshold: consecutive failures before marking unhealthy (default: 1)
  • SuccessThreshold: consecutive successes before marking healthy (default: 2)
  • Period: interval between probes (default: 4s)
  • Timeout: HTTP request timeout per probe (default: 4s)

HTTP Probe Behavior

The probe sends a GET request to the configured URL. Success is determined by:

  • 2xx status codes: success
  • 3xx (redirects), 4xx, 5xx, or connection errors: failure

The probe uses a custom dialer with SO_LINGER set (borrowed from Kubernetes) to ensure clean connection teardown, and disables keep-alives to get fresh connection state each probe.

Index

Constants

View Source
const (
	JSONRPCVersion = "2.0"
	// JSONRPCErrorInternal is geth's implementation-defined server error code;
	// jsonRPCSpecInternalError is the JSON-RPC 2.0 spec "Internal error" code.
	// Both are treated as internal (non-verdict) errors.
	JSONRPCErrorInternal = -32000
)
View Source
const (
	MetricsNamespace = "proxyd"

	RPCRequestSourceHTTP = "http"
	RPCRequestSourceWS   = "ws"

	BackendProxyd    = "proxyd"
	BackendCache     = "cache"
	SourceClient     = "client"
	SourceBackend    = "backend"
	MethodUnknown    = "unknown"
	MethodNotAllowed = "method_not_allowed"
	// MethodBatch is the method_name label for an HTTP request whose body is a
	// JSON-RPC batch. One request carries many methods, so it cannot take a real one.
	MethodBatch = "<batch>"

	// StatusCodeRelayed marks a WS call relayed to the backend whose response
	// cannot be correlated back to the request (eth_subscribe / eth_unsubscribe).
	// Deliberately non-numeric so status_code=~"2.." and status_code=~"5.." can
	// never match it: such a call is neither a success nor a failure.
	StatusCodeRelayed = "relayed"
)
View Source
const (
	ContextKeyAuth                      = "authorization"
	ContextKeyReqID                     = "req_id"
	ContextKeyXForwardedFor             = "x_forwarded_for"
	ContextKeyOpTxProxyAuth             = "op_txproxy_auth"
	ContextKeyInteropValidationStrategy = "interop_validation_strategy"
	ContextKeyReqReceivedAt             = "req_received_at"
	DefaultOpTxProxyAuthHeader          = "X-Optimism-Signature"
	DefaultMaxBatchRPCCallsLimit        = 100
	MaxBatchRPCCallsHardLimit           = 1000
)
View Source
const ConsensusGetReceiptsMethod = "consensus_getReceipts"
View Source
const (
	DefaultPollerInterval = 1 * time.Second
)
View Source
const ReceiptsTargetAlchemyGetTransactionReceipts = "alchemy_getTransactionReceipts"
View Source
const ReceiptsTargetDebugGetRawReceipts = "debug_getRawReceipts"
View Source
const ReceiptsTargetEthGetTransactionReceipts = "eth_getBlockReceipts"
View Source
const ReceiptsTargetParityGetTransactionReceipts = "parity_getBlockReceipts"

Variables

View Source
var (
	ErrParseErr = &RPCErr{
		Code:          -32700,
		Message:       "parse error",
		HTTPErrorCode: 400,
	}
	ErrInternal = &RPCErr{
		Code:          JSONRPCErrorInternal,
		Message:       "internal error",
		HTTPErrorCode: 500,
	}
	ErrMethodNotWhitelisted = &RPCErr{
		Code:          notFoundRpcError,
		Message:       "rpc method is not whitelisted",
		HTTPErrorCode: 403,
	}
	ErrBackendOffline = &RPCErr{
		Code:          JSONRPCErrorInternal - 10,
		Message:       "backend offline",
		HTTPErrorCode: 503,
	}
	ErrNoBackends = &RPCErr{
		Code:          JSONRPCErrorInternal - 11,
		Message:       "no backend is currently healthy to serve traffic",
		HTTPErrorCode: 503,
	}
	ErrBackendOverCapacity = &RPCErr{
		Code:          JSONRPCErrorInternal - 12,
		Message:       "backend is over capacity",
		HTTPErrorCode: 429,
	}
	ErrBackendBadResponse = &RPCErr{
		Code:          JSONRPCErrorInternal - 13,
		Message:       "backend returned an invalid response",
		HTTPErrorCode: 500,
	}
	ErrTooManyBatchRequests = &RPCErr{
		Code:    JSONRPCErrorInternal - 14,
		Message: "too many RPC calls in batch request",

		HTTPErrorCode: 413,
	}
	ErrGatewayTimeout = &RPCErr{
		Code:          JSONRPCErrorInternal - 15,
		Message:       "gateway timeout",
		HTTPErrorCode: 504,
	}
	ErrOverRateLimit = &RPCErr{
		Code:          JSONRPCErrorInternal - 16,
		Message:       "over rate limit",
		HTTPErrorCode: 429,
	}
	ErrOverSenderRateLimit = &RPCErr{
		Code:          JSONRPCErrorInternal - 17,
		Message:       "sender is over rate limit",
		HTTPErrorCode: 429,
	}
	ErrNotHealthy = &RPCErr{
		Code:          JSONRPCErrorInternal - 18,
		Message:       "backend is currently not healthy to serve traffic",
		HTTPErrorCode: 503,
	}
	ErrRequestBodyTooLarge = &RPCErr{
		Code:          JSONRPCErrorInternal - 21,
		Message:       "request body too large",
		HTTPErrorCode: 413,
	}

	ErrBackendResponseTooLarge = &RPCErr{
		Code:          JSONRPCErrorInternal - 20,
		Message:       "backend response too large",
		HTTPErrorCode: 400,
	}

	ErrInteropAccessListOutOfBounds = &RPCErr{
		Code:          JSONRPCErrorInternal - 22,
		Message:       "access list out of bounds",
		HTTPErrorCode: 413,
	}

	ErrContextCanceled = &RPCErr{
		Code:          JSONRPCErrorInternal - 23,
		Message:       context.Canceled.Error(),
		HTTPErrorCode: 499,
	}

	ErrTooManyRequests = &RPCErr{
		Code:          JSONRPCErrorInternal - 24,
		Message:       "too many requests",
		HTTPErrorCode: 429,
	}

	ErrTransactionRejected = &RPCErr{
		Code:          JSONRPCErrorInternal - 100,
		Message:       "transaction rejected",
		HTTPErrorCode: 400,
	}

	// Out-of-range answers keep HTTP 200, as an execution client's do. -32001 is
	// EIP-1898's "Resource not found", which op-reth returns for an unknown block.
	ErrBlockNotFound = &RPCErr{
		Code:    -32001,
		Message: "block not found",
	}

	// What op-geth and op-reth return for an eth_getLogs range past their head.
	ErrBlockRangeBeyondHead = &RPCErr{
		Code:    -32602,
		Message: "block range extends beyond current head block",
	}

	ErrCLConsensusSyncNotReady = &RPCErr{
		Code:          JSONRPCErrorInternal - 25,
		Message:       "optimism_syncStatus not available",
		HTTPErrorCode: 503,
	}

	ErrBackendUnexpectedJSONRPC = errors.New("backend returned an unexpected JSON-RPC response")

	ErrConsensusGetReceiptsCantBeBatched = errors.New("consensus_getReceipts cannot be batched")
	ErrConsensusGetReceiptsInvalidTarget = errors.New("unsupported consensus_receipts_target")
)
View Source
var (
	ErrRewriteBlockOutOfRange = errors.New("block is out of range")
	ErrRewriteRangeTooLarge   = errors.New("block range is too large")
)
View Source
var DefaultTxValidationMethods = []string{
	"eth_sendRawTransaction",
	"eth_sendRawTransactionConditional",
	"eth_sendBundle",
}
View Source
var ErrLimitReaderOverLimit = errors.New("over read limit")
View Source
var MillisecondDurationBuckets = []float64{1, 10, 50, 100, 500, 1000, 5000, 10000, 100000}
View Source
var NoopFrontendRateLimiter = &noopFrontendRateLimiter{}
View Source
var PayloadSizeBuckets = []float64{100, 500, 1000, 10000, 100000, 1000000, 2500000, 5000000, 7500000, 10000000, 25000000}
View Source
var WithAccessListSizeLimit = func(accessListSizeLimit int) commonStrategyOpt {
	return func(s *commonInteropStrategy) {
		s.accessListSizeLimit = accessListSizeLimit
	}
}
View Source
var WithChainID = func(chainID uint64) commonStrategyOpt {
	return func(s *commonInteropStrategy) {
		s.chainID = eth.ChainIDFromUInt64(chainID)
	}
}
View Source
var WithReqSizeLimit = func(reqSizeLimit int) commonStrategyOpt {
	return func(s *commonInteropStrategy) {
		s.reqSizeLimit = reqSizeLimit
	}
}
View Source
var WithValidateAndDeduplicateInteropAccessList = func(validateAndDeduplicateInteropAccessList bool) commonStrategyOpt {
	return func(s *commonInteropStrategy) {
		s.validateAndDeduplicateInteropAccessList = validateAndDeduplicateInteropAccessList
	}
}

Functions

func CheckRedisConnection

func CheckRedisConnection(client redis.UniversalClient) error

func CommonStrategyOpts

func CommonStrategyOpts(opts ...commonStrategyOpt) []commonStrategyOpt

func CreateTLSClient

func CreateTLSClient(ca string) (*tls.Config, error)

func GetAuthCtx

func GetAuthCtx(ctx context.Context) string

func GetOpTxProxyAuthHeader

func GetOpTxProxyAuthHeader(ctx context.Context) string

func GetReqID

func GetReqID(ctx context.Context) string

func GetReqReceivedAt

func GetReqReceivedAt(ctx context.Context) time.Time

GetReqReceivedAt returns the wall-clock time the request was received at ingress, stamped by populateContext (HTTP) or per-message in the WS pump. It falls back to time.Now() when unset (internal or test callers) so the tx monitor never records a zero start time.

func GetXForwardedFor

func GetXForwardedFor(ctx context.Context) string

func IsBatch

func IsBatch(raw []byte) bool

func IsValidID

func IsValidID(id json.RawMessage) bool

func LimitReader

func LimitReader(r io.Reader, n int64) io.Reader

func MaybeRecordErrorsInRPCRes

func MaybeRecordErrorsInRPCRes(ctx context.Context, backendName string, reqs []*RPCReq, resBatch []*RPCRes)

func MaybeRecordSpecialRPCError

func MaybeRecordSpecialRPCError(ctx context.Context, backendName, method string, rpcErr *RPCErr)

func NewAgreementStrategy

func NewAgreementStrategy(urls []string, minResponses int, opts ...commonStrategyOpt) *agreementStrategyImpl

func NewCommonInteropStrategy

func NewCommonInteropStrategy(urls []string, opts ...commonStrategyOpt) *commonInteropStrategy

func NewFirstFilterStrategy

func NewFirstFilterStrategy(urls []string, opts ...commonStrategyOpt) *firstFilterStrategyImpl

func NewHealthAwareBackend

func NewHealthAwareBackend(url string, unhealthinessTimeout time.Duration) *healthAwareBackend

func NewHealthAwareLoadBalancingStrategy

func NewHealthAwareLoadBalancingStrategy(urls []string, unhealthinessTimeout time.Duration, opts ...commonStrategyOpt) *healthAwareLoadBalancingStrategyImpl

func NewLoadBalancingBuffer

func NewLoadBalancingBuffer(urls []string, unhealthinessTimeout time.Duration) *loadBalancingBuffer

func NewMulticallStrategy

func NewMulticallStrategy(urls []string, opts ...commonStrategyOpt) *multicallStrategyImpl

func NewRedisClient

func NewRedisClient(url string, enable_cluster bool) (redis.UniversalClient, error)

func ParseBatchRPCReq

func ParseBatchRPCReq(body []byte) ([]json.RawMessage, error)

func ParseKeyPair

func ParseKeyPair(crt, key string) (tls.Certificate, error)

func ReadFromEnvOrConfig

func ReadFromEnvOrConfig(value string) (string, error)

func RecordBackendFinalizedBlock

func RecordBackendFinalizedBlock(b *Backend, blockNumber hexutil.Uint64)

func RecordBackendGroupFallbacks

func RecordBackendGroupFallbacks(bg *BackendGroup, name string, fallback bool)

func RecordBackendGroupMulticallCompletion

func RecordBackendGroupMulticallCompletion(bg *BackendGroup, backendName string, error string)

func RecordBackendGroupMulticallRequest

func RecordBackendGroupMulticallRequest(bg *BackendGroup, backendName string)

func RecordBackendLatestBlock

func RecordBackendLatestBlock(b *Backend, blockNumber hexutil.Uint64)

func RecordBackendNetworkErrorRateSlidingWindow

func RecordBackendNetworkErrorRateSlidingWindow(b *Backend, rate float64)

func RecordBackendNetworkLatencyAverageSlidingWindow

func RecordBackendNetworkLatencyAverageSlidingWindow(b *Backend, avgLatency time.Duration)

func RecordBackendProbeCheck

func RecordBackendProbeCheck(backendName string, success bool)

func RecordBackendProbeDuration

func RecordBackendProbeDuration(backendName string, duration time.Duration)

func RecordBackendProbeHealthy

func RecordBackendProbeHealthy(backendName string, healthy bool)

func RecordBackendSafeBlock

func RecordBackendSafeBlock(b *Backend, blockNumber hexutil.Uint64)

func RecordBackendUnexpectedBlockTags

func RecordBackendUnexpectedBlockTags(b *Backend, unexpected bool)

func RecordBatchRPCError

func RecordBatchRPCError(ctx context.Context, backendName string, reqs []*RPCReq, err error)

func RecordBatchRPCForward

func RecordBatchRPCForward(ctx context.Context, backendName string, reqs []*RPCReq, source string)

func RecordBatchSize

func RecordBatchSize(size int)

func RecordCLBackendCurrentL1

func RecordCLBackendCurrentL1(b *Backend, blockNumber uint64)

func RecordCLBackendL1Lag

func RecordCLBackendL1Lag(b *Backend, lag uint64)

func RecordCLBackendL1Stale

func RecordCLBackendL1Stale(b *Backend, stale bool)

func RecordCLBackendLocalSafeBlock

func RecordCLBackendLocalSafeBlock(b *Backend, blockNumber hexutil.Uint64)

func RecordCLBanInteropSafeGtLocalSafe

func RecordCLBanInteropSafeGtLocalSafe(b *Backend)

func RecordCLBanNotHealthy

func RecordCLBanNotHealthy(b *Backend)

func RecordCLBanOutputRootMismatch

func RecordCLBanOutputRootMismatch(b *Backend)

func RecordCLBanOutputRootTimeout

func RecordCLBanOutputRootTimeout(b *Backend)

func RecordCLBanUnexpectedBlockTags

func RecordCLBanUnexpectedBlockTags(b *Backend)

func RecordCLConsensusHalted

func RecordCLConsensusHalted(group *BackendGroup, halted bool)

RecordCLConsensusHalted updates the halted gauge for a group: 1 when halted, 0 otherwise. When halted is true it also increments the halt counter; the counter therefore rises once per halted consensus cycle, not once per transition into the halted state.

func RecordCLGroupLocalSafeBlock

func RecordCLGroupLocalSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)

func RecordCLGroupPinL1

func RecordCLGroupPinL1(group *BackendGroup, pinBackend *Backend, blockNumber uint64)

func RecordCLNoPinCandidate

func RecordCLNoPinCandidate(group *BackendGroup)

func RecordCLOutputRootDisagreement

func RecordCLOutputRootDisagreement(b *Backend)

func RecordCLSyncStatusCacheHit

func RecordCLSyncStatusCacheHit(group *BackendGroup)

func RecordCLSyncStatusCacheMiss

func RecordCLSyncStatusCacheMiss(group *BackendGroup)

func RecordCacheError

func RecordCacheError(method string)

func RecordCacheHit

func RecordCacheHit(method string)

func RecordCacheMiss

func RecordCacheMiss(method string)

func RecordConsensusBackendBanned

func RecordConsensusBackendBanned(b *Backend, banned bool)

func RecordConsensusBackendInSync

func RecordConsensusBackendInSync(b *Backend, inSync bool)

func RecordConsensusBackendPeerCount

func RecordConsensusBackendPeerCount(b *Backend, peerCount uint64)

func RecordConsensusBackendUpdateDelay

func RecordConsensusBackendUpdateDelay(b *Backend, lastUpdate time.Time)

func RecordGroupConsensusCount

func RecordGroupConsensusCount(group *BackendGroup, count int)

func RecordGroupConsensusError

func RecordGroupConsensusError(group *BackendGroup, label string, err error)

func RecordGroupConsensusFilteredCount

func RecordGroupConsensusFilteredCount(group *BackendGroup, count int)

func RecordGroupConsensusFinalizedBlock

func RecordGroupConsensusFinalizedBlock(group *BackendGroup, blockNumber hexutil.Uint64)

func RecordGroupConsensusHACLPinL1

func RecordGroupConsensusHACLPinL1(group *BackendGroup, leader string, l1Num uint64)

func RecordGroupConsensusHAFinalizedBlock

func RecordGroupConsensusHAFinalizedBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)

func RecordGroupConsensusHALatestBlock

func RecordGroupConsensusHALatestBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)

func RecordGroupConsensusHASafeBlock

func RecordGroupConsensusHASafeBlock(group *BackendGroup, leader string, blockNumber hexutil.Uint64)

func RecordGroupConsensusHAServingLocal

func RecordGroupConsensusHAServingLocal(group *BackendGroup, servingLocal bool)

func RecordGroupConsensusLatestBlock

func RecordGroupConsensusLatestBlock(group *BackendGroup, blockNumber hexutil.Uint64)

func RecordGroupConsensusSafeBlock

func RecordGroupConsensusSafeBlock(group *BackendGroup, blockNumber hexutil.Uint64)

func RecordGroupTotalCount

func RecordGroupTotalCount(group *BackendGroup, count int)

func RecordHTTPRequestByMethodDuration

func RecordHTTPRequestByMethodDuration(method string, d time.Duration)

RecordHTTPRequestByMethodDuration records an HTTP JSON-RPC request duration.

func RecordHealthyCandidates

func RecordHealthyCandidates(b *BackendGroup, candidates int)

func RecordRPCCall

func RecordRPCCall(backendName, method, statusCode, transport string)

RecordRPCCall records one client-initiated JSON-RPC call and the outcome the client received. Callers must pass a method name already bounded by Server.metricMethodName or WSProxier.metricMethodName — never a raw client-supplied method string, which is unbounded label cardinality.

func RecordRPCError

func RecordRPCError(ctx context.Context, backendName, method string, err error)

func RecordRPCForward

func RecordRPCForward(ctx context.Context, backendName, method, source string)

func RecordRPCNotification

func RecordRPCNotification(backendName string)

RecordRPCNotification records one client-bound WS subscription notification.

func RecordRedisError

func RecordRedisError(source string)

func RecordRequestPayloadSize

func RecordRequestPayloadSize(ctx context.Context, payloadSize int)

func RecordResponsePayloadSize

func RecordResponsePayloadSize(ctx context.Context, payloadSize int)

func RecordUnserviceableRequest

func RecordUnserviceableRequest(ctx context.Context, source string)

func RecordUp

func RecordUp()

func RecordWSMessage

func RecordWSMessage(ctx context.Context, backendName, source string)

func SetLogLevel

func SetLogLevel(logLevel slog.Leveler)

func ValidateRPCReq

func ValidateRPCReq(req *RPCReq) error

Types

type AliasRateLimitConfig

type AliasRateLimitConfig struct {
	BaseRate          *int                                     `toml:"base_rate"`
	BaseInterval      *TOMLDuration                            `toml:"base_interval"`
	InfiniteRateLimit bool                                     `toml:"infinite_rate_limit"`
	MethodOverrides   map[string]*AliasRateLimitMethodOverride `toml:"method_overrides"`
}

type AliasRateLimitMethodOverride

type AliasRateLimitMethodOverride struct {
	Limit             *int          `toml:"limit"`
	Interval          *TOMLDuration `toml:"interval"`
	InfiniteRateLimit bool          `toml:"infinite_rate_limit"`
}

type Backend

type Backend struct {
	Name string

	ProbeWorker *ProbeWorker
	// contains filtered or unexported fields
}

func NewBackend

func NewBackend(
	name string,
	rpcURL string,
	wsURL string,
	rpcSemaphore *semaphore.Weighted,
	opts ...BackendOpt,
) *Backend

func (*Backend) ClearSlidingWindows

func (b *Backend) ClearSlidingWindows()

func (*Backend) ErrorRate

func (b *Backend) ErrorRate() (errorRate float64)

ErrorRate returns the instant error rate of the backend

func (*Backend) Forward

func (b *Backend) Forward(ctx context.Context, reqs []*RPCReq, isBatch bool) ([]*RPCRes, error)

func (*Backend) ForwardRPC

func (b *Backend) ForwardRPC(ctx context.Context, res *RPCRes, id string, method string, params ...any) error

ForwardRPC makes a call directly to a backend and populate the response into `res`

func (*Backend) ForwardWithSource

func (b *Backend) ForwardWithSource(ctx context.Context, reqs []*RPCReq, isBatch bool, source string) ([]*RPCRes, error)

func (*Backend) IsDegraded

func (b *Backend) IsDegraded() bool

IsDegraded checks if the backend is serving traffic in a degraded state (i.e. used as a last resource)

func (*Backend) IsHealthy

func (b *Backend) IsHealthy() bool

IsHealthy checks if the backend is able to serve traffic, based on dynamic parameters

func (*Backend) IsProbeHealthy

func (b *Backend) IsProbeHealthy() bool

func (*Backend) Override

func (b *Backend) Override(opts ...BackendOpt)

func (*Backend) ProxyWS

func (b *Backend) ProxyWS(clientConn *websocket.Conn, methodWhitelist *StringSet, serverReadLimit int64) (*WSProxier, error)

func (*Backend) SetProbeHealth

func (b *Backend) SetProbeHealth(healthy bool)

type BackendConfig

type BackendConfig struct {
	Username         string            `toml:"username"`
	Password         string            `toml:"password"`
	RPCURL           string            `toml:"rpc_url"`
	WSURL            string            `toml:"ws_url"`
	WSPort           int               `toml:"ws_port"`
	MaxRPS           int               `toml:"max_rps"`
	MaxWSConns       int               `toml:"max_ws_conns"`
	CAFile           string            `toml:"ca_file"`
	ClientCertFile   string            `toml:"client_cert_file"`
	ClientKeyFile    string            `toml:"client_key_file"`
	StripTrailingXFF bool              `toml:"strip_trailing_xff"`
	Headers          map[string]string `toml:"headers"`

	ProbeFailureThreshold int    `toml:"probe_failure_threshold"`
	ProbeSuccessThreshold int    `toml:"probe_success_threshold"`
	ProbePeriodSeconds    int    `toml:"probe_period_seconds"`
	ProbeTimeoutSeconds   int    `toml:"probe_timeout_seconds"`
	ProbeURL              string `toml:"probe_url"`

	Weight int `toml:"weight"`

	SkipIsSyncingCheck          bool `toml:"skip_is_syncing_check"`
	ResponseTimeoutMilliseconds int  `toml:"response_timeout_milliseconds"`
	MaxRetries                  *int `toml:"max_retries"`

	SafeBlockDriftThreshold      uint64 `toml:"safe_block_drift_threshold"`
	FinalizedBlockDriftThreshold uint64 `toml:"finalized_block_drift_threshold"`

	ConsensusSkipPeerCountCheck bool   `toml:"consensus_skip_peer_count"`
	ConsensusForcedCandidate    bool   `toml:"consensus_forced_candidate"`
	ConsensusReceiptsTarget     string `toml:"consensus_receipts_target"`
	AllowedStatusCodes          []int  `toml:"allowed_status_codes"`
}

type BackendGroup

type BackendGroup struct {
	Name             string
	Backends         []*Backend
	WeightedRouting  bool
	Consensus        *ConsensusPoller
	FallbackBackends map[string]bool
	// contains filtered or unexported fields
}

func (*BackendGroup) ExecuteMulticall

func (bg *BackendGroup) ExecuteMulticall(ctx context.Context, rpcReqs []*RPCReq, source string) *BackendGroupRPCResponse

Note: rpcReqs should only contain 1 request of 'sendRawTransactions'

func (*BackendGroup) Fallbacks

func (bg *BackendGroup) Fallbacks() []*Backend

func (*BackendGroup) Forward

func (bg *BackendGroup) Forward(ctx context.Context, rpcReqs []*RPCReq, isBatch bool) ([]*RPCRes, string, error)

NOTE: BackendGroup Forward contains the log for balancing with consensus aware

func (*BackendGroup) ForwardRequestToBackendGroup

func (bg *BackendGroup) ForwardRequestToBackendGroup(
	rpcReqs []*RPCReq,
	backends []*Backend,
	ctx context.Context,
	isBatch bool,
	source string,
) *BackendGroupRPCResponse

func (*BackendGroup) ForwardWithSource

func (bg *BackendGroup) ForwardWithSource(ctx context.Context, rpcReqs []*RPCReq, isBatch bool, source string) ([]*RPCRes, string, error)

func (*BackendGroup) GetRoutingStrategy

func (bg *BackendGroup) GetRoutingStrategy() RoutingStrategy

func (*BackendGroup) MulticallRequest

func (bg *BackendGroup) MulticallRequest(backend *Backend, rpcReqs []*RPCReq, wg *sync.WaitGroup, ctx context.Context, ch chan *multicallTuple, source string)

func (*BackendGroup) OverwriteConsensusResponses

func (bg *BackendGroup) OverwriteConsensusResponses(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes, rewrittenReqs []*RPCReq) ([]*RPCReq, []*indexedReqRes)

func (*BackendGroup) OverwriteNonConsensusRequests

func (bg *BackendGroup) OverwriteNonConsensusRequests(rpcReqs []*RPCReq, overriddenResponses []*indexedReqRes) ([]*RPCReq, []*indexedReqRes)

func (*BackendGroup) Primaries

func (bg *BackendGroup) Primaries() []*Backend

func (*BackendGroup) ProcessMulticallResponses

func (bg *BackendGroup) ProcessMulticallResponses(ch chan *multicallTuple, ctx context.Context) (resp *BackendGroupRPCResponse, unserviceable bool)

func (*BackendGroup) ProxyWS

func (bg *BackendGroup) ProxyWS(ctx context.Context, clientConn *websocket.Conn, methodWhitelist *StringSet, serverReadLimit int64) (*WSProxier, error)

func (*BackendGroup) Shutdown

func (bg *BackendGroup) Shutdown()

type BackendGroupConfig

type BackendGroupConfig struct {
	Backends []string `toml:"backends"`

	WeightedRouting bool `toml:"weighted_routing"`

	RoutingStrategy RoutingStrategy `toml:"routing_strategy"`

	MulticallRPCErrorCheck bool `toml:"multicall_rpc_error_check"`

	/*
		Deprecated: Use routing_strategy config to create a consensus_aware proxyd instance
	*/
	ConsensusAware          bool         `toml:"consensus_aware"`
	ConsensusAsyncHandler   string       `toml:"consensus_handler"`
	ConsensusPollerInterval TOMLDuration `toml:"consensus_poller_interval"`

	ConsensusBanPeriod          TOMLDuration `toml:"consensus_ban_period"`
	ConsensusMaxUpdateThreshold TOMLDuration `toml:"consensus_max_update_threshold"`
	ConsensusMaxBlockLag        uint64       `toml:"consensus_max_block_lag"`
	ConsensusMaxBlockRange      uint64       `toml:"consensus_max_block_range"`
	ConsensusMinPeerCount       int          `toml:"consensus_min_peer_count"`
	// Will set Max Block Range for non-consensus eth_getLogs and eth_newFilter
	// Will override consensus_max_block_range if consensus_max_block range is also set
	MaxBlockRange uint64 `toml:"max_block_range"`

	// consensus_cl_sync_threshold is the maximum number of L1 blocks a CL (op-node) backend
	// may lag behind the network's head_l1 before it is considered out of sync and excluded
	// from the consensus group. Computed as head_l1.number - current_l1.number.
	// Default: 10 (~2 minutes at 12s L1 block time). Only applies when
	// routing_strategy = "consensus_aware_consensus_layer".
	ConsensusCLSyncThreshold uint64 `toml:"consensus_cl_sync_threshold"`

	// consensus_cl_head_l1_max_age is the maximum age of a CL backend's head_l1 timestamp
	// before the backend is considered stale and excluded from the consensus group.
	// A backend whose L1 head is older than this duration has likely lost its L1 connection.
	// Default: 5m. Set to 0 to disable the age check. Only applies when
	// routing_strategy = "consensus_aware_consensus_layer".
	ConsensusCLHeadL1MaxAge TOMLDuration `toml:"consensus_cl_head_l1_max_age"`

	// consensus_cl_output_root_ban_threshold is the number of consecutive per-cycle
	// optimism_outputAtBlock timeouts before a CL backend is banned. The counter resets
	// to 0 on any successful fetch. Default: 3. Only applies when
	// routing_strategy = "consensus_aware_consensus_layer".
	ConsensusCLOutputRootBanThreshold uint `toml:"consensus_cl_output_root_ban_threshold"`

	ConsensusHA                  bool         `toml:"consensus_ha"`
	ConsensusHAHeartbeatInterval TOMLDuration `toml:"consensus_ha_heartbeat_interval"`
	ConsensusHALockPeriod        TOMLDuration `toml:"consensus_ha_lock_period"`
	ConsensusHARedis             RedisConfig  `toml:"consensus_ha_redis"`
	// consensus_ha_serve_local_when_stale serves this instance's locally polled
	// consensus state when its copy of the shared HA state has not been refreshed
	// for longer than consensus_ha_lock_period (e.g. it cannot reach Redis),
	// instead of the frozen shared state. Instances may then disagree on the head.
	// Default: false.
	ConsensusHAServeLocalWhenStale bool `toml:"consensus_ha_serve_local_when_stale"`

	Fallbacks []string `toml:"fallbacks"`
}

func (*BackendGroupConfig) ValidateRoutingStrategy

func (b *BackendGroupConfig) ValidateRoutingStrategy(bgName string) bool

type BackendGroupRPCResponse

type BackendGroupRPCResponse struct {
	RPCRes   []*RPCRes
	ServedBy string
	// contains filtered or unexported fields
}

type BackendGroupsConfig

type BackendGroupsConfig map[string]*BackendGroupConfig

type BackendOpt

type BackendOpt func(b *Backend)

func WithAllowedStatusCodes

func WithAllowedStatusCodes(allowedStatusCodes []int) BackendOpt

func WithBasicAuth

func WithBasicAuth(username, password string) BackendOpt

func WithConsensusForcedCandidate

func WithConsensusForcedCandidate(forcedCandidate bool) BackendOpt

func WithConsensusReceiptTarget

func WithConsensusReceiptTarget(receiptsTarget string) BackendOpt

func WithConsensusSkipPeerCountCheck

func WithConsensusSkipPeerCountCheck(skipPeerCountCheck bool) BackendOpt

func WithFinalizedBlockDriftThreshold

func WithFinalizedBlockDriftThreshold(finalizedBlockDriftThreshold uint64) BackendOpt

func WithHeaders

func WithHeaders(headers map[string]string) BackendOpt

func WithIntermittentNetworkErrorSlidingWindow

func WithIntermittentNetworkErrorSlidingWindow(sw *sw.AvgSlidingWindow) BackendOpt

func WithMaxDegradedLatencyThreshold

func WithMaxDegradedLatencyThreshold(maxDegradedLatencyThreshold time.Duration) BackendOpt

func WithMaxErrorRateThreshold

func WithMaxErrorRateThreshold(maxErrorRateThreshold float64) BackendOpt

func WithMaxLatencyThreshold

func WithMaxLatencyThreshold(maxLatencyThreshold time.Duration) BackendOpt

func WithMaxRPS

func WithMaxRPS(maxRPS int) BackendOpt

func WithMaxResponseSize

func WithMaxResponseSize(size int64) BackendOpt

func WithMaxRetries

func WithMaxRetries(retries int) BackendOpt

func WithMaxWSConns

func WithMaxWSConns(maxConns int) BackendOpt

func WithOutOfServiceDuration

func WithOutOfServiceDuration(interval time.Duration) BackendOpt

func WithProbe

func WithProbe(probeURL string, probeFailureThreshold int, probeSuccessThreshold int, probePeriodSeconds int, probeTimeoutSeconds int) BackendOpt

func WithProxydIP

func WithProxydIP(ip string) BackendOpt

func WithSafeBlockDriftThreshold

func WithSafeBlockDriftThreshold(safeBlockDriftThreshold uint64) BackendOpt

func WithSkipIsSyncingCheck

func WithSkipIsSyncingCheck(skipIsSyncingCheck bool) BackendOpt

func WithStrippedTrailingXFF

func WithStrippedTrailingXFF() BackendOpt

func WithTLSConfig

func WithTLSConfig(tlsConfig *tls.Config) BackendOpt

func WithTimeout

func WithTimeout(timeout time.Duration) BackendOpt

func WithWeight

func WithWeight(weight int) BackendOpt

type BackendOptions

type BackendOptions struct {
	// Deprecated: Use ResponseTimeoutMilliseconds instead. Note this field will be overridden if `ResponseTimeoutMilliseconds` is also set.
	ResponseTimeoutSeconds      int          `toml:"response_timeout_seconds"`
	ResponseTimeoutMilliseconds int          `toml:"response_timeout_milliseconds"`
	MaxResponseSizeBytes        int64        `toml:"max_response_size_bytes"`
	MaxRetries                  int          `toml:"max_retries"`
	OutOfServiceSeconds         int          `toml:"out_of_service_seconds"`
	MaxDegradedLatencyThreshold TOMLDuration `toml:"max_degraded_latency_threshold"`
	MaxLatencyThreshold         TOMLDuration `toml:"max_latency_threshold"`
	MaxErrorRateThreshold       float64      `toml:"max_error_rate_threshold"`
}

type BackendsConfig

type BackendsConfig map[string]*BackendConfig

type BatchConfig

type BatchConfig struct {
	MaxSize      int    `toml:"max_size"`
	ErrorMessage string `toml:"error_message"`
}

type BlockHashOrNumberParameter

type BlockHashOrNumberParameter struct {
	BlockHash   *common.Hash     `json:"blockHash"`
	BlockNumber *rpc.BlockNumber `json:"blockNumber"`
}

BlockHashOrNumberParameter is a non-conventional wrapper used by alchemy_getTransactionReceipts

type Cache

type Cache interface {
	Get(ctx context.Context, key string) (string, error)
	Put(ctx context.Context, key string, value string) error
}

type CacheConfig

type CacheConfig struct {
	Enabled bool         `toml:"enabled"`
	TTL     TOMLDuration `toml:"ttl"`
}

type Config

type Config struct {
	WSBackendGroup               string                       `toml:"ws_backend_group"`
	Server                       ServerConfig                 `toml:"server"`
	Cache                        CacheConfig                  `toml:"cache"`
	Redis                        RedisConfig                  `toml:"redis"`
	Metrics                      MetricsConfig                `toml:"metrics"`
	RateLimit                    RateLimitConfig              `toml:"rate_limit"`
	BackendOptions               BackendOptions               `toml:"backend"`
	Backends                     BackendsConfig               `toml:"backends"`
	BatchConfig                  BatchConfig                  `toml:"batch"`
	Authentication               map[string]string            `toml:"authentication"`
	BackendGroups                BackendGroupsConfig          `toml:"backend_groups"`
	RPCMethodMappings            map[string]string            `toml:"rpc_method_mappings"`
	WSMethodWhitelist            []string                     `toml:"ws_method_whitelist"`
	WhitelistErrorMessage        string                       `toml:"whitelist_error_message"`
	SenderRateLimit              SenderRateLimitConfig        `toml:"sender_rate_limit"`
	InteropValidationConfig      InteropValidationConfig      `toml:"interop_validation"`
	TxValidationMiddlewareConfig TxValidationMiddlewareConfig `toml:"tx_validation_middleware"`
	TxMonitor                    TxMonitorConfig              `toml:"tx_monitor"`
}

type ConsensusAsyncHandler

type ConsensusAsyncHandler interface {
	Init()
	Shutdown()
}

ConsensusAsyncHandler controls the asynchronous polling mechanism, interval and shutdown

func NewNoopAsyncHandler

func NewNoopAsyncHandler() ConsensusAsyncHandler

func NewPollerAsyncHandler

func NewPollerAsyncHandler(ctx context.Context, cp *ConsensusPoller) ConsensusAsyncHandler

type ConsensusGetReceiptsResult

type ConsensusGetReceiptsResult struct {
	Method string      `json:"method"`
	Result interface{} `json:"result"`
}

type ConsensusOpt

type ConsensusOpt func(cp *ConsensusPoller)

func WithAsyncHandler

func WithAsyncHandler(asyncHandler ConsensusAsyncHandler) ConsensusOpt

func WithBanPeriod

func WithBanPeriod(banPeriod time.Duration) ConsensusOpt

func WithCLConsensusMode

func WithCLConsensusMode() ConsensusOpt

WithCLConsensusMode enables CL (op-node / consensus layer) consensus mode.

In this mode the poller queries optimism_syncStatus and optimism_outputAtBlock instead of eth_getBlockByNumber, and serves optimism_syncStatus responses from a cached pin backend (the consensus group member with the lowest current_l1 derivation position) rather than rewriting individual fields.

Output root verification: each poll cycle the poller calls optimism_outputAtBlock at the consensus safe block on every candidate backend. A backend whose output root disagrees with a strict majority is banned. If there is no majority (a tie or N-way split), the disagreement is unresolvable and consensus halts: the served block height and the cached optimism_syncStatus body stay frozen at the last-agreed value, while the served group is emptied so general RPCs fail closed rather than routing to a backend on an uncertain fork. Backends are not persistently banned, so consensus auto-recovers as soon as a majority returns. This catches derivation divergences between heterogeneous CL clients (e.g. op-node vs kona-node) before incorrect data reaches consumers.

Any number of backends is permitted, including even/2-node cross-client groups: a no-majority disagreement halts rather than being resolved by eviction.

func WithCLHeadL1MaxAge

func WithCLHeadL1MaxAge(maxAge time.Duration) ConsensusOpt

WithCLHeadL1MaxAge sets the maximum age of the L1 head timestamp before a CL backend is considered stale.

func WithCLOutputRootBanThreshold

func WithCLOutputRootBanThreshold(threshold uint) ConsensusOpt

WithCLOutputRootBanThreshold sets the number of consecutive per-cycle optimism_outputAtBlock timeouts before a CL backend is banned.

func WithCLSyncThreshold

func WithCLSyncThreshold(threshold uint64) ConsensusOpt

WithCLSyncThreshold sets the maximum tolerated L1 block lag before a CL backend is considered out of sync.

func WithListener

func WithListener(listener OnConsensusBroken) ConsensusOpt

func WithMaxBlockLag

func WithMaxBlockLag(maxBlockLag uint64) ConsensusOpt

func WithMaxBlockRange

func WithMaxBlockRange(maxBlockRange uint64) ConsensusOpt

func WithMaxUpdateThreshold

func WithMaxUpdateThreshold(maxUpdateThreshold time.Duration) ConsensusOpt

func WithMinPeerCount

func WithMinPeerCount(minPeerCount uint64) ConsensusOpt

func WithPollerInterval

func WithPollerInterval(interval time.Duration) ConsensusOpt

func WithTracker

func WithTracker(tracker ConsensusTracker) ConsensusOpt

type ConsensusPoller

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

ConsensusPoller checks the consensus state for each member of a BackendGroup resolves the highest common block for multiple nodes, and reconciles the consensus in case of block hash divergence to minimize re-orgs

func NewConsensusPoller

func NewConsensusPoller(bg *BackendGroup, opts ...ConsensusOpt) *ConsensusPoller

func (*ConsensusPoller) AddListener

func (cp *ConsensusPoller) AddListener(listener OnConsensusBroken)

func (*ConsensusPoller) Ban

func (cp *ConsensusPoller) Ban(be *Backend)

Ban bans a specific backend

func (*ConsensusPoller) BannedUntil

func (cp *ConsensusPoller) BannedUntil(be *Backend) time.Time

IsBanned checks if a specific backend is banned

func (*ConsensusPoller) ClearListeners

func (cp *ConsensusPoller) ClearListeners()

func (*ConsensusPoller) FilterCandidates

func (cp *ConsensusPoller) FilterCandidates(backends []*Backend) map[*Backend]*backendState

filterCandidates find out what backends are the candidates to be in the consensus group and create a copy of current their state

Note: exclusion here is a per-cycle soft filter — a backend can be excluded this cycle and pass next cycle with no penalty, and it continues to be polled via UpdateBackend. This is distinct from a ban, which is a time-bounded penalty (default 5 min) that stops all polling of the backend and resets its block state.

a candidate is a serving node within the following conditions:

  • not banned
  • healthy (network latency and error rate)
  • with minimum peer count
  • in sync
  • updated recently
  • not lagging latest block
  • (CL mode) finalized and local_safe blocks are at or above the current group consensus, preventing a restarting backend from dragging consensus backward

func (*ConsensusPoller) GetBackendState

func (cp *ConsensusPoller) GetBackendState(be *Backend) *backendState

GetBackendState creates a copy of backend state so that the caller can use it without locking

func (*ConsensusPoller) GetConsensusGroup

func (cp *ConsensusPoller) GetConsensusGroup() []*Backend

GetConsensusGroup returns the backend members that are agreeing in a consensus

func (*ConsensusPoller) GetConsensusSyncStatusBody

func (cp *ConsensusPoller) GetConsensusSyncStatusBody() json.RawMessage

GetConsensusSyncStatusBody returns the cached optimism_syncStatus response body from the current pin backend. Returns nil if no poll cycle has completed yet.

func (*ConsensusPoller) GetFinalizedBlockNumber

func (cp *ConsensusPoller) GetFinalizedBlockNumber() hexutil.Uint64

GetFinalizedBlockNumber returns the `finalized` agreed block number in a consensus

func (*ConsensusPoller) GetLastUpdate

func (cp *ConsensusPoller) GetLastUpdate(be *Backend) time.Time

func (*ConsensusPoller) GetLatestBlockNumber

func (cp *ConsensusPoller) GetLatestBlockNumber() hexutil.Uint64

GetLatestBlockNumber returns the `latest` agreed block number in a consensus

func (*ConsensusPoller) GetLocalSafeBlockNumber

func (cp *ConsensusPoller) GetLocalSafeBlockNumber() hexutil.Uint64

GetLocalSafeBlockNumber returns the `local_safe` agreed block number in a consensus (CL mode only)

func (*ConsensusPoller) GetSafeBlockNumber

func (cp *ConsensusPoller) GetSafeBlockNumber() hexutil.Uint64

GetSafeBlockNumber returns the `safe` agreed block number in a consensus

func (*ConsensusPoller) IsBanned

func (cp *ConsensusPoller) IsBanned(be *Backend) bool

IsBanned checks if a specific backend is banned

func (*ConsensusPoller) IsConsensusLayer

func (cp *ConsensusPoller) IsConsensusLayer() bool

IsConsensusLayer returns true if this poller is operating in CL (op-node) mode

func (*ConsensusPoller) Reset

func (cp *ConsensusPoller) Reset()

Reset resets all backend states.

func (*ConsensusPoller) Shutdown

func (cp *ConsensusPoller) Shutdown()

func (*ConsensusPoller) Unban

func (cp *ConsensusPoller) Unban(be *Backend)

Unban removes any bans from the backends

func (*ConsensusPoller) UpdateBackend

func (cp *ConsensusPoller) UpdateBackend(ctx context.Context, be *Backend)

UpdateBackend refreshes the consensus state of a single backend

func (*ConsensusPoller) UpdateBackendGroupConsensus

func (cp *ConsensusPoller) UpdateBackendGroupConsensus(ctx context.Context)

UpdateBackendGroupConsensus resolves the current group consensus based on the state of the backends

type ConsensusTracker

type ConsensusTracker interface {
	GetState() ConsensusTrackerState
	SetState(state ConsensusTrackerState)

	GetCLSyncBody() (body json.RawMessage, lastServedL1Num uint64)
	SetCLSyncBody(body json.RawMessage, l1Num uint64)
}

ConsensusTracker abstracts how we store and retrieve the current consensus allowing it to be stored locally in-memory or in a shared Redis cluster

func NewInMemoryConsensusTracker

func NewInMemoryConsensusTracker() ConsensusTracker

func NewRedisConsensusTracker

func NewRedisConsensusTracker(ctx context.Context,
	redisClient redis.UniversalClient,
	bg *BackendGroup,
	namespace string,
	opts ...RedisConsensusTrackerOpt) ConsensusTracker

type ConsensusTrackerState

type ConsensusTrackerState struct {
	Latest    hexutil.Uint64 `json:"latest"`
	Safe      hexutil.Uint64 `json:"safe"`
	Finalized hexutil.Uint64 `json:"finalized"`
	LocalSafe hexutil.Uint64 `json:"local_safe"`

	CLSyncBody json.RawMessage `json:"cl_sync_body,omitempty"`
	CLL1Num    uint64          `json:"cl_l1_num,omitempty"`
}

ConsensusTrackerState holds the full consensus state in one snapshot. Adding a new field only requires changing this struct and update().

type ELBlockState

type ELBlockState struct {
	LatestBlockNumber    hexutil.Uint64
	LatestBlockHash      string
	SafeBlockNumber      hexutil.Uint64
	FinalizedBlockNumber hexutil.Uint64
}

ELBlockState holds the block numbers and hashes fetched from an EL backend in a single polling cycle.

type FallbackRateLimiter

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

FallbackRateLimiter is a combination of a primary and secondary rate limiter. If the primary rate limiter fails, due to an unexpected error, the secondary rate limiter will be used. This is useful to reduce reliance on a single Redis instance for rate limiting. If both fail, the request is not let through.

func (*FallbackRateLimiter) Take

func (r *FallbackRateLimiter) Take(ctx context.Context, key string) (bool, error)

type FrontendRateLimiter

type FrontendRateLimiter interface {
	// Take consumes a key, and a maximum number of requests
	// per time interval. It returns a boolean denoting if
	// the limit could be taken, or an error if a failure
	// occurred in the backing rate limit implementation.
	//
	// No error will be returned if the limit could not be taken
	// as a result of the requestor being over the limit.
	Take(ctx context.Context, key string) (bool, error)
}

func NewFallbackRateLimiter

func NewFallbackRateLimiter(primary FrontendRateLimiter, secondary FrontendRateLimiter) FrontendRateLimiter

func NewMemoryFrontendRateLimit

func NewMemoryFrontendRateLimit(dur time.Duration, max int) FrontendRateLimiter

func NewRedisFrontendRateLimiter

func NewRedisFrontendRateLimiter(r redis.UniversalClient, dur time.Duration, max int, prefix string) FrontendRateLimiter

type InMemoryConsensusTracker

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

InMemoryConsensusTracker store and retrieve in memory, async-safe

func (*InMemoryConsensusTracker) Behind

func (*InMemoryConsensusTracker) GetCLSyncBody

func (ct *InMemoryConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)

func (*InMemoryConsensusTracker) GetState

func (*InMemoryConsensusTracker) SetCLSyncBody

func (ct *InMemoryConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)

func (*InMemoryConsensusTracker) SetState

func (ct *InMemoryConsensusTracker) SetState(state ConsensusTrackerState)

func (*InMemoryConsensusTracker) UpdatedAt

func (ct *InMemoryConsensusTracker) UpdatedAt() time.Time

UpdatedAt returns when the state was last written by update.

func (*InMemoryConsensusTracker) Valid

func (ct *InMemoryConsensusTracker) Valid() bool

type InteropStrategy

type InteropStrategy interface {
	ValidateAccessList(ctx context.Context, interopAccessList []common.Hash) error
}

type InteropValidationConfig

type InteropValidationConfig struct {
	Urls                              []string                  `toml:"urls"`
	Strategy                          InteropValidationStrategy `toml:"strategy"`
	ChainID                           uint64                    `toml:"chain_id"`
	LoadBalancingUnhealthinessTimeout time.Duration             `toml:"load_balancing_unhealthiness_timeout"`
	ReqSizeLimit                      int                       `toml:"req_size_limit"`
	AccessListSizeLimit               int                       `toml:"access_list_size_limit"`
	RateLimit                         SenderRateLimitConfig     `toml:"sender_rate_limit"`
	// MinResponses is the quorum required by the agreement strategy: the number
	// of definitive verdicts that must be collected before deciding. Defaults to
	// len(Urls) (unanimity) when unset.
	MinResponses int `toml:"min_responses"`
}

type InteropValidationStrategy

type InteropValidationStrategy string
const (
	EmptyStrategy                    InteropValidationStrategy = ""
	FirstFilterStrategy              InteropValidationStrategy = "first-filter"
	MulticallStrategy                InteropValidationStrategy = "multicall"
	HealthAwareLoadBalancingStrategy InteropValidationStrategy = "health-aware-load-balancing"
	AgreementStrategy                InteropValidationStrategy = "agreement"

	// LegacyFirstSupervisorStrategy is the pre-rename name for FirstFilterStrategy,
	// accepted for config backwards compatibility.
	LegacyFirstSupervisorStrategy InteropValidationStrategy = "first-supervisor"
)

type LimitedHTTPClient

type LimitedHTTPClient struct {
	http.Client
	// contains filtered or unexported fields
}

func (*LimitedHTTPClient) DoLimited

func (c *LimitedHTTPClient) DoLimited(req *http.Request) (*http.Response, error)

type LimitedReader

type LimitedReader struct {
	R io.Reader // underlying reader
	N int64     // max bytes remaining
}

A LimitedReader reads from R but limits the amount of data returned to just N bytes. Each call to Read updates N to reflect the new amount remaining. Unlike the standard library version, Read returns ErrLimitReaderOverLimit when N <= 0.

func (*LimitedReader) Read

func (l *LimitedReader) Read(p []byte) (int, error)

type MemoryFrontendRateLimiter

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

MemoryFrontendRateLimiter is a rate limiter that stores all rate limiting information in local memory. It works by storing a limitedKeys struct that references the truncated timestamp at which the struct was created. If the current truncated timestamp doesn't match what's referenced, the limit is reset. Otherwise, values in a map are incremented to represent the limit. This will never return an error.

func (*MemoryFrontendRateLimiter) Take

type MemoryPendingStore

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

func NewMemoryPendingStore

func NewMemoryPendingStore(maxPending int) *MemoryPendingStore

func (*MemoryPendingStore) Add

func (s *MemoryPendingStore) Add(e txmonEntry) bool

Add records a pending tx. Returns false when the store is at capacity. Re-adding a hash already present keeps whichever entry has the earlier IngestedAt: that is the user-perceived submission time, and because IngestedAt is stamped at request ingress, a later duplicate submission may be observed (enqueued) before an earlier one. Any already-set SubblockAt on the retained entry is preserved.

func (*MemoryPendingStore) ExpireBefore

func (s *MemoryPendingStore) ExpireBefore(cutoff time.Time) []txmonEntry

func (*MemoryPendingStore) Len

func (s *MemoryPendingStore) Len() int

func (*MemoryPendingStore) MarkSubblock

func (s *MemoryPendingStore) MarkSubblock(h common.Hash, at time.Time) (txmonEntry, bool)

MarkSubblock stamps the first subblock sighting. Returns the updated entry and true only on the first mark of a known hash.

func (*MemoryPendingStore) MatchAndRemove

func (s *MemoryPendingStore) MatchAndRemove(hashes []common.Hash) []txmonEntry

type MethodMappingsConfig

type MethodMappingsConfig map[string]string

type MetricsConfig

type MetricsConfig struct {
	Enabled bool   `toml:"enabled"`
	Host    string `toml:"host"`
	Port    int    `toml:"port"`
}

type NoopAsyncHandler

type NoopAsyncHandler struct{}

NoopAsyncHandler allows fine control updating the consensus

func (*NoopAsyncHandler) Init

func (ah *NoopAsyncHandler) Init()

func (*NoopAsyncHandler) Shutdown

func (ah *NoopAsyncHandler) Shutdown()

type NoopRPCCache

type NoopRPCCache struct{}

func (*NoopRPCCache) GetRPC

func (n *NoopRPCCache) GetRPC(context.Context, *RPCReq) (*RPCRes, error)

func (*NoopRPCCache) PutRPC

func (n *NoopRPCCache) PutRPC(context.Context, *RPCReq, *RPCRes) error

type OnConsensusBroken

type OnConsensusBroken func()

type PendingStore

type PendingStore interface {
	Add(e txmonEntry) bool
	MatchAndRemove(hashes []common.Hash) []txmonEntry
	MarkSubblock(h common.Hash, at time.Time) (txmonEntry, bool)
	ExpireBefore(cutoff time.Time) []txmonEntry
	Len() int
}

PendingStore tracks pending transactions. The interface is batch-shaped so a future Redis implementation can pipeline one multi-key op per block.

type PollerAsyncHandler

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

PollerAsyncHandler asynchronously updates each individual backend and the group consensus

func (*PollerAsyncHandler) Init

func (ah *PollerAsyncHandler) Init()

func (*PollerAsyncHandler) Shutdown

func (ah *PollerAsyncHandler) Shutdown()

type ProbeSpec

type ProbeSpec struct {
	FailureThreshold int
	SuccessThreshold int
	Period           time.Duration
	Timeout          time.Duration
}

type ProbeWorker

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

func NewProbeWorker

func NewProbeWorker(
	backendName string,
	probeUrl string,
	probeSpec ProbeSpec,
	resultHandler func(bool, string),
	tlsConfig *tls.Config,
) (*ProbeWorker, error)

func (*ProbeWorker) Start

func (w *ProbeWorker) Start()

func (*ProbeWorker) Stop

func (w *ProbeWorker) Stop()

type RPCCache

type RPCCache interface {
	GetRPC(ctx context.Context, req *RPCReq) (*RPCRes, error)
	PutRPC(ctx context.Context, req *RPCReq, res *RPCRes) error
}

type RPCErr

type RPCErr struct {
	Code          int             `json:"code"`
	Message       string          `json:"message"`
	Data          json.RawMessage `json:"data,omitempty"`
	HTTPErrorCode int             `json:"-"`
}

func ErrInvalidParams

func ErrInvalidParams(msg string) *RPCErr

func ErrInvalidRequest

func ErrInvalidRequest(msg string) *RPCErr

func ParseInteropError

func ParseInteropError(err error) *RPCErr

func (*RPCErr) Clone

func (r *RPCErr) Clone() *RPCErr

func (*RPCErr) Error

func (r *RPCErr) Error() string

type RPCMethodHandler

type RPCMethodHandler interface {
	GetRPCMethod(context.Context, *RPCReq) (*RPCRes, error)
	PutRPCMethod(context.Context, *RPCReq, *RPCRes) error
}

type RPCReq

type RPCReq struct {
	JSONRPC string          `json:"jsonrpc"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params"`
	ID      json.RawMessage `json:"id"`
}

func ParseRPCReq

func ParseRPCReq(body []byte) (*RPCReq, error)

type RPCRes

type RPCRes struct {
	JSONRPC string
	Result  interface{}
	Error   *RPCErr
	ID      json.RawMessage
	// contains filtered or unexported fields
}

func NewRPCErrorRes

func NewRPCErrorRes(id json.RawMessage, err error) *RPCRes

func NewRPCRes

func NewRPCRes(id json.RawMessage, result interface{}) *RPCRes

func OverrideResponses

func OverrideResponses(res []*RPCRes, overriddenResponses []*indexedReqRes) []*RPCRes

func ParseRPCRes

func ParseRPCRes(r io.Reader) (*RPCRes, error)

func (*RPCRes) IsError

func (r *RPCRes) IsError() bool

func (*RPCRes) MarshalJSON

func (r *RPCRes) MarshalJSON() ([]byte, error)

type RateLimitConfig

type RateLimitConfig struct {
	UseRedis         bool                                `toml:"use_redis"`
	UseAuthAlias     bool                                `toml:"use_auth_alias"`
	BaseRate         int                                 `toml:"base_rate"`
	BaseInterval     TOMLDuration                        `toml:"base_interval"`
	ExemptOrigins    []string                            `toml:"exempt_origins"`
	ExemptUserAgents []string                            `toml:"exempt_user_agents"`
	ErrorMessage     string                              `toml:"error_message"`
	MethodOverrides  map[string]*RateLimitMethodOverride `toml:"method_overrides"`
	IPHeaderOverride string                              `toml:"ip_header_override"`
	AliasOverrides   map[string]*AliasRateLimitConfig    `toml:"alias_overrides"`
}

type RateLimitMethodOverride

type RateLimitMethodOverride struct {
	Limit    int          `toml:"limit"`
	Interval TOMLDuration `toml:"interval"`
	Global   bool         `toml:"global"`
}

type RedisConfig

type RedisConfig struct {
	// If `redis_cluster = true`, you can specify url string for multi-node cluster:
	//    "redis://<user>:<password>@<host>:<port>?addr=<host2>:<port2>&addr=<host3>:<port3>"
	// OR "rediss://<user>:<password>@<host>:<port>?addr=<host2>:<port2>&addr=<host3>:<port3>"
	//
	// Otherwise, it is also possible to specify single url for Redis cluster with proxy support.
	URL              string `toml:"url"`
	Namespace        string `toml:"namespace"`
	ReadURL          string `toml:"read_url"`
	FallbackToMemory bool   `toml:"fallback_to_memory"`
	RedisCluster     bool   `toml:"redis_cluster"`
}

type RedisConsensusTracker

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

RedisConsensusTracker store and retrieve in a shared Redis cluster, with leader election

func (*RedisConsensusTracker) GetCLSyncBody

func (ct *RedisConsensusTracker) GetCLSyncBody() (json.RawMessage, uint64)

func (*RedisConsensusTracker) GetState

func (*RedisConsensusTracker) Init

func (ct *RedisConsensusTracker) Init()

func (*RedisConsensusTracker) SetCLSyncBody

func (ct *RedisConsensusTracker) SetCLSyncBody(body json.RawMessage, l1Num uint64)

func (*RedisConsensusTracker) SetState

func (ct *RedisConsensusTracker) SetState(state ConsensusTrackerState)

type RedisConsensusTrackerOpt

type RedisConsensusTrackerOpt func(cp *RedisConsensusTracker)

func WithHeartbeatInterval

func WithHeartbeatInterval(heartbeatInterval time.Duration) RedisConsensusTrackerOpt

func WithLockPeriod

func WithLockPeriod(lockPeriod time.Duration) RedisConsensusTrackerOpt

func WithServeLocalWhenStale

func WithServeLocalWhenStale(serveLocalWhenStale bool) RedisConsensusTrackerOpt

type RedisFrontendRateLimiter

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

RedisFrontendRateLimiter is a rate limiter that stores data in Redis. It uses the basic rate limiter pattern described on the Redis best practices website: https://redis.com/redis-best-practices/basic-rate-limiting/.

func (*RedisFrontendRateLimiter) Take

type RewriteContext

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

type RewriteResult

type RewriteResult uint8
const (
	// RewriteNone means request should be forwarded as-is
	RewriteNone RewriteResult = iota

	// RewriteOverrideError means there was an error attempting to rewrite
	RewriteOverrideError

	// RewriteOverrideRequest means the modified request should be forwarded to the backend
	RewriteOverrideRequest

	// RewriteOverrideResponse means to skip calling the backend and serve the overridden response
	RewriteOverrideResponse
)

func RewriteRequest

func RewriteRequest(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)

RewriteRequest modifies the request object to comply with the rewrite context before the method has been called at the backend it returns false if nothing was changed

func RewriteResponse

func RewriteResponse(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)

RewriteResponse synthesizes responses from consensus state before the backend is called. This is EL-only: CL mode intercepts optimism_syncStatus entirely in OverwriteConsensusResponses and serves it from the pin-backend cache, so no rewriting is needed here.

func RewriteTags

func RewriteTags(rctx RewriteContext, req *RPCReq, res *RPCRes) (RewriteResult, error)

RewriteTags modifies the request and the response based on block tags

type RoutingStrategy

type RoutingStrategy string
const (
	ConsensusAwareRoutingStrategy   RoutingStrategy = "consensus_aware"
	ConsensusAwareCLRoutingStrategy RoutingStrategy = "consensus_aware_consensus_layer"
	MulticallRoutingStrategy        RoutingStrategy = "multicall"
	FallbackRoutingStrategy         RoutingStrategy = "fallback"
)

type SenderRateLimitConfig

type SenderRateLimitConfig struct {
	Enabled         bool
	Interval        TOMLDuration
	Limit           int
	AllowedChainIds []*big.Int `toml:"allowed_chain_ids"`
}

SenderRateLimitConfig configures the sender-based rate limiter for eth_sendRawTransaction requests. To enable pre-eip155 transactions, add '0' to allowed_chain_ids.

type Server

type Server struct {
	BackendGroups map[string]*BackendGroup
	// contains filtered or unexported fields
}

func NewServer

func NewServer(
	backendGroups map[string]*BackendGroup,
	wsBackendGroup *BackendGroup,
	wsMethodWhitelist *StringSet,
	rpcMethodMappings map[string]string,
	maxBodySize int64,
	authenticatedPaths map[string]string,
	publicAccess bool,
	timeout time.Duration,
	maxUpstreamBatchSize int,
	enableServedByHeader bool,
	cache RPCCache,
	rateLimitConfig RateLimitConfig,
	senderRateLimitConfig SenderRateLimitConfig,
	interopSenderRateLimitConfig SenderRateLimitConfig,
	enableRequestLog bool,
	maxRequestBodyLogLen int,
	maxBatchSize int,
	limiterFactory limiterFactoryFunc,
	interopValidatingConfig InteropValidationConfig,
	interopStrategy InteropStrategy,
	enableTxHashLogging bool,
	limExemptKeys []string,
	txValidationConfig TxValidationMiddlewareConfig,
	gracefulShutdownDuration time.Duration,
	maxConcurrentWSRPCs int64,
) (*Server, error)

func Start

func Start(config *Config) (*Server, func(), error)

func (*Server) Drain

func (s *Server) Drain()

func (*Server) HandleHealthz

func (s *Server) HandleHealthz(w http.ResponseWriter, r *http.Request)

func (*Server) HandleRPC

func (s *Server) HandleRPC(w http.ResponseWriter, r *http.Request)

func (*Server) HandleWS

func (s *Server) HandleWS(w http.ResponseWriter, r *http.Request)

func (*Server) RPCListenAndServe

func (s *Server) RPCListenAndServe(host string, port int) error

func (*Server) Shutdown

func (s *Server) Shutdown()

func (*Server) WSListenAndServe

func (s *Server) WSListenAndServe(host string, port int) error

type ServerConfig

type ServerConfig struct {
	RPCHost           string `toml:"rpc_host"`
	RPCPort           int    `toml:"rpc_port"`
	WSHost            string `toml:"ws_host"`
	WSPort            int    `toml:"ws_port"`
	MaxBodySizeBytes  int64  `toml:"max_body_size_bytes"`
	MaxConcurrentRPCs int64  `toml:"max_concurrent_rpcs"`
	// MaxConcurrentWSRPCs limits concurrent mapped RPCs handled over a single WS connection.
	MaxConcurrentWSRPCs int64 `toml:"max_concurrent_ws_rpcs"`
	// DisableConcurrentRequestSemaphore=true allows unlimited concurrent RPC requests. This takes precedence over MaxConcurrentRPCs.
	DisableConcurrentRequestSemaphore bool   `toml:"disable_concurrent_request_semaphore"`
	LogLevel                          string `toml:"log_level"`

	// TimeoutSeconds specifies the maximum time spent serving an HTTP request. Note that isn't used for websocket connections
	TimeoutSeconds int `toml:"timeout_seconds"`

	MaxUpstreamBatchSize int `toml:"max_upstream_batch_size"`

	EnableRequestLog      bool `toml:"enable_request_log"`
	MaxRequestBodyLogLen  int  `toml:"max_request_body_log_len"`
	EnablePprof           bool `toml:"enable_pprof"`
	EnableXServedByHeader bool `toml:"enable_served_by_header"`
	AllowAllOrigins       bool `toml:"allow_all_origins"`
	PublicAccess          bool `toml:"public_access"`
	EnableTxHashLogging   bool `toml:"enable_tx_hash_logging"`

	// GracefulShutdownSeconds is the duration to wait during drain before shutting down.
	// Defaults to 0 (no drain delay). Set to a positive value to enable graceful drain.
	GracefulShutdownSeconds int `toml:"graceful_shutdown_seconds"`
}

type StaticMethodHandler

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

func (*StaticMethodHandler) GetRPCMethod

func (e *StaticMethodHandler) GetRPCMethod(ctx context.Context, req *RPCReq) (*RPCRes, error)

func (*StaticMethodHandler) PutRPCMethod

func (e *StaticMethodHandler) PutRPCMethod(ctx context.Context, req *RPCReq, res *RPCRes) error

type StringSet

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

func NewStringSet

func NewStringSet() *StringSet

func NewStringSetFromStrings

func NewStringSetFromStrings(in []string) *StringSet

func (*StringSet) Add

func (s *StringSet) Add(str string)

func (*StringSet) Entries

func (s *StringSet) Entries() []string

func (*StringSet) Extend

func (s *StringSet) Extend(in []string) *StringSet

func (*StringSet) Has

func (s *StringSet) Has(test string) bool

type TOMLDuration

type TOMLDuration time.Duration

func (*TOMLDuration) UnmarshalText

func (t *TOMLDuration) UnmarshalText(b []byte) error

type TransactionWithFrom

type TransactionWithFrom map[string]interface{}

TransactionWithFrom represents a transaction with the sender address included. We use a map instead of types.Transaction because go-ethereum's Transaction type does not include the "from" field in its JSON marshaling - the sender address must be derived from the signature using ecrecover. This type allows us to include "from" at the same level as other transaction fields for the validation service.

type TxFilter

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

TxFilter is the single chokepoint for transaction-submission filtering. It owns an ordered list of modules and runs them in order, short-circuiting on the first rejection (logical AND).

func NewTxFilter

func NewTxFilter(decode txDecodeFunc, modules ...TxFilterModule) *TxFilter

func (*TxFilter) Apply

func (f *TxFilter) Apply(ctx context.Context, sub *TxSubmission) error

Apply runs every module in order, returning the first module's rejection.

func (*TxFilter) Build

func (f *TxFilter) Build(ctx context.Context, req *RPCReq, bypassRateLimit bool) (*TxSubmission, error)

Build decodes a submission request into a TxSubmission using the decoder registered for its method, propagating that decoder's errors and enforcing maxBundleTransactions here so the cap applies to every bundle regardless of middleware enablement.

func (*TxFilter) IsSubmissionMethod

func (f *TxFilter) IsSubmissionMethod(method string) bool

IsSubmissionMethod reports the static set of submission methods the filter handles. Per-method middleware opt-out is enforced inside the middleware module, not here — chain-ID/rate-limit/interop always apply.

type TxFilterModule

type TxFilterModule interface {
	Name() string
	Apply(ctx context.Context, sub *TxSubmission) error
}

TxFilterModule is a single check in the submission filter pipeline.

Apply returns nil to accept (allowing the pipeline to continue) or an error to reject the whole submission. The contract:

  • Apply runs for EVERY submission method the filter handles. Per-method scoping is the module's own responsibility — see txMiddlewareModule, which opts out of methods not in its configured set.
  • Modules MUST treat sub.Txs as immutable. TxSubmission.Sender memoizes ecrecover per index keyed by position in sub.Txs; mutating or reordering the slice would corrupt that memo.
  • The default failure policy is fail-CLOSED: returning an error rejects the submission. Fail-open (returning nil despite an internal failure) must be an explicit, operator-gated decision, as txMiddlewareModule does via its failOpen flag — never a silent default.

type TxMonitor

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

TxMonitor passively measures user tx inclusion latency. It is fed by Observe (non-blocking) from the request hot path and runs its own block-poll, subblocks-stream, and reaper goroutines. Never critical: every failure mode degrades to missing metrics, not degraded ingestion.

func NewTxMonitor

func NewTxMonitor(cfg TxMonitorConfig, backendGroups map[string]*BackendGroup, rpcMethodMappings map[string]string) (*TxMonitor, error)

func (*TxMonitor) Observe

func (m *TxMonitor) Observe(hash common.Hash, backendGroup string, source string, at time.Time)

Observe records a successfully forwarded tx. Non-blocking by construction: a full channel drops the observation and counts it. This is the ONLY method called from the request hot path. at is the request-arrival time captured at ingress, so inclusion latency accounts for proxyd-internal handling and the forward round-trip, not just backend-ack-to-block.

func (*TxMonitor) Shutdown

func (m *TxMonitor) Shutdown()

func (*TxMonitor) Start

func (m *TxMonitor) Start()

type TxMonitorConfig

type TxMonitorConfig struct {
	Enabled bool `toml:"enabled"`
	// BlockPollURL is an explicit RPC endpoint for block polling. When empty,
	// the monitor polls through a proxyd backend group instead (see
	// BlockPollBackendGroup).
	BlockPollURL string `toml:"block_poll_url"`
	// BlockPollBackendGroup names the backend group to poll blocks from when
	// BlockPollURL is empty. Defaults to the group mapped for
	// eth_getBlockByNumber, falling back to eth_sendRawTransaction's group.
	BlockPollBackendGroup string `toml:"block_poll_backend_group"`
	// SubblocksWSURL enables the subblocks preconfirmation watcher when set.
	SubblocksWSURL string `toml:"subblocks_ws_url"`
	// InclusionTimeout evicts pending txs and counts a timeout. Default 60s.
	InclusionTimeout TOMLDuration `toml:"inclusion_timeout"`
	// MaxPending caps the in-memory pending map. Default 10000.
	MaxPending int `toml:"max_pending"`
	// PollInterval is the block poll cadence. Default 1s.
	PollInterval TOMLDuration `toml:"poll_interval"`
}

TxMonitorConfig configures the passive transaction-UX monitor: it observes successfully forwarded eth_sendRawTransaction hashes and measures latency until they appear in a block (and, optionally, in the subblocks stream). Purely observational — never blocks or affects tx ingestion.

type TxSubmission

type TxSubmission struct {
	Method          string
	Req             *RPCReq
	Txs             []*types.Transaction
	BypassRateLimit bool
	// contains filtered or unexported fields
}

TxSubmission is the decoded form of a single transaction-submission request (eth_sendRawTransaction, eth_sendRawTransactionConditional, eth_sendBundle). The submission is decoded once and the recovered sender for each tx is memoized so that the chain-ID, sender-rate-limit, and interop modules can all share a single ecrecover per transaction.

Not safe for concurrent use.

func (*TxSubmission) Sender

func (s *TxSubmission) Sender(i int) (common.Address, error)

Sender returns the recovered sender for Txs[i], computing it at most once. Recovery uses the same signer selection as getSender (HomesteadSigner for chainID 0, else LatestSignerForChainID) and memoizes both value and error. A recovery error is returned to the caller; modules treat it as a hard reject.

type TxValidationClient

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

TxValidationClient is a reusable HTTP client for validation requests.

func NewTxValidationClient

func NewTxValidationClient(cfg TxValidationMiddlewareConfig) *TxValidationClient

NewTxValidationClient creates a new validation client from the middleware config. Unset (zero or negative) numeric fields fall back to defaults. cfg.APIKey is optional: when non-empty it is sent on every request in the x-api-key header.

func (*TxValidationClient) Validate

func (c *TxValidationClient) Validate(ctx context.Context, endpoint string, payload []byte) (map[string]bool, error)

Validate performs the HTTP request to the validation middleware service. Returns a map of tx hashes to unauthorized status.

type TxValidationFunc

type TxValidationFunc func(ctx context.Context, endpoint string, payload []byte) (map[string]bool, error)

TxValidationFunc validates a batch of transactions and returns a map of tx hashes to unauthorized status. The endpoint is the middleware service URL, and payload is the request body to send.

type TxValidationMethodSet

type TxValidationMethodSet map[string]struct{}

func NewTxValidationMethodSet

func NewTxValidationMethodSet(methods []string) TxValidationMethodSet

func (TxValidationMethodSet) Contains

func (s TxValidationMethodSet) Contains(method string) bool

type TxValidationMiddlewareConfig

type TxValidationMiddlewareConfig struct {
	// Enabled determines whether the middleware is active
	Enabled bool `toml:"enabled"`

	// Endpoint is the URL of the validation middleware service
	Endpoint string `toml:"endpoint"`

	// Methods is the list of RPC methods to apply validation to.
	// Defaults to ["eth_sendRawTransaction", "eth_sendRawTransactionConditional", "eth_sendBundle"] if not specified.
	Methods []string `toml:"methods"`

	// APIKey is an optional credential sent to the validation service in the
	// x-api-key header. No header is sent when empty. Supports $ENV_VAR
	// indirection like other secrets in the config.
	APIKey string `toml:"api_key"`

	// TimeoutSeconds is the timeout for validation HTTP requests. Defaults to 5 seconds.
	TimeoutSeconds int `toml:"timeout_seconds"`

	// MaxConnsPerHost caps concurrent connections to the validation service.
	// Over plain HTTP/1.1 this is also the cap on in-flight validations; further
	// requests queue for a free connection, and that wait counts against
	// TimeoutSeconds. Defaults to 10.
	MaxConnsPerHost int `toml:"max_conns_per_host"`

	// MaxIdleConns is the number of idle connections kept open to the validation
	// service between bursts. Defaults to 10.
	MaxIdleConns int `toml:"max_idle_conns"`

	// FailOpen determines whether transactions should be allowed through if the validation
	// service returns an error. Defaults to true for safety (fail-open).
	FailOpen *bool `toml:"fail_open"`
}

TxValidationMiddlewareConfig configures the transaction validation middleware.

type WSProxier

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

func NewWSProxier

func NewWSProxier(backend *Backend, clientConn, backendConn *websocket.Conn, methodWhitelist *StringSet, onClose func()) *WSProxier

func (*WSProxier) Proxy

func (w *WSProxier) Proxy(ctx context.Context) error

Directories

Path Synopsis
cmd
proxyd command
pkg
tools
mockserver command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址