# Goldsky cache (gRPC)

> Source: https://docs.erpc.cloud/config/database/goldsky-cache
> Plug Goldsky's hosted, read-only gRPC cache into eRPC — historical blocks, logs, transactions and receipts served from Goldsky's indexed chain data before your requests reach your upstreams — and Monad's MIP-16 eth_queryLogs and eth_queryTransactions served natively.
> Format: machine-readable markdown export of the docs page above.
> All collapsible AI sections are inlined and fully expanded.

# Goldsky cache (gRPC)

Goldsky hosts a read-only gRPC cache backed by its indexed chain data. Add it as a `grpc` [cache connector](/config/database/drivers.llms.txt) and eRPC asks it first for historical reads; a miss goes to your upstreams exactly as before.

## Set it up

### Get a Goldsky API key

Sign up or sign in at [app.goldsky.com](https://app.goldsky.com), open **Edge RPC**, click **New endpoint**, then **Create endpoint**. Copy the **API Key** shown in the **Edge Endpoint Created** dialog. The same key works for Edge RPC and for the cache. Keep it out of your config file:

```bash
export GOLDSKY_API_KEY=gs_edge_...
```

### Add the connector and a policy

One URL per chain; eRPC calls `ChainId` on each at startup to map it to its network.

**Config path:** `database.evmJsonRpcCache`

**YAML — `erpc.yaml`:**

```yaml
database:
  evmJsonRpcCache:
    connectors:
      - id: goldsky-cache
        driver: grpc
        grpc:
          servers:
            - grpcs://edge.goldsky.com/cache/ethereum
            - grpcs://edge.goldsky.com/cache/base
          headers:
            x-api-key: \${GOLDSKY_API_KEY}
          # a read the cache can't answer this fast goes to your upstreams;
          # raise it to keep wide eth_getLogs ranges in the cache
          getTimeout: 200ms
      - id: memory-cache
        driver: memory
    policies:
      - connector: goldsky-cache
        network: "evm:1|evm:8453"
        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_getBlockReceipts|eth_chainId"
        finality: finalized
      - connector: goldsky-cache
        network: "evm:1|evm:8453"
        method: eth_blockNumber
        finality: realtime
      - connector: memory-cache
        network: "*"
        method: "*"
        finality: finalized
```

**TypeScript — `erpc.ts`:**

```typescript
database: {
  evmJsonRpcCache: {
    connectors: [
      {
        id: "goldsky-cache",
        driver: "grpc",
        grpc: {
          servers: [
            "grpcs://edge.goldsky.com/cache/ethereum",
            "grpcs://edge.goldsky.com/cache/base",
          ],
          headers: { "x-api-key": "\${GOLDSKY_API_KEY}" },
          // a read the cache can't answer this fast goes to your upstreams;
          // raise it to keep wide eth_getLogs ranges in the cache
          getTimeout: "200ms",
        },
      },
      { id: "memory-cache", driver: "memory" },
    ],
    policies: [
      {
        connector: "goldsky-cache",
        network: "evm:1|evm:8453",
        method: "eth_getBlockByNumber|eth_getBlockByHash|eth_getLogs|eth_getTransactionByHash|eth_getTransactionReceipt|eth_getBlockReceipts|eth_chainId",
        finality: "finalized",
      },
      {
        connector: "goldsky-cache",
        network: "evm:1|evm:8453",
        method: "eth_blockNumber",
        finality: "realtime",
      },
      { connector: "memory-cache", network: "*", method: "*", finality: "finalized" },
    ],
  },
}
```

The Goldsky cache is read-only. Keep a memory or Redis connector (above: `memory-cache`) for writes and for recent blocks the cache has not indexed yet.

### Check it works

At startup eRPC logs one line per URL:

```
gRPC client initialized for network  server=grpcs://edge.goldsky.com/cache/ethereum networkId=evm:1
```

Then request an old block and look at the `X-ERPC-Cache` response header — `HIT` when the response came from a cache, `MISS` when it went to an upstream:

```bash
curl -si http://localhost:4000/main/evm/1 \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x1000000",false]}' \
  | grep -i x-erpc-cache
```

Per connector, the Prometheus counter `erpc_cache_get_success_hit_total{connector="goldsky-cache"}` counts hits.

## What it serves

- **Methods:** `eth_getBlockByNumber`, `eth_getBlockByHash`, `eth_getLogs`, `eth_getTransactionByHash`, `eth_getTransactionReceipt`, `eth_getBlockReceipts`, `eth_chainId`, `eth_blockNumber`. eRPC never sends other methods to the connector.
- **Misses:** data not indexed yet (e.g. the chain tip) answers gRPC `OUT_OF_RANGE`; eRPC treats it as a cache miss and calls your upstreams.
- **`eth_getLogs`:** up to 30,000 blocks per call. Block, transaction and receipt reads answer well within `getTimeout: 200ms`; a wide or dense `eth_getLogs` range takes longer and goes to your upstreams unless you raise it.
- **Chains:** abstract, arbitrum, arbitrum-sepolia, arc, avalanche, base, base-sepolia, bsc, celo, ethereum, gnosis, hyperevm, ink, monad, optimism, polygon, robinhood, robinhood-testnet, sei, sepolia, tempo, tron. Use the name in the URL: `grpcs://edge.goldsky.com/cache/<chain>`.
- **No writes:** the connector is read-only and eRPC never writes to it, so the policy needs no `appliesTo`.

## Monad `eth_query*` (MIP-16)

On Monad (chain 143), the same endpoint also serves `eth_queryLogs` and `eth_queryTransactions` ([MIP-16](https://github.com/monad-crypto/MIPs/pull/89)) natively through `bds.evm.QueryService`: one paged read from Goldsky's index instead of a node call per block. Add it as a gRPC **upstream** (not a cache connector) that allows those methods. eRPC tries it first and answers `eth_queryBlocks`, `eth_queryTraces` and `eth_queryTransfers` with the [query shim](/reference/evm/method-handlers.llms.txt) on your archive node:

**Config path:** `upstreams`

**YAML — `erpc.yaml`:**

```yaml
upstreams:
  - id: goldsky-monad
    endpoint: grpcs://edge.goldsky.com/cache/monad
    grpc:
      headers:
        x-api-key: \${GOLDSKY_API_KEY}
    evm:
      chainId: 143
    ignoreMethods: ["*"]
    allowMethods:
      - eth_chainId
      - eth_getBlockByNumber
      - eth_queryLogs
      - eth_queryTransactions
  - id: monad-archive
    endpoint: https://your-monad-archive-node
    evm:
      chainId: 143
      # serves eth_queryBlocks, eth_queryTraces and eth_queryTransfers,
      # and any range the Goldsky upstream cannot answer
      queryShim:
        enabled: true
```

**TypeScript — `erpc.ts`:**

```typescript
upstreams: [
  {
    id: "goldsky-monad",
    endpoint: "grpcs://edge.goldsky.com/cache/monad",
    grpc: { headers: { "x-api-key": "\${GOLDSKY_API_KEY}" } },
    evm: { chainId: 143 },
    ignoreMethods: ["*"],
    allowMethods: ["eth_chainId", "eth_getBlockByNumber", "eth_queryLogs", "eth_queryTransactions"],
  },
  {
    id: "monad-archive",
    endpoint: "https://your-monad-archive-node",
    evm: {
      chainId: 143,
      // serves eth_queryBlocks, eth_queryTraces and eth_queryTransfers,
      // and any range the Goldsky upstream cannot answer
      queryShim: { enabled: true },
    },
  },
]
```

- **Both transports:** JSON-RPC `eth_query*` and gRPC `QueryService` streams use the same upstreams and return the same MIP-16 pages.
- **Range:** genesis to the chain tip. eRPC resolves `latest`, `safe` and `finalized` to block numbers before it calls the upstream.
- **Without an archive node:** leave out `monad-archive`. `eth_queryBlocks`, `eth_queryTraces` and `eth_queryTransfers` then return `-32004` (method not supported).
- **Edge RPC:** Goldsky Edge RPC endpoints for Monad (`https://edge.goldsky.com/standard/evm/143`) already serve all five `eth_query*` methods this way.


## Navigation (machine-readable surface)

- Up: [All pages index](https://docs.erpc.cloud/llms.txt)
- Root index of every page: [llms.txt](https://docs.erpc.cloud/llms.txt) · everything in one file: [llms-full.txt](https://docs.erpc.cloud/llms-full.txt)

### Sibling pages

- [Storage drivers](https://docs.erpc.cloud/config/database/drivers.llms.txt) — Five interchangeable cache back-ends — memory, Redis, PostgreSQL, DynamoDB, and a read-only gRPC BDS connector — all behind one uniform interface, with optional per-operation failsafe policies that keep transient storage hiccups invisible to your upstreams.
- [Cache policies](https://docs.erpc.cloud/config/database/evm-json-rpc-cache.llms.txt) — Stop paying for the same upstream call twice — eRPC caches every EVM JSON-RPC response by finality bucket, fans out reads in parallel, and rejects stale tip-of-chain data before it ever reaches your users.
- [Shared state](https://docs.erpc.cloud/config/database/shared-state.llms.txt) — Give every pod in your fleet the same real-time view of each upstream's block height — routing stays consistent as you scale out, with zero added latency on the request path.
- [SVM JSON-RPC cache](https://docs.erpc.cloud/config/database/svm-json-rpc-cache.llms.txt) — Cache Solana JSON-RPC responses without ever serving a stale account balance — eRPC classifies every SVM read by Solana's own commitment rules, keys base58 params case-sensitively, and refuses to treat a moving rooted head as immutable.