eth_getProof is an Ethereum JSON-RPC method. It returns the Merkle proof of a specific account and its storage at a given block. If you’re not familiar with these terms, don’t worry. Most people don’t understand them. By the end of this article, you should have a better understanding of what eth_getProof is and how to use it.
eth_getProof was proposed in EIP-1186. The proposal summary states the following:
In order to allow verification of accounts outside the client, we need an additional function delivering us the required proof. These proofs are important to secure Layer2-Technologies.
But how does the proof work?
In the Chainstack blog Deep dive into eth_call, we discuss how Ethereum uses Merkle tries for data storage. There are four types of tries used by Ethereum:
State trie
Storage trie
Receipt trie
Transaction trie
The state trie of Ethereum is like a real tree in some ways. All the account information is stored at the end of the branches, which are represented by the leaves.
Merkle trie in a nutshell
Each block has a unique hash value that references the storage root. In a full mode, which has access to the most recent 128 blocks, there are 128 isolated state tries (in reality, it is slightly more complicated than this). When the EVM needs to access the account state, it uses the block number to find the proper root hash, then uses the root hash to determine which trie to query, and finally traverses down the branches to identify the correct leaf containing the account information.
Now, here’s the question: we have account information (storageRoot, codeHash, balance, and nonce); how do we verify this information’s authenticity and correctness? The answer is by using the storage root hash.
For Ethereum, the final root hash is derived by hashing every layer of the trie.
A simplified version of binary Merkle trie. Source
//In a very simplified fashionstateRootHash =hash(hash(hash(hash(A)+hash(B))+hash(hash(C)+hash(D)))+hash(hash(hash(E)+hash(F))+hash(hash(G)+hash(H))))
The final root hash is computed by hashing all the sub-nodes in the state trie. If any of the account information differs from the original, the resulting root hash will also be different. Therefore, any account information can be verified using an authenticated root hash.
For example, consider the following Ethereum account: 0xdac17f958d2ee523a2206206994597c13d831ec7.
At block 16947990, its account information is as follows:
The state root hash at block 16947990 is: 0x98612efbedabf19646d53f903810e156143d3174a4e985b00cbf01dc257431d1
If any of the account information does not match the original value, the final root hash will not match 0x98612efbedabf19646d53f903810e156143d3174a4e985b00cbf01dc257431d1. Therefore, we can prove that this information is incorrect.
Here comes another question: do we need every account’s information to produce a proof? The answer is obviously no. With millions of accounts on the blockchain, it is not feasible to retrieve all these data just to verify one single account, especially for off-chain verification.
In fact, to verify account C, we don’t really need the information from leaf nodes A, B, D, E, F, G, H; we just need the hash of the intermediate branch nodes.
//In a very simplified fashionstateRootHash =hash(hash(hashAB +hash(hash(C)+hashD)+ hashEFGH)
This is much easier, isn’t it?
Essentially, eth_getProof returns the values of hashEFGH, hashAB, and hashD. It is also known as Merkle proof.
Merkle proof doesn’t only work for account information but also for storage information. Storage refers to the data that lives within an account, such as the owner and balance mapping from an ERC-20 token smart contract.
eth_getProof returns the Merkle proof for a specific account and its associated storage values. Merkle proofs are used to verify the inclusion of a certain piece of data within a Merkle trie.
balance: QUANTITY — the balance of the account. See eth_getBalance in the API reference.
codeHash: DATA— the code hash of the account. For a simple account without code, it will return "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470".
storageHash: DATA — SHA3 of the StorageRoot. All storage will deliver a Merkle proof starting with this root hash. This hash is used as the starting point to retrieve a Merkle proof for all storage entries associated with the account.
accountProof: ARRAY — the array of RLP-serialized Merkle trie nodes, starting with the stateRoot-Node, following the path of the SHA3 (address) as key, and can be used to prove the existence and validity of a piece of data in the trie.
storageProof: ARRAY — the requested array of storage entries, where each entry is represented as an object that includes the following properties:
key: QUANTITY — the requested storage key
value: QUANTITY — the storage value
proof: ARRAY — the array of RLP-serialized Merkle trie nodes, starting with the storageHash-Node, following the path of the SHA3 (key) as the path.
Next, you can run the code to see it in action. Scroll all the way down to the last section of the script. This is where the code is executed.
To begin, we retrieve the latest block information by calling w3.eth.get_block("latest").
Next, we obtain the Merkle proof of the account 0xdAC17F958D2ee523a2206206994597C13D831ec7 and one of its storage values by calling w3.eth.get_proof('0xdAC17F958D2ee523a2206206994597C13D831ec7', ["0x9c7fca54b386399991ce2d6f6fbfc3879e4204c469d179ec0bba12523ed3d44c"], "latest").
Then, we verify the proof by calling verify_eth_get_proof(proof, block.stateRoot). If the proof is valid, verify_eth_get_proof returns true to the isValidProof variable. Otherwise, it returns a “Failed to verify account proof” error.
This method allows for efficient verification of the network’s state without having to download the entire state trie for a block. This can be particularly useful for building lightweight clients or auditing smart contract state changes.
There are many reasons why Ethereum uses a Merkle trie for data storage, but one of the most important is its verifiability. As a famous blockchain quote goes, “Don’t trust, verify.” You can learn more about the Merkle trie in the Ethereum documentation article.
The implementation determines this. For Ethereum, the trie is hexary, which means that there are 16 entries for every node.
Yes, Ethereum keeps a separate storage trie for each state.
The storage trie is a part of the state trie that stores the contract state. Each contract on the blockchain has its own storage trie, which is a key-value store that maps 256-bit keys to 256-bit values. This allows smart contracts to persist data across transactions and to maintain their own state.
When a contract is executed, and its state is updated, the new state is stored in a new storage trie, which is then added to the state trie. This creates a new state root, which represents the updated state of the blockchain.
RLP (recursive length prefix) serialization is a technique widely used by Ethereum clients for serialization purposes. In a Merkle trie, RLP is used to convert key-value pairs (the node entries) into a long string, which is then used for hashing. You can read more in Recursive-length prefix (RLP) serialization.
Yes, eth_getProof is available on the Erigon client but only supports 100,000 blocks in the past. On Geth, there’s no 100,000 blocks limit. Note that you need an archive node for eth_getProof.
This concludes the article. Congratulations! You now know how to use the eth_getProof method to retrieve a Merkle proof and verify a user’s ERC-20 token balance.
When using eth_getProof, remember to provide the correct block number, account address, and key path to retrieve the desired proof.
