Upstreams

Every field on upstreams[]

evm.* fields

Deprecated: getLogsMaxAllowedRange, getLogsMaxAllowedAddresses, getLogsMaxAllowedTopics, getLogsSplitOnError on upstream.evm — these moved to the network level.

jsonRpc.* fields

Method filters — interaction rules

• Both ignoreMethods and allowMethods accept matcher syntax (* wildcard, | OR).
• allowMethods takes precedence over ignoreMethods when both match.
• Setting allowMethods without ignoreMethods implicitly adds ignoreMethods: ["*"] — you must explicitly set ignoreMethods: [] to opt out of that behavior.
• autoIgnoreUnsupportedMethods (default true) augments ignoreMethods at runtime when the upstream returns a "method not supported" error. Disable when probing experimental methods.

Groups & the fallback magic value

group is a free-form label, but the value "fallback" is special:

• If any upstream in a network has group: fallback, eRPC auto-creates a default network-level selection policy that prefers non-fallback upstreams and only reaches into the fallback group when the primaries are unhealthy.
• This behavior is enabled by the ROUTING_POLICY_* env-controlled defaults — see selection policies for the exact eval body.
• Any other group value is purely a label and only matters if you reference it from your own selection-policy evalFunction or want it as a metric label.

Apart from the fallback magic value, you can use group purely as a label that's referenced by your own selection-policy evalFunction and surfaces in Prometheus metric labels.

routing.* — per-upstream score tuning

upstreams:
  - id: my-alchemy
    endpoint: https://eth-mainnet.g.alchemy.com/v2/KEY
    routing:
      scoreLatencyQuantile: 0.70           # latency percentile used for scoring (default 0.70)
      scoreMultipliers:
        # ── Selectors: which (network × method × finality) bucket these weights apply to.
        - network: "*"                     # matcher: "evm:1", "evm:*", "evm:1|evm:10"
          method: "*"                      # matcher: "eth_getLogs|eth_call", etc.
          finality: ["realtime", "unfinalized"]  # filter — apply only to these finality buckets
          # ── Weights (numeric). `overall` is a final multiplier; the others scale individual penalties.
          overall: 1.0                     # boost the final score (>1 = preferred)
          errorRate: 4.0                   # higher = bigger penalty when error rate is bad
          respLatency: 8.0                 # higher = bigger penalty for slow tail latency
          throttledRate: 3.0
          blockHeadLag: 2.0
          finalizationLag: 1.0
          totalRequests: 1.0               # weight on observed request volume (favor warmer pools)
          misbehaviors: 5.0                # weight on consensus-misbehavior count

How scoring works. Each upstream is scored separately for every (network × method × finality) bucket it serves. The score is a weighted aggregate of penalty signals (error rate, latency quantile, throttling, head-lag, finalization-lag, misbehavior count, request volume); higher weight on a penalty dimension means that metric hurts the score more. overall is the final multiplier applied on top, so an upstream with overall: 10 and slightly worse metrics still outranks one with overall: 1 and a perfect score.

Selectors vs weights:

• network, method, finality are selectors — they decide which buckets this entry applies to. finality is an array (["realtime", "unfinalized"]); valid values are finalized, unfinalized, realtime, unknown. Omitting finality matches all buckets.
• overall, errorRate, respLatency, throttledRate, blockHeadLag, finalizationLag, totalRequests, misbehaviors are weights (floats, default 1.0). Setting one to 0 removes that signal from the score for the selected buckets.
• Default weights: if no scoreMultipliers entry matches a given bucket (because no entry exists, or no selector matches), every dimension defaults to 1.0 and overall defaults to 1.0 — uniform weight across all signals, no boost.

Worked example. Suppose upstream A has errorRate: 8.0 and upstream B has errorRate: 1.0. Both observe a 5% error rate in the same window. The errorRate penalty contribution for A is 0.05 × 8.0 = 0.40; for B it is 0.05 × 1.0 = 0.05. That 0.35-point gap compounds with the other dimensions — A scores meaningfully lower and is deprioritized sooner and more aggressively than B, even though both see identical traffic. Setting errorRate: 8.0 on a latency-sensitive bucket is a way of saying "I care much more about errors than the default here."

Multipliers compose: an upstream with overall: 10 and a perfect score will outrank one with overall: 1 even at slightly worse metrics. To prefer a cheap upstream by default:

upstreams:
  - { id: cheap, endpoint: ..., routing: { scoreMultipliers: [{ overall: 10 }] } }
  - { id: pricey, endpoint: ..., routing: { scoreMultipliers: [{ overall: 1 }] } }

Tuning tips:

• Fast failover — set scoreSwitchHysteresis: -1 and scoreMinSwitchInterval: -1 to always use the current best upstream immediately.
• Smoother scoring — increase scorePenaltyDecayRate toward 0.98 so transient blips don't move the primary.
• Reactive scoring — decrease toward 0.80 so degradation kicks in quickly.

When to tune what:

• High respLatency weight — use when tail-latency variance between providers is large and client timeout budget is tight. Raising respLatency to 8.0–16.0 makes slow p70 latency a dominant signal.
• High misbehaviors weight — use when running consensus failsafe and you want divergent upstreams de-prioritized aggressively after they produce wrong answers. Default 1.0 is gentle; 10.0+ will effectively exile a misbehaving upstream until its penalty decays.
• Narrow method-scoped entry — use when an upstream is excellent for some methods but bad for others. A separate entry with a tight method selector applies heavier penalty only where the upstream is weak:

routing:
  scoreMultipliers:
    - method: '*'
      overall: 2.0         # generally preferred
    - method: 'eth_getLogs'
      respLatency: 16.0    # but penalize hard for getLogs where it's slow
      errorRate: 4.0

rateLimitAutoTune fields

rateLimitAutoTune:
  enabled: true              # default: true if a rateLimitBudget is bound
  adjustmentPeriod: 1m       # window for evaluating throttled ratio
  errorRateThreshold: 0.1    # if throttled-rate > this, decrease
  increaseFactor: 1.05       # multiply budget by this when below threshold
  decreaseFactor: 0.9        # multiply budget by this when above threshold
  minBudget: 0
  maxBudget: 10000

The new budget applies to every upstream sharing that budget — auto-tune decreases on one Quicknode upstream tighten the budget for all Quicknode upstreams sharing it.

Per-upstream integrity — evm.integrity

Validate eth_getBlockReceipts responses on this upstream specifically. Useful when a vendor has known correctness issues you want to catch before the response is cached or returned.

upstreams:
  - id: suspect-vendor
    endpoint: https://...
    evm:
      integrity:
        eth_getBlockReceipts:
          enabled: true
          checkLogIndexStrictIncrements: true   # log.index must be strictly increasing within a block
          checkLogsBloom: true                   # recalculated bloom must match the header's logsBloom

When a check fails, the response is treated as an upstream error — retried, scored against, and optionally exported via consensus.misbehaviorsDestination.

Shadow upstreams

shadow mirrors a fraction of real traffic to this upstream without affecting the response sent to the client. The shadow result is compared against the primary's; mismatches are logged or exported. Useful for vendor evaluations, regression detection, and silent validation of new endpoints.

upstreams:
  # Primary serves traffic normally.
  - id: primary
    endpoint: https://prod-vendor.example
  # Shadow only — receives a 10% sample of every request the primary serves.
  - id: candidate
    endpoint: https://candidate-vendor.example
    shadow:
      enabled: true
      sampleRate: 0.1                  # 0.0–1.0; fraction of requests to mirror
      ignoreFields:                    # diff-comparison ignore lists
        "*": ["blockTimestamp"]
        "transactions.*": ["gasPrice"]

Notes:

• Shadow upstreams don't count in selection — they only see traffic that the primary served first.
• Diffs are emitted as a metric (erpc_upstream_shadow_diff_total) and, when paired with a misbehaviors destination, written out for inspection.
• ignoreFields uses the same dot-path matcher as consensus.ignoreFields — * matches a single segment, ** matches any depth.

Failsafe at upstream level (matchMethod + matchFinality)

failsafe[] accepts per-policy matchMethod and matchFinality so you can have different retry budgets for different categories of methods on the same upstream:

upstreams:
  - id: archive
    endpoint: https://archive.example
    failsafe:
      - matchMethod: "trace_*|debug_*"
        timeout: { duration: 60s }
        retry: { maxAttempts: 1 }            # expensive — don't multiply
      - matchMethod: "*"
        matchFinality: ["realtime", "unfinalized"]
        timeout: { duration: 5s }
        retry: { maxAttempts: 3, delay: 100ms }
      - matchMethod: "*"
        matchFinality: ["finalized"]
        timeout: { duration: 30s }
        retry: { maxAttempts: 5, delay: 200ms }

consensus and hedge are also valid at upstream level. The full vocabulary is the same as the network-level failsafe.

Defaults via upstreamDefaults

project.upstreamDefaults applies before any per-upstream config — useful for proxy pools, gzip, or a baseline failsafe across every upstream in a project.

projects:
  - id: main
    upstreamDefaults:
      jsonRpc:
        proxyPool: eu-dc1-pool
        enableGzip: true
      failsafe:
        - matchMethod: "*"
          timeout: { duration: 20s }
          retry: { maxAttempts: 2 }
    upstreams:
      - id: a
        endpoint: https://a.example          # inherits the defaults above
      - id: b
        endpoint: https://b.example
        jsonRpc:
          proxyPool: us-dc1-pool             # per-upstream override

Per-upstream values override the defaults; arrays don't merge.

Outbound compression

eRPC supports gzip at four points:

# Example client → eRPC gzipped request
curl -X POST \
  -H "Content-Encoding: gzip" \
  -H "Content-Type: application/json" \
  --data-binary @<(echo '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[]}' | gzip) \
  http://localhost:4000/main/evm/42161

Custom HTTP headers

upstreams:
  - id: private
    endpoint: https://private-provider.io/v1
    jsonRpc:
      headers:
        Authorization: Bearer SECRET_VALUE
        X-Custom-Header: HelloWorld

Headers are applied on every outbound request from eRPC to this upstream.

Proxy pools

A proxy pool is a named list of outbound HTTP/SOCKS proxies. When an upstream (or upstreamDefaults) references a pool by ID via jsonRpc.proxyPool, every request eRPC makes to that upstream goes through one of the pool's proxies. eRPC round-robins across proxies using an atomic counter — each successive request picks the next proxy in sequence. Useful for geographic distribution, egress IP pinning, ISP routing, or private/public splits.

proxyPools:  - id: eu-dc1-pool    urls:      - http://proxy111.myorg.local:3128      - https://proxy222.myorg.local:3129  - id: us-dc1-pool    urls:      - http://proxy333.myorg.local:3128      - socks5://user:pass@proxy444.myorg.local:1080
projects:  - id: main    upstreamDefaults:      jsonRpc:        proxyPool: eu-dc1-pool        # default for all upstreams in this project    upstreams:      - id: us-rpc        endpoint: https://us.example        jsonRpc:          proxyPool: us-dc1-pool      # override for this upstream      - id: direct-rpc        endpoint: https://direct.example        jsonRpc:          proxyPool: ''               # opt out (empty string disables the inherited default)

proxyPools[] fields

Accepted URL schemes

Round-robin and failover

eRPC selects proxies with a lockless atomic counter — each request increments the counter and picks counter % len(urls). There is no automatic failover: if the selected proxy is unreachable, the upstream request fails and normal upstream-level retry/circuit-breaker logic applies. To tolerate proxy failures, put a single reliable entry per pool or front your proxies with a load balancer.

Deprecated fields — migration map

The legacy forms still parse, so existing configs work — but new code should use the new shape. Mixing both in one config will emit a deprecation warning.

Common pitfalls

• allowMethods without ignoreMethods: [] — allowMethods silently adds an implicit ignoreMethods: ["*"], so an upstream with allowMethods: ["eth_getLogs"] will block every other method. To allow eth_getLogs while still serving the defaults, prefer adding to ignoreMethods instead.
• group: fallback is magic — using this value triggers auto-creation of a default selection policy. Use any other label if you don't want that behavior.
• Compound rate-limit budgets — rateLimitAutoTune decreases on one upstream tighten the budget for every upstream sharing it. If you need independent rate limits per upstream, give each its own budget.
• statePollerInterval: 0s — disables polling entirely, so eRPC has no notion of the chain's latest/finalized state for this upstream. Every response goes into the unknown finality bucket; the cache layer will treat them accordingly.
• blockAvailability.upper.updateRate is ignored — for latestBlockMinus the bound is computed on-demand from the state poller's latest head. Only earliestBlockPlus honors updateRate.