If you like eRPC, give it a star on GitHub ⭐️
Config
Rate limiters

Rate limiters

To add self-imposed rate limits when sending requests to upstreams (RPS, Daily, etc) you can define one or more rate limiter budgets.

A "budget" can be assigned to one or more upstreams, and those upstreams will share the usage of the budget.

Config

erpc.yaml
# ...
projects:
  - id: main
    # ...
 
    # A project can have a budget that applies to all requests (any network or upstream)
    # Useful to prevent a project (e.g. frontend, or indexer) to send too much requests.
    rateLimitBudget: frontend
 
    # ...
 
    # Each upstream can have its own budget
    upstreams:
      - id: blastapi-chain-42161
        type: evm
        endpoint: https://arbitrum-one.blastapi.io/xxxxxxx-xxxxxx-xxxxxxx
        rateLimitBudget: global-blast
        # ...
      - id: blastapi-chain-1
        type: evm
        endpoint: https://eth-mainnet.blastapi.io/xxxxxxx-xxxxxx-xxxxxxx
        rateLimitBudget: global-blast
        # ...
      - id: quiknode-chain-42161
        type: evm
        endpoint: https://xxxxxx-xxxxxx.arbitrum-mainnet.quiknode.pro/xxxxxxxxxxxxxxxxxxxxxxxx/
        rateLimitBudget: global-quicknode
        # ...
 
# Rate limiter allows you to create "shared" budgets for upstreams.
# For example upstream A and B can use the same budget, which means both of them together must not exceed the defined limits.
rateLimiters:
  budgets:
    - id: frontend
      rules:
        - method: '*'
          maxCount: 1000
          period: 1s
        - method: 'eth_trace*'
          maxCount: 100
          period: 1s
    - id: global-blast
      rules:
        # You can limit which methods apply to this rule e.g. eth_getLogs or eth_* or * (all methods).
        - method: '*'
          maxCount: 1000
          period: 1s
    - id: global-quicknode
      rules:
        - method: '*'
          maxCount: 300
          period: 1s

Auto-tuner

The auto-tuner feature allows dynamic adjustment of rate limits based on the upstream's performance. It's particularly useful in the following scenarios:

  1. When you're unsure about the actual RPS limit imposed by the provider.
  2. When you need to update the limits dynamically based on the provider's current capacity.

The auto-tuner is enabled by default when an upstream has any rate limit budget defined. Here's an example configuration with explanations:

upstreams:
  - id: example-upstream
    type: evm
    endpoint: https://example-endpoint.com
    rateLimitBudget: example-budget
    rateLimitAutoTune:
      enabled: true                # Enable auto-tuning (default: true)
      adjustmentPeriod: "1m"       # How often to adjust the rate limit (default: "1m")
      errorRateThreshold: 0.1      # Maximum acceptable error rate (default: 0.1)
      increaseFactor: 1.05         # Factor to increase the limit by (default: 1.05)
      decreaseFactor: 0.9          # Factor to decrease the limit by (default: 0.9)
      minBudget: 1                 # Minimum rate limit (default: 0)
      maxBudget: 10000             # Maximum rate limit (default: 10000)

It's recommended to set minBudget to at least 1. This ensures that some requests are always routed to the upstream, allowing the auto-tuner to re-adjust if the provider can handle more requests.

The auto-tuner works by monitoring the "rate limited" (e.g. 429 status code) error rate of requests to the upstream. If the 'rate-limited' error rate is below the errorRateThreshold, it gradually increases the rate limit by the increaseFactor. If the 'rate-limited' error rate exceeds the threshold, it quickly decreases the rate limit by the decreaseFactor.

By default, the auto-tuner is enabled with the following configuration:

rateLimitAutoTune:
  enabled: true
  adjustmentPeriod: "1m"
  errorRateThreshold: 0.1
  increaseFactor: 1.05
  decreaseFactor: 0.9
  minBudget: 0
  maxBudget: 10000

You can override these defaults by specifying the desired values in your configuration.

Metrics

The following metrics are available for rate limiter budgets:

  • erpc_rate_limiter_budget_max_count with labels budget and method

This metrics shows how maxCount is adjusted over time if auto-tuning is enabled.

AuthMatcher syntax