Networks

Every field on networks[]

evm.* fields

Per-network method overrides — methods.*

By default, eRPC uses a built-in cacheable-method table (see evmJsonRpcCache → default methods). You can extend or replace it per network:

networks:
  - architecture: evm
    evm: { chainId: 999 }
    methods:
      # When true (default), per-network entries augment the global defaults.
      # Set false to ENTIRELY REPLACE the defaults with the definitions below.
      preserveDefaultMethods: true
      definitions:
        # Add a chain-specific RPC method that's not in the default table
        custom_specialQuery:
          finalized: true
        # Override an existing default: don't translate `latest` tag to a number for this method
        eth_blockNumber:
          translateLatestTag: false

Each entry in definitions is a CacheMethodConfig with the following fields:

When to use stateful: true. Mark a method stateful when its result depends on caller-supplied session state — for example, a custom RPC method tenant_query that takes a session token as a parameter and returns data scoped to that caller. Without stateful: true, eRPC can multiplex different callers' requests through the same upstream connection, which can yield cross-tenant cache hits or wrong results if the upstream ties its response to the connection's session context. Setting stateful: true disables request multiplexing for that method.

networks:
  - architecture: evm
    evm: { chainId: 999 }
    methods:
      definitions:
        tenant_query:
          stateful: true    # each caller gets a dedicated upstream connection

selectionPolicy fields

selectionPolicy:
  evalInterval: 15s           # how often to re-evaluate eligibility (default 15s)
  evalTimeout: 100ms          # per-tick eval deadline (must be < evalInterval; prior cache retained on timeout)
  evalScope: network          # 'network' (default) | 'network-method' | 'network-finality' | 'network-method-finality'
  evalFunc: |
    (upstreams, ctx) =>
      upstreams
        .removeCordoned()
        .excludeIf(all(samplesAbove(10), errorRateAbove(0.7)))
        .whenEmpty(() => upstreams)
        .preferTag('!tier:fallback', { minHealthy: 1, fallback: 'tier:fallback' })
        .sortByScore(PREFER_FASTEST)
        .stickyPrimary({ hysteresis: 0.30, minSwitchInterval: '30s' })
        .probeExcluded({ sampleRate: 0.1, minSamples: 10, maxConcurrent: 4, timeout: '10s' })

evalFunc returns an ordered Upstream[]: position 0 is the primary, the rest are retry order, anything missing is excluded. Use the chainable stdlib (removeCordoned, excludeIf, whenEmpty, preferTag, sortByScore, stickyPrimary, probeExcluded, …) — see Selection policy for the full DSL + every method.

Default policy: omitting selectionPolicy (or evalFunc) applies a production-hardened chain-agnostic default — removeCordoned + excludeIf filters (error / throttle rates each gated on ≥ 10 samples, p70 latency deviation gated on ≥ 20 samples, block-head lag) + tier-based fallback via preferTag('!tier:fallback') + sortByScore(PREFER_FASTEST) + sticky primary + probeExcluded shadow-mirroring (gives excluded upstreams a chance to heal via background traffic). See the full default-policy chain for thresholds and rationale. Investigations are exposed via OTLP tracing and the erpc_selection_* Prometheus metric family.

directiveDefaults — request directives at network level

These apply to every request on this network unless the client explicitly overrides them via HTTP header (X-ERPC-…) or query param.

eth_getLogs — splitting and limits

Splitting preserves order. Address count is the length of the address array (if present). Topic count considers only topics[0] when it's an OR-list.

trace_filter and arbtrace_filter — splitting

Same pattern as eth_getLogs, but opt-in (disabled by default):

• Proactive splitting: set upstream.evm.traceFilterAutoSplittingRangeThreshold to a positive value. Pick something below the upstream's per-response result cap for typical trace density.
• Split on error: set network.evm.traceFilterSplitOnError: true. Bisects block range, then fromAddress, then toAddress.
• Concurrency: network.evm.traceFilterSplitConcurrency (default 10).

Sub-ranges and address-list halves are disjoint by construction — no server-side deduplication. Order is preserved by sub-request index.

eth_sendRawTransaction — idempotent broadcasting

Enabled by default via evm.idempotentTransactionBroadcast: true. When set:

• "Already known" / duplicate-transaction errors are converted to success responses (the tx hash is recomputed from the signed payload).
• "Nonce too low" errors are verified against on-chain state — if the tx exists, return success.

This makes retry and hedge policies safe for transaction broadcast — duplicate broadcasts to multiple upstreams don't surface as errors to the client.

To disable (e.g. on chains where you want to see the duplicate-broadcast errors):

networks:
  - architecture: evm
    evm:
      chainId: 1
      idempotentTransactionBroadcast: false

eth_getTransactionCount — return highest nonce, not most-common

When fanning nonce queries across multiple upstreams, you usually want the highest value, not the most-agreed value (lagging upstreams will report stale lower nonces).

networks:
  - architecture: evm
    evm: { chainId: 1 }
    failsafe:
      - matchMethod: eth_getTransactionCount
        consensus:
          maxParticipants: 3        # query 3 upstreams in parallel
          agreementThreshold: 1     # only need 1 valid response; pick the highest
          preferHighestValueFor:
            eth_getTransactionCount:
              - result              # the result IS the nonce (hex string)

The preferHighestValueFor map keys are method names; values are arrays of JSON field paths to compare:

• "result" — compare the response's direct result value (works for eth_getTransactionCount which returns "0x5" directly).
• Field name(s) — for object results (e.g. ["nonce", "blockNumber"] for eth_getTransactionByHash where you want highest nonce, breaking ties by highest blockNumber).
• Multiple fields are compared in declaration order; first decides, later ones break ties.

When preferHighestValueFor is set:

• maxParticipants — set to the number of upstreams you want to compare (2-3 is typical).
• agreementThreshold — recommended 1. The highest nonce typically reflects the most recently mined tx; requiring agreement would prefer the stale value. Use ≥2 only when you fear compromised upstreams returning artificially-high nonces.

preferHighestValueFor takes precedence over normal hash-based consensus for the matched method. Error responses are ignored; only valid numeric responses are compared.

markEmptyAsErrorMethods

Treat empty responses on specific methods as errors (so they're retried and the upstream is scored down):

networks:
  - architecture: evm
    evm:
      chainId: 1
      markEmptyAsErrorMethods:
        - eth_getTransactionReceipt   # empty here means tx missing, not pending

By default, empty responses on most methods are valid data (caching them is safe). Use this only when an empty value indicates the upstream lacks the data.

Static-response error variant

The staticResponses example in the human section shows result-style. For error-style:

staticResponses:
  - method: some_unsupported_method
    params: []
    response:
      error:
        code: -32601                  # JSON-RPC standard error codes; -32601 = method not found
        message: "Method not found"
        data:                          # optional, embedded as response.error.data
          hint: "use eth_call instead"

The same (method, params) matching rules apply. Use this for methods you want clients to immediately know are unsupported on this chain without round-tripping to an upstream.

Multiplexing override

By default, identical concurrent requests on the same network are deduplicated — a single upstream call is made, and the result is shared with all callers. To disable for one network (e.g. to force every probe through to upstream during latency testing):

networks:
  - architecture: evm
    evm: { chainId: 1 }
    multiplexing: false

true is the default and almost always what you want — disabling triples upstream RPS during traffic spikes for no benefit in production.

Common pitfalls

• failsafe replaces, doesn't deep-merge networkDefaults.failsafe — if networks[].failsafe is set, the network entirely overrides defaults for that field. Same for selectionPolicy. Other fields like rateLimitBudget and directiveDefaults ARE deep-merged.
• matchFinality: ["latest"] — there is no latest finality state. Valid values are finalized, unfinalized, realtime, unknown. Invalid values silently never match.
• Network timeout vs upstream timeout — the network timeout.duration covers the full request lifecycle including every upstream retry. The upstream's own timeout only bounds one attempt. Set the network timeout generously (≥ upstream timeout × maxAttempts).
• fallbackFinalityDepth: 1024 blocks finality detection — if you set this and the upstream actually supports eth_getBlockByNumber("finalized"), eRPC still uses the dynamic value. The fallback only kicks in if the upstream doesn't.
• Static responses bypass everything — including auth's rate-limit budgets. Don't put privileged data in a static response.
• alias: eth/1 is invalid — only alphanumeric, dash, and underscore allowed.