Motivation

eth_getStorageAt fetches one storage slot per call. Consumers doing heavy local simulations often need hundreds of slots across multiple contracts at the same block. Today this requires N round-trips and N independent state lookups. A batch method eliminates both.

Note: JSON-RPC batch requests solve the round-trip problem but not the repeated state lookups. Each sub-request independently resolves the block and opens the state. Moreover clients often cache state on a per-simulation basis, which means the contract will be cold every time.

Method

eth_getStorageValues(requests, blockNrOrHash)

Parameters

1. requests: Map<Address, Array>: mapping of contract addresses to the storage slot keys to read from each. Clients SHOULD enforce a cap on total slot count (sum of all arrays) and return an error if
   exceeded. Suggested default cap: 1024 total slots.
2. blockNrOrHash: BlockNumberOrHash: block at which to read state. Supports block number, block hash, and tags ("latest", "pending", "earliest", "finalized", "safe").

Returns

Map<Address, Array>: mapping of addresses to storage values. The outer keys correspond to the input addresses. Each inner array corresponds positionally 1:1 with the input slots for that address. Values are 32-byte, zero-padded.

Example

  // Request
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_getStorageValues",
    "params": [
      {
        "0xdAC17F958D2ee523a2206206994597C13D831ec7": [
          "0x0000000000000000000000000000000000000000000000000000000000000002",
          "0x0000000000000000000000000000000000000000000000000000000000000006"
        ],
        "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": [
          "0x0000000000000000000000000000000000000000000000000000000000000003"
        ]
      },
      "latest"
    ]
  }

  // Response
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "0xdAC17F958D2ee523a2206206994597C13D831ec7": [
        "0x00000000000000000000000000000000000000000000000000000000000f4240",
        "0x0000000000000000000000000000000000000000000000000000000000000012"
      ],
      "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": [
        "0x0000000000000000000000000000000000000000000000000000000000000001"
      ]
    }
  }

Error cases

• Invalid address or slot key: return standard JSON-RPC invalid params error (-32602).
• Total slot count exceeds implementation limit: return error with a descriptive message.
• Block not found or state unavailable: return standard error (same as eth_getStorageAt).