Database

Long-term storage is optional but used for various purposes such as caching, rate limit persistence, etc.

erpc.yaml

# ...
database:
  evmJsonRpcCache:
    driver: memory | redis | postgresql | dynamodb
    # ... (driver specific config, see below)

`evmJsonRpcCache`

This config defines the destination for caching JSON-RPC cals towards any EVM architecture upstream. Caching mechanism is non-blocking on critical path, and is used as best-effort. If the database is not available, the cache set/get will be skipped.

Make sure the storage requirements meet your usage, for example caching 70m blocks + 10m txs + 10m traces on Arbitrum needs 200GB of storage.

Re-org mechanism

At the moment eRPC will track finalized block, only cache data for finalized blocks. This first version will ensure invalidation is not needed. In future releases (opens in a new tab) it is planned to add capability to cache unfinalized data and invalidaiton re-org.

For chains which do not support "finalized" block method, eRPC will consider last 1024 blocks unfinalized. This number is decided based on historical performance on real-world worst reorgs (e.g. on Polygon chain).

Cacheable methods

Methods are cached if they include a blockNumber or blockHash in the request or response, allowing cache invalidation during blockchain reorgs. If no blockNumber is present, caching is still viable if the method returns data unaffected by reorgs, like eth_chainId, or if the data won't change after a reorg, such as eth_getTransactionReceipt. Here is an overview of cacheable methods:

Method Name	Description
`eth_getTransactionReceipt`	Retrieves the receipt of a transaction by its hash.
`eth_getTransactionByHash`	Retrieves a transaction based on its hash.
`arbtrace_replayTransaction`	Replays a transaction on the blockchain (specific to Arbitrum).
`trace_replayTransaction`	Replays a transaction and returns the trace of execution.
`debug_traceTransaction`	Traces the execution of a transaction.
`trace_transaction`	Returns the trace of a transaction by its hash.
`eth_chainId`	Returns the chain ID of the network.
`eth_getBlockByNumber`	Retrieves a block by its number.
`eth_getUncleByBlockNumberAndIndex`	Retrieves an uncle block by its number and index.
`eth_getTransactionByBlockNumberAndIndex`	Retrieves a transaction by block number and transaction index.
`eth_getUncleCountByBlockNumber`	Retrieves the number of uncles in a block by block number.
`eth_getBlockTransactionCountByNumber`	Retrieves the number of transactions in a block by block number.
`eth_getBlockReceipts`	Retrieves all receipts for a block by block number.
`eth_getLogs`	Retrieves logs based on filter criteria.
`eth_getBalance`	Retrieves the balance of an account at a specified block.
`eth_getCode`	Retrieves the code at a given address at a specified block.
`eth_getTransactionCount`	Retrieves the number of transactions sent from an address at a specified block.
`eth_call`	Executes a new message call immediately without creating a transaction on the blockchain.
`eth_feeHistory`	Returns the history of gas fees.
`eth_getAccount`	Retrieves account information at a specified block.
`eth_getBlockByHash`	Retrieves a block by its hash.
`eth_getTransactionByBlockHashAndIndex`	Retrieves a transaction by block hash and transaction index.
`eth_getBlockTransactionCountByHash`	Retrieves the number of transactions in a block by block hash.
`eth_getUncleCountByBlockHash`	Retrieves the number of uncles in a block by block hash.
`eth_getProof`	Retrieves the proof for an account and its storage.
`eth_getStorageAt`	Retrieves the value from a storage position at a specified address and block.

Drivers

Depending on your use-case you can use different drivers.

Memory

Mainly useful for local testing or when you don't need to cache too much data.

erpc.yaml

# ...
database:
  evmJsonRpcCache:
    driver: memory
    maxItems: 10000

Redis

Redis is useful when you need to store cached data temporarily with eviction policy (e.g. certain amount of memory).

erpc.yaml

# ...
database:
  evmJsonRpcCache:
    driver: redis
    redis:
      addr: YOUR_REDIS_ADDRESS_HERE
      password: YOUR_REDIS_PASSWORD_HERE
      db: XXX
# ...

Example of Redis config with eviction policy:

maxmemory 2000mb
maxmemory-policy allkeys-lru

PostgreSQL

Useful when you need to store cached data permanently without TTL i.e. forever.

You don't need to create the table, the driver will automatically create the table and requried indexes.

erpc.yaml

# ...
database:
  evmJsonRpcCache:
    driver: postgresql
    postgresql:
      connectionUri: >-
        postgres://YOUR_USERNAME_HERE:YOUR_PASSWORD_HERE@your.postgres.hostname.here.com:5432/your_database_name
      table: rpc_cache
# ...

DynamoDB

When you need to have scalable (compared to Postgres) permanent caching and are happy with the costs.

erpc.yaml

# ...
database:
  evmJsonRpcCache:
    driver: dynamodb
    dynamodb:
      table: rpc_cache
      region: eu-west-1
      endpoint: https://dynamodb.eu-west-1.amazonaws.com # Optional
      # Auth is optional if you are running within AWS.
      auth:
        mode: secret # file, or env
        accessKeyId: YOUR_ACCESS_KEY_ID # Only if mode is secret
        secretAccessKey: YOUR_SECRET_ACCESS_KEY # Only if mode is secret
        profile: xxxxx # Only if mode is file
        credentialsFile: xxxx # Only if mode is file

Rate limiters Docker