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          maxTotalSize: '1GB'          # For debugging purposes, enable metrics collection (expect 10% performance hit)          emitMetrics: false    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=...&pool_size=...]          # Example: redis://:some-secret@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

The tls block uses the shared TLSConfig struct. See TLS configuration for the full field reference.

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

connectors:
  - id: hot
    driver: memory
    memory:
      maxItems: 100000
      maxTotalSize: 1GB
      emitMetrics: false   # default; turning on incurs ~10% performance hit

connectors:
  - id: redis-cache
    driver: redis
    redis:
      # Connection — pick ONE of these two ways:
      uri: redis://user:pass@host:6379/0?dial_timeout=5s&pool_size=10
      # OR explicit fields:
      addr: host:6379
      username: user
      password: pass
      db: 0
      connPoolSize: 10
 
      # Operation timeouts
      initTimeout: 5s
      getTimeout: 1s
      setTimeout: 2s
 
      # Lock retry interval (for shared-state lock semantics, if used here)
      lockRetryInterval: 100ms
 
      # TLS — only needed for mTLS or private CA;
      # rediss:// URIs negotiate TLS automatically.
      tls:
        enabled: true
        certFile: /secrets/redis-client.crt
        keyFile: /secrets/redis-client.key
        caFile: /secrets/redis-rootCA.pem
        insecureSkipVerify: false

maxmemory 2000mb
maxmemory-policy allkeys-lru

connectors:
  - id: postgres-cache
    driver: postgresql
    postgresql:
      connectionUri: postgres://user:pass@host:5432/erpc
      table: rpc_cache
      minConns: 2
      maxConns: 20
      initTimeout: 5s
      getTimeout: 1s
      setTimeout: 2s

connectors:
  - id: dynamodb-cache
    driver: dynamodb
    dynamodb:
      table: erpc_json_rpc_cache
      region: eu-west-1
      endpoint: https://dynamodb.eu-west-1.amazonaws.com   # optional
 
      # Schema attribute overrides (only set these if you provisioned the table manually)
      partitionKeyName: requestKey
      rangeKeyName: groupKey
      reverseIndexName: idx_requestKey_groupKey
      ttlAttributeName: ttl
 
      # AWS SDK behavior
      maxRetries: 3
 
      # Timing
      initTimeout: 5s
      getTimeout: 1s
      setTimeout: 2s
      statePollInterval: 250ms
      lockRetryInterval: 100ms
 
      # Auth (optional when running inside AWS with an instance role)
      auth:
        mode: secret           # secret | file | env
        accessKeyId: AKIA...
        secretAccessKey: ...
        # OR for mode: file
        profile: erpc-prod
        credentialsFile: /home/erpc/.aws/credentials

connectors:
  - id: remote-redis
    driver: redis
    redis: { uri: redis://... }
    failsafeForGets:           # reads are best-effort: short timeout, no retry
      - matchMethod: "*"
        timeout: { duration: 50ms }
    failsafeForSets:           # writes can wait longer + retry
      - matchMethod: "*"
        timeout: { duration: 500ms }
        retry: { maxAttempts: 2, delay: 100ms }