Projects

ProjectConfig — every field

Routing behaviour (which upstream is primary, when to flip, when to exclude, hysteresis, cooldowns, …) lives in networks[].selectionPolicy. The default policy gives you production-grade routing out of the box.

clusterKey — top-level (shares behavior across the project tree)

The top-level clusterKey is not under projects[]; it sits at the root of the config. It identifies a logical group of eRPC replicas — useful when multiple instances coordinate via shared state.

clusterKey: erpc-prod-eu                  # all replicas in EU prod share this key
 
server: # ...
projects: # ...
database:
  sharedState:
    connector:
      driver: redis
      redis: { uri: redis://... }
    # When set, this overrides the top-level clusterKey for shared-state specifically.
    # clusterKey: erpc-prod-eu-sharedstate

If database.sharedState.clusterKey is set, it overrides the top-level value for shared-state operations only. For consistent behavior, leave only the top-level one set.

Defaults & merge semantics

networkDefaults and upstreamDefaults are deep-merged into each entry:

• Scalar fields (rateLimitBudget, userAgentMode, etc.) — the entry-level value wins if set.
• Object fields (evm, directiveDefaults, jsonRpc) — deep merge per sub-field.
• Array fields are NOT merged — if networkDefaults.failsafe is set and networks[i].failsafe is also set, the entry's array completely replaces the defaults. Same for selectionPolicy.

userAgentMode — concrete behavior

The User-Agent header has very high natural cardinality (thousands of distinct strings even on a small site). The two modes:

simplified buckets known agents — Chrome, Firefox, Safari, Edge, Brave, Curl, Go-http-client, Python-requests, Node-fetch, etc. Unknown agents fall through as unknown.

Use raw only when actively debugging a particular client's behavior.

forwardHeaders — what passes through

By default, eRPC does not forward client headers to upstreams (other than the body and content-type machinery it creates itself). forwardHeaders is an explicit allowlist:

projects:
  - id: indexer
    forwardHeaders:
      - X-Request-ID
      - traceparent           # W3C trace context
      - X-Indexer-Job

Hop-by-hop headers (Host, Connection, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding, Upgrade) are stripped regardless of this list — that's a fundamental HTTP/1.1 invariant.

Use for distributed tracing (forward traceparent/tracestate) and customer-supplied request context.

ignoreMethods / allowMethods — project-level vs upstream-level

Both fields exist at:

1. Project level — blocks across the whole project.
2. Upstream level — blocks per upstream.

The interaction:

• A request is rejected by project-level ignoreMethods BEFORE any upstream is considered.
• A request is rejected by upstream-level ignoreMethods only when that specific upstream would otherwise serve it.
• allowMethods precedence is the same — project allow first, then upstream allow.
• When allowMethods is set at either level and ignoreMethods is NOT, an implicit ignoreMethods: ["*"] applies.

Use project-level for product-shape decisions ("this project never serves debug methods"). Use upstream-level for capability differences ("this archive node serves trace methods; this RPC vendor does not").

Routing & scoring tuning recipes

Stable production setup (default — change nothing):

routingStrategy: score-based
scoreGranularity: upstream
scoreRefreshInterval: 30s
scorePenaltyDecayRate: 0.95
scoreSwitchHysteresis: 0.10
scoreMinSwitchInterval: 2m

Fast failover — when reliability matters more than upstream cost stability:

scoreSwitchHysteresis: -1        # always pick the highest-scoring
scoreMinSwitchInterval: -1       # no cooldown

Reactive scoring — for upstreams that degrade quickly:

scorePenaltyDecayRate: 0.80      # recent metrics dominate
scoreRefreshInterval: 10s        # faster ticks

Per-method scoring — when method profiles differ a lot:

scoreGranularity: method

This triples the metric series count (one score per (network, method, upstream)) — pair with scoreMetricsMode: compact to manage cardinality.

Common pitfalls

• Two projects with the same id — eRPC fails to start. IDs are checked at config load.
• forwardHeaders includes Authorization — your upstream gets the client's auth header. Usually fine for vendor URLs (they ignore unknown auth schemes) but can confuse private upstreams. Be explicit about what's in the list.
• allowMethods set at project level but you also want admin/debug methods — project-level allowMethods doesn't combine with upstream-level. Use one or the other, not both.
• scoreGranularity: method × hundreds of methods × many upstreams — massive metric cardinality. Stick to upstream granularity unless you have a specific reason.
• scoreSwitchHysteresis: 0 — primary switches on every refresh tick. Use 0.10 (default) or higher for stability.
• userAgentMode: raw in production with a Grafana Cloud / hosted Prometheus — can blow past cardinality limits in days. Stick to simplified.