eth_getStorageAt | Ethereum

Ethereum API method that returns the data stored at a specific storage slot within a smart contract. It can help developers to read a smart contract’s internal state, like user data or balances, to inform decisions and build more advanced applications that interact with smart contracts on the blockchain.

​

Parameters

• address — the address of the smart contract to query

• quantity — the index of the storage position to retrieve the data from

• quantity or tag — the integer of a block encoded as hexadecimal or the string with:

  • latest — the most recent block in the blockchain and the current state of the blockchain at the most recent block. A chain reorganization is to be expected.
  • safe — the block that received justification from the beacon chain. Although this block could be involved in a chain reorganization, it would necessitate either a coordinated attack by the majority of validators or an instance of severe propagation latency.
  • finalized — the block accepted as canonical by more than 2/3 of the validators. A chain reorganization is extremely unlikely, and it would require at least 1/3 of the staked ETH to be burned.
  • earliest — the earliest available or genesis block
  • pending — the pending state and transactions block. The current state of transactions that have been broadcast to the network but have not yet been included in a block.

​

Response

data — the data stored in the storage slot. Returned as a hexadecimal string.

​

eth_getStorageAt code examples

The following example returns the storage value at slot 0 from the Chainlink VRFCoordinatorV2 on the Ethereum mainnet. In this case, this is the address owning the smart contract.

This method can retrieve the different storage values in time by querying different blocks in the past. Note that to query a state in the past, you need an archive node.

const ethers = require("ethers");



// Create a ChainstackProvider instance for Ethereum mainnet

const chainstack = new ethers.ChainstackProvider("mainnet");



const getstorage = async (address, slot, block) => {

  const storage = await chainstack.send("eth_getStorageAt", [

    address,

    slot,

    block,

  ]);

  console.log(storage);

};



getstorage("0x271682DEB8C4E0901D1a1550aD2e64D568E69909", "0", "latest");

​

Use case

One use case for eth_getStorageAt is analyzing how the value stored at a specific storage slot of a smart contract changes over time. For example, a developer may want to track the change in a specific variable of a smart contract, such as the total supply of a token, and perform some analysis on it.

Here’s an example implementation of this use case using web3.js.

The following program analyzes the Ape token smart contract on the Ethereum chain to track how the total supply changes over time.

The storage slot matches the position of the variable in the smart contract; the following code snippet shows the top of the APE smart contract where the variables used in this program are declared.

contract ERC20 is Context, IERC20 {

    using SafeMath for uint256;

    using Address for address;

	

  // Variables declared

    mapping (address => uint256) private _balances;	// Storage slot 0x0



    mapping (address => mapping (address => uint256)) private _allowances; // Storage slot 0x1



    uint256 private _totalSupply; // Storage slot 0x2



    string private _name; // Storage slot 0x3

    string private _symbol;	// Storage slot 0x4

    uint8 private _decimals;	// Storage slot 0x5

  .

  .

  .

Here’s an example implementation of this use case using web3.js:

const { Web3 } = require("web3");

const NODE_URL = "CHAINSTACK_NODE_URL";

const web3 = new Web3(NODE_URL);



// You need an archive node is going more than 127 blocks in the past.



async function getStorageValueOverTime() {

  // The address of the APE smart contract

  const apeAddress = '0x4d224452801ACEd8B2F0aebE155379bb5D594381';



  // The index of the storage slots where the total supply and name data are stored

  const totalSupplySlot = 2;

  const nameSlot = 3;



  // The range of blocks to analyze

  const startBlock = 18000000n;

  const endBlock = await web3.eth.getBlockNumber();



  for (let blockNumber = startBlock; blockNumber <= endBlock; blockNumber++) {



    // Retrieve the name and total supply from the smart contract storage at each block

    const [name, supply] = await Promise.all([

      web3.eth.getStorageAt(apeAddress, nameSlot, blockNumber),

      web3.eth.getStorageAt(apeAddress, totalSupplySlot, blockNumber)

    ]);



    // Decode the name and total supply from hexadecimal format to their original values

    const decodedName = web3.utils.hexToUtf8(name);

    const decodedSupply = BigInt(supply);



    // Convert the total supply from Wei to Ether and round to 4 decimal places

    const convertedSupply = web3.utils.fromWei(decodedSupply, 'ether');

    const adjustedSupply = Number(convertedSupply).toFixed(4);



    // Output the block number, name, and total supply for each block

    console.log(`Block ${blockNumber}: Name = ${decodedName}, Total supply = ${adjustedSupply}`);

  }

}



async function main() {

  try {

    await getStorageValueOverTime();

  } catch (error) {

    console.error(error);

  }

}



main();

The bulk of the program is the getStorageValueOverTime function.

The getStorageValueOverTime function retrieves and outputs the name and total supply of the APE smart contract at each block height between a specified start block and the current block height.

The function begins by declaring constants for the APE contract address, the storage slot indices for the name and total supply data, the starting block height, and the current block height.

Next, the function enters a for loop that iterates over every block between the start block and the current block height. Within the loop, the function retrieves the name and total supply from the smart contract storage at the current block height using the web3.eth.getStorageAt method.

The Promise.all method is used to retrieve the name and total supply in parallel for improved efficiency. The web3.utils.hexToUtf8 method is then used to convert the name from hexadecimal format to its original string value.

The web3.utils.toBN method is used to convert the total supply from hexadecimal format to a BigNumber object, which can be used for mathematical operations. The web3.utils.fromWei method is then used to convert the total supply from Wei to ether.

Finally, the Number and toFixed methods are used to round the total supply to four decimal places and output the block number, name, and total supply for each block; note that this is for readability, and you should use the raw Wei data to make calculations.

Overall, the getStorageValueOverTime function provides a way to monitor changes in the state of a smart contract over time, which can be useful for understanding the contract’s behavior and performance.