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:
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
# ...
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.
# ...
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.
# ...
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.
# ...
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.
# ...
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.
# ...
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.
# ...
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.
# ...
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.
# ...
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.