The debug_storageRangeAt method returns the contract storage for a specified range. This method is primarily used for debugging purposes and allows developers to inspect and analyze on-chain storage data. It's commonly used by development tools like Remix to implement debugging features and provides direct access to the raw storage slots of a smart contract.

Use Cases

Smart Contract Debugging: Inspect specific storage values to identify state-related bugs in your contracts
Contract State Analysis: Analyze how contract state changes during execution of different functions
Storage Layout Verification: Verify that your contract's storage layout matches your expectations
Contract Auditing: Examine storage slots to find security vulnerabilities or unexpected state changes
Development Tool Integration: Build debugging tools that can visualize contract state and memory
Post-Mortem Analysis: Investigate contract state after failures or exploits
Proxy Contract Verification: Verify slot assignments in upgradeable proxy patterns
Governance Inspection: Review storage state for DAO or governance contracts
Historical State Analysis: Compare storage values across different blocks to track state evolution

Method Details

This method returns storage entries for a contract within a specified range.

Paramètres:

blockHashstring[required]

Hash of the block to fetch storage from

txIndexinteger[required]

Transaction index within the block

addressstring[required]

Contract address whose storage is to be retrieved

startKeystring[required]

Hash of the starting storage key

limitinteger[required]

Maximum number of storage entries to return

Retours:

resultobject

Object containing storage entries with key-value pairs

[storageHash]object

Object for each storage entry

keystring

The storage key as a hex string

valuestring

The storage value as a hex string

nextKeystring

The key to use for the next range query, or not present if no more entries

Response Example

{
	"jsonrpc": "2.0",
	"id": 1,
	"result": {
		"storage": {
			"0x0000000000000000000000000000000000000000000000000000000000000000": {
				"key": "0x0000000000000000000000000000000000000000000000000000000000000000",
				"value": "0x0000000000000000000000000000000000000000000000000000000000000001"
			},
			"0x0000000000000000000000000000000000000000000000000000000000000001": {
				"key": "0x0000000000000000000000000000000000000000000000000000000000000001",
				"value": "0x000000000000000000000000d7acd2a9fd159e69bb102a1ca21c9a3e3a5f771b"
			},
			"0x0000000000000000000000000000000000000000000000000000000000000002": {
				"key": "0x0000000000000000000000000000000000000000000000000000000000000002",
				"value": "0x0000000000000000000000000000000000000000000000000000000000000064"
			}
		},
		"nextKey": "0x0000000000000000000000000000000000000000000000000000000000000003"
	}
}

Response Fields Explained

storage: Object containing each storage entry as a key-value pair.
The key is the keccak256 hash of the storage slot.
Each entry contains:
key: The original storage key (slot number).
value: The value stored at this key.
nextKey: The next storage key to start from when retrieving the next batch, or absent if no more entries.

Understanding Storage Slots

In Ethereum smart contracts, storage is organized in 32-byte slots:

Slot 0, 1, 2, ...: Simple state variables are stored sequentially.
Mappings: Stored at keccak256(key . slot) where . is concatenation.
Dynamic Arrays: Length at slot, data at keccak256(slot) + index.
Nested Mappings: Use multiple hashing steps.

Performance Considerations

Querying large storage ranges can result in significant response sizes
Consider using smaller limits for contracts with extensive storage
Using a precise startKey helps reduce unnecessary data transfer
This method is more resource-intensive than basic storage queries

Important Notes

This method is primarily used by development tools like Remix and other Ethereum IDEs
Requires the debug API to be enabled on the Ethereum node
Not all Ethereum clients support this method (fully supported in Geth and some others)
For accurate results, use block hash and transaction index that reflect the desired state
The limit parameter helps manage response size for contracts with large storage
Some archive nodes might impose limits on storage range queries
The method returns raw storage values which may require additional parsing for complex data types
Cannot be used to read private variables directly as they may be packed into the same storage slot
Historical queries require an archive node; non-archive nodes only support recent blocks

debug_storageRangeAt