Upstreams

An upstream is defined to handle 1 or more networks (a.k.a. chains). There are currently these types of upstreams:

evm A generic EVM-compatible JSON-RPC endpoint. This is the default and most-used type.
alchemy A special upstream type that accepts Alchemy.com API-KEY and automatically adds all their EVM chains.
drpc A special upstream type that accepts dRPC.org API-KEY and automatically adds all their EVM chains.
blastapi A special upstream type that accepts BlastAPI.io API-KEY and automatically adds all their EVM chains.
thirdweb A special upstream type that accepts Thirdweb.com API-KEY and automatically adds all their EVM chains.
envio A special upstream type for Envio.dev HyperRPC endpoint and automatically adds all chains by HyperRPC.
pimlico A special upstream type for Pimlico.io account-abstraction (ERC-4337) support.
etherspot A special upstream type for Etherspot.io account-abstraction (ERC-4337) support.

eRPC supports any EVM-compatible JSON-RPC endpoint when using evm type. Specialized types like "evm+alchemy" are built for well-known providers to make it easier to import "all supported evm chains" with just an API-KEY.

Selection mechanism

eRPC records various metrics about each upstream, and uses them to decide which upstream to use when a request is made. These metrics include:

Total request failures gives higher priority to upstreams with lower failure rate.
Total rate limited requests gives higher priority to upstreams with lower rate limited requests.
P90 latency of requests gives higher priority to upstreams with lower latency.
Total requests served gives higher priority to upstreams with least served requests so they have a chance to prove themselves.

These metrics amount to a certain Score per upstream (alchemy, infura, etc) and per method (eth_blockNumber, eth_getLogs, etc), within a defined windowSize (default 30 minutes), which can be configured as:

erpc.yaml

projects:
  # ...
  - id: main
    # ...
    healthCheck:
      scoreMetricsWindowSize: 1h
      # ...

Scoring mechanism only affects the order which upstreams are tried. To completely disable a bad upstream, you should use Circuit Breaker (opens in a new tab) failsafe policy on upstream-level.

Config

erpc.yaml

# ...
projects:
  - id: main
    # ...
 
    # Each upstream supports 1 or more networks (i.e. evm chains)
    upstreams:
      - id: blastapi-chain-42161
        type: evm
        endpoint: https://arbitrum-one.blastapi.io/xxxxxxx-xxxxxx-xxxxxxx
 
        # Defines which budget to use when hadnling requests of this upstream (e.g. to limit total RPS)
        # Since budgets can be applied to multiple upstreams they all consume from the same budget.
        # For example "global-blast" below can be applied to all chains supported by BlastAPI,
        # to ensure you're not hitting them more than your account allows.
        rateLimitBudget: global-blast
 
        # Rate limit budget can be automatically adjusted based on the "rate-limited" error rate,
        # received from upstream. Auto-tuning is enabled by default with values below.
        # This is useful to automatically increase the budget if an upstream is capable of handling more requests,
        # and decrease the budget if upstream is degraded.
        # Every "adjustmentPeriod" total number of requests vs rate-limited will be calculated,
        # if the value (0 to 1) is above "errorRateThreshold" then budget will be decreased by "decreaseFactor",
        # if the value is below "errorRateThreshold" then budget will be increased by "increaseFactor".
        # Note that the new budget will be applied to any upstream using this budget (e.g. Quicknode budget decreases).
        rateLimitAutoTune:
          enabled: true
          adjustmentPeriod: 1m
          errorRateThreshold: 0.1
          increaseFactor: 1.05
          decreaseFactor: 0.9
          minBudget: 0
          maxBudget: 10_000
 
        # chainId is optional and will be detected from the endpoint (eth_chainId),
        # but it is recommended to set it explicitly, for faster initialization.
        evm:
          chainId: 42161]
 
        # To allow auto-batching requests towards the upstream.
        # Remember even if "supportsBatch" is false, you still can send batch requests to eRPC
        # but they will be sent to upstream as individual requests.
        jsonRpc:
          supportsBatch: true
          batchMaxSize: 100
          batchMaxWait: 100ms
 
        # Which methods must never be sent to this upstream.
        # For example this can be used to avoid archive calls (traces) to full nodes
        ignoreMethods:
          - "eth_traceTransaction"
          - "alchemy_*"
        # Explicitly allowed methods will take precedence over ignoreMethods.
        # For example if you only want eth_getLogs to be served, set ignore methods to "*" and allowMethods to "eth_getLogs".
        allowMethods:
          - "eth_getLogs"
        # By default a dynamic mechanism automatically adds "Unsupported" methods to ignoreMethods,
        # based on errors returned by the upstream. Set this to false to disable this behavior.
        autoIgnoreUnsupportedMethods: true
 
        # Refer to "Failsafe" section for more details:
        failsafe:
          timeout:
            duration: 15s
          retry:
            maxCount: 2
            delay: 1000ms
            backoffMaxDelay: 10s
            backoffFactor: 0.3
            jitter: 500ms

Upstream Types

`evm` JSON-RPC

These are generic well-known EVM-compatible JSON-RPC endpoints. This is the default and most-used type. They can be your own self-hosted nodes, or remote 3rd-party provider nodes.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: my-infura
        type: evm
        endpoint: https://mainnet.infura.io/v3/YOUR_INFURA_KEY
        evm:
          chainId: 1 # Optional. If this is not set it'll be detected from the endpoint (eth_chainId)
          nodeType: full # Optional. Can be "full" or "archive"
        # ...

`alchemy` JSON-RPC

This upstream type is built specially for Alchemy (opens in a new tab) 3rd-party provider to make it easier to import "all supported evm chains" with just an API-KEY.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: my-alchemy
        endpoint: alchemy://YOUR_ALCHEMY_API_KEY
        # ...

`drpc` JSON-RPC

This upstream type is built specially for dRPC (opens in a new tab) 3rd-party provider to make it easier to import "all supported evm chains" with just an API-KEY.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: my-drpc
        endpoint: drpc://YOUR_DRPC_API_KEY
        # ...

`blastapi` JSON-RPC

This upstream type is built specially for BlastAPI (opens in a new tab) 3rd-party provider to make it easier to import "all supported evm chains" with just an API-KEY.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: my-blastapi
        endpoint: blastapi://YOUR_BLASTAPI_API_KEY
        # ...

`thirdweb` JSON-RPC

This upstream type is built specially for Thirdweb (opens in a new tab) 3rd-party provider to make it easier to import "all supported evm chains" with just a CLIENT-ID.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: my-thirdweb
        endpoint: thirdweb://YOUR_THIRDWEB_CLIENT_ID
        # ...

For production traffic consult with Thirdweb team about the chains you are goin to use and amount of traffic you expect to handle.

`envio` JSON-RPC

Envio HyperRPC (opens in a new tab) service provides a higher-performance alternative for certain read methods. When handling requests if a method is supported by HyperRPC (opens in a new tab), then this upstream may be used.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: envio-public
        endpoint: envio://rpc.hypersync.xyz
        # ...

For indexing use-cases it is recommended to this upstream. This will automatically add all supported EVM chains by HyperRPC.

`pimlico` JSON-RPC

Pimlico (opens in a new tab) adds account-abstraction (ERC-4337) support to your eRPC instance. With this upstream added when a AA-related request arrives it'll be forwarded to Pimlico, which allows you to use the same RPC endpoint for both usual eth_* methods along with ERC-4337 methods.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: pimlico-public
        endpoint: pimlico://public
        # Or provide your API-KEY as:
        # endpoint: pimlico://xxxxxmy-api-key
        # ...

`etherspot` JSON-RPC

Etherspot (opens in a new tab) adds account-abstraction (ERC-4337) support to your eRPC instance. With this upstream added when a AA-related request arrives it'll be forwarded to Etherspot, which allows you to use the same RPC endpoint for both usual eth_* methods along with ERC-4337 methods.

erpc.yaml

# ...
projects:
  - id: main
    # ...
    upstreams:
      - id: etherspot-public
        endpoint: etherspot://public
        # Or provide your API-KEY as:
        # endpoint: etherspot://xxxxxmy-api-key
        # ...

Roadmap

On some doc pages we like to share our ideas for related future implementations, feel free to open a PR if you're up for a challenge:

Add a "exclusiveMethods" to make it easier to configure which upstreams are only ones supporting certain methods (e.g. alchemy_*)
Automatically detect type of EVM nodes (full, archive) and engines (erigon, geth, etc)
Implement the logic for "getLogsMaxBlockRange" to split multiple requests when the block range is too high.
Add more special types for well-known vendors (BlastAPI, Ankr, LlamaRPC, etc) for easier multi-chain support.

Networks CORS

Upstreams

Selection mechanism

Config

Upstream Types

evm JSON-RPC

alchemy JSON-RPC

drpc JSON-RPC

blastapi JSON-RPC

thirdweb JSON-RPC

envio JSON-RPC

pimlico JSON-RPC

etherspot JSON-RPC

Roadmap

`evm` JSON-RPC

`alchemy` JSON-RPC

`drpc` JSON-RPC

`blastapi` JSON-RPC

`thirdweb` JSON-RPC

`envio` JSON-RPC

`pimlico` JSON-RPC

`etherspot` JSON-RPC