Drivers

Depending on your use-case storage and performance requirements, you can use different drivers.

Memory

Mainly useful when you want fast access for limited amount of cached data. Use this driver for high-frequency RPC calls.

database:
  evmJsonRpcCache:
    connectors:
      - id: memory-cache
        driver: memory
        memory:
          maxItems: 10000
    policies:
      - network: "*"
        method: "*"
        finality: finalized
        connector: memory-cache

Redis

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

database:
  evmJsonRpcCache:
    connectors:
      - id: redis-cache
        driver: redis
        redis:
          # Connection URI (Required)
          # Format: redis://[username]:[password]@[host][:port][/database][?dial_timeout=value1&read_timeout=value2&write_timeout=value3&pool_size=value4]
          # Example: redis://:some-secret@global-shared-states-redis-master.redis.svc.cluster.local:6379/?pool_size=10
          uri: "redis://username:password@host:port/db?dial_timeout=5s&read_timeout=1s&write_timeout=2s&pool_size=10"
          tls:
            enabled: false # or "true" if redis is configured with TLS
            certFile: /path/to/client.crt # Optional
            keyFile: /path/to/client.key # Optional
            caFile: /path/to/ca.crt # Optional
    policies:
      - network: "*"
        method: "*"
        finality: finalized
        connector: redis-cache

TLS options

When your Redis endpoint already uses rediss:// (for example, Railway or Upstash), TLS is negotiated automatically and you can omit the entire tls: block.
Add the tls: section only when you need mutual‑TLS (client certificate/key) or your server uses a private CA:

redis:
  uri: rediss://user:pass@redis.internal:6380/0
  tls:
    enabled: true
    certFile: /secrets/redis-client.crt   # sent to server (mTLS)
    keyFile:  /secrets/redis-client.key
    caFile:   /secrets/redis-rootCA.pem   # trust this CA instead of system roots

Redis URI Format

The Redis URI format follows this pattern:

redis://[[username]:[password]@][host][:port][/database][?dial_timeout=value1&read_timeout=value2&write_timeout=value3&pool_size=value4]

Examples:

• redis://localhost:6379/0 - Basic connection to localhost
• redis://user:pass@redis.example.com:6379/0 - Connection with authentication
• redis://:password@redis.example.com:6379/0 - Connection with password only (no username)
• redis://redis.example.com:6379 - Connection without database number (defaults to 0)
• redis://redis.example.com:6379/0?dial_timeout=5s&read_timeout=1s&write_timeout=2s&pool_size=10 - Connection with timeouts and pool size
• redis://global-shared-states-redis-master.redis.svc.cluster.local:6379 - Kubernetes service deployed via Bitnami charts (opens in a new tab)

You can include these parameters directly in the URI:

• dial_timeout - Timeout for initial connection (e.g., 5s)
• read_timeout - Timeout for read operations (e.g., 1s)
• write_timeout - Timeout for write operations (e.g., 2s)
• pool_size - Connection pool size (e.g., 10)

Configuration Notes

maxmemory 2000mb
maxmemory-policy allkeys-lru

PostgreSQL

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

database:
  evmJsonRpcCache:
    connectors:
      - id: postgres-cache
        driver: postgresql
        postgresql:
          connectionUri: >-
            postgres://YOUR_USERNAME_HERE:YOUR_PASSWORD_HERE@your.postgres.hostname.here.com:5432/your_database_name
          table: rpc_cache
          initTimeout: 5s
          getTimeout: 1s
          setTimeout: 2s
    policies:
      - network: "*"
        method: "*"
        finality: finalized
        connector: postgres-cache

DynamoDB

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

database:
  evmJsonRpcCache:
    connectors:
      - id: dynamodb-cache
        driver: dynamodb
        dynamodb:
          table: erpc_json_rpc_cache
          region: eu-west-1
          initTimeout: 5s
          getTimeout: 1s
          setTimeout: 2s
          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
    policies:
      - network: "*"
        method: "*"
        finality: finalized
        connector: dynamodb-cache

IAM Permissions

Make sure the IAM role/user has the necessary permissions to create and/or access the DynamoDB table:

• Table Management:
  • dynamodb:CreateTable - For creating the table if it doesn't exist
  • dynamodb:DescribeTable - For checking table existence and configuration
  • dynamodb:UpdateTable - For adding the global secondary index
  • dynamodb:UpdateTimeToLive - For configuring TTL attributes
• Data Operations:
  • dynamodb:PutItem - For storing data and creating locks
  • dynamodb:GetItem - For retrieving data (certain cache queries such as eth_getBlockByNumber with a hex block number)
  • dynamodb:Query - For querying with the reverse index (certain cache queries such as eth_getBlockReceipts by blockHash)
  • dynamodb:DeleteItem - For removing locks
  • dynamodb:UpdateItem - For counter operations with conditions